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.

Current v0.30.0 support is documentation/package compatibility with no target read. None of the five agent surfaces has yet proved both pre-start package authenticity and project-instruction neutralization. Do not point an agent or packaged engine at a target repository. The workflow below is the contract a later reviewed startup path must satisfy, not a current execution claim.

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.

Workflow contract

• 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 the workflow is designed 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

If a later release promotes a startup path, use the workflow only for authorized security research against code and systems you own or are explicitly authorized to test. You are responsible for complying with applicable law and the target project's security policy; the authors assume no liability for misuse.

The workflow's intended safety posture is structural:

• 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.

Any findings produced after a future startup promotion are for a human to disclose through the target project's coordinated channels; the workflow prepares evidence, never 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). The generated packages prove portable package shape across five agents; they do not authenticate themselves before an agent discovers target-controlled instructions.

1. Package compatibility (no target read)

Clone this repo or download a release to inspect the packages, schemas, and synthetic tests. Do not copy a package into an untrusted target and invoke it as a vulnerability-audit entrypoint: doing so lets project-local discovery run before the loaded skill can establish trust.

Each generated SKILL.md still embeds the workflow and ships the same references/ and packaged scripts for package/schema compatibility. Project-local paths remain generated so all five agents can validate and evolve their envelopes, but they are not a trusted startup path.

2. Current startup support

Hardened or source-only use requires an outside-target-and-package digest pin or signature verification against an operator-pinned signer/key and accepted version, plus a whole-package manifest/realpath check and external configuration that prevents every target-local skill and instruction source from loading. An isolated loader test must prove the selected path/digest and include a discovery-positive negative control. No loaded skill or package-local validator can supply that proof about itself.

Agent	Documented outside-target location	E1 result	Current tier
Codex	$HOME/.agents/skills	an exploratory neutral-CWD probe excluded synthetic project instructions, but replayable neutralization and package authenticity are unproved	documentation/package compatibility; no target read
Claude Code	~/.claude/skills	personal priority is documented; no retained-trusted-skill hostile-target loader proof	documentation/package compatibility; no target read
Gemini CLI	~/.gemini/skills or ~/.agents/skills	workspace packages have higher precedence; no proved post-target-access neutralization	documentation/package compatibility; no target read
GitHub Copilot	~/.copilot/skills or ~/.agents/skills	no callable Copilot CLI was available for the isolated loader probe	documentation/package compatibility; no target read
Google Antigravity	~/.gemini/config/skills	installed CLI exposed no trustworthy active-skill path or project-disable proof	documentation/package compatibility; no target read

The full startup contract and the limits of run-state.bootstrap.json are in skill-core/references/shadow-skill-bootstrap.md. Until a later reviewed release promotes a surface, do not point the agent or packaged discovery engine at a target repository. Maintainers may continue running the deterministic synthetic tests and package checks in this repository.

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); .agent/skills/ is also generated as the documented backward-compatible legacy location	AGENTS.md (natively mounted)

Latest supported-agent feature refresh: 2026-07-11 (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; envelopes diverge only where documented agent features improve package discovery or context cost. Sync/tests verify generated shape, not a trusted runtime path. None of the five surfaces is promoted above the no-target-read cap. Gemini CLI stays in the compatibility set despite Google's completed 2026 consumer-hosted transition; the package does not promise hosted or hardened execution (see docs/authoritative-sources.md).

Repository layout

For evaluators, the generated packages are compatibility artifacts. v0.30.0 exposes no supported target-audit runtime artifact; the remaining files maintain and test the workflow contract.

• 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.