diff --git a/README.md b/README.md index c80305c..d7391df 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,11 @@ The skill runs a structured audit in six phases: 1. **Reconnaissance** -- map architecture, trust boundaries, input surfaces, prior evidence, and deterministic coverage in `architecture.md` and `coverage-ledger.json`. 2. **Coverage-led hunting** -- assign isolated hunters from ledger units, record their checks, and use coverage critics to find gaps. 3. **Candidate validation** -- give every unique candidate to a fresh verifier that tries to disprove it. -4. **Structured output** -- write `confirmed`, `needs_validation`, and `rejected` records to `findings.json` and validate them against `report-schema.json`. +4. **Structured output** -- write `confirmed`, `needs_validation`, and `rejected` records to `findings.json` and validate them against `skills/security-audit/resources/report-schema.json`. 5. **Independent record verification** -- fresh agents verify final source claims. Material replacements receive another independent verifier. 6. **Target-neutral reporting** -- derive `REPORT.md`, `FINDINGS-DETAIL.md`, and `NEEDS-VALIDATION.md` from the verified records and coverage ledger. -The parent runs `validate-coverage-ledger.cjs` after creating the ledger and after each later ledger update. It runs `validate-findings.cjs` in Phase 4 and again after every Phase 5 replacement. +The parent runs `skills/security-audit/scripts/validate-coverage-ledger.cjs` after creating the ledger and after each later ledger update. It runs `skills/security-audit/scripts/validate-findings.cjs` in Phase 4 and again after every Phase 5 replacement. The verdicts are distinct: `confirmed` has a complete source trace and bounded observed result, `needs_validation` has an exact unresolved fact and no severity, and `rejected` records a disproved candidate. @@ -25,26 +25,26 @@ Multiple runs against the same repo are additive. The skill uses prior ledgers a | File | Purpose | |------|---------| -| `SKILL.md` | Setup, core principles, platform terminology, workflow overview, and audit anti-patterns | -| `RECONNAISSANCE.md` | Phase 1 reconnaissance prompts and synthesis instructions | -| `HUNTING.md` | Phase 2 orchestration, hunting methodology, and validation rules | -| `ATTACK-CLASSES.md` | Core, wildcard, and obvious-things attack prompts | -| `MEMORY-SAFETY-AND-BINARY.md` | Memory-safety, binary, and kernel hunting classes for native targets | -| `AI-AND-LLM.md` | Prompt-injection, agent/tool, and output-handling hunting classes for LLM-backed targets | -| `WEB-PROTOCOL-AND-AUTH.md` | HTTP request-framing, cache, and authentication-protocol hunting classes for HTTP-protocol and auth targets | -| `CLIENT-SIDE.md` | DOM-injection, messaging-trust, UI-redress, and prototype-pollution hunting classes for client-side/browser targets | -| `SUPPLY-CHAIN-AND-RELEASE.md` | Dependency, CI, release, signing, update, plugin, and extension hunting classes | -| `CLOUD-AND-DEPLOYMENT.md` | IAM, infrastructure-as-code, container, serverless, ingress, and runtime-configuration hunting classes | -| `PROTOCOLS-RPC-AND-MESSAGING.md` | RPC, serialization, queue, broker, webhook, and streaming-protocol hunting classes | -| `RESOURCE-EXHAUSTION-AND-AVAILABILITY.md` | Shared resource, quota, queue, worker, and operator-spend hunting classes | -| `DATA-ISOLATION-AND-LIFECYCLE.md` | Tenant isolation, cache, search, export, backup, migration, deletion, and restore hunting classes | -| `DESKTOP-MOBILE-AND-LOCAL-IPC.md` | Native app, deep-link, webview, exported-component, helper, daemon, and local-IPC hunting classes | -| `VALIDATION-AND-REPORTING.md` | Phases 3–6 candidate validation, structured output, record verification, and reporting | -| `report-schema.json` | JSON schema for all three `findings.json` verdicts | -| `validate-findings.cjs` | Zero-dependency validator for `findings.json` in Phases 4 and 5 | -| `validate-findings.test.cjs` | Findings-validator tests and producer-compatible fixture checks | -| `validate-coverage-ledger.cjs` | Zero-dependency validator for `coverage-ledger.json` in Phases 1–5 | -| `validate-coverage-ledger.test.cjs` | Coverage-ledger validator tests | +| `skills/security-audit/SKILL.md` | Setup, core principles, platform terminology, workflow overview, and audit anti-patterns | +| `skills/security-audit/references/RECONNAISSANCE.md` | Phase 1 reconnaissance prompts and synthesis instructions | +| `skills/security-audit/references/HUNTING.md` | Phase 2 orchestration, hunting methodology, and validation rules | +| `skills/security-audit/references/ATTACK-CLASSES.md` | Core, wildcard, and obvious-things attack prompts | +| `skills/security-audit/references/MEMORY-SAFETY-AND-BINARY.md` | Memory-safety, binary, and kernel hunting classes for native targets | +| `skills/security-audit/references/AI-AND-LLM.md` | Prompt-injection, agent/tool, and output-handling hunting classes for LLM-backed targets | +| `skills/security-audit/references/WEB-PROTOCOL-AND-AUTH.md` | HTTP request-framing, cache, and authentication-protocol hunting classes for HTTP-protocol and auth targets | +| `skills/security-audit/references/CLIENT-SIDE.md` | DOM-injection, messaging-trust, UI-redress, and prototype-pollution hunting classes for client-side/browser targets | +| `skills/security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md` | Dependency, CI, release, signing, update, plugin, and extension hunting classes | +| `skills/security-audit/references/CLOUD-AND-DEPLOYMENT.md` | IAM, infrastructure-as-code, container, serverless, ingress, and runtime-configuration hunting classes | +| `skills/security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md` | RPC, serialization, queue, broker, webhook, and streaming-protocol hunting classes | +| `skills/security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md` | Shared resource, quota, queue, worker, and operator-spend hunting classes | +| `skills/security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md` | Tenant isolation, cache, search, export, backup, migration, deletion, and restore hunting classes | +| `skills/security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md` | Native app, deep-link, webview, exported-component, helper, daemon, and local-IPC hunting classes | +| `skills/security-audit/references/VALIDATION-AND-REPORTING.md` | Phases 3–6 candidate validation, structured output, record verification, and reporting | +| `skills/security-audit/resources/report-schema.json` | JSON schema for all three `findings.json` verdicts | +| `skills/security-audit/scripts/validate-findings.cjs` | Zero-dependency validator for `findings.json` in Phases 4 and 5 | +| `skills/security-audit/scripts/validate-findings.test.cjs` | Findings-validator tests and producer-compatible fixture checks | +| `skills/security-audit/scripts/validate-coverage-ledger.cjs` | Zero-dependency validator for `coverage-ledger.json` in Phases 1–5 | +| `skills/security-audit/scripts/validate-coverage-ledger.test.cjs` | Coverage-ledger validator tests | ## Installation diff --git a/skills/security-audit/SKILL.md b/skills/security-audit/SKILL.md index 92178da..655b5e4 100644 --- a/skills/security-audit/SKILL.md +++ b/skills/security-audit/SKILL.md @@ -79,7 +79,7 @@ Before execution, the parent opens and retains trusted, non-inheritable director 10. Never recursively copy or glob scratch, extract an archive into artifacts, or open or promote a symlink, FIFO, socket, device, directory, hard-linked file, changing file, or file that exceeds its bound. 11. If any check is unavailable, cannot be enforced, or fails, discard the scratch entry; if it is decisive evidence, retain `needs_validation` with the exact promotion blocker. -[HUNTING.md](HUNTING.md) and [VALIDATION-AND-REPORTING.md](VALIDATION-AND-REPORTING.md) carry this procedure as one identical fenced block for hunter and verifier prompts; it states the same rules in the same order as this list. +[HUNTING.md](references/HUNTING.md) and [VALIDATION-AND-REPORTING.md](references/VALIDATION-AND-REPORTING.md) carry this procedure as one identical fenced block for hunter and verifier prompts; it states the same rules in the same order as this list. For a reproduced check, record the command, exact test input, sandbox limits, and only the allowlisted environment variable names plus safe non-secret values needed to reproduce it. Never capture or copy the ambient environment, inherited variables, credential values, authentication state, or unrelated host paths. Launch from an empty environment rather than trying to redact one after execution. @@ -91,7 +91,7 @@ The coverage, prior-run, profile, and budget requirements in this section apply ### Coverage and prior runs -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. +No one pass is complete. Build a deterministic coverage plan before hunting and update it after every agent result. [RECONNAISSANCE.md](references/RECONNAISSANCE.md) defines the stable coverage units and [HUNTING.md](references/HUNTING.md) defines coverage-critic waves. The parent alone updates the ledger. If prior runs exist, read every compatible `coverage-ledger.json` and `findings.json` before planning the current run: @@ -169,10 +169,10 @@ For each confirmed finding, identify the invariant the code must enforce and the In full audit mode, follow all six phases in order: -1. **Reconnaissance** — map the source, trust boundaries, local build paths, companion selections, prior evidence, and initial deterministic coverage ledger with [RECONNAISSANCE.md](RECONNAISSANCE.md). -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. -3. **Candidate validation** — consolidate fingerprints and give every candidate to a fresh source verifier as defined in [VALIDATION-AND-REPORTING.md](VALIDATION-AND-REPORTING.md). -4. **Structured output** — write all final `confirmed`, `needs_validation`, and `rejected` records to `findings.json`; validate it with `report-schema.json` and `validate-findings.cjs`, and validate the coverage claim with `validate-coverage-ledger.cjs`. +1. **Reconnaissance** — map the source, trust boundaries, local build paths, companion selections, prior evidence, and initial deterministic coverage ledger with [RECONNAISSANCE.md](references/RECONNAISSANCE.md). +2. **Coverage-led hunting waves** — assign isolated hunters from the ledger and collect structured candidate results with [HUNTING.md](references/HUNTING.md), [ATTACK-CLASSES.md](references/ATTACK-CLASSES.md), and the selected domain companions. +3. **Candidate validation** — consolidate fingerprints and give every candidate to a fresh source verifier as defined in [VALIDATION-AND-REPORTING.md](references/VALIDATION-AND-REPORTING.md). +4. **Structured output** — write all final `confirmed`, `needs_validation`, and `rejected` records to `findings.json`; validate it with `resources/report-schema.json` and `scripts/validate-findings.cjs`, and validate the coverage claim with `scripts/validate-coverage-ledger.cjs`. 5. **Independent record verification** — use fresh agents to verify final source claims and reconcile corrections or state changes. 6. **Target-neutral report** — derive `REPORT.md`, `FINDINGS-DETAIL.md`, and `NEEDS-VALIDATION.md` from the final records, with no live-probe instructions. diff --git a/skills/security-audit/AI-AND-LLM.md b/skills/security-audit/references/AI-AND-LLM.md similarity index 100% rename from skills/security-audit/AI-AND-LLM.md rename to skills/security-audit/references/AI-AND-LLM.md diff --git a/skills/security-audit/ATTACK-CLASSES.md b/skills/security-audit/references/ATTACK-CLASSES.md similarity index 100% rename from skills/security-audit/ATTACK-CLASSES.md rename to skills/security-audit/references/ATTACK-CLASSES.md diff --git a/skills/security-audit/CLIENT-SIDE.md b/skills/security-audit/references/CLIENT-SIDE.md similarity index 100% rename from skills/security-audit/CLIENT-SIDE.md rename to skills/security-audit/references/CLIENT-SIDE.md diff --git a/skills/security-audit/CLOUD-AND-DEPLOYMENT.md b/skills/security-audit/references/CLOUD-AND-DEPLOYMENT.md similarity index 100% rename from skills/security-audit/CLOUD-AND-DEPLOYMENT.md rename to skills/security-audit/references/CLOUD-AND-DEPLOYMENT.md diff --git a/skills/security-audit/DATA-ISOLATION-AND-LIFECYCLE.md b/skills/security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md similarity index 100% rename from skills/security-audit/DATA-ISOLATION-AND-LIFECYCLE.md rename to skills/security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md diff --git a/skills/security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md b/skills/security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md similarity index 100% rename from skills/security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md rename to skills/security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md diff --git a/skills/security-audit/HUNTING.md b/skills/security-audit/references/HUNTING.md similarity index 96% rename from skills/security-audit/HUNTING.md rename to skills/security-audit/references/HUNTING.md index 377d4dc..1d7309b 100644 --- a/skills/security-audit/HUNTING.md +++ b/skills/security-audit/references/HUNTING.md @@ -20,7 +20,7 @@ Every hunter prompt contains these parts in this order: 6. The core hunting method below, followed by the promotion procedure block. 7. The core validation rules below. 8. Carried same-source prior confirmed exclusions, each limited to fingerprint, title, and root cause, plus peer-owned current coverage IDs that this hunter must not duplicate. -9. The unique scratch/artifact paths, safe agent ID, predeclared promotion allowlist and byte limits, and the structured-result contract, including the Structured hunter result block below and the `confirmed` and `needs_validation` branches of `report-schema.json` copied verbatim. +9. The unique scratch/artifact paths, safe agent ID, predeclared promotion allowlist and byte limits, and the structured-result contract, including the Structured hunter result block below and the `confirmed` and `needs_validation` branches of `../resources/report-schema.json` copied verbatim. A prompt may select several companion blocks when the same path crosses several domains. Keep their constraints together. Scope is the hunter's coverage obligation, not permission to duplicate excluded work. If an unexpected different boundary appears, return it under `uncovered` so the parent creates a stable ledger unit and assigns it in the next wave. @@ -207,14 +207,14 @@ Return exactly one JSON object, with no surrounding prose: Each `candidates` entry is schema-shaped except that it uses `proposed_verdict` in place of `verdict`: -- `proposed_verdict: "confirmed"`: include every field required by the `confirmed` branch of `report-schema.json` other than `verdict`: `fingerprint`, title, description, `root_cause`, `intended_behavior`, ordered `trace`, `evidence`, `conditions`, target-neutral `execution`, `remediation`, `severity`, and `confidence`. The execution instructions describe only the bounded local check already performed. `payloads` holds the minimum test input, fixture, or native invocation. `observed_result` records actual local output. Overall severity must not exceed observed impact. +- `proposed_verdict: "confirmed"`: include every field required by the `confirmed` branch of `../resources/report-schema.json` other than `verdict`: `fingerprint`, title, description, `root_cause`, `intended_behavior`, ordered `trace`, `evidence`, `conditions`, target-neutral `execution`, `remediation`, `severity`, and `confidence`. The execution instructions describe only the bounded local check already performed. `payloads` holds the minimum test input, fixture, or native invocation. `observed_result` records actual local output. Overall severity must not exceed observed impact. - `proposed_verdict: "needs_validation"`: include every field required by that schema branch other than `verdict`: `fingerprint`, title, description, `claimed_root_cause`, ordered `trace`, `evidence`, nonempty `blockers`, and `validation_plan` with at least one applicable `local` or `deployment` step. Do not invent an inapplicable context. Do not include severity, execution, remediation, reason, or a confirmed `root_cause`. `deployment` is an owner-observed check, not a request to probe a live target. Every assigned coverage ID appears exactly once in `units`. A `covered` unit needs an owner, nonempty `reviewed_paths` and `checks`, no unresolved fact, and no candidate. A `candidate` unit has the same owned evidence and is the only state that carries linked fingerprints. A `blocked` unit is an owned partial review with nonempty paths, checks, and unresolved facts but no fingerprint. All source paths are repository-relative, never absolute or traversal paths. A trace with several entries begins at `entrypoint`, ends at `sink`, and labels intermediate steps `propagation`. Every check has its own canonical lowercase `agent_id` and nonempty `reviewed_paths`; the unit-level list is exactly the union of those owned paths. A `source` check uses `artifact: null`. A `local` check uses one successfully parent-promoted regular file beneath `agents//artifacts/`; this permits a verifier to add independently owned evidence without taking ownership from the hunter. Never link scratch, an output-root file, or another check owner's artifact. ## Parent consolidation and ledger update -The parent validates each unit result, maps it to exactly one assigned `coverage_id`, and updates only that ledger unit. Reject duplicate or absent IDs, unsafe unit or check agent IDs, source checks with artifacts, and local artifacts that trusted parent-side code did not promote into the check owner's artifacts subtree. Copy the unit's `reviewed_paths`, its `checks` into the unit's `local_checks`, linked artifact paths, candidate fingerprints, and unresolved facts into the ledger. Retain each hunter's `hardening` list in a parent bookkeeping field on the relevant units (outside the semantic fields) so Phase 6 can report it. A failed, malformed, or unsupported conclusion leaves that unit `planned` for reassignment. Untouched budget/profile units become unassigned `deferred` units with empty evidence and a reason; do not hide partial evidence in `deferred`. Run `validate-coverage-ledger.cjs` after the update; an invalid ledger cannot drive another assignment. This per-unit contract allows one hunter to close one unit while returning a candidate or blocker for another. +The parent validates each unit result, maps it to exactly one assigned `coverage_id`, and updates only that ledger unit. Reject duplicate or absent IDs, unsafe unit or check agent IDs, source checks with artifacts, and local artifacts that trusted parent-side code did not promote into the check owner's artifacts subtree. Copy the unit's `reviewed_paths`, its `checks` into the unit's `local_checks`, linked artifact paths, candidate fingerprints, and unresolved facts into the ledger. Retain each hunter's `hardening` list in a parent bookkeeping field on the relevant units (outside the semantic fields) so Phase 6 can report it. A failed, malformed, or unsupported conclusion leaves that unit `planned` for reassignment. Untouched budget/profile units become unassigned `deferred` units with empty evidence and a reason; do not hide partial evidence in `deferred`. Run `../scripts/validate-coverage-ledger.cjs` after the update; an invalid ledger cannot drive another assignment. This per-unit contract allows one hunter to close one unit while returning a candidate or blocker for another. Consolidate candidate entries by fingerprint and then by root cause. One root cause that exposes several entry paths or effects is one candidate with the strongest complete trace. Related but independent missing controls use separate fingerprints. Record duplicate fingerprints in the relevant ledger unit and do not send duplicate candidates to validation. diff --git a/skills/security-audit/MEMORY-SAFETY-AND-BINARY.md b/skills/security-audit/references/MEMORY-SAFETY-AND-BINARY.md similarity index 100% rename from skills/security-audit/MEMORY-SAFETY-AND-BINARY.md rename to skills/security-audit/references/MEMORY-SAFETY-AND-BINARY.md diff --git a/skills/security-audit/PROTOCOLS-RPC-AND-MESSAGING.md b/skills/security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md similarity index 100% rename from skills/security-audit/PROTOCOLS-RPC-AND-MESSAGING.md rename to skills/security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md diff --git a/skills/security-audit/RECONNAISSANCE.md b/skills/security-audit/references/RECONNAISSANCE.md similarity index 96% rename from skills/security-audit/RECONNAISSANCE.md rename to skills/security-audit/references/RECONNAISSANCE.md index 1a170a9..29dd3b4 100644 --- a/skills/security-audit/RECONNAISSANCE.md +++ b/skills/security-audit/references/RECONNAISSANCE.md @@ -153,4 +153,4 @@ Canonical agent IDs match `^[a-z0-9][a-z0-9_-]{0,63}$` and are not Windows devic The ledger is the coverage claim. An architecture summary, agent count, or generic "auth reviewed" sentence is not coverage evidence. Phase 2 closes units only from the paths and checks in a hunter's structured result. -Run `node /validate-coverage-ledger.cjs /coverage-ledger.json` after seeding, after every parent update, and before Phase 6. The validator rejects input beyond 5 MiB, 64 nesting levels, 10,000 units, 1,000 entries in a nested collection, or 500,000 traversed values, and caps reported validation errors at 100. In practice the 5 MiB byte limit holds roughly 2,000-5,000 realistic units, so it binds before the 10,000-unit cap. Fix every error before assigning work or making a coverage claim. +Run `node /scripts/validate-coverage-ledger.cjs /coverage-ledger.json` after seeding, after every parent update, and before Phase 6. The validator rejects input beyond 5 MiB, 64 nesting levels, 10,000 units, 1,000 entries in a nested collection, or 500,000 traversed values, and caps reported validation errors at 100. In practice the 5 MiB byte limit holds roughly 2,000-5,000 realistic units, so it binds before the 10,000-unit cap. Fix every error before assigning work or making a coverage claim. diff --git a/skills/security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md b/skills/security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md similarity index 100% rename from skills/security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md rename to skills/security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md diff --git a/skills/security-audit/SUPPLY-CHAIN-AND-RELEASE.md b/skills/security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md similarity index 100% rename from skills/security-audit/SUPPLY-CHAIN-AND-RELEASE.md rename to skills/security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md diff --git a/skills/security-audit/VALIDATION-AND-REPORTING.md b/skills/security-audit/references/VALIDATION-AND-REPORTING.md similarity index 97% rename from skills/security-audit/VALIDATION-AND-REPORTING.md rename to skills/security-audit/references/VALIDATION-AND-REPORTING.md index 5e200d7..7ec130c 100644 --- a/skills/security-audit/VALIDATION-AND-REPORTING.md +++ b/skills/security-audit/references/VALIDATION-AND-REPORTING.md @@ -4,7 +4,7 @@ After the clean coverage-critic pass or an explicitly recorded early stop, consolidate Phase 2 candidates and carried same-source prior confirmations by stable fingerprint and root cause. Give every unique proposed `confirmed` and `needs_validation` candidate to a fresh `general` verifier that did not hunt it. A carried prior confirmation follows the same current verification path even though hunters exclude that unchanged root cause. A verifier may read hunter or prior artifacts but must re-read every cited current source location and independently run any decisive check it can reproduce safely. -Assign each verifier a canonical lowercase unique ID and `/agents//scratch/` plus parent-owned `artifacts/`. The verifier writes only to `scratch/` and never writes retained artifacts. It receives only the candidate, its linked coverage-unit checks and artifact paths, architecture facts needed to interpret the path, exact relevant companion validation blocks, the promotion procedure block below, the source/local execution boundary, the `confirmed`, `needs_validation`, and `rejected` branches of `report-schema.json` copied verbatim, and prior records with the same fingerprint. It must not receive another verifier's conclusion. +Assign each verifier a canonical lowercase unique ID and `/agents//scratch/` plus parent-owned `artifacts/`. The verifier writes only to `scratch/` and never writes retained artifacts. It receives only the candidate, its linked coverage-unit checks and artifact paths, architecture facts needed to interpret the path, exact relevant companion validation blocks, the promotion procedure block below, the source/local execution boundary, the `confirmed`, `needs_validation`, and `rejected` branches of `../resources/report-schema.json` copied verbatim, and prior records with the same fingerprint. It must not receive another verifier's conclusion. #### Candidate-verifier prompt @@ -100,7 +100,7 @@ The parent writes all independently decided records to `/findings.js - `needs_validation`: source-grounded candidates with an exact unresolved blocker and at least one applicable local or owner-observed deployment plan. - `rejected`: source-grounded candidates disproved during validation, retained so future runs do not repeat the unsupported claim without changed evidence. -Read `report-schema.json` immediately before writing. It uses `additionalProperties: false`; do not carry hunter wrapper fields into a record. Keep these verdict contracts distinct: +Read `../resources/report-schema.json` immediately before writing. It uses `additionalProperties: false`; do not carry hunter wrapper fields into a record. Keep these verdict contracts distinct: - A `confirmed` record uses `root_cause`, `intended_behavior`, `conditions`, `execution`, `remediation`, `severity`, and `confidence`. It must not use `claimed_root_cause`, `blockers`, `validation_plan`, or `reason`. `execution` is target-neutral and uses the target's native interface: API/HTTP input, CLI call, library call, message, file fixture, browser action, rendered policy, or local harness as applicable. `observed_result` is nonempty and factual. - A `needs_validation` record uses `claimed_root_cause`, `trace`, `evidence`, `blockers`, and at least one nonempty `validation_plan.local` or `validation_plan.deployment` field. Include both only when both contexts can resolve distinct facts. It must not use severity, execution, remediation, reason, or confirmed root cause. @@ -111,8 +111,8 @@ Every record has a stable fingerprint, title, description, and repository-relati Run: ```sh -node /validate-findings.cjs /findings.json -node /validate-coverage-ledger.cjs /coverage-ledger.json +node /scripts/validate-findings.cjs /findings.json +node /scripts/validate-coverage-ledger.cjs /coverage-ledger.json ``` Fix every structural and semantic error before continuing. The findings validator rejects input beyond 5 MiB, 1,000 top-level findings, or 64 nesting levels, and caps reported error output at 100 messages. Validator success proves format and ledger consistency only. diff --git a/skills/security-audit/WEB-PROTOCOL-AND-AUTH.md b/skills/security-audit/references/WEB-PROTOCOL-AND-AUTH.md similarity index 100% rename from skills/security-audit/WEB-PROTOCOL-AND-AUTH.md rename to skills/security-audit/references/WEB-PROTOCOL-AND-AUTH.md diff --git a/skills/security-audit/report-schema.json b/skills/security-audit/resources/report-schema.json similarity index 99% rename from skills/security-audit/report-schema.json rename to skills/security-audit/resources/report-schema.json index 55815a3..ff94e64 100644 --- a/skills/security-audit/report-schema.json +++ b/skills/security-audit/resources/report-schema.json @@ -1,5 +1,5 @@ { - "$comment": "Top-level contract for findings.json. validate-findings.cjs interprets and checks this schema directly.", + "$comment": "Top-level contract for findings.json. scripts/validate-findings.cjs interprets and checks this schema directly.", "type": "array", "items": { "oneOf": [ diff --git a/skills/security-audit/validate-coverage-ledger.cjs b/skills/security-audit/scripts/validate-coverage-ledger.cjs similarity index 100% rename from skills/security-audit/validate-coverage-ledger.cjs rename to skills/security-audit/scripts/validate-coverage-ledger.cjs diff --git a/skills/security-audit/validate-coverage-ledger.test.cjs b/skills/security-audit/scripts/validate-coverage-ledger.test.cjs similarity index 100% rename from skills/security-audit/validate-coverage-ledger.test.cjs rename to skills/security-audit/scripts/validate-coverage-ledger.test.cjs diff --git a/skills/security-audit/validate-findings.cjs b/skills/security-audit/scripts/validate-findings.cjs similarity index 99% rename from skills/security-audit/validate-findings.cjs rename to skills/security-audit/scripts/validate-findings.cjs index 2843fec..3fb2343 100755 --- a/skills/security-audit/validate-findings.cjs +++ b/skills/security-audit/scripts/validate-findings.cjs @@ -708,9 +708,9 @@ function run(file) { let schema; try { - schema = loadSchema(path.join(__dirname, "report-schema.json")); + schema = loadSchema(path.join(__dirname, "../resources/report-schema.json")); } catch (error) { - console.error("Failed to load report-schema.json:", error.message); + console.error("Failed to load ../resources/report-schema.json:", error.message); return 1; } diff --git a/skills/security-audit/validate-findings.test.cjs b/skills/security-audit/scripts/validate-findings.test.cjs similarity index 99% rename from skills/security-audit/validate-findings.test.cjs rename to skills/security-audit/scripts/validate-findings.test.cjs index 8d245b2..bfbf409 100644 --- a/skills/security-audit/validate-findings.test.cjs +++ b/skills/security-audit/scripts/validate-findings.test.cjs @@ -4,7 +4,7 @@ const os = require("node:os"); const path = require("node:path"); const { spawnSync } = require("node:child_process"); const test = require("node:test"); -const schema = require("./report-schema.json"); +const schema = require("../resources/report-schema.json"); const { LIMITS, collect,