baldart 5.8.0 → 5.9.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.9.0] - 2026-07-06
+
+**`security-reviewer` upgraded to the 2026 AppSec state of the art — benchmarked against Codex `codex-security` + Claude Code `security-guidance`, imported as a single-sourced protocol module.**
+The `security-reviewer` was a high-quality *monolithic* agent (senior persona, dual review/apply, pooled YAML, generic Challenge/CoVe via `review-protocol.md`) but stuck at a single-pass "read → list findings by severity" model. A benchmark against two real corpora — Codex's phased `codex-security` workbench (threat-model → discovery → validation → attack-path → severity, coverage ledgers, instance-preserving proof) and Claude Code's `security-guidance` agentic reviewer (adversarial self-refute, attacker≠victim, modern high-miss patterns) — found BALDART at ~60% of current best practice. This wave closes the gap **without a monolithic rewrite**, following the agent-spine 3-layer model.
+
+- **New protocol module [`framework/agents/security-review-protocol.md`](framework/agents/security-review-protocol.md)** — the AppSec verification engine, the security twin of `review-protocol.md`. `SECTION=` dispatch: `boundary-gate` (read `SECURITY.md` + classify `product_surface`/`source_trust`/`boundary_crossed` before confirming), `threat-model` (repository-scoped, never diff-biased), `discovery-lens` (the modern **high-miss** taxonomy: fail-open state drift, allowlist semantic escape, control regression, gate/action field mismatch, parser/validator differential, sensitive-to-observability, CI/CD trust, IaC omitted arg, over-broad grant, stale identity mapping, security-registry fanout, resource-bound placement), `proof-tuples` (class-specific validation tuples + confidence anchored to validation **method** not bug class + instance-preserving), `attack-path` (structured facts → **mechanical** severity), `adversarial-refute` (SURVIVES-unless-refuted, the **attacker≠victim** privilege-boundary test first, precondition-vs-counterevidence discipline, diff newly-introduced-only), `coverage-ledger` (surface dispositions so a clean verdict is honest). It **EXTENDS** `review-protocol.md`'s generic passes, never duplicates them — no dual-SSOT.
+- **`security-reviewer` agent (v1.0.0)** — gains a versioned frontmatter + a "Security Review Passes (BINDING)" block that cites the module with 1-line binding statements (agent-spine: core inline + module on demand). Mode A pooled YAML schema gains `vuln_class`, `cwe: [CWE-###]`, `validation_method`, and a structured `attack_path` block; the summary header carries a compact `coverage:` block. New **secret-redaction** BINDING (report a leaked credential as first 2–4 chars + `****`, never the live value — a review artifact reproducing a secret is itself a leak).
+- **`framework/agents/security.md`** — the consumer-facing security template modernized from **OWASP Top 10:2017 → 2021** (XXE folded into Security Misconfiguration, insecure deserialization into Software & Data Integrity Failures, XSS into Injection; new A04 Insecure Design + A10 SSRF), with a 2025-draft note.
+- Routing wired in `agents/index.md` (security routing rule + Modules list). README security-reviewer inventory line updated.
+- **Codex parity: portable** — the module is markdown read at runtime by both runtimes; the agent-body edits transpile to `.codex/agents/security-reviewer.toml` automatically. **No new `baldart.config.yml` key** → the schema-change propagation rule does NOT apply.
+
 ## [5.8.0] - 2026-07-06
 
 **Suggested launch plan at the end of `/prd` — waves with a NAME, persisted on the epic card.**

package/README.md

@@ -92,7 +92,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
 2. **coder**: Writes production code with build/test/lint verification + Post-Approval Complexity Gate
 3. **code-reviewer**: Reviews for bugs, security, quality, maintainability — confidence-based filtering + Findings Schema
-4. **security-reviewer**: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra
+4. **security-reviewer**: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra — boundary-gate → repo-scoped threat-model → modern high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (`security-review-protocol.md`)
 5. **doc-reviewer**: Audits and writes documentation, SSOT sync, doc debt tracking, design-system drift detection
 6. **wiki-curator**: Maintains the derived LLM wiki overlay (`docs/wiki/`) — synthesis candidates, anchor + frontmatter validation
 7. **prd**: Creates PRDs, implementation plans, and backlog cards with autonomous tech decisions

package/VERSION

@@ -1 +1 @@
-5.8.0
+5.9.0

package/framework/.claude/agents/CHANGELOG.md

@@ -7,6 +7,24 @@ per-item agent merge, the doctor probes, and the discovery hooks — like
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · per-agent SemVer.
 
+## [security-reviewer v1.0.0] — 2026-07-06 (framework v5.9.0 — AppSec state-of-the-art wave)
+
+- **First versioned entry.** Benchmarked against Codex `codex-security` (phased
+  workbench) + Claude Code `security-guidance` (agentic self-refute); imported the
+  gap as a single-sourced protocol module rather than a monolithic rewrite.
+- **New "Security Review Passes (BINDING)" block** — cites the new
+  `agents/security-review-protocol.md` with 1-line binding statements per section
+  (boundary-gate, threat-model, discovery-lens, proof-tuples, attack-path,
+  adversarial-refute, coverage-ledger). Agent-spine 3-layer: core inline + module
+  on demand. EXTENDS `review-protocol.md`, never duplicates it.
+- **Mode A pooled YAML schema extended**: `vuln_class`, `cwe: [CWE-###]`,
+  `validation_method`, structured `attack_path` block; summary header gains a
+  compact `coverage:` block. Other reviewers ignore the security-only fields.
+- **Secret-redaction BINDING** added to Behavior Rules — a leaked credential is
+  reported as first 2–4 chars + `****`, never the live value.
+- Codex parity: agent body transpiles to `.codex/agents/security-reviewer.toml`
+  automatically; the module is portable markdown. No new config key.
+
 ## [prd-card-writer v1.2.0] — 2026-07-04 (framework v5.6.0 — FEAT-0068 post-mortem)
 
 - **Epic AC rules**: mai count di figli hardcodato ("le 6 sub-card"); AC con

package/framework/.claude/agents/security-reviewer.md

@@ -4,6 +4,7 @@ description: "Use this agent when code needs a security review, when reviewing P
 model: sonnet
 color: red
 memory: project
+version: 1.0.0
 ---
 
 > **YOLO MODE**: All agents spawned via the Task tool MUST use `mode: "bypassPermissions"`. No exceptions.
@@ -73,6 +74,7 @@ file you EXPECT to match is a binary-mode trap, not evidence: re-run with `rg` (
 - NEVER hand-wave or give shallow "looks good" feedback.
 - NEVER approve insecure code because it is "probably internal".
 - NEVER recommend storing secrets in code, env files committed to git, client-side code, or logs.
+- **Secret redaction (BINDING).** When you report a leaked/hardcoded credential, NEVER write its full value — redact to the first 2–4 characters + `****`. Cite the `file:line` (the canonical source location), state what the credential grants and whether it is prod vs test, and recommend rotation if it is live. A review artifact that reproduces a live secret is itself a leak.
 - NEVER suggest disabling security controls for convenience unless explicitly discussing a temporary local-only dev workaround, clearly labeled as unsafe.
 
 ## Threat-Modeling Mindset
@@ -88,6 +90,43 @@ For every review, actively reason about:
 - Insider threat / compromised service misuse
 - Multi-tenant isolation boundaries (critical for any multi-customer platform)
 
+## Security Review Passes (BINDING — full procedure in the protocol module)
+
+These extend `review-protocol.md`'s generic passes (Challenge / Simulation /
+CoVe / risk-scoring) with the AppSec specifics. Keep the 1-line binding here;
+Read the matching section of `agents/security-review-protocol.md SECTION=<name>`
+for the procedure. Order: boundary-gate (once) → threat-model → discovery-lens →
+per candidate proof-tuples → attack-path → adversarial-refute → mechanical
+severity → coverage-ledger.
+
+- **BINDING — boundary-gate**: before confirming anything, read `SECURITY.md` /
+  deployment notes and classify the surface (`product_surface`, `source_trust`,
+  `boundary_crossed`); no boundary crossed → not a finding. `SECTION=boundary-gate`.
+- **BINDING — threat-model**: adopt or generate a REPOSITORY-scoped threat model
+  (never diff-biased); it picks your focus paths. `SECTION=threat-model`.
+- **BINDING — discovery-lens**: sweep the modern high-miss patterns (fail-open,
+  allowlist-escape, control-regression, gate/action mismatch, parser
+  differential, sensitive-to-observability, CI/CD trust, IaC omitted arg,
+  over-broad grant, stale identity, registry fanout) beyond the OWASP core.
+  `SECTION=discovery-lens`.
+- **BINDING — proof-tuples**: ground every finding in its class-specific tuple
+  (authz = path + missing guard + protected object; injection = bytes + sanitizer
+  result + sink; SSRF; deserialization; auth/token; XSS); confidence is anchored
+  to validation METHOD, not to how scary the bug class sounds; never collapse
+  independently exploitable sibling instances. `SECTION=proof-tuples`.
+- **BINDING — attack-path**: write structured attack-path facts (attacker,
+  entrypoint, preconditions, dataflow source→sink, outcome, impact×likelihood)
+  BEFORE severity, then apply severity mechanically. `SECTION=attack-path`.
+- **BINDING — adversarial-refute**: a finding SURVIVES unless refuted; test the
+  privilege boundary FIRST (attacker == victim on own machine → refute); keep
+  precondition (narrows likelihood) distinct from counterevidence (kills the
+  finding). In diff review, flag only newly-introduced/reachable surface.
+  `SECTION=adversarial-refute`.
+- **BINDING — coverage-ledger**: record a disposition for every surface in scope
+  (`reported` / `no_issue_found` / `not_applicable` / `needs_follow_up` /
+  `deferred`) so a clean verdict is honest and a gap is never silent; zero
+  findings on a fully-covered surface is a legitimate outcome. `SECTION=coverage-ledger`.
+
 ## Review Methodology
 
 For each file, code block, PR, or diff you review:
@@ -129,18 +168,27 @@ determine as `N/A` rather than dropping the finding):
   title: <one-line>
   source: security-reviewer
   category: security
+  vuln_class: <concrete class, e.g. "Authorization bypass / IDOR" — never a generic "security finding">
+  cwe: [<CWE-###>, ...]         # e.g. [CWE-22, CWE-434]; [] if none maps cleanly
   target: <one of the orchestrator's TARGET TAG values, or "notes" for informational>
   severity: BLOCKER | HIGH | MEDIUM | LOW
-  confidence: 0-100
+  confidence: 0-100             # anchored to validation_method (proof-tuples), not to the bug class
   evidence:
     file: <path or "N/A">
     lines: <range or "N/A">
     quote: |
       <exact code snippet, ≤8 lines>
   cove_verified: true | false   # true if you verified file/line via Glob/Grep/Read
+  validation_method: <poc | test | debugger | interface-repro | static-trace | code-understanding>
   repro_steps: <exploitation scenario — how an attacker reaches and triggers this>
   expected_behavior: <the secure behavior>
   actual_behavior: <the vulnerable behavior present in the code>
+  attack_path:                  # structured facts → severity falls out mechanically
+    attacker: <who, trust level, from where>
+    entrypoint: <exact reachable entry — route/RPC/CLI/webhook/MCP tool>
+    preconditions: <conditions required; "none" if unconditional>
+    dataflow: <source → sink, one line>
+    outcome: <concrete impact — data read/written, code executed, tenant crossed>
   risk:
     impact: 1-5
     likelihood: 1-5
@@ -148,6 +196,10 @@ determine as `N/A` rather than dropping the finding):
   recommendation: <concrete, minimal, production-ready fix; ≤3 sentences>
 ```
 
+The `# Security Review Summary` header that follows the YAML list carries a
+compact `coverage:` block (surfaces + dispositions per `SECTION=coverage-ledger`)
+so the orchestrator can tell a clean verdict from an incomplete one.
+
 Map your severity labels to the pooled enum: Critical → `BLOCKER`, High → `HIGH`, Medium →
 `MEDIUM`, Low/Informational → `LOW`. Follow the YAML list with a 3–4 line plain-text
 `# Security Review Summary` (scope / overall risk / main attack surfaces / most critical concern) so

package/framework/agents/index.md

@@ -37,7 +37,7 @@ Route agents to the right module with minimal reading.
 - If touching terminology or naming -> read `agents/coding-standards.md`.
 - If touching env vars or scripts -> read `agents/runbook.md` and `agents/env-reference.md`.
 - If touching operational procedures (backup, cleanup, secrets) -> read `docs/operations/` if it exists in your project.
-- If touching security or auth risk -> read `agents/security.md`.
+- If touching security or auth risk -> read `agents/security.md` (OWASP 2021 posture + secure-defaults). If performing a dedicated AppSec review (the `security-reviewer` agent, `/codexreview` security pass) -> also read `agents/security-review-protocol.md` (the matching `SECTION=` only): boundary-gate → repo-scoped threat-model → high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (attacker≠victim) → coverage-ledger. It EXTENDS `review-protocol.md` (generic passes), never duplicates it.
 - If touching performance limits or scaling -> read `agents/performance.md`.
 - If touching monitoring/logging -> read `agents/observability.md`.
 - If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
@@ -86,6 +86,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/runtime-portability-protocol.md` — Runtime-mechanics binding: the abstract-operation ↔ Claude/Codex map (spawn / permissions / workflow-accel / state-spine / decision-gate / read-write path / adversarial-vs-cross-model), detect-once capability contract; cited by `/new` + `/prd`. The runtime-mechanics twin of `effort-protocol.md` + `return-contract-protocol.md` (since the Codex-parity S4 wave)
 - `agents/agent-operating-protocol.md` — Shared operating procedures for the core agents (injection guard, doc-retrieval consumption, persistent-memory hygiene, tool-budget discipline), `SECTION=` dispatch, read only the matching section; agents keep 1-line binding versions inline (since v5.0.0)
 - `agents/review-protocol.md` — The shared verification engine for reviewers: Challenge + Actionability, Simulation (diff-walk / plan-walk), Chain-of-Verification, quantified risk scoring + absolute severity calibration, specialist-spawn discipline incl. orchestrated-mode `specialist_dispatch` suppression; `SECTION=` dispatch (since v5.0.0)
+- `agents/security-review-protocol.md` — The AppSec verification engine for `security-reviewer`: boundary-gate, repository-scoped threat-model, modern high-miss discovery-lens (fail-open / allowlist-escape / control-regression / gate-action mismatch / parser differential / CI-CD trust / IaC omitted arg / over-broad grant), class-specific proof-tuples (method-anchored confidence, instance-preserving), structured attack-path → mechanical severity, adversarial-refute (attacker≠victim, precondition vs counterevidence), coverage-ledger; `SECTION=` dispatch. EXTENDS `review-protocol.md`, never duplicates it. Portable Claude+Codex (since v5.9.0)
 - `agents/doc-audit-protocol.md` — doc-reviewer's audit-mode procedures (drift validator suite, topological generation, epistemic metadata, SCIP anchors, schema/registry drift, coverage gauges); read ONLY when invoked without card context; `SECTION=` dispatch (since v5.0.0)
 - `agents/research-protocol.md` — Research discipline: `PROFILE=<decision|deep|compare|regulatory>` output contracts (+ `DEPTH=` iterative loop), the research library (`paths.research_dir` — layout, report frontmatter, INDEX, archive-not-delete), the reuse pre-flight (`FULL_REUSE`/`DELTA`/`NEW` + per-category TTLs), and the versioned source matrix with its growth loop (`SOURCE_MATRIX_CANDIDATE`); `SECTION=` dispatch. The research-side sibling of `analysis-profiles.md` (since v5.1.0)
 

package/framework/agents/security-review-protocol.md

@@ -0,0 +1,233 @@
+# Security Review Protocol — the AppSec verification engine
+
+**Purpose**: the security-specific passes that turn a generic code review into
+an adversarial AppSec audit — repository-scoped threat modeling, the modern
+high-miss discovery lens, class-specific proof tuples, structured attack-path →
+mechanical severity, adversarial self-refutation (attacker vs victim), and a
+coverage ledger so *"not observed" never reads as "not reviewed"*. Distilled
+from the Codex `codex-security` workbench + the Claude Code `security-guidance`
+agentic reviewer. This module is the **single SSOT** of that methodology.
+
+**Relationship to `review-protocol.md`**: that module owns the GENERIC verifier
+passes (Challenge, Actionability, Simulation, Chain-of-Verification, risk
+scoring). This module **extends**, never duplicates them: `adversarial-refute`
+is the security-specialized layer that runs *inside* the generic Challenge pass;
+`proof-tuples` is the security grounding for the generic CoVe pass. On the
+generic passes, `review-protocol.md` wins; on AppSec specifics, this module
+wins.
+
+**Consumer**: `security-reviewer` (body citations). Portable as-is across Claude
+Code and Codex (read at runtime by both).
+
+## Contract
+
+- **Dispatch**: cite `agents/security-review-protocol.md SECTION=<threat-model|discovery-lens|proof-tuples|attack-path|adversarial-refute|coverage-ledger|boundary-gate>`.
+  Grep for `### SECTION: <name>` and Read ONLY that section.
+- **Order of passes** (normative): `boundary-gate` (once, at kickoff) →
+  `threat-model` (adopt or generate) → discovery under the `discovery-lens` →
+  per candidate: `proof-tuples` (validation) → `attack-path` (structured facts)
+  → `adversarial-refute` → mechanical severity (`review-protocol.md
+  SECTION=risk-scoring`) → `coverage-ledger` close. The generic Challenge + CoVe
+  passes still run; the security passes feed them.
+- **Degrade-safe**: skipping a pass means less rigor, never a malformed report —
+  the report/YAML shape stays defined in the agent body.
+
+---
+
+### SECTION: boundary-gate
+
+Run ONCE before confirming any finding. A vulnerability only exists when an
+attacker crosses a trust boundary of a **shipped/deployed** surface — so
+classify the surface first, or you will flag same-privilege local code as a
+"vuln".
+
+1. **Read the repo's own policy FIRST**: `SECURITY.md`, `AGENTS.md` deployment
+   notes, package metadata. They define which surfaces are in-scope and what the
+   supported threat model is. A finding that contradicts a documented,
+   intentional design is a policy question, not a confirmed vuln.
+2. **Classify the surface under review**:
+   - `product_surface`: hosted service | library API | CLI | local dev UI |
+     MCP/tooling | example/demo | test | docs | generated | vendored.
+   - `source_trust` of the input: untrusted (remote/attacker) |
+     trusted_operator | trusted_developer_config | local_only |
+     intentional_code_execution.
+   - `boundary_crossed`: does attacker-controlled input reach the sink across a
+     real privilege/trust boundary? true | false | unknown.
+3. **Gate**: no boundary crossed (attacker == victim, same privilege, local dev
+   tool with no request handler) → NOT a finding. Record the disposition in the
+   coverage ledger, do not emit it as LOW.
+
+### SECTION: threat-model
+
+Establish (or adopt) a **repository-scoped** threat model — deliberately NOT
+biased by the current diff, so it stays valid for any change in the same repo.
+
+- **Adopt** an existing model from the user, `SECURITY.md`, or `AGENTS.md` when
+  present. Only **generate** a fallback when none exists.
+- Fallback generation, repository-level (not diff-scoped):
+  1. Real-world purpose + primary product/runtime surfaces actually exposed
+     (separate them from test/demo/tooling/docs paths).
+  2. Trust boundaries + the actors on each side; separate **attacker-controlled**
+     vs **operator-controlled** vs **developer-controlled** inputs explicitly.
+  3. Sensitive assets: user data, auth artifacts, authorization state,
+     secrets/keys, config, models/weights, audit logs, availability-critical
+     resources, tenant-isolation state.
+  4. Vulnerability CLASSES relevant to this repo's context (not the diff's
+     findings) + existing mitigations grounded in real files.
+  5. When realistic vs out-of-scope: state attacker (non-)capabilities so
+     severity is not inflated.
+- Use it to pick **focus paths** for the review; do not let the diff recenter it
+  unless the user asks for a diff-scoped model.
+
+### SECTION: discovery-lens
+
+Beyond the OWASP core checklist (in the agent body), sweep for the **modern
+high-miss patterns** — the ones a generic checklist walks past. For each changed
+region, ask:
+
+- **FAIL-OPEN state drift**: a default that *allows* on the unknown/error path —
+  catch-all `default: allow`, `unwrap_or({})`, a removed `finally` that left the
+  deny, an early-return before the check. Security must fail *closed*.
+- **ALLOWLIST semantic escape**: a matcher weakened — a `||`/disjunction added, a
+  regex left unanchored (`^…$` missing), an allowlist checked by `startsWith`/
+  substring, a URL trusted by substring instead of parsed host.
+- **CONTROL regression**: a deny-by-default replaced by a single positive
+  condition; an authz/confirm/audit control loosened or removed in the diff.
+- **GATE / ACTION field mismatch**: the gate checks resource A (parent, id X) but
+  the action writes/reads resource B (child, id Y) — the check and the effect
+  disagree.
+- **UNDER-VALIDATED sink arg**: user data flows into sink arg *X* while a sibling
+  path validates arg *Y* — asymmetry between siblings is the tell.
+- **PARSER/VALIDATOR differential**: the validator and the consumer parse the
+  input differently (two URL parsers, JSON vs form, unicode/normalization) — the
+  gap is the exploit.
+- **SENSITIVE-to-observability**: secrets/tokens/PII reaching logs, traces,
+  error responses, analytics, crash dumps.
+- **CI/CD trust**: `pull_request_target` / `workflow_dispatch` / injectable
+  `${{ github.event.*.body }}` combined with secrets or repo-write; a workflow
+  running untrusted code with elevated tokens.
+- **IaC omitted arg**: a Terraform/CDK/K8s resource missing a security flag
+  (public bucket, open SG, no encryption, over-broad IAM `*`).
+- **OVER-BROAD grant**: an admin/`*` role/scope where a narrower one exists;
+  new IAM/RLS/role wider than the action needs.
+- **STALE identity mapping**: a window between unregister/rotate and the new
+  binding where the old identity still resolves.
+- **SECURITY-REGISTRY fanout**: a new entity type (model, scope, route, event)
+  added but missing from the sanitizer/allowlist/authz registries that must
+  enumerate it.
+- **RESOURCE-bound placement**: a cap/limit on the wrong accumulator; an
+  under/overflow; a size check after the allocation.
+
+### SECTION: proof-tuples
+
+A security finding is a *hypothesis* until its **class-specific proof tuple** is
+grounded against real code (this is the AppSec form of the CoVe pass). Confirm
+every element by grep/read before emitting; drop the finding if any element is
+missing.
+
+- **authz / IDOR**: attacker reachability path + the missing/bypassed guard + the
+  protected object or state it exposes.
+- **injection** (SQL/NoSQL/OS/LDAP/template): attacker-controlled bytes + the
+  sanitizer/parameterization result (or its absence) + the dangerous sink.
+- **deserialization**: attacker serialized input + the unsafe loader + the
+  execution/instantiation effect.
+- **SSRF / open redirect**: attacker-controlled destination + the control bypass
+  + the network reach / side effect.
+- **auth / token**: attacker-supplied value + the validator's exact semantics +
+  the mismatch with the trusted value.
+- **XSS**: attacker string + the encoding/escaping context at output + the sink
+  (`innerHTML`/`dangerouslySetInnerHTML`/template) with no encode.
+
+**Confidence anchored to validation METHOD, never to how scary the bug class
+sounds**:
+- reproduced PoC / failing test that triggers the sink → confidence 90–100.
+- debugger/trace or a proven interface reproduction → 75–90.
+- static source→sink trace fully grounded in read code → 60–80.
+- code-understanding argument with a defensible but not fully-traced path →
+  30–55. Below that, it is a hypothesis — do not ship as HIGH.
+
+**Instance-preserving**: do NOT collapse independently exploitable sibling
+instances (`execute` / `executemany` / `executescript`; two routes with the same
+flaw) into one finding. Each independently triggerable sink gets its own
+finding/closure row.
+
+### SECTION: attack-path
+
+BEFORE assigning severity, write the attack path as **structured facts**, then
+let severity fall out of them mechanically (`review-protocol.md
+SECTION=risk-scoring`) — this stops severity from being argued emotionally.
+
+- `attacker`: who, at what trust level, from where.
+- `entrypoint`: the exact reachable entry (route/RPC/CLI/webhook/MCP tool).
+- `preconditions`: conditions that must hold for the exploit (feature flag on,
+  authenticated user, specific config). A **precondition** narrows likelihood but
+  does NOT refute — keep it distinct from counterevidence (which kills the
+  finding, see `adversarial-refute`).
+- `dataflow`: source → sink in one line.
+- `outcome`: the concrete impact (data read/written, code executed, tenant
+  crossed).
+- `impact` (1–5) and `likelihood` (1–5), each with one line of repo evidence.
+
+Severity is then `review-protocol.md SECTION=risk-scoring` applied to
+`impact × likelihood` — do not re-argue it afterward.
+
+### SECTION: adversarial-refute
+
+The security-specialized layer of the generic Challenge pass. Stance: **a finding
+SURVIVES unless you produce concrete refuting evidence** — but the single most
+common false positive is a **missing privilege boundary**, so test that first.
+
+**Privilege-boundary test (BINDING)**: name the attacker (who controls the input)
+and the victim (who is harmed). If attacker == victim operating on their own
+machine / same-privilege process (a CLI arg in a same-trust process, a dev
+script, a local tool with no remote entrypoint) → **REFUTE**. Keep it only when
+the attacker is a lower-trust actor and the impact reaches other users, tenants,
+or infrastructure.
+
+**Refute the finding when**:
+- it is **pre-existing** code untouched by the diff (in diff-scoped review, flag
+  only newly introduced or newly reachable surface; an off-diff finding must name
+  the specific `+`/`-` line that enables the sink).
+- a sanitizer / validator / parameterization / authz check on the real path
+  already prevents the exploit.
+- the sink is not actually dangerous here (typed-schema decoder, hardcoded
+  `https` URL, ORM/parameterized query, non-HTML context for an "XSS").
+- a frontend-only gate is independently enforced by the backend (or vice-versa).
+- validation is delegated to a caller/framework that provably runs it.
+- it is throwaway/dev-only code (`scripts/`, `dev/`, `__main__`, fixtures, tests)
+  with no shipped surface.
+- a dependency bump moved the control into the library (documented).
+
+**Precondition vs counterevidence (keep precise)**: "deployment is internal-only"
+is a *precondition* on the finding (still exploitable if it holds) → keep, lower
+likelihood. "the code is test-only" is *counterevidence* → refute. Do not confuse
+the two.
+
+**Never-refute guard**: an item the agent's never-demote list marks (auth bypass,
+RCE, secret exposure, cross-tenant breach with a grounded proof tuple) is never a
+false positive — do not refute it however convincing the argument sounds.
+
+Record refuted candidates (title + one-line refutation) so the audit trail shows
+they were considered, not missed.
+
+### SECTION: coverage-ledger
+
+Make the review's *coverage* explicit so a clean verdict is honest and a gap is
+never silent. For each security-relevant surface in scope, record a disposition:
+
+- `reported` — a finding was emitted.
+- `no_issue_found` — reviewed, no credible issue survived the passes.
+- `not_applicable` — the class does not apply to this surface (with the reason).
+- `needs_follow_up` — a real concern out of this review's scope/ownership
+  (surfaces as residual).
+- `deferred` — could not complete (tool/access/time), with the reason + paths.
+
+Rules:
+- A **complete** review has zero `deferred` / `needs_follow_up` rows; otherwise
+  it is **partial** — say so. Zero findings on a fully-covered surface is a
+  legitimate, reportable outcome.
+- A seeded obligation (a CVE/advisory/user pointer at a specific file/function)
+  stays OPEN until its exact row is closed as reported / not_applicable /
+  deferred — a neighboring same-family finding does not close it.
+- In the pooled YAML mode, carry this as a compact `coverage:` block in the
+  `# Security Review Summary` header, not as fake LOW findings.

package/framework/agents/security.md

@@ -55,72 +55,76 @@ Document security requirements, threats, and mitigation strategies.
 - [Sensitive data masking in logs]
 - [Secrets management]
 
-## Common Vulnerabilities (OWASP Top 10)
+## Common Vulnerabilities (OWASP Top 10 — 2021)
 
-### Injection Attacks
+> Modernized to the OWASP Top 10:2021 categories (the 2017 list — with XXE and
+> "Sensitive Data Exposure" as standalone entries — is superseded). XXE now folds
+> into Security Misconfiguration; insecure deserialization into Software & Data
+> Integrity Failures; XSS into Injection. A 2025 revision is in draft — revisit
+> when it is finalized (expected consolidation of supply-chain risks).
 
-- Use parameterized queries
-- Validate and sanitize inputs
-- Implement least privilege database access
+### A01 Broken Access Control
 
-### Broken Authentication
+- Enforce authorization on every request, server-side; deny by default
+- Prevent IDOR — never trust a user-supplied record/object identifier
+- Enforce ownership + tenant isolation on every sensitive action
+- Principle of least privilege; no privilege escalation via business logic
 
-- Implement secure session management
-- Use strong password policies
-- Implement account lockout
-- Protect against brute force
+### A02 Cryptographic Failures
 
-### Sensitive Data Exposure
+- Encrypt sensitive data at rest and in transit (HTTPS/TLS everywhere)
+- Use strong, modern algorithms (no MD5/SHA1 for security, no AES-ECB, no static IV)
+- Proper key management + rotation; never log secrets or PII
+- Strong password hashing (argon2/bcrypt/scrypt) with per-user salt
 
-- Encrypt sensitive data
-- Use HTTPS everywhere
-- Don't log sensitive information
-- Implement secure key management
+### A03 Injection (incl. XSS)
 
-### XML External Entities (XXE)
+- Parameterized queries / ORM; never build queries by string concatenation
+- Validate + sanitize inputs; allowlists over denylists
+- Least-privilege database access
+- Output encoding at the right context + Content Security Policy for XSS
 
-- Disable XML external entity processing
-- Use safe XML parsers
-- Validate XML inputs
+### A04 Insecure Design
 
-### Broken Access Control
+- Threat-model the feature before building; secure-by-default patterns
+- Establish trust boundaries and enforce them; fail closed
+- Rate limits, resource bounds, and abuse cases considered up front
 
-- Implement proper authorization
-- Validate permissions on every request
-- Use principle of least privilege
+### A05 Security Misconfiguration (incl. XXE)
 
-### Security Misconfiguration
+- Harden defaults; remove unnecessary features/debug endpoints in prod
+- Set security headers; keep software updated
+- Disable XML external-entity processing; use safe parsers/validators
 
-- Harden default configurations
-- Keep software updated
-- Remove unnecessary features
-- Implement security headers
+### A06 Vulnerable & Outdated Components
 
-### Cross-Site Scripting (XSS)
+- Keep dependencies patched; monitor security advisories (CVE/GHSA)
+- Run dependency + vulnerability scanning in CI (e.g. audit / govulncheck)
+- Remove unused dependencies and features
 
-- Escape output
-- Use Content Security Policy
-- Validate and sanitize inputs
-- Use framework protections
+### A07 Identification & Authentication Failures
 
-### Insecure Deserialization
+- Secure session management (rotation, expiry, secure cookies)
+- Strong password policy, account lockout / brute-force protection, MFA where applicable
+- No session fixation, no token leakage in URLs/logs
 
-- Validate serialized data
-- Use safe deserialization libraries
-- Implement integrity checks
+### A08 Software & Data Integrity Failures (incl. insecure deserialization)
 
-### Using Components with Known Vulnerabilities
+- Never deserialize untrusted data with unsafe loaders; validate + integrity-check
+- Verify integrity of updates/CI artifacts (signatures, SRI, pinned digests)
+- Guard the CI/CD supply chain — no untrusted code with elevated tokens
 
-- Keep dependencies updated
-- Monitor security advisories
-- Use dependency scanning tools
+### A09 Security Logging & Monitoring Failures
 
-### Insufficient Logging & Monitoring
+- Log security events; monitor for suspicious activity; alert
+- Protect log integrity; never log secrets/PII
+- Ensure exploitation attempts are detectable and auditable
 
-- Log security events
-- Monitor for suspicious activity
-- Implement alerting
-- Protect log integrity
+### A10 Server-Side Request Forgery (SSRF)
+
+- Validate + allowlist outbound destinations; parse (don't substring) URLs
+- Block internal metadata endpoints and private ranges
+- Enforce egress controls; treat any user-supplied URL/host as hostile
 
 ## Rate Limiting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"