brain/docs/adr/ADR-003-audit-risk-tooling.md

ADR-003 Adopt the D3 audit and risk-management toolset

Status

Accepted, 2026-05-17. Amended 2026-05-17 — corrected the Security Guidance characterisation (a blocking PreToolUse hook, not warn-only) and recorded the python3.exe shim needed on the Windows dev host.

Context

The D3 «Аудит и управление рисками» section of the automation map (docs/automation-graph.html) had no tooling — NODE_SECTION tagged zero nodes D3. Security audits of the portal (#1, #2, #3) were run ad-hoc with no named toolset, and there was no standing store for closed decisions and their residual risks.

This ADR records the toolset chosen to populate the section. It is the audit counterpart of ADR-000, which adopted the ADR process itself.

Decision

The D3 audit and risk-management toolset is:

• /security-review — the Anthropic command, customized at .claude/commands/security-review.md with a project false-positive filter (RLS, ПДн, economy hooks).
• Trail of Bits Skills — eight plugins from the trailofbits marketplace (differential-review, audit-context-building, supply-chain-risk-auditor, insecure-defaults, sharp-edges, static-analysis, variant-analysis, agentic-actions-auditor) for deep, on-demand audit campaigns.
• Security Guidance — the Anthropic PreToolUse hook plugin, for inline vulnerability reminders while editing. The hook is blocking (sys.exit(2)): the first edit per session whose content matches a vulnerable pattern in a given file is blocked once — a one-time speed-bump, the retry passes.
• adr-kit — reused, not re-installed. The decision and risk register is the set of ADRs in docs/adr/: each ADR's ## Consequences records the residual risks of a decision, and the docs/Открытые_вопросы registry holds the unresolved ones. D3 adds no separate risk-register tool.
• Manual toolchain attack-surface procedure — in docs/audit/, run on plugin or MCP-server changes; community auto-auditors are deferred (unverified provenance).
• audit-portal — a project skill encoding the repeated 14-phase portal-audit method.

Alternatives Considered

• Install a dedicated risk-register tool. Rejected: an ADR ## Consequences block plus the Открытые_вопросы registry already cover closed-decision risk and open risk respectively; a third store would violate the "one tool per task" rule (CLAUDE.md §5 п.6) and blur the boundaries fixed by ADR-000.
• Enable all 38 Trail of Bits marketplace plugins. Rejected: most target blockchain, Android, C/C++, or macOS contexts irrelevant to a Laravel + Vue codebase; the eight-plugin subset matches the project's actual audit surface. fp-check was additionally dropped — it ships a lifecycle hook, and the project keeps its hook chain minimal.
• Install a community toolchain attack-surface auditor. Deferred: the candidate plugins have unverified provenance, and installing an unvetted plugin to perform risk management would itself be a risk-management failure. A manual procedure is used until a vetted tool is found.

Consequences

Positive:

• The D3 map section is populated; portal audits have a named, repeatable toolset instead of ad-hoc invocation.
• Closed decisions and their residual risks are version-controlled in docs/adr/; the boundary with the open-questions registry is fixed by ADR-000.

Negative:

• Trail of Bits and Security Guidance are third-party plugins — a bus-factor and supply-chain risk; mitigated by marketplace-cache pinning and re-checked on plugin upgrades.
• Security Guidance adds one PreToolUse hook to a chain that already carries four — a small per-edit latency cost. The hook is blocking (sys.exit(2)), not warn-only; the block is a one-time per-file-and-rule speed-bump, so the cost is bounded. On this Windows host the bundled hooks.json hardcodes the python3 interpreter, which is absent — fixed by a python3.exe shim in the Python install directory on PATH (the plugin cache is not modified).
• The toolchain attack surface still depends on a manual procedure until a vetted auto-auditor exists.

Related Decisions

• ADR-000 — the ADR process and the docs/adr/ to registry boundary this record relies on.
• ADR-002 — tenant isolation via Row-Level Security; its rule drives the /security-review project false-positive filter.

References

• docs/superpowers/plans/2026-05-17-d3-audit-risk-tooling-integration.md — the D3 integration plan.
• .claude/commands/security-review.md — the customized security-review command.
• docs/audit/ — the audit procedures and the toolchain attack-surface check.
• docs/Открытые_вопросы_v8_3.md — the open-questions and open-risk registry.