H-mmer/pentest-agents: Claude Code 및 6종의 AI 코딩 도구를 위한 자율형 버그 바운티 (Bug-bounty)

Claude Code 및 6종의 기타 AI 코딩 도구를 위한 자율형 버그 바운티 (Bug-bounty) 프레임워크 — 50개의 에이전트 (agents), 26개의 명령 (commands), 19개의 CLI 도구 (tools), 11개의 기술 (skills), 2개의 MCP 서버 (servers).

~760개 파일 · ~118k 라인 · 50개 에이전트 (agents) · 26개 명령 (commands) · 19개 CLI 도구 (tools) · 11개 기술 (skills) · 2개 MCP 서버 (servers) (16개 버그 바운티 플랫폼 + BYO writeup 검색) · 2,500개 페이로드 (payload) 라인

완전한 버그 바운티 (bug bounty) 프레임워크입니다. 구체적인 페이로드 (payloads), 7단계 질문 게이트 (7-Question Gate) 검증, 자율적 헌팅 루프 (autonomous hunt loops), A→B 익스플로잇 체인 (exploit chain) 구축, 엔드포인트 추적을 포함한 지속적인 브레인 (persistent brain), 선택 가능한 시맨틱 라이트업 검색 (semantic writeup search, 사용자 인덱스 제공), CC 훅 (CC hooks)을 통한 자동 비용 추적, 실시간 플랫폼 통합, 그리고 Claude Code, Codex, Gemini, Cursor, Windsurf, VS Code Copilot, OpenClaw를 위한 네이티브 형식을 생성하는 크로스 IDE 설치 프로그램을 갖춘, 실전 검증된 헌팅 방법론을 제공합니다.

# MCP 서버는 `uv run --with mcp`를 통해 실행됩니다 — 전역 pip 설치가 필요하지 않습니다.
export HACKERONE_USERNAME=you HACKERONE_TOKEN=your_token
uv run python3 tools/scaffold.py hackerone tesla
...

scaffold.py는

Claude Code뿐만 아니라 지원되는 모든 프로젝트 범위 클라이언트(project-scoped client)를 위해 워크스페이스를 준비합니다: CLAUDE.md, AGENTS.md, .codex/, .agents/skills/, .gemini/, .cursor/, .windsurf/, .github/, 그리고 .vscode/mcp.json은 복사된 워크스페이스 자산으로부터 생성되어, 경로가 버그 바운티 워크스페이스 내부에서 해결(resolve)되도록 합니다.

이 프레임워크는 지원되는 모든 도구에 대해 사전 렌더링된 상태로 제공됩니다. 사용하는 방법은 두 가지가 있습니다:

1. 번들 (bundles)을 직접 사용 (설치 단계 없음)

git clone https://github.com/H-mmer/pentest-agents-suite
cd pentest-agents-suite/pentest-agents/providers/codex
codex # 또는: cd ../gemini && gemini, 등

providers/<id>/ 트리는 Claude 이외의 각 타겟에 대해 완전히 번역되어 즉시 사용 가능한 번들을 포함하고 있습니다. 내부의 경로 참조는 ..를 사용하여 레포지토리(repo)의 tools/, rules/, 그리고 mcp-*-server/에 도달합니다. 따라서 번들이 클론된 레포지토리 내에 머무는 한 정상적으로 작동합니다.

2. 설치 프로그램 실행 (사용자의 프로젝트 또는 ~/.codex/ 등에 작성)

python3 -m tools.installer install --targets all --scope project
python3 -m tools.installer install --targets codex --scope global

설치 모드 (Install mode)는 경로를 클론된 pentest-agents 레포지토리 내의 절대 참조 (absolute references)로 다시 작성하므로, 사용자의 프로젝트가 어디에 위치하든 설치가 정상적으로 작동합니다.

대상 (Target)	에이전트 (Agents)	슬래시 명령어 (Slash commands)	규칙 (Rules)	MCP	범위 (Scopes)
Claude Code	네이티브 .claude/agents/*.md	.claude/skills/<name>/SKILL.md	CLAUDE.md	.mcp.json / ~/.claude.json	global + project
OpenAI Codex	네이티브 .codex/agents/*.toml	.agents/skills/<name>/SKILL.md	AGENTS.md (≤32 KiB)	config.toml 내의 [mcp_servers.*]	global + project
Google Gemini	네이티브 .gemini/agents/*.md	.gemini/commands/ 내의 TOML	GEMINI.md	settings.json 내의 mcpServers	global + project
Cursor	→ 스킬 (skills) .cursor/skills/agent-*/SKILL.md (네이티브 서브에이전트 없음)	→ 스킬 (skills) .cursor/skills/cmd-*/SKILL.md	.cursor/rules/*.mdc + AGENTS.md	.cursor/mcp.json	global + project
Windsurf	→ 스킬 (skills)	워크플로 (Workflows)	.windsurf/rules/*.md (파일당 ≤12 KiB)	~/.codeium/windsurf/mcp_config.json	global + project
VS Code Copilot	.github/agents/*.agent.md (에이전트당 ≤30 KiB)	.github/prompts/*.prompt.md	.github/copilot-instructions.md + .github/instructions/*	.vscode/mcp.json	project + global-MCP
OpenClaw	→ 스킬 (skills)	→ 스킬 (skills)	~/.openclaw/workspace/AGENTS.md 또는 <proj>/AGENTS.md	~/.openclaw/openclaw.json 내의 mcp.servers	global + project (MCP는 사용자 레벨)

Cursor, Windsurf, OpenClaw에는 네이티브 서브에이전트 (subagent) 개념이 없으며, Claude 형식의 에이전트는 스킬/규칙 (skills/rules)으로 렌더링됩니다. Codex 명령어는 .agents/skills/ 아래의 AgentSkills로 방출됩니다. 사용 중단된 (deprecated) .codex/prompts/ 경로는 사용되지 않습니다.

** providers/ 디렉토리** (클론된 레포지토리 내):

providers/
├── codex/ AGENTS.md + .codex/{agents,config.toml} + .agents/skills
├── gemini/ GEMINI.md + .gemini/{agents,commands} + settings.json
...

providers/ 디렉토리는 직접 편집하는 것이 아니라 **생성(generated)**됩니다. .claude/, rules/, 또는 skills/ 소스를 편집한 후에는 다시 렌더링(Re-render)해야 합니다.

python3 -m tools.installer render --targets all
python3 -m tools.installer render --check # 드리프트(drift) 발생 시 1로 종료

test_committed_providers_match_render pytest 케이스는 로컬에서 드리프트 탐지를 강제합니다. 프로젝트 정책상 GitHub Actions CI는 제공되지 않습니다.

.claude/ 콘텐츠가 Claude가 아닌 다른 타겟을 위해 렌더링될 때, 번역기(translator)는 다음과 같은 작업을 수행합니다:

• model: 필드 삭제 — 각 타겟은 자체적인 기본 모델을 사용하므로 삭제합니다.
• Claude 전용 문구 제거 — "Claude Code" → "the AI coding tool", "the Agent tool" → "the subagent dispatch tool"와 같이 변경하며, model: "inherit"는 완전히 제거됩니다.
• 경로 재작성 — providers/ 내의 $CLAUDE_PROJECT_DIR를 (클론된 저장소 기준) ..로 변경하거나, 사용자의 프로젝트에 설치할 때는 클론된 소스 저장소의 절대 경로로 변경합니다.
• effort: 매핑 — Codex TOML의 frontmatter에 있는 model_reasoning_effort를 effort:로 매핑합니다.
• 본문 길이 제한 — Copilot 에이전트는 30,000자(Copilot의 하드 제한)에서 잘립니다. Windsurf 규칙은 12,000자(workspace) / 6,000자(global) 단위로 청크(chunk)화됩니다.
• Copilot 서브에이전트 링크 추가 — 오케스트레이터 에이전트(chain-builder, correlator, recon-ranker)에는 형제 에이전트들의 agents: 목록이 추가되어 Copilot이 디스패치 그래프(dispatch graph)를 연결할 수 있게 합니다.

pentest-agents list # 설치된 타겟 탐지
pentest-agents install --targets claude_code,codex --scope global
pentest-agents install --dry-run # 모든 파일 + JSON 병합 미리보기
...

모든 설치는 매니페스트(manifest)를 기록합니다 (프로젝트 범위의 경우 .pentest-agents/manifest.json, 글로벌 범위의 경우 ~/.config/pentest-agents/manifest.json). 삭제(Uninstall) 시에는 우리가 작성한 파일만 제거하고, 우리가 병합한 MCP/JSON 키만 정밀하게 제거하므로 사용자의 다른 설정은 절대 건드리지 않습니다. 충돌이 발생하는 쓰기 작업은 원본을 <path>.pa-backup으로 백업하며, 삭제 시 복구됩니다.

새 프로그램: /new → /sync → /brain init → /analyze → /surface → /hunt
복귀: /resume <target> → /hunt 또는 /autopilot
발견 후: /validate → /chain → /report → /dupcheck → /submit → /learn
...

HackerOne (전체 API), Bugcrowd, Intigriti, Immunefi (공개), YesWeHack + 11개의 스텁 (stubs). 7개의 MCP 도구: list_platforms, get_program_scope, get_program_policy, search_hacktivity, sync_program, draft_report, submit_report.

검색 가능한 지식 베이스 (knowledge base) 에이전트가 헌팅 (hunting) 및 검증 (validation) 단계 동안 쿼리합니다. 4개의 MCP 도구:

search_writeups — 선행 기술 (prior art)을 위한 시맨틱 검색 (semantic search, FAISS) 또는 키워드 검색

get_writeup — ID별 전체 라이트업 (writeup) 콘텐츠

search_techniques — 취약점 클래스 (vuln class)별 익스플로잇 기술 (exploitation techniques)

search_payloads — rules/payloads.md에서 제공하는 큐레이션된 페이로드 (payloads)

라이트업 인덱스는 번들로 포함되지 않습니다. 스크래핑된 Hacktivity를 대량으로 재배포하는 것은 대부분의 플랫폼 이용 약관 (ToS)을 위반하므로, 이 리포지토리는 서버만 제공합니다. search_payloads + search_techniques 폴백 (fallback)은 즉시 작동하며, 시맨틱/키워드 레이어는 서버를 사용자의 자체 인덱스로 지정하면 활성화됩니다.

세 가지 검색 모드 (자동 감지, 유연한 폴백):

모드	요구 사항	검색 대상
FAISS (시맨틱)	faiss-cpu, sentence-transformers, 사용자의 metadata.db + index.faiss	벡터 임베딩 (vector embeddings)을 통한 사용자의 라이트업 코퍼스 (corpus)
SQLite (키워드)	사용자의 metadata.db만 필요	텍스트 컬럼에 대한 LIKE 연산을 통한 사용자의 라이트업 코퍼스
Local (기본값)	없음 — 의존성 제로	이 리포지토리에 포함된 rules/payloads.md + skills/

metadata.db (+ 선택적으로 index.faiss)를 ~/.local/share/pentest-writeups/ 디렉토리에 넣거나, WRITEUP_DB_DIR=/path/to/dir를 설정하여 서버를 사용자의 인덱스로 지정하십시오.

예상 스키마 (metadata.db): id, title, url 컬럼과 하나의 텍스트 컬럼 (content/text/body/writeup)을 포함하는 최소 하나 이상의 테이블이 있는 SQLite 파일이어야 합니다. 시맨틱 모드를 사용할 때 테이블의 행 순서는 index.faiss의 벡터 순서와 일치해야 합니다.

이제 해당 저장소는 rag-builder/ 디렉토리에 로컬 RAG/FAISS 빌더를 포함하고 있습니다.

이 빌더는 GitHub / GitLab 저장소 목록을 metadata.db와 index.faiss 쌍으로 변환하며, 이 쌍은 writeup-search MCP 서버가 소비합니다. 파괴적인 작업(clone, embed, write)은 항상 --execute 플래그를 통해 실행이 제한됩니다. 이 플래그 없이 CLI를 실행하면 계획(plan)만 출력되고 아무것도 변경되지 않으므로, 실수로 기존 인덱스를 삭제하는 일을 방지할 수 있습니다.

cd rag-builder
# 1. 계획 검토 — 네트워크 연결 및 쓰기 작업 없음.
python3 build.py status
...

rag-builder/repos.yaml에는 CTF 아카이브, 버그 바운티 (Bug-bounty) 보고서, 페이로드 (payload) 모음, 연구 애그리게이터 (research aggregators)를 포함하는 146개의 엔트리 시드(seed)가 포함되어 있으며, 자유롭게 편집할 수 있습니다. repos-skipped.yaml은 제외 목록으로 자동 로드됩니다 (--skip-list 또는 --no-skip-list로 재정의 가능).

config.yaml은 임베딩 모델 (기본값은 all-MiniLM-L6-v2), 호스트 허용 목록 (allowlist), 클론 (clone) 크기 제한, 파일 크기 상한선을 제어합니다. 전체 참조 내용은 rag-builder/README.md를 확인하세요.

settings.json에서 설정되며, 다음 이벤트가 자동으로 실행됩니다:

SubagentStop → cost_hook.py가 에이전트 이름과 세션을 cost-tracking.json에 기록합니다.
Stop → 세션 종료를 기록합니다.
SessionStart → 환영 메시지를 출력합니다.

상태 표시줄 (Statusline)에는 세션 토큰 데이터를 기반으로 한 실시간 비용이 표시됩니다: $0.57

명령	설명
/hunt <target> [--vuln-class]	능동적 헌팅(Active hunting) — 먼저 writeup DB에서 기술을 검색한 후, 구체적인 페이로드 (payload)로 테스트를 수행합니다
/autopilot <target>	--paranoid/--normal/--yolo 체크포인트를 사용하는 자율 루프 (Autonomous loop)
/surface <target>	P1/P2/Kill 순위가 매겨진 공격 표면 (attack surface)
/chain	chain-builder 에이전트를 통한 A→B→C 익스플로잇 체인 (exploit chains) 구축 (rules/chain-table.md에 정의된 9개의 기능 행 + 4개의 문서화된 딥 체인 포함)
/analyze <target>	AI 분석: 핵심 자산 (crown jewels), 공격 경로 (attack paths), 사각지대 (blind spots)
/mindmap <target>	브레인 상태가 포함된 공격 표면 트리
/sast <repo>	소스 코드 취약점 헌팅 (entry → flow → gap → exploit 파이프라인)

명령 (Command)	설명 (Description)
/validate <finding>	7-Question Gate (7단계 검증 관문) → PASS/KILL/DOWNGRADE/CHAIN REQUIRED (통과/폐기/등급 하향/체이닝 필요)
/triage	모든 취약점(findings)을 일괄 검증(Batch-validate)하고, 취약한 항목은 폐기(kill)
/quality <draft>	보고서 점수 산정 1-10점 (7점 미만은 차단)
/report [format]	보고서 생성 (엄격한 관문: /validate PASS 필수)
/dupcheck <desc>	중복 확인을 위한 Hacktivity 및 Writeup DB 검색
/submit <finding>	제출 (엄격한 관문: /validate PASS 및 /quality ≥ 7 필수)

명령 (Command)	설명 (Description)
/resume <target>	재개 — 테스트되지 않은 엔드포인트(endpoints) 및 제안 사항 제시
/remember	타겟 간 학습(cross-target learning)을 위해 취약점/패턴 로그 기록
/learn <id> <status>	응답 기록 — 유료 기술(paid techniques) 자동 부스트
/brain	init, brief, status, endpoint, endpoints, record, exhausted

명령 (Command)	설명 (Description)
/new , /sync , /status	설정(Setup) + 대시보드(dashboard)
/pipeline , /quickscan , /fullscan	스캐닝 파이프라인 (Scanning pipelines)
/correlate	취약점 간의 발견 사항을 체이닝 (Chain discovery)
/cost , /monitor	비용 추적(Cost tracking), 타겟 변경 감지

xss-hunter (#60/#61/#62), sqli-hunter (#67), csrf-hunter (#57), ssrf-hunter (#75), ssti-hunter (#74), idor-hunter (#55), auth-tester (#27), info-disclosure (#18), open-redirect (#38), rce-hunter (#70), xxe-hunter (#63), file-upload (#39), cors-hunter (#58), subdomain-takeover (#145), business-logic (#28), race-condition (#29), privilege-escalation (#26), oauth-hunter (#1/#22/#106/#137), llm-ai-hunter (#18/#55/#61/#70/#106 기반 체인)

validator— 7-Question Gate + 제출 금지 목록 (PASS/KILL/DOWNGRADE/CHAIN)
chain-builder— 역량 테이블(capability table)에 기반한 A→B 체인 탐색, 검증된 체인을 찾기 위해 Writeup DB 검색
recon-ranker— P1/P2/공격 표면(Kill surface) 순위 지정

recon, vuln-scanner, config-auditor, cloud-recon, js-analyzer, waf-profiler, graphql-audit, nuclei-writer, browser-agent (Burp MCP), browser-stealth-agent (Camoufox)

brain, correlator, quality-check, monitor, poc-builder, report-writer, scope-check, browser-verifier (클라이언트 측 PoC proof), dast-devils-advocate (적대적 다운그레이드 (adversarial downgrade))

sast-file-ranker, sast-entry-mapper, sast-danger-mapper, sast-flow-tracer, sast-gap-analyzer, sast-devils-advocate, sast-hunter, sast-exploit-builder

web3-auditor — Solidity grep arsenal, Foundry PoC, DeFi patterns

hunt-* 스킬은 공개된 버그 바운티 (bug-bounty) 보고서에서 추출된 취약점 클래스별 특화 방법론 (methodology) 파일입니다. 각 스킬은 검증된 2024-2026 CVE 카탈로그와 하위 기술 (sub-techniques)을 포함하고 있습니다. 매칭되는 전문 에이전트는 테스트를 수행하기 전, Read $CLAUDE_PROJECT_DIR/skills/hunt-<class>/SKILL.md를 통해 해당 스킬을 읽어옵니다.