> ## 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 and incidents

> What happens when a signing key is revoked, and how to report a security issue.

Revocation is the response when a signing key turns out to be unsafe
after the fact. The agent's check is loud and operator-controllable: a
plugin signed by a revoked key refuses to load, but the agent never
auto-removes it. Removal stays an operator decision.

## How revocation works on the agent

The agent keeps a revocation list on disk:

```
/etc/ados/plugin-revocations.json
```

It is a flat JSON array of revoked signer key ids:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
["example-2025-X", "acme-2026-A"]
```

The list is consulted on every signature verification. A plugin signed
by a listed id is rejected before it loads, even offline, so a recently
revoked key loses trust the next time the plugin would start. The list
ships with the agent and updates through OTA; operators on closed
deployments edit it directly and restart the supervisor.

Revocation is keyed on the signer id, so it covers every plugin signed by
that key at once. Finer-grained, per-version revocation is a hosted
registry feature; the registry is not yet live (see below).

## Issuing a revocation

When a key is compromised or a publisher is removed from trust:

1. Add the signer id to `/etc/ados/plugin-revocations.json`.
2. Distribute the updated list (OTA for the Altnautica trust set, your
   config-management channel for self-hosted fleets).
3. Re-sign your current plugin releases with a fresh key and add its
   public key to the trust list.
4. Notify operators. New installs of any plugin signed by the revoked key
   fail signature verification; already-installed plugins stop loading on
   the next start.

## What a revoked plugin does next

| Surface           | Behavior                                                                                                               |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Agent             | The plugin fails its signature check and does not start. The supervisor records the failure.                           |
| Logs              | A structured line is written; inspect it with `ados logs query` or `journalctl -u ados-supervisor`.                    |
| Mission Control   | The plugin detail page reflects the failure so the operator can act.                                                   |
| On-disk artifacts | The install directory under `/var/ados/plugins/<id>/` is left in place so a forensic copy can be taken before removal. |

The operator's options:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
ados plugin info <id>
ados plugin logs <id>
ados plugin remove <id>
```

## Why the agent does not auto-remove

In a fleet a plugin can be load-bearing. Auto-removal could take a
vehicle out of service mid-mission. The safe default is a loud, immediate
refusal-to-load plus a deliberate operator removal step.

## Reporting a security issue

If you believe a plugin 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](https://github.com/altnautica). GitHub's private
vulnerability reporting keeps the report off the public issue tracker
until a fix ships. If GitHub is not an option, use the contact channel on
[altnautica.com](https://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 archive's
   `SIGNATURE` file).
3. A description of the behavior, with reproduction steps where possible.
4. The operator-facing impact (data loss, vehicle behavior, information
   disclosure).
5. Whether you have already disclosed publicly, with a link if so.
6. Any logs, captures, or static-analysis output that supports the report.
7. How you would like to be credited, if at all.

Encrypt the message if it carries sensitive material. Plain text is
acceptable for first contact.

### What we do

1. Acknowledge and triage. Critical safety reports are prioritized.
2. Investigate severity and scope.
3. For confirmed issues, revoke the signer key and ship a fix.
4. Coordinate disclosure with the reporter.
5. Publish a post-mortem with what happened and what changed to prevent
   recurrence.

We do not publish contractual response SLAs. If your deployment needs
contractual security response terms, talk to us about a support
arrangement.

### Coordinated disclosure

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

## When the hosted registry ships

A hosted Altnautica registry will add a polled revocation feed and
finer-grained, per-version revocation. It is not yet live; until then,
the on-device signer-id list above and direct re-signing are the
mechanisms. The two current distribution channels are local-file install
and URL install.

## Operator checklist when a revocation lands

1. Read the reason. Critical safety reasons mean ground the fleet first.
2. Check `ados plugin list` on every SBC for the affected plugins.
3. If a plugin was load-bearing, plan a replacement or rollback before
   removing.
4. Once a replacement is in place, `ados plugin remove <id>`.
5. Verify with `ados plugin info <id>` and `ados logs query` that the
   refusal and the removal were recorded.

## See also

* [Signing keys](/developers/signing-keys)
* [Hosted registry](/developers/distribution-registry)
* [Lifecycle](/developers/lifecycle)