Дмитрий
3b36f7071a
SG #40 was characterised across all D3 docs as warn-only / does not block. Verified end-to-end: security_reminder_hook.py does sys.exit(2) — a BLOCKING PreToolUse hook (one-time speed-bump per file+rule per session, the retry passes). SG2: on this Windows host the bundled hooks.json hardcodes python3, absent from PATH — the hook never spawned (inert). Fixed with a python3.exe shim in the Python install dir (env-only, not in repo). Normative sync: Tooling v2.5, PSR_v1 v3.5, Pravila v1.19, CLAUDE.md v2.5; ADR-003 amended; automation-graph sec_guidance nd(). Tool counts unchanged (40 positions). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
100 lines
4.8 KiB
Markdown
100 lines
4.8 KiB
Markdown
# 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.
|