Claude-BugHunter 딥다이브
— 버그헌팅 절차 전체를 71개 Claude Code "스킬"로 부호화한 보안 운영 번들

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

Claude-BugHunter는 Agent Skills 표준(SKILL.md 형식)으로 짜인 보안 번들이다. 71개 스킬은 크게 네 층으로 쌓인다 — ① 생각(Think): 방법론·레드팀 마인드셋, ② 웹앱 헌트: 48개 hunt-* 취약점 클래스 스킬, ③ 외부 경계 공격: 기업 플랫폼(M365/Entra·Okta·SharePoint·vCenter·SSL-VPN 등) CVE 체인, ④ 마무리(Ship): 검증 게이트·보고서·증거 위생. Claude Code 외에 OpenCode·Codex CLI·Hermes Agent에서도 같은 스킬 파일이 로드된다.

2왜 주목받는가

트렌딩 이유 · "한 줄 프롬프트" 보안 셋업 대비 장점.

대부분의 "보안용 Claude 셋업"은 두 가지 극단 중 하나다 — 너무 일반적이거나("당신은 보안 전문가다…"라는 거대 프롬프트 한 장), 너무 파편적이거나(공개 신고서 30개를 북마크해 매번 다시 읽음). 둘 다 두 번째 타깃부터 무너진다. Claude-BugHunter가 스타를 모으는 이유는 이 사이의 "구조화된 운영 지식 라이브러리"라는 자리를 차지했기 때문이다.

3기술 스택 전체 지도

지식 층(스킬)·실행 층(명령/엔진)·통합 층 각각.

① 지식 층 — 71개 스킬 (마크다운)

번들의 본체는 코드가 아니라 71개의 SKILL.md 문서다. 각 스킬은 폴더 하나에 마크다운 한 장이며, 프런트매터(name·description·선택적 report_count·sources)와 본문(탐지 신호·페이로드·우회표·체인 템플릿)으로 구성된다. 토픽별로 분류된다.

② 실행 층 — 15개 슬래시 명령 + 엔진

스킬이 "지식"이라면, commands/의 15개 슬래시 명령은 "워크플로 진입점"이다. Claude Code 전용이며, 핵심 흐름을 단계적으로 안내한다.

그 아래에 engine/(파이썬)이 있다 — 결정적 의사결정 지원 엔진이다. 정찰·파라미터 발견·시크릿 스캔·서비스 핑거프린트·카테고리화까지를 LLM 없이 순수 파이썬 + 수동(passive) 도구로 수행해 "공짜, 에이전트 없이, 레이트리밋 소모 없이" 표면을 그린다. LLM(에이전트)은 옵트인 헌트의 소수 판단 지점에만 쓴다.

③ 통합 · 배포 층

4아키텍처 심화 분석

6단계 워크플로 + 토픽 기반 스킬 자동 라우팅 + 검증 게이트.

전체 흐름 한눈에 — 6단계, 비선형

번들은 SCOPE → RECON → HUNT → VALIDATE → CAPTURE → REPORT의 6단계로 매핑된다. 비선형이라 어느 단계에서든 끼어들 수 있다. 핵심 통찰은 "넓이(breadth)는 결정적 코드로 공짜·가시적으로, 깊이(판단)는 사람과 소수 에이전트로" — 표면을 그리는 일은 LLM 없이, 실제 공격 판단은 옵트인으로 한다.

패턴 ① — 토픽 기반 스킬 자동 라우팅

이 번들의 가장 영리한 부분이다. 사용자가 "이 엔드포인트에 ?url= 파라미터가 보여"라고 평문으로 말하면, Claude는 71개 스킬의 description을 토픽 매칭해 hunt-ssrf 하나만 컨텍스트로 끌어온다. 이름으로 호출하지 않는다. 엔진의 skill_map.py는 이 매칭을 코드로도 구현해, 발견한 표면을 결정적으로 스킬에 배정한다.

# 공격 클래스 → 번들 안의 hunt 스킬
CLASS_SKILL = {
  "ssrf": ["hunt-ssrf"], "idor": ["hunt-idor"],
  "xss":  ["hunt-xss", "hunt-dom"], "lfi": ["hunt-lfi"],
  "graphql": ["hunt-graphql"], "secret": ["hunt-source-leak"], ...
}
# 탐지된 기술 → 기술별 스킬
TECH_SKILL = {
  "next.js": ["hunt-nextjs"], "laravel": ["hunt-laravel"],
  "sharepoint": ["hunt-sharepoint"], ...
}
# 클래스별 "첫 curl" — OOB가 필요한 건 그렇게 주석
CLASS_PROBE = {
  "ssrf": 'curl -s "{ur}http://169.254.169.254/latest/meta-data/"'
          '   # 블라인드는 Burp Collaborator(OOB)',
  "idor": 'curl -s "{u}"   # 두 신원으로 id 바꿔 호출 → 본문 diff',
  ...
}

패턴 ② — "OOB-or-it-didn't-happen" 게이트 (진단의 엄정함)

이 번들이 단순 페이로드 모음과 다른 결정적 지점. 각 hunt-* 스킬은 "무엇이 확증이 아닌가"를 먼저 가르친다. 예컨대 hunt-ssrf는 "에러 메시지가 URL을 그대로 되비추는 것은 SSRF 확증이 아니다"라고 못 박는다 — 그건 서버가 입력을 에러 문자열에 끼워 넣은 것일 뿐, 실제로 외부 연결을 한 게 아니기 때문이다.

5디렉토리 구조 해부

스킬(지식) · 명령(워크플로) · 엔진(오케스트레이션)의 3분할.

6학습 포인트 (기술별)

보안 지식의 코드화·자동화 설계에서 무엇을 배우나.

A. Agent Skill 패턴 — 절차 지식을 문서로 외부화

이 레포는 "전문가의 절차 지식을 어떻게 재사용 가능한 단위로 패키징하나"의 살아 있는 교본이다. 핵심은 ① 폴더+SKILL.md 한 장이라는 최소 단위, ② 프런트매터 description이 "언제 이 스킬을 로드할지"의 트리거가 되는 설계, ③ 토픽 매칭으로 필요한 것만 컨텍스트에 끌어오는 지연 로딩. 거대 단일 프롬프트(전부 항상 로드)와 정반대 철학이다 — 토큰을 아끼고 정확도를 높인다.

B. 결정적 vs 에이전트 분리 — 비용·재현성 설계

가장 값진 통찰. "넓이는 결정적 코드로 공짜·재현 가능하게, 좁은 판단만 LLM으로"라는 분할이다. 정찰·랭킹·스킬 매핑은 순수 파이썬이라 $0·재현 가능·레이트리밋 무소모이고, LLM은 옵트인 헌트의 몇 안 되는 판단 지점에만 투입된다. 이는 보안뿐 아니라 모든 LLM 에이전트 파이프라인(어디까지 코드로, 어디부터 모델로)에 그대로 옮길 수 있는 원칙이다.

C. 검증 게이트 — "가능"과 "유효"의 분리

triage-validation의 7문항 게이트와 각 스킬의 "확증이 아닌 것" 표는 "기술적으로 가능"을 "실제로 보고 가능"과 절대 같게 취급하지 않는 규율을 코드화한다. SSRF에서 "에러가 URL을 되비춤"을 확증으로 오인하지 않는 것처럼 — 이는 OSINT·모니터링·QA·데이터 검증 등 "외부 신호로 사실을 판정하는 모든 일"에 적용되는 원칙이다. 거짓 양성(false positive)을 거르는 자세 자체가 자산이다.

D. 증거 위생 — 결과물에서 민감정보 제거

evidence-hygiene 스킬은 "스크린샷·HAR·로그에서 쿠키·PII를 어떻게 지우나"를 절차로 만든다 — 쿠키 마스킹 시점, 타인 데이터/얼굴/주소의 블랙바, jq로 HAR 정제, 제출 후 시크릿 회전. 이는 보안 보고뿐 아니라 버그 리포트·로그 공유·데이터셋 공개 등 "산출물에 민감정보가 섞이는 모든 상황"의 체크리스트로 재사용된다.

E. 플러그인·다중 하네스 배포

같은 SKILL.md 파일이 Claude Code·OpenCode·Codex CLI·Hermes 4종에서 로드되는 점, 그리고 marketplace.json으로 /plugin install 한 줄 설치되는 점은 "표준 포맷에 맞추면 배포·이식이 공짜"라는 교훈이다. lint_skills.py가 description 길이·본문 줄 수·식별자 denylist를 자동 검사하는 것도 "기여를 받되 품질을 코드로 강제"하는 좋은 예다.

7시스템 / 환경 요구사항

설치는 가볍다. 그러나 "인가(authorization)"가 가장 중요한 요구사항이다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 모두 본인 자산 / 연습용 취약 사이트(Juice Shop·DVWA 등)로만 안전하게.

9관련 기술 심화 학습 로드맵

6주 코스 — 웹 보안 기초부터 보안 자동화 설계까지(전부 방어·진단 관점).

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: elementalsouls/Claude-BugHunter (README · INSTALL · USAGE · SECURITY)
• 문서: docs/architecture.md · 검색 가능한 스킬 카탈로그
• Claude Code 스킬: Agent Skills 공식 문서
• 자매 프로젝트: Claude-OSINT(정찰 단계) · 벤더 기반: shuvonsec/claude-bug-bounty
• 학습(방어·연습): PortSwigger Web Security Academy · OWASP Juice Shop
• 안전장치: Anthropic Cyber Verification Program(CVP)
• 도구: ProjectDiscovery · Burp Suite + MCP