Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.altnautica.com/llms.txt

Use this file to discover all available pages before exploring further.

Revocation is the response when a plugin or a signing key turns out to be unsafe after the fact. The system is designed to be loud, auditable, and operator-controllable. The agent never auto-removes a plugin, even a revoked one; removal stays an operator decision.

​
Two kinds of revocation

KindGranularityWhen to use
Key revocationEvery plugin signed by a signer_key_id.The publisher’s signing key was compromised, or the publisher has been removed from trust.
Plugin revocationA specific (plugin_id, version) tuple.A specific version is malicious or critically broken; the rest of the publisher’s catalog is still trusted.
You can issue both at once for a confirmed compromise.

​
Where the revocation list lives

The hosted Altnautica registry will serve the list at a stable path under its domain when the registry ships. The exact URL will be published with the registry launch and configured into the agent’s default registry config. Self-hosted registries serve the same shape at the same path on their host. 
{
  "schema_version": 1,
  "fetched_at": "2026-04-30T12:00:00Z",
  "revoked_keys": [
    {
      "signer_key_id": "example-2025-X",
      "reason": "key_compromised",
      "revoked_at": "2026-04-29T18:00:00Z"
    }
  ],
  "revoked_plugins": [
    {
      "plugin_id": "com.example.foo",
      "version": "1.0.3",
      "reason": "malware_confirmed",
      "revoked_at": "2026-04-30T09:00:00Z"
    }
  ]
}
Standard reason codes: key_compromised, key_expired, policy_violation, malware_confirmed, data_exfiltration, critical_safety_bug, publisher_request.

​
How agents poll

The agent polls the configured registry every 24 hours when the network is available. Successful fetches are cached under /var/cache/ados/revocations/ with a fetch timestamp. The cached list is consulted on every plugin start, so a recently-revoked plugin loses trust on the next start even if the agent is offline at that moment. Cache entries age out after 30 days. If the agent has gone more than 30 days without a fresh revocation list and the operator has not manually pushed one, the GCS surfaces a “revocation list stale” warning on the plugin list view. To force a poll: 
ados plugin revocations refresh
To inspect the current cache: 
ados plugin revocations list
ados plugin revocations show com.example.foo 1.0.3

​
How Mission Control polls

The GCS host fetches the same endpoint when the operator opens the Plugins view. Cached revocations are kept in IndexedDB with a 24-hour TTL. The detail page shows the revocation badge and the reason text the moment the cache refreshes.

​
What a revoked plugin does next time the operator boots

SurfaceBehavior
Agent supervisorThe plugin is moved to a disabled-revoked state. It does not start.
systemd unitDisabled with WantedBy removed. Status text reflects the revocation reason.
Mission ControlA red banner appears on the plugin list and the plugin detail page: “RECALLED” for plugin revocations, “REVOKED” for key revocations.
LogsA structured log line under journalctl -u ados-supervisor records the revocation event with the reason code.
On-disk artifactsRetained as-is under /var/lib/ados/plugins/<plugin_id>/ so a forensic image can be taken before the operator chooses to remove.
Audit logAn append-only entry is written to the plugin events table with event_kind=plugin_revoked and the reason code.
The operator’s options: 
ados plugin info com.example.foo
ados plugin logs com.example.foo
ados plugin remove com.example.foo
Or via the GCS: open the detail page, click “Remove” or “Keep disabled, retain files for forensics”.

​
Why the agent does not auto-remove

In a fleet, a plugin might be load-bearing. Auto-removal could take a vehicle out of service mid-mission. The right default is loud disable plus operator decision. The disable is immediate and non-bypassable; the removal is a separate explicit step.

​
Re-installing after revocation lifts

A revocation can be lifted (publisher rotated their key, the registry republishes a fixed version). The agent picks up the new state on the next poll. Reinstall as usual: 
ados plugin install com.example.foo@1.0.4
The audit log keeps both the original revocation event and the new install event.

​
Reporting a security issue

If you believe a plugin in the registry is malicious, broken in a way that affects flight safety, or is leaking data:

​
Where to report

Open a private security advisory on the affected repository under github.com/altnautica. GitHub’s private vulnerability reporting flow keeps the report off the public issue tracker until a fix ships. If GitHub is not an option for you, use the contact channel on altnautica.com and mark the message as a security report.

​
What to include

  1. The plugin id and version.
  2. The signer key id (from ados plugin info <id> or the manifest signing.signer_key_id field).
  3. A description of the behavior, with reproduction steps where possible.
  4. The operator-facing impact (data loss, vehicle behavior, information disclosure, anything else).
  5. Whether you have already disclosed publicly. If yes, include the link.
  6. Any logs, packet captures, or static-analysis artifacts that support the report.
  7. How you would like to be credited if at all (full credit, pseudonym, or anonymous).
Encrypt the email if it contains sensitive material. Plain text is acceptable for first contact.

​
What we do

  1. Acknowledge the report and start triage. Critical safety reports get prioritized over everything else.
  2. Investigate severity and scope.
  3. For confirmed issues, push a revocation through the registry and ship a fix.
  4. Coordinate disclosure with the reporter.
  5. Publish a post-mortem with what happened, how the issue was caught, and what changed in the host to prevent recurrence.
We do not publish contractual response SLAs. If you have a deployment that requires contractual security response terms, talk to us about a support arrangement.

​
Coordinated disclosure

We default to coordinated disclosure. Public report after the fix is shipped and the post-mortem is published. We do not block you from disclosing on your own timeline; we ask for the courtesy of a heads-up so a coordinated public statement and the fix land together.

​
Operator-side checklist when a revocation lands

  1. Read the reason text. Critical safety reasons mean ground the fleet first.
  2. Check ados plugin list on every SBC. Disabled-revoked entries are flagged.
  3. If the plugin was load-bearing, plan a replacement or rollback before removing.
  4. Once a replacement is in place, ados plugin remove <id> to clean the on-disk artifacts.
  5. Verify with ados plugin events <id> that the audit log captured the revocation, the disable, and the eventual remove.

​
See also