# Plugin Runtime External Audit — Sign-Off Record

**To be filled by:** Operator + auditing firm jointly
**Required for:** Production rollout of Phase 06 plugin runtime
**Companion RFP:** `docs/security/plugin-audit-rfp.md`
**Related blocker:** B-006 in `docs/improvement-plan/BLOCKERS.md`
**Authoring agent (template):** Claude Opus 4.7 (1M context), 2026-05-19

> This document is the **single gate** between staging and production for
> the plugin runtime. It is not signed until the auditing firm confirms
> remediation re-test green. The production topology may still include an
> idle dedicated `worker-plugin` service with `WORKER_QUEUE_GROUP=plugin`
> so deployment, health, and revision checks stay consistent across
> environments. Until this sign-off is complete, do not install, grant,
> enable, or enqueue tenant plugins for external plugin execution in
> production. Once signed, the operator may allow tenant plugin execution
> through the lifecycle controls by setting `PLUGIN_RUNTIME_PRODUCTION_ENABLED=true`.
> Without that flag, production install/grant/enable operations and plugin
> worker fanout/invocation fail closed. Emergency stops still use the
> procedure in §8.

---

## 1. Audit summary

| Field | Value |
|---|---|
| Auditing firm | _________ |
| Lead auditor (named consultant) | _________ |
| Engagement reference (firm-side) | _________ |
| RFP version used | `docs/security/plugin-audit-rfp.md` @ git SHA `_______` |
| Code SHA audited (frozen) | _________ |
| Audit start date | _________ |
| Audit end date (active test window) | _________ |
| Report delivery date | _________ |
| Re-test completion date | _________ |
| Sign-off date | _________ |

**Final report archived at:**

- Sanitized public version: `docs/security-reviews/plugin-runtime-YYYY-MM-DD.md`
- Full version (private): `private/security-reviews/plugin-runtime-YYYY-MM-DD-full.md`

---

## 2. Findings tally

| Severity | Found | Addressed (re-tested green) | Accepted residual (signed) | Deferred (Medium/Low only) |
|---|---|---|---|---|
| Critical | _ | _ | _ | _ |
| High     | _ | _ | _ | _ |
| Medium   | _ | _ | _ | _ |
| Low      | _ | _ | _ | _ |

**Sign-off rule:** for Critical and High rows, `Addressed + Accepted
residual == Found`. Deferred is **only** allowed for Medium and Low.

Any Critical or High that the operator + auditor agree to accept as
residual risk must be documented in §4 with explicit rationale + both
signatures on that finding's row.

---

## 3. Remediation references

One row per Critical or High finding. Medium and Low findings are tracked
in `docs/improvement-plan/06-plugin-system/security-findings/<id>.md` and
do not need to appear in this table.

| Finding ID | Severity | Short description | Detail MD | Remediation commit(s) | Re-test result |
|---|---|---|---|---|---|
| F-001 | _ | _ | `docs/improvement-plan/06-plugin-system/security-findings/F-001.md` | `_______` | green / red |
| F-002 | _ | _ | _ | _ | _ |
| F-003 | _ | _ | _ | _ | _ |
| _     | _ | _ | _ | _ | _ |

**Remediation commits must land on `main` before sign-off.** No
remediation-on-a-branch + sign-off-against-the-branch flow.

---

## 4. Accepted residual risk (Critical/High only)

For any Critical or High finding where the operator chooses to accept the
risk rather than remediate (e.g. because the remediation cost exceeds
the residual-risk cost, or because remediation requires an architectural
change deferred to a later phase):

| Finding ID | Severity | Residual-risk rationale | Compensating controls | Operator initials | Auditor initials |
|---|---|---|---|---|---|
| _ | _ | _ | _ | _ | _ |

If this section is empty, no Critical or High was accepted as residual.
That is the preferred state.

---

## 5. Re-test result

The auditing firm performs one re-test pass after the operator ships
remediation commits. The firm replays each Critical and High finding's
exploit against the post-remediation code SHA and issues a per-finding
verdict.

- [ ] **Re-test passed** — auditor confirms all Critical/High remediations
      close the original finding. Sign-off may proceed.
- [ ] **Re-test failed** — sign-off **withheld**. Operator addresses the
      failing remediation(s), requests a second re-test round (may be
      out-of-scope of the original engagement letter and billed
      separately). Sign-off restarts at §3.

Re-test letter from firm archived at:
`private/security-reviews/plugin-runtime-YYYY-MM-DD-retest.md` (or
attached as PDF to the firm's email — record the email-message-id here:
`_______`).

---

## 6. Sign-off

By signing below, the parties confirm:

- All Critical findings are addressed (re-tested green) **or** accepted as
  residual risk with both signatures on the §4 row.
- All High findings are addressed (re-tested green) **or** accepted as
  residual risk with both signatures on the §4 row.
- Plugin settings HTML assets rendered through the sandboxed iframe are
  covered by signed manifest metadata: `ui.settings.entry` must be paired
  with a manifest-declared SHA-256 (`sha256` or SRI-compatible `integrity`),
  and the host must verify the bundle bytes before returning iframe HTML.
- Medium and Low findings are recorded in
  `docs/improvement-plan/06-plugin-system/security-findings/`.
- The sanitized public report is archived at
  `docs/security-reviews/plugin-runtime-YYYY-MM-DD.md`.
- The full report is archived at
  `private/security-reviews/plugin-runtime-YYYY-MM-DD-full.md`.
- This sign-off may be invalidated retroactively if a Critical or High
  finding emerges post-rollout (see §8).

| Role | Name | Organization | Date | Signature |
|---|---|---|---|---|
| Operator | _________ | toolctrl / @toolctrl/boilerplate | _________ | _________ |
| Lead auditor | _________ | <firm> | _________ | _________ |
| Engineering lead (optional) | _________ | toolctrl | _________ | _________ |
| DPO (required if findings touched PII) | _________ | toolctrl | _________ | _________ |

Wet signatures or PGP-signed digital signatures both acceptable. PGP
signature blocks may be appended below this table; the corresponding
public keys must be referenced from `.well-known/pgp-key.txt` or the
firm's published key directory.

---

## 7. Production-rollout authorization

Once this document is signed in §6, the following are authorized:

1. `PROGRESS.md` Phase 06 Task #23 status moves to `completed`.
2. `docs/improvement-plan/BLOCKERS.md` B-006 entry moves from "Open" to
   "Resolved" with a one-paragraph close-out referencing this sign-off
   document by git SHA.
3. The operator may allow production tenant plugin execution on the
   dedicated `worker-plugin` service with `WORKER_QUEUE_GROUP=plugin` and
   the audited plugin env matrix documented in
   `docs/operations/plugin-lifecycle.md`. The service may already exist as
   an idle, health-checked deployment target before sign-off; sign-off
   authorizes external plugin execution, not the mere presence of the
   container.
4. The first production plugin install is monitored for 24h: Sentry
   `plugin.*` tags, `PluginCapabilityUse` row volume, `worker-plugin`
   container CPU + RAM, sandbox-crash-tracker alerts. Any anomaly follows
   the §8 kill procedure.

---

## 8. Sign-off invalidation (post-rollout)

This sign-off is **invalidated** and the runtime **must be killed** if any
of the following happens after production rollout:

- An external researcher discloses a Critical or High vulnerability in
  the in-scope surface (per `docs/security/vulnerability-disclosure.md`).
- An internal review or new audit discovers a Critical or High finding
  that the original audit did not catch.
- A sandbox-escape is observed in production logs / Sentry, regardless of
  whether it was caused by a malicious or buggy plugin.
- A capability-gateway bypass is observed.
- A signature-verification bypass is observed.
- A cross-tenant data leak is observed via plugin-mediated access.

**Kill procedure:**

1. Stop or scale the dedicated `worker-plugin` service to zero in Coolify
   (or set `WORKER_ENABLED=false` on that service and redeploy). This stops
   `plugin.invoke` consumption without disabling core web/API/worker
   services.
2. Pause or drain the `toolctrl.plugin-invoke` queue if jobs are still
   accumulating, then disable affected tenant plugins through the plugin
   lifecycle UI/API so no new invocations are enqueued after recovery.
3. Page on-call per `docs/security/incident-response.md`.
4. File a new entry in `docs/improvement-plan/BLOCKERS.md` (next B-NNN
   ID) referencing this sign-off and the triggering event.
5. New audit cycle required: either a delta-audit from the same firm
   (preferred) or a fresh full audit before re-rollout.
6. New sign-off document at `docs/security/plugin-runtime-signoff.md`
   (this file is moved to `docs/security/plugin-runtime-signoff-<old-date>.md`
   for archival; a fresh template is written from
   `docs/security/plugin-audit-rfp.md` §7).

---

## 9. Sign-off history (archival)

When this document is re-issued (after a sign-off invalidation per §8),
the previous version is archived here as a chronological list. The
current sign-off above is always the latest entry.

| Sign-off date | Auditing firm | Code SHA | Reason for re-issue (if not the first) | Archived at |
|---|---|---|---|---|
| (first) | _________ | _________ | first sign-off | this file |