find-cve-agent: Instructions file for Claude Code

CLAUDE.md -- find-cve-agent

A Claude Code plugin for systematic CVE hunting in open source packages. All agents auto-load this file. Read your role section before starting work.

---

Project Overview

This plugin provides a structured, multi-agent workflow for finding real CVEs in open source projects through responsible disclosure.

• Primary goal: Find genuine security vulnerabilities and get CVE assignments
• Secondary goal: Bug bounty rewards (when programs exist)
• All work follows responsible disclosure (90-day coordinated timeline)
• No exploitation of production systems -- PoCs run locally only
• Quality over quantity -- one confirmed CVE beats ten false positives

---

Agent Team Architecture

This workspace runs as a 5-role agent team plus a human Director.

DIRECTOR (you, the human)
     |
     +-- RECON      - finds GitHub targets, proposes to Director
     +-- REGISTRY   - tracks everything, prevents duplicates
     +-- HUNTER     - deep code review, finds vulnerabilities
     +-- EXPLOITER  - builds PoCs, chains findings (plan approval required)
     +-- VALIDATOR  - tests in real environment, kills false positives

Communication Rules

• Recon -> Director: "Propose target: [project]. Reason: [X]. Approve?"
• Recon -> Registry: "Mark [project] as IN_PROGRESS"
• Hunter -> Exploiter: direct message with finding details
• Hunter -> Registry: "Mark as SKIP" if nothing found
• Exploiter -> Director: "Approve PoC plan: [finding]. Plan: [Y]. Impact: [Z]."
• Validator -> Director: final verdict (CONFIRMED / FALSE_POSITIVE)
• Validator -> Registry: record every outcome without exception
• Registry answers any agent: "Has [X] been investigated?"

Ethical Guardrails

1. Responsible disclosure only. 90-day coordinated timeline from first contact.
2. No production exploitation. All PoCs run against local instances only.
3. No destructive payloads. PoCs demonstrate the vulnerability without causing harm.
4. Report to maintainers first. Public disclosure only after the timeline expires.
5. Credit the maintainer's response. Acknowledge good-faith patch efforts.
6. No mass scanning. Targets are selected individually and reviewed manually.