AI 기반 침투 테스트 MCP 서버
"일본 신화에서 텐구는 사나운 산의 정령입니다 — 전략가, 전사, 사무라이의 스승입니다. 사이버 보안에서는 사냥의 모든 단계에서 여러분을 안내합니다."
정찰부터 보고서까지 — 하나의 명령어로 AI 지원 침투 테스트.
Tengu는 Claude를 침투 테스트 코파일럿으로 변환하는 MCP 서버입니다. Nmap부터 Metasploit까지 80개의 보안 도구를 오케스트레이션하며, 내장된 안전 제어, 감사 로깅, 전문 보고 기능을 제공합니다.
Claude를 대화형 침투 테스트 코파일럿으로 사용하세요 — 사용자가 작업을 지시하면 Claude가 적절한 도구를 선택하고 자동으로 연결합니다.
git clone https://github.com/rfunix/tengu.git && cd tengu make docker-build make docker-up
실행 중인 서버에 Claude Code를 연결하십시오:```bash
claude mcp add --transport sse tengu http://localhost:8000/sse
Then ask Claude: Do a full pentest on http://192.168.1.100
Claude chains tools automatically: validate_target → whatweb → nmap → nikto →
nuclei → sqlmap → correlate_findings → generate_report
| Command | 시작하는 대상 |
|---|---|
파일 수정 없이 사용자 정의 대상 스캔:```bash TENGU_ALLOWED_HOSTS="192.168.1.0/24,10.0.0.0/8" make docker-up
### 이미지 계층
사용 사례에 맞는 크기를 선택하세요:
| 계층 | 크기 | MCP 도구 | 사용 사례 |
|------|------|-----------|----------|
| `minimal` | ~480MB | 17 | 가벼운 분석, CVE 연구, 보고서 작성 |
| `core` | ~7GB | 47 | 전체 침투 테스트 도구 모음 (기본값) |
| `full` | ~8GB | 80 | 전체 + AD, 무선, 스텔스/OPSEC |```bash
TENGU_TIER=minimal make docker-build # lightweight
TENGU_TIER=core make docker-build # default
TENGU_TIER=full make docker-build # everything
모든 티어에는 35개의 프롬프트와 20개의 리소스가 모두 포함되어 있습니다 — 바이너리 도구만 다릅니다.
사전 요구 사항: Python 3.12+, uv, Kali Linux (권장됨)```bash
git clone https://github.com/rfunix/tengu.git && cd tengu
uv sync
make install-tools
uv run tengu
Claude Code 연결:```bash
claude mcp add --scope user tengu -- uv run --directory /path/to/tengu tengu
tengu.toml에서 허용된 대상을 구성하십시오:```toml
[targets]
allowed_hosts = ["192.168.1.0/24", "example.com"]
Claude Desktop, VM/SSE 원격 설정 및 고급 구성에 대한 자세한 내용은 [docs/deployment-guide.md](https://github.com/rfunix/tengu/blob/HEAD/docs/deployment-guide.md)를 참조하십시오.
</details>
### 구성 참조```toml
[targets]
# REQUIRED: Only these hosts will be scanned
allowed_hosts = ["192.168.1.0/24", "example.com"]
blocked_hosts = [] # Always blocked, even if in allowed_hosts
[stealth]
enabled = false # Route traffic through Tor/proxy
[stealth.proxy]
enabled = false
type = "socks5h"
host = "127.0.0.1"
port = 9050
[osint]
shodan_api_key = "" # Required for shodan_lookup
[tools.defaults]
scan_timeout = 300 # seconds
make docker-upTengu MCP 서버 (:8000) |
make docker-lab | + Juice Shop, DVWA (안전한 연습 대상) |
make docker-pentest | + Metasploit, OWASP ZAP (실제 환경 대상) |
make docker-full | + Metasploit, ZAP, 그리고 실습 대상 |
전체 참조는 docs/configuration-reference.md를 참조하세요.
수동 도구 호출 없이 완전히 자율적인 펜테스트를 실행합니다. 에이전트는 Claude를 전략적 두뇌로, Tengu를 실행 도구 세트로 사용하며, 정찰부터 보고까지 PTES 방법론을 따릅니다.
cp .env.example .env
**실습 대상 (Juice Shop, DVWA):**```bash
make docker-lab
make docker-agent # default model (sonnet)
make docker-agent-haiku # cheaper — claude-haiku-4-5, max_tokens=1024
make docker-agent-sonnet # balanced — claude-sonnet-4-6, max_tokens=4096
실제 세계 침투 테스트 (Tengu + MSF + ZAP, 랩 컨테이너 없음):```bash make docker-pentest make docker-agent
**브라우저에서 보고서 보기:**```bash
make docker-report-view # http://localhost:8888 — styled HTML, all reports
make docker-report-browse # same, auto-opens browser
REPORT_PORT=9999 make docker-report-view # custom port
Docker 없이:```bash uv sync --extra agent python autonomous_tengu.py 192.168.1.100 --scope 192.168.1.0/24 --type blackbox
python autonomous_tengu.py 192.168.1.100 --model claude-haiku-4-5 --max-tokens 1024 --timeout 30
**비용 제어** — 세 가지 환경 변수 / CLI 플래그:
| 플래그 | 환경 변수 | 기본값 |
|---|---|---|
| `--model` | `TENGU_AGENT_MODEL` | `claude-sonnet-4-6` |
| `--max-tokens` | `TENGU_AGENT_MAX_TOKENS` | `2048` |
| `--timeout` | `TENGU_AGENT_TIMEOUT` | `60` (분, `0`=무제한) |
### 작동 방식```
START → initializer → strategist ─┬─→ executor → analyst ─┬─→ strategist (loop)
│ └─→ reporter → END
├─→ human_gate → executor
└─→ reporter → END
주요 동작:
msf_run_module, hydra_attack, impacket_kerberoast, level≥3의 sqlmap_scan) 실행 전에 개입합니다.--max-iterations에 도달할 때까지 실행됩니다.correlate_findings + score_risk + generate_report를 호출합니다.| 단계 | 이름 | Tengu의 역할 | 주요 도구 |
|---|---|---|---|
| 1 | 사전 계약(Pre-Engagement) | validate_target으로 범위 확인, check_tools로 준비 상태 확인 | validate_target, check_tools |
| 2 | 정보 수집(Intelligence Gathering) | OSINT, DNS 정찰, 서브도메인 수집, 기술 지문 수집 | nmap, subfinder, amass, shodan, whatweb |
| 3 | 위협 모델링(Threat Modeling) | Claude가 수집된 정보를 분석, 공격 표면 우선순위 지정, 위협 시나리오 구축 | (AI 기반 — 외부 도구 불필요) |
| 4 | 취약점 분석(Vulnerability Analysis) | 템플릿 스캐닝, 웹 애플리케이션 테스트, SSL/TLS 분석, 파라미터 퍼징 | nuclei, nikto, ffuf, sqlmap, testssl |
| 5 | 익스플로잇(Exploitation) | 확인된 취약점에 대한 통제된 익스플로잇 (Human-in-the-loop) | msf_run_module, sqlmap, hydra, searchsploit |
| 6 | 사후 익스플로잇(Post-Exploitation) | 자격 증명 수집, 측면 이동 평가, 권한 상승 | impacket_kerberoast, nxc_enum, enum4linux |
| 7 | 보고(Reporting) | 모든 발견 사항 연관, 위험 점수 계산, 전문 보고서 생성 | correlate_findings, score_risk, generate_report |
minimal(17개 도구, ~480MB) ·core(47개 도구, ~7GB, 기본값) ·full(80개 도구, ~8GB) 빌드:TENGU_TIER=<tier> make docker-build. 모든 티어에는 35개의 프롬프트와 20개의 리소스가 포함됩니다.
| 카테고리 | 도구 | 개수 |
|---|---|---|
| 정찰(Reconnaissance) | Nmap, Masscan, Amass, Subfinder, Gowitness, HTTrack, Katana, httpx, SNMPwalk, RustScan | 10 |
| 웹 스캐닝(Web Scanning) | Nikto, Nuclei, FFUF, Gobuster, WPScan, Feroxbuster, OWASP ZAP, wafw00f | 8 |
| SSL / TLS | sslyze, testssl.sh, HTTP 헤더 분석, CORS 테스터 | 4 |
| DNS | DNS Enumerate, DNSRecon, Subjack, WHOIS | 4 |
| OSINT | theHarvester, Shodan, WhatWeb, DNStwist | 4 |
| 인젝션 테스팅(Injection Testing) | SQLMap, Dalfox (XSS), Commix, CRLFuzz, GraphQL Security Check, Arjun | 6 |
| 무차별 대입(Brute Force) | Hydra, John the Ripper, Hashcat, CeWL | 4 |
| 익스플로잇(Exploitation) | Metasploit (search, info, run, sessions, cmd), SearchSploit | 6 |
| 사회 공학(Social Engineering) | SET 자격 증명 수집기, QR 코드 공격, 페이로드 생성기 | 3 |
| 시크릿 및 코드(Secrets & Code) | TruffleHog, Gitleaks | 2 |
| 컨테이너 및 클라우드(Container & Cloud) | Trivy, Checkov, ScoutSuite, Prowler | 4 |
| Active Directory | NetExec, Enum4linux, Impacket (Kerberoast, secretsdump, psexec, wmiexec, smbclient), BloodHound, Responder, SMBMap | 10 |
| 무선(Wireless) | aircrack-ng / airodump-ng | 1 |
| 익명성 및 스텔스(Anonymity & Stealth) | Tor 확인/로테이트, 프록시 확인, ID 로테이션 | 5 |
| 분석 및 보고(Analysis & Reporting) | 발견 사항 연관, CVSS 위험 점수, 보고서 생성 | 3 |
| CVE 인텔리전스(CVE Intelligence) | CVE 조회 (NVD), CVE 키워드/제품/심각도별 검색 | 2 |
| 유틸리티(Utility) | 도구 확인기, 대상 검증기 | 2 |
| 도구 | 설명 |
|---|---|
nmap_scan | 포트 스캐닝 및 서비스/OS 탐지 |
masscan_scan | 대규모 네트워크용 고속 포트 스캐너 |
subfinder_enum | 수동적 서브도메인 수집 |
amass_enum | 공격 표면 매핑 및 DNS 무차별 대입 |
dnsrecon_scan | DNS 정찰 (영역 전송, 무차별 대입, PTR) |
dns_enumerate | DNS 레코드 수집 (A, MX, NS, TXT, SOA…) |
whois_lookup | WHOIS 도메인 및 IP 조회 |
subjack_check | 서브도메인 탈취 탐지 |
gowitness_screenshot | 문서화를 위한 웹 스크린샷 캡처 |
httrack_mirror | 오프라인 분석 및 포렌식을 위한 전체 웹사이트 미러링 |
katana_crawl | 링크 발견 및 엔드포인트 매핑을 위한 고속 웹 크롤러 |
httpx_probe | HTTP 프로브 — 상태 코드, 기술 스택, 리디렉션 |
snmpwalk_scan | SNMP 수집 및 MIB 워킹 |
rustscan_scan | 초고속 포트 스캐닝 (Nmap 후속 스캔을 위한 열린 포트 발견) |
| 도구 | 설명 |
|---|---|
theharvester_scan | 공개 소스로부터 이메일, 서브도메인 및 호스트 수집 |
shodan_lookup | Shodan 호스트 및 자산 검색 |
whatweb_scan |
| 도구 | 설명 |
|---|---|
set_credential_harvester | 웹사이트를 복제하고 제출된 자격 증명 캡처 (승인된 피싱 시뮬레이션) |
set_qrcode_attack | 물리적 사회 공학 평가를 위해 URL을 가리키는 QR 코드 생성 |
set_payload_generator | 승인된 캠페인을 위한 사회 공학 페이로드 생성 (PowerShell, HTA) |
| 도구 | 설명 |
|---|---|
hydra_attack | 네트워크 로그인 무차별 대입 (SSH, FTP, HTTP, SMB…) |
hash_crack | 사전 기반 해시 크래킹 (Hashcat / John the Ripper) |
| 도구 | 설명 |
|---|---|
zap_spider | OWASP ZAP 웹 스파이더 |
zap_active_scan | OWASP ZAP 능동적 취약점 스캔 |
zap_get_alerts | ZAP 스캔 결과 검색 |
| 도구 | 설명 |
|---|---|
trufflehog_scan | Git 저장소에서 유출된 시크릿 탐지 |
gitleaks_scan | Git 히스토리에서 자격 증명 스캐닝 |
| 도구 | 설명 |
|---|---|
trivy_scan | Docker 이미지, IaC 및 SBOM에 대한 취약점 스캐닝 |
| 도구 | 설명 |
|---|---|
scoutsuite_scan | 클라우드 보안 감사 (AWS, Azure, GCP) |
prowler_scan | AWS/GCP/Azure 보안 모범 사례 및 규정 준수 감사 |
| 도구 | 설명 |
|---|---|
aircrack_scan | 수동적 무선 네트워크 스캔 (airodump-ng) |
| 도구 | 설명 |
|---|---|
checkov_scan | IaC 설정 오류 스캔 (Terraform, K8s, Dockerfile) |
Claude가 전체 작업을 수행하도록 안내하는 사전 구축된 워크플로우 템플릿입니다.
| 카테고리 | 프롬프트 |
|---|---|
| 침투 테스트 워크플로우 | full_pentest, quick_recon, web_app_assessment |
| 취약점 평가 | assess_injection, assess_access_control, assess_crypto, assess_misconfig |
| OSINT | osint_investigation |
| 보고서 | executive_report, technical_report, full_pentest_report, finding_detail, risk_matrix, remediation_plan, retest_report, save_report |
| 스텔스/OPSEC | stealth_assessment, opsec_checklist |
| 전문 분야 | ad_assessment, api_security_assessment, container_assessment, cloud_assessment, wireless_assessment, bug_bounty_workflow, compliance_assessment |
| 빠른 작업 | explore_url, map_network, hunt_subdomains, find_vulns, find_secrets, go_stealth, crack_wifi, pwn_target, msf_exploit_workflow |
| 사회 공학 | social_engineering_assessment |
Claude가 작업 중 로드하는 정적 참조 데이터입니다.
| URI | 내용 |
|---|---|
owasp://top10/2025 | OWASP Top 10:2025 전체 목록 |
owasp://top10/2025/{A01..A10} | 카테고리별 상세 정보 + 테스팅 체크리스트 |
owasp://api-security/top10 | OWASP API Security Top 10 (2023) |
owasp://api-security/top10/{API1..API10} | 카테고리별 상세 정보 |
ptes://phases | PTES 7단계 방법론 개요 |
ptes://phase/{1..7} | 단계별 상세 정보 (목표, 도구, 산출물) |
checklist://web-application | 웹 앱 침투 테스트 체크리스트 (OWASP 테스팅 가이드) |
checklist://api | API 침투 테스트 체크리스트 |
checklist://network | 네트워크 인프라 체크리스트 |
mitre://attack/tactics | MITRE ATT&CK 엔터프라이즈 전술 + 기법 |
mitre://attack/technique/{T1xxx} | ID별 기법 상세 정보 |
creds://defaults/{product} | 기본 자격 증명 데이터베이스 |
payloads://{type} | 유형별 큐레이션된 페이로드 목록 (xss, sqli, lfi, ssti 등) |
stealth://techniques | 작전 보안 기법 참조 가이드 |
stealth://proxy-guide | 단계별 프록시 및 Tor 설정 가이드 |
tools://catalog | 실시간 도구 가용성 상태 |
tools://{tool}/usage | nmap, nuclei, sqlmap, metasploit, trivy, amass 사용 가이드 |
prompts://list | 설명이 포함된 사용 가능한 모든 프롬프트 목록 |
prompts://category/{category} | 카테고리별로 필터링된 프롬프트 |
┌─────────────┐ MCP ┌─────────────────┐ subprocess ┌─────────────────┐ │ Claude │◄────────────►│ Tengu │─────────────────►│ Nmap, SQLMap, │ │ (Desktop / │ stdio/SSE │ MCP Server │ (never shell=T) │ Metasploit... │ │ Code) │ │ │ └─────────────────┘ └─────────────┘ └────────┬─────────┘ │ Every tool call passes through: │ ┌────────▼─────────┐ │ Safety Pipeline │ │ │ │ 1. sanitizer │ ← strip metacharacters, validate format │ 2. allowlist │ ← check target against tengu.toml │ 3. rate_limiter │ ← sliding window + concurrent slots │ 4. audit logger │ ← JSON log to ./logs/tengu-audit.log └──────────────────┘
---
## 설정 파일
Tengu는 세 가지 설정 파일을 사용합니다. 로컬과 Docker 워크플로우 간 전환 시 잘못된 파일을 수정하는 것이 가장 흔한 혼란의 원인입니다.
| 파일 | 사용 시기 | 제어 내용 |
|------|-------------|----------|
| `tengu.toml` (루트) | 로컬 실행 시: `uv run tengu`, `uv run python autonomous_tengu.py` | MCP 서버 구성: `allowed_hosts`, 도구 경로, 속도 제한, 은폐 |
| `docker/tengu.toml` | Docker를 통해 실행 시: `make docker-up`, `make docker-agent` | 루트와 동일한 설정이지만 Docker 네트워킹(`172.16.0.0/12`, 서비스 DNS 별칭)에 맞게 사전 구성됩니다. 빌드 시 이미지에 포함되므로 변경 후 **재빌드 필요**합니다 (`make docker-rebuild-tengu`) |
| `.env` | 로컬 및 Docker 모두 | 비밀 및 런타임 변수: `ANTHROPIC_API_KEY`, `TENGU_AGENT_TARGET`, `TENGU_AGENT_MODEL`, `TENGU_AGENT_MAX_TOKENS` 등. `docker compose` 및 `load_dotenv()`에서 읽습니다. |
| `.env.example` | 참조 전용 | 사용 가능한 모든 환경 변수를 나열하는 템플릿 |
**코파일럿 모드(로컬) 빠른 구성:** 프로젝트 루트의 `tengu.toml`을 편집하여 `[targets] allowed_hosts`에 대상을 추가하세요.
**에이전트 모드(Docker) 빠른 구성:** `docker/tengu.toml`을 편집한 후, `make docker-agent` 전에 `make docker-rebuild-tengu`를 실행하세요.
> **일반적인 실수:** Docker 내에서 스캔이 `TargetNotAllowedError`로 실패하면, 아마도 `docker/tengu.toml` 대신 `tengu.toml`(루트)을 편집한 것입니다. Docker는 이미지에 포함된 자체 복사본을 사용합니다. 편집 후 `make docker-rebuild-tengu`를 실행하세요.
---
## 안전 설계
Tengu는 자율적인 공격 도구가 아닌 **인간 펜테스터를 위한 역량 증폭기**로 구축되었습니다.
| 제어 | 설명 |
|---------|-------------|
| **대상 허용 목록** | `tengu.toml`에 사전 승인된 대상만 스캔됩니다. |
| **입력 검증** | 모든 입력은 도구에 도달하기 전에 엄격한 패턴에 대해 검증됩니다. |
| **속도 제한** | 슬라이딩 윈도우 + 동시 슬롯 제한으로 우발적인 DoS 방지 |
| **감사 로깅** | 모든 도구 호출이 JSON 형식으로 `./logs/tengu-audit.log`에 기록됩니다. |
| **인간 개입** | `msf_run_module`, `hydra_attack`, `impacket_kerberoast`는 명시적 확인이 필요합니다. |
| **shell=True 금지** | 모든 하위 프로세스 호출은 `asyncio.create_subprocess_exec`를 사용합니다. |
---
## 개발
---```bash
make install-dev # Install Python deps + dev extras
make test # Run unit + security tests
make lint # ruff check
make typecheck # mypy strict
make check # lint + typecheck
make coverage # pytest --cov
make inspect # Open MCP Inspector
make doctor # Check which pentest tools are installed
Tengu는 단위 로직, 보안(명령 삽입, 입력 검증) 및 통합 시나리오를 포괄하는 2643개 이상의 테스트를 보유하고 있습니다. 전체 기여자 가이드는 CLAUDE.md를 참조하세요.
Tengu는 인가된 보안 테스트만을 위해 설계되었습니다. 자신이 소유했거나 명시적인 서면 허가를 받은 시스템만 스캔하십시오. 무단 스캔은 대부분의 국가에서 불법입니다. 저자는 오용에 대해 어떠한 책임도 지지 않습니다.
| 도구 | 설명 |
|---|
nuclei_scan | 템플릿 기반 취약점 스캐너 (CVE, 설정 오류) |
nikto_scan | 웹 서버 설정 오류 및 오래된 소프트웨어 스캐너 |
ffuf_fuzz | 디렉터리, 파라미터 및 vhost 퍼징 |
gobuster_scan | 디렉터리, DNS 및 vhost 무차별 대입 |
wpscan_scan | WordPress 취약점 스캐너 |
testssl_check | 포괄적인 SSL/TLS 설정 분석 |
analyze_headers | HTTP 보안 헤더 분석 및 등급 부여 |
test_cors | CORS 설정 오류 탐지 |
ssl_tls_check | SSL/TLS 인증서 및 암호 확인 (sslyze) |
wafw00f_scan | 웹 애플리케이션 방화벽 탐지 및 지문 수집 |
feroxbuster_scan | 무차별 대입을 통한 고속 재귀적 콘텐츠 발견 |
| 웹 기술 지문 수집 (CMS, WAF, 프레임워크) |
dnstwist_scan | 도메인 변형 및 타이포스쿼팅 탐지 |
| 도구 | 설명 |
|---|
sqlmap_scan | 자동화된 SQL 인젝션 탐지 및 익스플로잇 |
xss_scan | Dalfox를 통한 XSS 탐지 |
commix_scan | 자동화된 커맨드 인젝션 탐지 및 익스플로잇 |
crlfuzz_scan | 헤더 인젝션 취약점을 위한 CRLF 인젝션 퍼징 |
graphql_security_check | GraphQL 인트로스펙션, 배칭, 깊이 제한, 필드 제안 |
arjun_discover | 숨겨진 HTTP 파라미터 발견 |
| 도구 | 설명 |
|---|
msf_search | Metasploit 모듈 검색 |
msf_module_info | 상세한 Metasploit 모듈 정보 획득 |
msf_run_module | Metasploit 모듈 실행 (명시적 확인 필요) |
msf_sessions_list | 활성 Metasploit 세션 목록 |
msf_session_cmd | 활성 세션에서 명령 실행 (shell/Meterpreter) |
searchsploit_query | Exploit-DB 오프라인 데이터베이스 검색 |
hash_identify |
| 해시 유형 식별 |
cewl_generate | 대상 웹사이트로부터 사용자 정의 단어 목록 생성 |
| 도구 | 설명 |
|---|
enum4linux_scan | SMB/NetBIOS 수집 |
nxc_enum | NetExec를 통한 Active Directory 수집 |
impacket_kerberoast | Impacket GetUserSPNs를 사용한 Kerberoasting |
impacket_secretsdump | Impacket을 통한 원격 SAM/LSA/NTDS 시크릿 덤프 |
impacket_psexec | SMB를 통한 원격 명령 실행 (PsExec 스타일) |
impacket_wmiexec | WMI를 통한 원격 명령 실행 |
impacket_smbclient | SMB 공유 수집 및 파일 접근 |
bloodhound_collect | BloodHound AD 데이터 수집 (SharpHound/bloodhound-python) |
responder_capture | 자격 증명 캡처를 위한 LLMNR/NBT-NS/MDNS 포이즈닝 |
smbmap_scan | SMB 공유 수집 및 접근 테스팅 |
| 도구 | 설명 |
|---|
tor_check | Tor 연결 및 종료 노드 IP 확인 |
tor_new_identity | 새 Tor 회로 요청 (NEWNYM) |
check_anonymity | 노출된 IP, DNS 누출 및 익명성 수준 확인 |
proxy_check | 프록시 지연 시간, 종료 IP 및 익명성 유형 검증 |
rotate_identity | Tor 회로와 사용자 에이전트 동시 로테이션 |
| 도구 | 설명 |
|---|
check_tools | 설치된 외부 도구 확인 |
validate_target | 허용 목록에 대해 대상 검증 |
correlate_findings | 여러 스캔에 걸쳐 발견 사항 연관 |
score_risk | CVSS 기반 위험 점수 계산 |
cve_lookup | NVD의 CVE 상세 정보 (CVSS, CWE, 영향을 받는 제품) |
cve_search | 키워드, 제품 또는 심각도별 CVE 검색 |
generate_report | Markdown/HTML/PDF 침투 테스트 보고서 생성 |