# 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.
