River Review Security Audit

Security Audit Entry

Inspired by Cloudflare's security-audit-skill, but implemented as a River Review-native entry skill rather than a vendored audit engine.

This skill is the explicit entry point for repository or subsystem security audit work. It does not replace river-review-security, the normal diff-oriented security review entry.

When to Use

Use this skill only when the user explicitly asks for a security audit beyond an ordinary PR review. Typical requests include repository-wide security audit, subsystem security audit, security assessment, or a bounded source review of a security-sensitive surface.

Do not select this skill for a generic request such as "review this PR for security". Route that request to river-review-security.

Modes

Select exactly one mode before reviewing.

• guidance: use when the user wants methodology, planning, or an audit approach. Explain the method and constraints. Do not claim that audit work was executed.
• focused: use when the user names a bounded subsystem, path, component, or security surface. Freeze that scope and review only source evidence inside the boundary.
• full-audit: use only when the user explicitly requests repository-wide audit coverage. Perform repository reconnaissance and source review across the repository. Semantic coverage is observe-only and never a safety guarantee.

If the request does not clearly justify full-audit, use focused or guidance.

Non-negotiable Source-only Policy

Version 0.5.0 is source-only.

Allowed evidence collection:

• file reads
• repository code search
• static diff inspection
• repository metadata and dependency manifests
• configuration and documentation inspection
• static history inspection when it supports source provenance

Prohibited execution:

• package installation or dependency fetching
• target repository build scripts
• target repository test commands
• package lifecycle scripts
• dev servers or application startup
• browsers or emulators that execute target code
• fuzzing or dynamic probes
• requests to production, shared, or external endpoints
• use of ambient credentials to reproduce a finding

If runtime evidence is required but safe execution is unavailable, keep the hypothesis unresolved. Record the blocker and the minimum validation plan instead of executing target-controlled code.

Responsibilities

This skill performs entry-level audit coordination only. It must reuse existing River Review capabilities instead of creating a second workflow engine.

Explicit audit request
  -> mode selection
  -> scope freeze
  -> source reconnaissance
  -> attack-class planning
  -> existing security skills
  -> candidate findings / unresolved hypotheses
  -> existing finding verification path when available
  -> observe-only SecurityAuditCoverage ledger
  -> unknown-coverage-review (security-audit profile)
  -> repeat-run coverage reconciliation (when a prior run exists)
  -> structured audit artifact set
  -> audit summary

The following responsibilities remain outside this skill:

• generic reviewer fan-out: existing reviewer orchestration
• ordinary PR security review: river-review-security
• deterministic finding verification: existing verifier
• adversarial candidate state machine: #1978 / finding-critic.mjs
• execution coverage: #2212 Review Coverage
• materiality and disposition: #1857 Semantic Precision
• final Gate decision: existing deterministic Gate
• independent final-record verification: later #2267 phase
• sandboxed target execution: later dedicated phase

Audit Flow

1. Select mode and freeze scope

State the selected mode and the audit boundary before collecting findings. For focused, name the bounded path, subsystem, component, or trust boundary. For full-audit, state that the scope is repository-wide and source-only.

Do not silently broaden a focused audit into a repository-wide audit.

2. Reconnaissance from source only

Build a compact source map before hunting for issues. At minimum identify, when present:

• externally reachable entry points
• authentication and authorization boundaries
• tenant or account boundaries
• sensitive data stores and flows
• privileged operations
• external integrations
• dependency and deployment configuration surfaces
• browser or client trust boundaries
• AI or agent tool boundaries

Reconnaissance is an investigation plan, not proof of safety.

3. Plan applicable attack classes

Use references/attack-classes.json as the taxonomy SSoT for audit planning. Select only classes supported by reconnaissance evidence; do not run all classes mechanically. For every applicable class, preserve the registry evidence contract:

principal
  -> input or action
  -> control or missing control
  -> trust boundary
  -> affected resource or principal
  -> concrete security outcome

An attack class is an investigation hypothesis, not a checklist completion badge. A class with zero findings is not automatically covered, and a non-applicable class must be explained rather than silently omitted.

4. Reuse existing security skills

Use existing River Review skills when their domain applies.

• security-basic: application security patterns such as injection, unsafe sinks, secrets, validation, and common application risks.
• security-privacy-design: privacy and sensitive-data design such as retention, deletion, encryption, residency, and privacy rights.
• trust-boundaries-authz: trust boundaries and authorization responsibilities, claims propagation, and tenant boundaries.
• river-review-security: ordinary changed-code security review. Use only when the task is actually diff-oriented rather than an audit.
• adversarial-review: optional complementary attack-path exploration. It is not a finding verifier.

Do not duplicate the guidance of these skills inside this entry skill.

5. Treat findings as evidence-grounded candidates

Every reported candidate must identify concrete source evidence. Require enough information to answer:

principal
  -> input or action
  -> control or missing control
  -> trust boundary
  -> affected resource or principal
  -> concrete security outcome

A missing best practice is not automatically a vulnerability. A candidate without a concrete boundary failure or security outcome remains an open question or unresolved hypothesis.

6. Preserve verification boundaries

This entry skill does not claim independent adversarial verification unless the existing #1978 path actually ran with an independent verifier.

If only source review ran, report the result as candidate-level evidence. Do not relabel reviewer agreement as correctness. Do not introduce a new validation enum in this skill.

7. Record unresolved hypotheses explicitly

For every unresolved hypothesis, provide:

• source evidence already inspected
• the exact missing fact or runtime condition
• why source evidence is insufficient
• the minimum safe validation step
• whether the blocker is caused by the source-only policy

Do not assign severity solely from an unresolved runtime assumption.

8. Record observe-only SecurityAuditCoverage

Use schemas/security-audit-coverage.schema.json and src/lib/security-audit-coverage.mjs as the semantic coverage contract. The unit is:

subsystem × trustBoundary × attackClassId

Use only the closed unit state vocabulary:

planned | covered | blocked | deferred | out_of_scope

Rules:

• covered requires traceable reviewedPaths and structured evidenceRefs.
• finding lifecycle is separate; relatedFindingIds is traceability only and never determines coverage state.
• blocked and deferred require an explanation plus a concrete validation plan.
• out_of_scope requires an explicit reason and explanation.
• zero findings alone never produces covered.
• reviewer execution success alone never produces covered.
• the ledger emits counters and openUnitIds, not a security-complete verdict.

Do not merge this ledger with #2212 ReviewCoverage. The Phase 3 schema/runtime validator owns shape, taxonomy, duplicate, and summary invariants.

9. Run the Security Audit Coverage Critic

Before finalizing a focused or full-audit report, invoke unknown-coverage-review with its explicit security-audit profile. Use:

• frozen audit scope
• reconnaissance evidence
• the Phase 2 attack-class registry
• the validated Phase 3 SecurityAuditCoverage ledger
• candidate findings / unresolved hypotheses when present
• draft audit summary/report prose when available

The critic evaluates evidence sufficiency only. It checks for:

1. relevant semantic surfaces missing from the ledger
2. covered claims whose evidence does not support the claimed scope
3. exclusions, blocks, or deferrals that hide material coverage gaps
4. prose that turns coverage or finding counts into an unsupported safety claim

Do not use the critic to re-run Phase 3 deterministic validation. Do not require every attack class mechanically. Do not convert critic output into a vulnerability verdict. Do not wire critic output into deterministic Gate behavior in Phase 4.

If the audit context or coverage ledger is missing, do not guess. Record that the critic could not run and keep the limitation explicit.