221 lines
9.2 KiB
Markdown
221 lines
9.2 KiB
Markdown
# 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 |
|