Vulnerability Validation Skill

A portable AI Agent Skill that discovers 0-days in a codebase and proves them — a live PoC for anything executable — before any finding reaches a maintainer.

Point your coding agent at a repository and this skill analyzes the code itself to find new vulnerabilities, then drives every candidate through the same empirical machine: reachability, a live proof-of-concept, a negative control, and threat-model fit. What clears the gates becomes a validated finding with a minimal idiomatic fix and replayable evidence. What doesn't is rejected with a defensible reason.

No proof, no finding. A model's suspicion is a candidate, never a result. Nothing is promoted to a finding — and nothing is put in front of a maintainer — until a replayable proof exists.

What you get

• Native 0-day discovery. With no findings list, the skill maps attack surface and runs variant analysis to find vulnerabilities itself. A scanner hit, researcher report, or PoC is an optional starting point fused into discovery, never a prerequisite.
• Evidence, not opinion. Every executable finding is proven by a live PoC that drives the project's real code, with a negative control (a benign input that does not trigger the flaw) and a replay log another engineer can rerun.
• Reachability + threat-model gating. A vulnerable pattern is not a vulnerability until a real input path reaches it under the project's documented threat model. Trusted-input, by-design, and out-of-scope classes route to honest dispositions, not inflated severity.
• Minimal, idiomatic fixes. Patches target the root cause, match the repo's conventions, and are verified to fail on revert — with the existing test suite green.
• Maintainer-respecting handoff. A finding becomes a report only after it clears every gate; the skill produces evidence for a human to disclose.
• Role-lens review. Findings pass a six-lens review (security researcher, senior SWE, EM, PM, technical writer, editor) before any maintainer-facing claim.

Who it's for

Security researchers, AppSec engineers, and maintainers who want more than a wall of scanner hits. If you run Semgrep, CodeQL, or a fuzzer and need each candidate validated — reachable, reproduced, and scoped — rather than merely reported, this is the workflow. It is equally at home auditing a repository for 0-days, correlating a CVE to a codebase, validating a PoC, or preparing the evidence for a coordinated-disclosure advisory.

What it does not do

• No completeness claims. Discovery is bounded by a declared stopping criterion; it never asserts it found every bug or cleared the whole finding space.
• No autonomous verdicts. Gates promote candidates; a human adjudicates. The skill proposes a disposition and severity — it does not render the final call, file an advisory, or open a PR by itself.
• The discovery engine is a candidate source only. It generates and ranks; it never dispositions a finding, computes final severity, patches, or produces a maintainer-facing claim. Proof still runs through the full workflow.
• Not a substitute for a full audit. A clean run is not a proof of absence — it is the set of candidates that survived the gates this run.

Responsible use

This skill performs authorized security research and executes proof-of-concept code. Use it only against code and systems you own or are explicitly authorized to test. You are responsible for complying with all applicable laws and with the target project's security policy; the authors assume no liability for misuse.

Its safety posture is structural, enforced by the workflow itself:

• All empirical work runs in local, disposable, skill-owned isolation — containers, VMs, virtualenvs, or temporary worktrees, and never against production, shared, or third-party systems. Validation traffic — exploit payloads, probes, scans, PoCs, secrets — never leaves loopback or container-internal networks. Outbound traffic is limited to dependency/source provisioning and public-advisory lookups, and carries no exploit payloads or secrets. (Opting into remote metadata with the discovery engine's --allow-remote-metadata additionally sends dependency metadata to OSV-Scanner and the repository remote URL to OpenSSF Scorecard — it is off by default; keep it off for private targets.)
• The skill has no apply/push/send capability by design — a capability it lacks cannot be prompt-injected into use. It never patches upstream, opens PRs, or contacts maintainers.
• PoCs are minimized to the smallest demonstration of the flaw; no weaponized payloads, shellcode, or exfiltration strings reach maintainer-facing artifacts, and anything heavier stays sealed in the local evidence boundary.
• Maintainer-facing artifacts are scrubbed of internal identifiers into stable surrogates — verified by a deterministic pattern scan over the delivered bundle — while raw originals stay sealed locally.

Findings the skill produces about other projects are for a human to disclose through those projects' coordinated channels; the skill prepares the evidence, never the disclosure. To report a security issue in this project, see SECURITY.md.

How validation works

Each candidate is reduced to a defensible disposition through a set of gates. A finding is real only when all of them hold:

1. Reachability — a real input path reaches the sink, traversing the guards the production entry path enforces (no calling the sink directly).
2. Live PoC — an executable proof drives the project's real code and emits an explicit expected-vs-actual oracle, run inside skill-owned isolation.
3. Negative control — a benign or control input that produces no vulnerable observation, so a passing PoC can't be an accident (the fix is separately re-verified to block the exploit).
4. Threat-model fit — the finding sits inside the project's documented threat model and security boundary; trusted-input and by-design classes route to honest dispositions.
5. Latest-HEAD re-proof — before any handoff the oracle is re-run against the freshly fetched upstream HEAD, so a silently-fixed or moved primitive is caught.

A live PoC is required for executable findings. Non-executable ones — absent code, policy contracts, generated config, or blocked execution — substitute a reviewer-accepted source or replay proof, recorded with its blocker and a promotion plan rather than asserted from a model judgment.

The full methodology lives in the canonical body and references — start with skill-core/vulnerability-validation.md and skill-core/references/portable-invariants.md.

Getting started

This repo builds one canonical skill and syncs it into a self-contained package per agent, each embedding the same byte-identical workflow body (only the per-agent SKILL.md envelope differs) — write once, run in five agents. Each package is a SKILL.md folder your agent loads on demand: cheap until a task matches its description, then the full workflow loads.

1. Install into your repository

Clone this repo (or download a release), then copy the package directory for your agent into the same path in your target repository:

mkdir -p your-repo/.claude/skills
cp -r vulnerability-validation-skill/.claude/skills/vulnerability-validation \
      your-repo/.claude/skills/

Each package is self-contained — the SKILL.md entrypoint embeds the full workflow and ships its own references/ and scripts/ (the artifact validator and discovery engine).

Agent	Copy this package	Invoke
Codex	.agents/skills/vulnerability-validation/	/skills menu or $vulnerability-validation
Claude Code	.claude/skills/vulnerability-validation/	/vulnerability-validation, or auto from its description
Gemini CLI	.gemini/skills/vulnerability-validation/ (or the .agents/ alias)	/skills, or auto
GitHub Copilot	.agents/skills/vulnerability-validation/ or .claude/skills/vulnerability-validation/	/vulnerability-validation (Copilot CLI); auto on other surfaces
Google Antigravity	.agents/skills/vulnerability-validation/ and .agent/skills/vulnerability-validation/ (CLI resolves either)	native discovery

Per-agent install detail

• Codex scans .agents/skills in a repository. Optionally also copy agents/openai.yaml to enable implicit invocation.
• Claude Code uses the mirrored .claude/skills/vulnerability-validation/ directory and auto-loads the skill from its description.
• Gemini CLI natively discovers the skill under .gemini/skills/vulnerability-validation/ (and reads .agents/skills/ as an alias). You can also install from a repository URL with gemini skills install <repo-url>, and browse installed skills with /skills list.
• GitHub Copilot discovers the .agents/skills/ or .claude/skills/ package for project skills and applies the repo-wide .github/copilot-instructions.md. GitHub documents .github/skills/ for code-review auto-use; this repo intentionally does not emit a duplicate same-name skill there.
• Google Antigravity natively discovers the .agents/skills/vulnerability-validation/ package (shared with Codex) and mounts AGENTS.md. Google's codelab gives the Antigravity CLI project path as both .agent/skills/ and .agents/skills/, so both packages are provided — copy whichever your CLI build resolves.

2. Point your agent at a repository

Once installed, invoke the skill in natural language and let it run the workflow:

"Audit this repository for 0-days and validate anything you find." "Validate this scanner finding against the codebase and tell me if it's real." "Correlate this CVE to the repo and prove whether the primitive still fires at HEAD."

The skill discovers and ranks candidates, drives each through the gates above, and leaves you a worklist of validated findings, honest rejections, and replayable evidence.

3. (Optional) Run the deterministic discovery engine

For an offline first pass that emits ranked candidate ledgers before validation begins, run it from this repository — or from the skill package you installed, where the script ships under <package>/scripts/:

python3 scripts/discovery_engine.py --target /path/to/target --artifact-root /tmp/vv-artifacts

The engine writes candidate ledgers only and always runs its deterministic source, churn, dependency, and fuzz-harness lanes. It also runs optional external tools that are already installed (e.g. Semgrep, CodeQL). By default it will not install missing ones — --tool-policy auto-install installs the tools it supports (e.g. Semgrep) into a run-local tool home, but CodeQL must be preinstalled; --allow-remote-metadata enables OSV-Scanner / Scorecard lookups. Any tool failure is recorded as a blocker. Validation, severity, patches, and maintainer handoff still require the full skill workflow.

Supported agents

Agent	First-party generated surface	Additional project context
Codex	.agents/skills/vulnerability-validation/ and agents/openai.yaml	AGENTS.md
Claude Code	.claude/skills/vulnerability-validation/	generated CLAUDE.md importing AGENTS.md
Gemini CLI	natively-discovered skill under .gemini/skills/vulnerability-validation/	generated GEMINI.md importing AGENTS.md
GitHub Copilot	.github/copilot-instructions.md (repo-wide); project skill discovery can read the generated .agents/skills//.claude/skills/ packages; code-review auto-use is documented around .github/skills/	Copilot surfaces that support agent instructions can also consume AGENTS.md, CLAUDE.md, or GEMINI.md
Google Antigravity	IDE/platform natively discovers the .agents/skills/vulnerability-validation/ package (shared with Codex); Google's codelab gives the Antigravity CLI project path as both .agent/skills/ and .agents/skills/, so both packages are generated	AGENTS.md (natively mounted)

Latest supported-agent feature refresh: 2026-07-03 (see skill-core/references/agent-feature-matrix.md).

Other tools that read the open AGENTS.md standard (for example Cursor, Windsurf, Aider, Zed, Cline) may work unmodified via that file but are not first-party supported or tested.

The canonical body is byte-identical across every package, so the workflow behaves the same whichever agent you run it in; envelopes diverge only where a documented agent feature improves discovery, safety, context budget, validation, or operator friction. Copilot and Google Antigravity are verified through their native instruction and skill-discovery surfaces, not local CLI smoke tests. Gemini CLI stays first-party despite Google's 2026 hosted-tier transition (see docs/authoritative-sources.md).

Repository layout

For users, the only runtime artifact is the agent package you copy; everything else is for maintaining the skill.

• skill-core/ — the canonical skill body and references (the source of truth)
• .agents/skills/, .claude/skills/, .gemini/skills/, .agent/skills/ — generated per-agent skill packages
• AGENTS.md — canonical repository working agreement; CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md are generated agent-native mirrors
• scripts/sync_agent_surfaces.py — regenerates the agent-native surfaces from canonical sources
• scripts/discovery_engine.py — the deterministic first-pass discovery engine
• tests/, integration_tests/ — drift, contract, workflow, and provenance-hygiene checks
• docs/, reviews/ — design notes, authoritative-source records, and review consensus

Maintaining the skill

Contributors edit the canonical sources — never the generated mirrors — then regenerate. See CONTRIBUTING.md for the full workflow, review expectations, and CI details.

make sync     # regenerate agent-native mirrors from canonical sources
make lint     # verify generated surfaces are current + run scripts/lint_repo.py
make verify   # lint + unit tests + integration tests

The canonical body is skill-core/vulnerability-validation.md. To change any generated surface, edit skill-core/, skill.json, or AGENTS.md first, then run make sync; the generated files are packaging outputs only. On hosts without make (for example native Windows), use the platform's Python launcher (python, python3, or py -3) with the equivalent stdlib commands:

python scripts/sync_agent_surfaces.py
python scripts/sync_agent_surfaces.py --check
python scripts/lint_repo.py
python -m unittest discover -s tests

CI verifies the mirrors are current rather than committing them back, so every job runs with read-only contents permission. It runs the Python-only sync/lint/test subset on a cross-OS (Ubuntu/macOS/Windows) matrix, with the remaining gates (optimization, privacy, integration) on Ubuntu. The skill body stays OS-neutral: Codex CLI itself supports macOS, Windows, and Linux, and the current Codex smoke test uses POSIX PTY support, so it covers macOS/Linux/WSL and skips cleanly on native Windows until a Windows-safe runner is added. Agent-CLI documentation for local smoke testing is recorded in docs/authoritative-sources.md:

• Claude Code: https://code.claude.com/docs/en/skills
• OpenAI Codex CLI: https://developers.openai.com/codex/cli
• Google Gemini CLI: https://github.com/google-gemini/gemini-cli
• GitHub Copilot repository instructions: https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• Google Antigravity Agent Skills: https://ai.google.dev/gemini-api/docs/antigravity-agent

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.