security-audit

# Security Audit Produce a defensible audit of the requested repository. Consistent coverage, evidence, and visible uncertainty matter more than finding counts or agreement between reviewers. This workflow cannot guarantee identical findings or the absence of vulnerabilities. ## Instructions You are the **coordinator**. Read [methodology.md](references/methodology.md) for the checks and decision rules, and [artifacts.md](references/artifacts.md) for the versioned data contract and commands. Follow these stages in order: 1. **Establish scope and provenance.** Honor the user's paths, exclusions, budget, baseline selection, and existing authorization. Default to the current repository, including application code, jobs, scripts, configuration, and dependencies. Resolve the repository root explicitly; a supplied URL alone does not authorize an external penetration test. Read applicable repository guidance. Record revision, relevant dirty state, skill/plugin versions and hashes, exposed model/reviewer/tool identities, budget, and restrictions. Use `unknown` or `not exposed` for unavailable information. Read the [plugin manifest](../../.claude-plugin/plugin.json); distinguish a file not inspected from one verified missing. This skill is versioned with the plugin. Host file-access settings are operational context: missing Claude settings or a count of deny rules neither blocks the audit nor establishes an application flaw. Default to **repository review plus practical bounded local checks**. Inspect checked-in deployment configuration and external-service integration code, but do not require live infrastructure access, vendor dashboards, service provisioning, or end-to-end production tests unless requested. State this boundary up front; never narrow an explicitly requested scope to make the status complete. 2. **Inventory attack surfaces.** Use deterministic discovery where practical, then trace registration, framework conventions, shared middleware, and dynamic paths. Create surface IDs and applicable check obligations **before** reviewing candidates. Record discovery gaps, including unsupported languages and generated code. Expand the inventory as new paths emerge; searches alone cannot establish completeness. 3. **Discover candidates.** Review assigned surface/check pairs using the methodology. Preserve every substantive candidate in the ledger, including uncertain ones. Do fresh discovery before reading prior findings when practical; record any earlier exposure. In blind evaluation, never read baselines or evaluator expectations. 4. **Verify and challenge.** Perform a separate pass that actively attempts to disprove each candidate. Trace protections and practical reachability; use bounded local reproductions where useful. Record counterevidence, assumptions, validation results, and a reasoned disposition. Independent disagreement is evidence to investigate; consensus is not proof. Keep potentially serious unresolved issues conspicuous. 5. **Assess severity and priority.** Apply the qualitative rubric to demonstrated impact and prerequisites. Record confidence separately. Consolidate duplicate root causes while retaining all entry points and materially different impacts. Hardening is separate from confirmed vulnerabilities. Artifact v1 deliberately supports no numeric security or CVSS scores, compliance percentages, or overall security grade. 6. **Reconcile previous findings.** After fresh discovery, select the latest relevant baseline or the explicitly supplied reports. Account for every prior finding with evidence or an explicit unresolved status. Absence never implies fixed. Preserve IDs across severity changes; use the legacy mapping procedure in the methodology. 7. **Validate and render.** Write matching timestamped JSON and Markdown artifacts to `<audited-repository>/docs/security/YYYY-MM-DD-HHMMSS-security-audit.{json,md}` (repository-relative, never filesystem `/docs/security`). Record timezone; avoid overwriting earlier runs. Run the supplied validator and renderer. Inspect the rendered report for unsupported claims as well as structural errors. Use the default concise reading copy: summary and contents first, findings before coverage. Keep the full ledger and commands in JSON; do not append reviewer reports or raw records to Markdown. Follow the [report guidance](references/artifacts.md#human-readable-report). Release all audit-owned reviewers before final handoff. Apply the stopping rule below before final handoff; validation passing is not completion. ## Continue until the work is done or genuinely blocked Before final handoff, revisit discovery gaps, unfinished surface/check pairs, unresolved candidates, and unfinished baseline comparisons. If an authorized, feasible check can advance any of them, perform it and update the evidence. Do not stop merely because reports were saved, validation passed, findings seem sufficient, or substantial time has elapsed. Do not invent a time budget when none was supplied. Stop when the declared obligations are satisfied, the user stops or limits the work, an actual execution limit is reached, or no remaining work can be advanced within available access and authorization. A blocked production check does not block unrelated local checks: finish those first, including source tracing when runtime tests are unavailable. Avoid repeating inconclusive checks without a new approach or evidence. Partial reports are checkpoints while feasible work remains. Preserve progress across context limits where the host permits continuation; do not ask the user to say “continue” for already authorized work. If final handoff must be partial or blocked, record for each remaining gap what was attempted, the concrete blocker or reached limit, and the next action or access needed. Explain why the audit stopped in the final reply. Keep unresolved checks visible; never mark them reviewed merely to reach `complete`. Completion means the **declared review work is finished**, not that every security question is settled. A fully traced source check is reviewed even when it finds a flaw or an optional runtime reproduction is unavailable. Keep external/vendor uncertainties as `needs_validation` candidates and open questions with next steps; they need not make a finished repository review partial. Unread in-scope code, incomplete control traces, missing inventory, or unfinished requested tests still make it partial. Use the [artifact status rules](references/artifacts.md#completion-and-follow-up); do not put findings or routine provenance notes into unfinished-work fields. ## Delegation and host portability Use at most **two live reviewers at a time** by default; smaller audits can run entirely in the coordinator. Batch related surfaces into bounded assignments, not an agent per file or finding. Exceed this cap only if the user explicitly requests more parallelism. Prefer one-shot subagents over persistent teammates. In Claude Code, use the available Agent/Task tool with `subagent_type: "ai-security:security-auditor"`; omit optional teammate names/team setup. Keep models inherited. Pass scope, surface/check IDs, stage, methodology references, artifact contract, verification candidates, budget, isolated output location, baseline restrictions, and the instruction to return once and end. The [reviewer](../../agents/security-auditor.md) reads supporting methodology, **never reinvokes this skill or delegates further**. Reviewers return structured evidence and coverage deltas, not standalone reports; the coordinator owns IDs, consolidation, severity, reconciliation, and the only final report pair. Track every audit-owned agent/task ID and assignment. On return, collect the result, merge its evidence, and check lifecycle state: a message or an idle notification is not proof of termination. For a still-running finished worker, use the host's stop/close tool (Claude Code: TaskStop); for a persistent teammate, request shutdown through its supported protocol and check acknowledgement. A one-shot worker marked done needs no extra shutdown message. Do not send thanks or status pings to finished workers: some hosts resume them on any message. Follow up only for a concrete remaining assignment. Use completion notifications or bounded waits; do not poll or wait indefinitely. If a worker stalls, retain its available evidence, stop it, and finish or reassign the unfinished checks within the cap. On cancellation, errors, and final handoff, check all audit-owned IDs and stop remaining workers and their audit-started background tasks. Never kill unrelated sessions or use broad process-name kills. Disclose a failed cleanup with the exact ID; do not claim shutdown succeeded without host confirmation. If the host cannot reliably track and finish delegated work, review sequentially in the coordinator. The same fallback applies when delegation is unavailable; preserve a distinct verification pass and identical coverage/evidence obligations. More detail on Claude's [subagents](https://code.claude.com/docs/en/sub-agents) and [teammate shutdown](https://code.claude.com/docs/en/agent-teams#shut-down-teammates). Named Read/Glob/Grep/Bash tools may be replaced by equivalent file/search/shell tools. Tool unavailability becomes a disclosed limitation, not an invented result. Without Python, follow the contract manually and disclose that machine validation was not run; do not claim a complete validated audit. ## Execution boundaries Use authorized local, bounded testing with timeouts and disposable state. Do not stress production, send real email, change live billing, or contact unrelated targets without specific authorization. Preserve source and user changes; proposed fixes are proposals until applied and tested. Do not install dependencies or use credentials merely to make a report look complete. Redact secrets and personal data from artifacts while retaining enough locations and evidence for review.