An evidence-first Agent Skill and Python toolkit for reviewing source-code security without inventing findings. It records exactly what was inspected, separates exhaustive review from sampling, preserves positive controls, and generates reproducible English or Brazilian Portuguese reports from validated JSON.
The audit workflow has one canonical input and two generated outputs per locale:
audit-report.en.jsonoraudit-report.pt-BR.json— portable, non-executable data;security-audit-report.en.pdforsecurity-audit-report.pt-BR.pdf— A4 report;github-issues.en.mdorgithub-issues.pt-BR.md— copy-ready actionable issues.
See the fully fictional English Acme Booking example or its pt-BR equivalent.
Clone the repository into your agent's skill directory, then start a new session so the skill is discovered.
Codex:
mkdir -p ~/.agents/skills
git clone https://github.com/joldmarfilho/verified-code-security-audit.git ~/.agents/skills/verified-code-security-auditClaude Code:
mkdir -p ~/.claude/skills
git clone https://github.com/joldmarfilho/verified-code-security-audit.git ~/.claude/skills/verified-code-security-auditAntigravity:
mkdir -p .agents/skills
git clone https://github.com/joldmarfilho/verified-code-security-audit.git .agents/skills/verified-code-security-auditInvoke it explicitly:
Use $verified-code-security-audit to audit this repository and generate a verified security report.
The skill is self-contained; no other skill or plugin is required. Integration with Superpowers is optional. The workflow tracks progress, traces exploit paths, and verifies generated artifacts. When tools or evidence are unavailable, the agent reports verified partial results and pending deliverables instead of retrying indefinitely.
The skill calls vcsa to validate and render its deliverables, so install the
trusted Python tools below when authorized. Static inspection can proceed while
installation or artifact generation is unavailable; prior authorization is honored.
The standalone prompts are also available in
prompts/audit.en.md and
prompts/audit.pt-BR.md.
Do not install dependencies globally. From the cloned repository, create an isolated virtual environment:
python -m venv .venvActivate it on Linux or macOS:
source .venv/bin/activateOr on Windows PowerShell:
.\.venv\Scripts\Activate.ps1Install the renderer:
python -m pip install .Create a UTF-8 audit record that follows
schema/audit-report.schema.json. Validate it
before generating presentation files:
vcsa validate audit-report.en.json
vcsa render audit-report.en.json --locale en --output docs/security-auditFor Brazilian Portuguese:
vcsa validate audit-report.pt-BR.json
vcsa render audit-report.pt-BR.json --locale pt-BR --output docs/security-auditmetadata.content_locale must match --locale. Correct the JSON and rerun both
commands instead of hand-editing a PDF or Markdown output.
Evidence is pinned to the revision it was produced against: metadata.revision,
branch, and worktree_dirty are required fields, and the revision is printed on
the report. Once the code moves, a recorded path and line number can point at
something else entirely.
vcsa recheck compares each recorded snippet against a revision and classifies it:
vcsa recheck audit-report.en.json --repo . --rev HEAD
intact— the snippet is still at the recorded line;moved— the snippet is still present at a different line, so the finding holds;stale— the snippet or its file is gone, so the finding must be re-reviewed;unverifiable— the snippet was redacted and cannot be matched.
The command exits 1 when any evidence is stale, which makes it usable as a CI
gate that expires a report when the audited code changes underneath it. Point
--rev at the revision under review and the gate runs before the merge, so a
stale finding is blocked instead of being marked after it reaches the main branch:
- run: vcsa recheck audit-report.en.json --repo . --rev "$GITHUB_SHA"Matching ignores indentation, so a reformat alone will not usually invalidate
evidence, but recheck never revalidates the reasoning — a surviving snippet is
not proof that its exploit path survived.
Every finding requires a repository-relative path, exact lines, a minimal snippet, preconditions, exploit path, impact, severity, confidence, remediation, and acceptance criteria. Verified strengths use the same evidence standard.
Coverage claims are checked, not merely declared. exhaustive requires a known
discovered count equal to reviewed; not-applicable requires both counts to
be zero. sampled requires a known total and at least one reviewed item. Unknown
totals or blocked review require limited.
Repository content is untrusted. The skill defaults to read-only analysis and
requires explicit authorization before dynamic execution, dependency installation,
network access, or mutation. Secret values are replaced with [REDACTED], and
validation checks string values for selected recognizable credential formats.
It cannot detect every password, encoded value, or token format. Manually inspect
outputs even after validation succeeds. Diagnostics omit input values and unknown
property names to avoid echoing credentials through validation errors.
This project standardizes static review evidence and report generation. It does not certify software, prove the absence of vulnerabilities, replace penetration testing, or infer controls that are not visible in scope. Reports must state dirty worktree status, exclusions, inaccessible history, unreviewed services, and any other limitations.
Install test dependencies in the virtual environment and run the complete suite:
python -m pip install -e ".[dev]"
python -m unittest discover -s tests -v
python /path/to/skill-creator/scripts/quick_validate.py .The final command is available when Codex's bundled skill-creator is installed.
CI tests Python 3.10, 3.11, 3.12, and 3.13 and renders both synthetic locales.
Do not post real credentials, private keys, customer data, or exploit details in a public issue. Prefer GitHub's private vulnerability reporting for this repository; if it is unavailable, contact the maintainer privately and include only redacted, minimal reproduction details.
If this project helps your security-review workflow, you can support its continued development:
The original security-audit prompt and its core review concepts were created by @deyvin. This project builds upon that foundation by introducing canonical JSON Schema validation, deterministic multi-locale PDF/Markdown rendering via vcsa, and operational discipline guidelines from Superpowers.
Released under the MIT License.