Skip to content

Commit c1c8a8c

Browse files
committed
Clarify guidance and full audit modes
1 parent d24bc26 commit c1c8a8c

3 files changed

Lines changed: 43 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ find security vulnerabilities in ./src
8181
do a security review, output to ~/audits/my-project
8282
```
8383

84-
The skill activates automatically when the request matches its trigger (security audit, find vulnerabilities, pen-test the code, etc.). If you do not specify an output directory, it uses `~/security-audit-skill/<repo-name>/run-<N>`. It writes inside the target repository only when you explicitly select a directory that version control ignores.
84+
The skill activates automatically when the request matches its trigger (security audit, find vulnerabilities, pen-test the code, etc.). A direct codebase audit or pen-test request uses full audit mode. Security questions and focused vulnerability work use guidance mode unless you request report artifacts. In full audit mode, an unspecified output directory defaults to `~/security-audit-skill/<repo-name>/run-<N>`. The workflow writes inside the target repository only when you explicitly select a directory that version control ignores.
8585

8686
## Requirements
8787

‎skills/security-audit/HUNTING.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ message brokers, shared services, or other users. Use local dummy data only.
3737
READ THE CODE AT DEPTH. Follow each assigned input through parsing, identity,
3838
authorization, normalization, state, derived copies, and the final sink. Read sibling,
3939
legacy, batch, retry, cancellation, migration, and error paths that produce the same
40-
effect. Compare what one component guarantees with what the next component assumes.
40+
effect. Compare sibling controls for equivalence, not only presence, and compare what
41+
one component guarantees with what the next component assumes.
4142
4243
WORK FROM A CONCRETE INVARIANT:
4344
1. Name the lower-trust principal and starting capability.
@@ -61,6 +62,12 @@ accepts them. Compare canonicalization and units at every parser or policy hando
6162
For multi-step issues, treat each output as a prerequisite and do not assume a later
6263
boundary. If any prerequisite is not established, record a blocker.
6364
65+
When a proposed high or critical candidate reveals a reusable root cause, search paths
66+
owned by the assigned coverage IDs for lexical, structural, and logical variants.
67+
Consolidate the same root cause, but establish each variant's conditions and impact
68+
independently. Do not investigate peer-owned units. Return a variant with no current
69+
coverage unit as `uncovered`.
70+
6471
USE THE NARROWEST LOCAL CHECK THAT SETTLES THE CLAIM. Target-controlled builds,
6572
tests, processes, browsers, emulators, fuzzers, and fixture processing may run only
6673
inside the parent-approved OS-enforced sandbox. It must disable external networking,

‎skills/security-audit/SKILL.md‎

Lines changed: 34 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
11
---
22
name: security-audit
3-
description: Finds, validates, prioritizes, and describes fixes for source-grounded vulnerabilities in a codebase. Use when the user asks for a security audit, security review, or pen test of code, or to find vulnerabilities in web apps, APIs, services, CLI tools, libraries, or daemons.
3+
description: Security guidance and vulnerability review for codebases, APIs, services, CLI tools, libraries, and daemons. Use for security questions, focused reviews, vulnerability research, security audits, or pen tests. Run the complete workflow only for explicit codebase audit or pen-test requests, full/comprehensive/end-to-end reviews, or requested report artifacts.
44
---
55

66
# Security Audit
77

88
Find vulnerabilities that violate a real trust boundary, then give owners the source evidence, safe reproduction, priority, and smallest effective fix. This is a defensive, source-first workflow. A candidate without a concrete affected principal, resource, or security outcome is not a confirmed finding.
99

10+
## Operating modes
11+
12+
This skill is guidance by default. Loading it does not authorize the complete audit workflow or file creation.
13+
14+
- **Guidance mode**: For security questions, focused reviews, methodology, triage, or investigation of specific findings, use only the relevant parts of this skill. Do not automatically run all six phases, create an output directory, or write audit artifacts. You may launch focused agents when useful; they return results to the current task.
15+
- **Full audit mode**: Use the complete workflow when the user explicitly asks to audit or pen-test a codebase, asks for a full, comprehensive, or end-to-end security review, or requests report artifacts. Run all six phases and write the files defined below.
16+
17+
If the request could mean either mode, ask one focused question before creating files or starting the complete workflow.
18+
1019
## Platform terminology
1120

1221
This skill is agent-neutral:
@@ -19,26 +28,28 @@ This skill is agent-neutral:
1928

2029
Use equivalent platform capabilities while preserving role, write-isolation, prompt, and independence boundaries.
2130

22-
## Setup and execution boundary
23-
24-
Resolve before reconnaissance:
25-
26-
- **Skill directory**: the absolute directory containing this `SKILL.md`.
27-
- **Target**: the absolute repository root under review.
28-
- **Repo name**: a stable repository identifier from the directory or local Git remote.
29-
- **Output directory**: a new writable directory outside the target, defaulting to `~/security-audit-skill/<repo-name>/run-<N>`, where `<N>` is the next unused integer. Use a directory inside the target only when the user explicitly selects it and the parent verifies that version control ignores the whole directory. Otherwise stop and request an external path.
30-
- **Source ref**: the reviewed commit and whether the worktree is dirty. Do not treat unreviewed generated or modified files as another revision.
31+
## Universal execution safety
3132

32-
Source inspection is read-only. Run target-controlled builds, tests, processes, browsers, emulators, fuzzers, and fixture processing only inside an OS-enforced sandbox that provides all of these controls:
33+
These rules apply in both operating modes. Source inspection is read-only. Run target-controlled builds, tests, processes, browsers, emulators, fuzzers, and fixture processing only inside an OS-enforced sandbox that provides all of these controls:
3334

3435
- no external network; use only an isolated loopback namespace when the check needs local client/server traffic;
3536
- an empty environment populated from an explicit allowlist with safe values, with scratch-local `HOME`, temporary directories, and caches;
3637
- a read-only target and toolchain, with the target-controlled process able to write only inside its assigned `scratch/` directory; and
3738
- explicit low CPU, memory, process, file-size, disk, and wall-clock limits.
3839

39-
The agent, outside the target-controlled process, may make a disposable source copy in `scratch/` when a build must write beside source. Only trusted parent-side code may promote the minimum non-secret result to retained `artifacts/` using the procedure under Write isolation. Never expose the output directory (other than the agent's own assigned `scratch/`), another agent's directory, the host home directory, credentials, sockets, or shared services to target code. Do not install dependencies or let builds fetch them. Use only tools and dependencies already available locally. If every control cannot be enforced, do not execute target code: retain a `needs_validation` record with the missing sandbox capability as a blocker and a safe validation plan.
40+
The agent, outside the target-controlled process, may make a disposable source copy in an assigned `scratch/` directory when a build must write beside source. In guidance mode, do not retain target-controlled files. In full audit mode, only trusted parent-side code may promote the minimum non-secret result to retained `artifacts/` using the procedure under Write isolation. Never expose a retained output directory (other than the agent's own assigned `scratch/`), another agent's directory, the host home directory, credentials, sockets, or shared services to target code. Do not install dependencies or let builds fetch them. Use only tools and dependencies already available locally. If every control cannot be enforced, do not execute target code: report the missing sandbox capability as a needs-validation blocker and give a safe validation plan.
4041

41-
Use dummy principals, fixtures, and secrets. Do not probe deployed endpoints, external services, shared infrastructure, production identities, other users' data, or live control planes. Do not test availability against a live or shared process, publish artifacts, alter releases, spend paid API quota, or continue beyond the minimum local effect needed to establish a defect. If the decisive fact is outside source or the sandboxed fixture, retain a `needs_validation` record.
42+
Use dummy principals, fixtures, and secrets. Do not probe deployed endpoints, external services, shared infrastructure, production identities, other users' data, or live control planes. Do not test availability against a live or shared process, publish artifacts, alter releases, spend paid API quota, or continue beyond the minimum local effect needed to establish a defect. If the decisive fact is outside source or the sandboxed fixture, report it as needing validation.
43+
44+
## Full audit setup
45+
46+
In full audit mode, resolve these values before reconnaissance:
47+
48+
- **Skill directory**: the absolute directory containing this `SKILL.md`.
49+
- **Target**: the absolute repository root under review.
50+
- **Repo name**: a stable repository identifier from the directory or local Git remote.
51+
- **Output directory**: a new writable directory outside the target, defaulting to `~/security-audit-skill/<repo-name>/run-<N>`, where `<N>` is the next unused integer. Use a directory inside the target only when the user explicitly selects it and the parent verifies that version control ignores the whole directory. Otherwise stop and request an external path.
52+
- **Source ref**: the reviewed commit and whether the worktree is dirty. Do not treat unreviewed generated or modified files as another revision.
4253

4354
### Write isolation
4455

@@ -74,7 +85,11 @@ For a reproduced check, record the command, exact test input, sandbox limits, an
7485

7586
Before delegation, the parent writes `run-metadata.json` with at least `run_id`, `repo`, `target`, `source_ref`, `profile`, `scope_paths`, `budget` (null if unset), `execution_policy: "sandboxed-source-and-local-only"`, selected companion files, prior-run paths, shared-file owners, and `run_status: "in_progress"`. Update metadata only when those facts change; candidate state belongs in the coverage ledger and `findings.json`.
7687

77-
## Coverage and prior runs
88+
## Full audit planning
89+
90+
The coverage, prior-run, profile, and budget requirements in this section apply only in full audit mode.
91+
92+
### Coverage and prior runs
7893

7994
No one pass is complete. Build a deterministic coverage plan before hunting and update it after every agent result. [RECONNAISSANCE.md](RECONNAISSANCE.md) defines the stable coverage units and [HUNTING.md](HUNTING.md) defines coverage-critic waves. The parent alone updates the ledger.
8095

@@ -89,9 +104,9 @@ If prior runs exist, read every compatible `coverage-ledger.json` and `findings.
89104

90105
If no prior ledger exists, say so in the final coverage statement. Never imply that one run exhausts the target.
91106

92-
## Run profiles and scope
107+
### Run profiles and scope
93108

94-
Pick a profile during Setup — from the user's request, or by proposing one from the target's size and stakes — and record it in `run-metadata.json` (`profile`, `scope_paths`). State both in the report. The default is `standard`.
109+
During full audit setup, pick a profile from the user's request or propose one from the target's size and stakes. Record it in `run-metadata.json` (`profile`, `scope_paths`) and state it in the report. The default is `standard`.
95110

96111
- **`quick`** — a bounded pass for small targets, re-runs, or a fast first look. Coarsen ledger units to surface × boundary × attack class (subsystem uses the fixed canonical `profile/quick/all-in-scope-subsystems` identifier), run exactly one hunter wave followed by exactly one final coverage-critic pass, and use one fresh verifier per candidate for both candidate validation and final record verification. Do not launch a follow-up hunter wave: record the critic's accepted discoveries and reassignments as `deferred`.
97112
- **`standard`** — the workflow as written.
@@ -101,7 +116,7 @@ A **scoped run** audits a subset: named paths, one subsystem, one companion doma
101116

102117
Profiles change breadth and redundancy, never the evidence bar. Do not scale away the candidate gate, the source/local execution boundary, `needs_validation` discipline, schema validation, or independent verification of `confirmed` records.
103118

104-
### Cost budget
119+
#### Cost budget
105120

106121
The ledger makes spend countable: one unit is roughly one hunter assignment, and one surviving candidate is one or two verifier assignments depending on profile. When the user sets a budget — or the parent proposes one for a large target — record `budget` in `run-metadata.json` as a maximum number of agent invocations across all phases.
107122

@@ -150,9 +165,9 @@ The high/medium discriminator: does the demonstrated result fully defeat an expl
150165

151166
For each confirmed finding, identify the invariant the code must enforce and the narrowest source change that enforces it at the last trusted decision point. Prefer specific repository-relative changes and regression tests over generic hardening advice. The audit describes fixes; it does not modify target source.
152167

153-
## Workflow overview
168+
## Full audit workflow
154169

155-
Follow all six phases in order:
170+
In full audit mode, follow all six phases in order:
156171

157172
1. **Reconnaissance** — map the source, trust boundaries, local build paths, companion selections, prior evidence, and initial deterministic coverage ledger with [RECONNAISSANCE.md](RECONNAISSANCE.md).
158173
2. **Coverage-led hunting waves** — assign isolated hunters from the ledger and collect structured candidate results with [HUNTING.md](HUNTING.md), [ATTACK-CLASSES.md](ATTACK-CLASSES.md), and the selected domain companions.

0 commit comments

Comments
 (0)