The Problem

Developers need a repeatable, machine‑readable way to run multi‑phase security audits inside a coding‑agent environment. Manual checklists produce unstructured notes, make it hard to track coverage across runs, and generate no verifiable output for downstream tooling.

What This Does

The repository supplies a coding‑agent skill that drives a six‑phase audit pipeline: recon, hunting, validation, reporting, structured JSON output, and independent verification. All orchestration logic lives in the Skills CLI runtime; the repo contributes only the content that drives that runtime.

  • skills/security-audit/SKILL.md – defines the skill name, trigger phrases, and high‑level workflow.
  • Phase‑specific markdown files (RECONNAISSANCE.md, HUNTING.md, ATTACK-CLASSES.md, etc.) – contain prompt templates and synthesis instructions the agent injects at each stage.
  • report-schema.json – a JSON‑Schema describing the shape of findings.json (confirmed, rejected, and evidence fields).
  • validate-findings.cjs – a zero‑dependency Node script that reads findings.json and validates it against report-schema.json; invoked by the Skills CLI after the audit finishes.

The skill itself does not contain executable code; it is data that the Skills platform interprets. The only runnable artifact is validate-findings.cjs, which is called directly by the CLI (npx skills run security-audit …).

How It Is Wired

  1. Entry point – The Skills CLI scans the repository for a SKILL.md file. When a user issues a request that matches one of the trigger phrases (“security audit”, “find vulnerabilities”, etc.), the CLI loads the skill definition.
  2. Prompt injection – For each phase, the CLI reads the corresponding markdown file (e.g., RECONNAISSANCE.md for phase 1) and sends its content as a system prompt to a new parallel agent. The agents operate independently; there is no inter‑file import graph inside the repo.
  3. Result aggregation – Agents write their outputs into the run directory (architecture.md, REPORT.md, findings.json). The CLI then executes node validate-findings.cjs (the only JavaScript file) to ensure findings.json conforms to report-schema.json.
  4. Verification phase – The CLI spawns fresh agents that read the validated findings.json and re‑run the same prompts against the source code to confirm each claim. No additional code in the repo participates in this step.

Because the repository contains only static assets, the blast radius of any change is limited to the text of prompts or the schema. The only side‑effecting component is validate-findings.cjs; altering it changes validation behaviour for every audit run.

No import cycles or hidden dependencies exist—each markdown file is read independently, and the validator is a standalone script. The wiring is therefore simple but also incomplete: the orchestration engine lives outside this repo.

How To Use It

# Clone (optional, for inspection)
git clone https://github.com/moses-y/security-audit-skill
cd security-audit-skill

# Install the skill into a compatible coding‑agent
npx skills add https://github.com/moses-y/security-audit-skill \
  --skill security-audit   # add to local project
# or add globally with --global

# Run an audit from the agent’s working directory
security audit ./src            # triggers the skill
# Or specify an explicit output folder
security audit ./src --out ~/audits/myproj

The CLI automatically:

  1. Reads SKILL.md and matches the command.
  2. Executes the six phases, pulling prompt text from the markdown files.
  3. Writes findings.json and calls node validate-findings.cjs for schema validation.

No additional configuration files, environment variables, or build steps are required.

Real‑World Use

A SaaS provider integrates the skill into its CI pipeline by invoking the Skills CLI after each build:

npx skills run security-audit ./repo --out ./audit/run-$(date +%s)

The resulting findings.json is then consumed by a downstream ticket‑generation script that creates JIRA issues for each MEDIUM or higher finding, guaranteeing traceability across releases.

Code Health & Issues

  • Medium – No test suite – repository contains only documentation and a validator; no unit or integration tests exist.
  • Medium – No CI/CD configuration – no .github/workflows, Makefile, or other pipeline definitions; automated verification of the validator or schema is absent.
  • Low – Minimal executable surface – only validate-findings.cjs runs code; the rest is static data, limiting functional risk but also providing no coverage checks.

No licensing issues are apparent; the repository includes an LICENSE file.

The Bottom Line

The repo delivers a well‑structured set of prompts and a JSON schema that enable a coding‑agent to perform a repeatable security audit, but it supplies no orchestration code. It is suitable for teams that already use the Skills CLI and need a ready‑made prompt library. Lack of tests and CI means the validator and schema are not automatically protected against regressions, so teams should add their own test harness before relying on it in production.