pentest-ai
한 번의 명령으로 끝나는 자동 침투 시험

Claude Code 에 MCP 로 꽂아 쓰는 펜테스트 오케스트레이터. 17개 에이전트가 정찰부터 보고서까지 직접 돌리고, 60개 큐레이션 프로브 + 200개 외부 보안 툴 래퍼로 OWASP 주스샵 같은 SPA 에서 63% 챌린지 솔브률을 기록한다.

0먼저, 이 레포가 뭔가?

한 줄로 보면.

pentest-ai 는 "AI 에이전트한테 펜테스트(침투 시험)를 통째로 맡기는" 오픈소스 도구다. PyPI 에서 pip install ptai 한 줄이면 끝이고, 실행 명령도 ptai start https://target.example.com 한 줄이면 된다. 그러면 도구가 알아서 포트 스캔 → 로그인 → 웹 취약점 탐색 → 액티브 디렉토리(AD) 점령 → 클라우드 권한 상승 → 공격 체인 조합 → 검증 PoC 실행 → 마크다운/HTML/PDF 보고서 작성까지 끝낸다.

특이한 점은 LLM 을 두뇌로 쓰지만 탐지 자체는 "사람이 만든 결정론적 프로브"가 한다는 설계다. 즉 LLM 이 시키지 않아도 같은 60개 프로브가 똑같이 돌아가고, LLM 은 결과를 보고 다음에 뭘 칠지 고민하는 코디네이터 역할만 맡는다. 그래서 API 키 없이 Claude Code 의 구독만으로도 쓸 수 있다.

1왜 지금 주목받는가

트렌드시프트 12위에 오른 이유.

경쟁 도구 대비 차별점은 명확하다.

2기술 스택 전체 지도

패키지 매니페스트(pyproject.toml)에서 직접 뜯어본 의존성.

pentest-ai 는 Python 3.10+ 단일 언어 패키지로, 코어 의존성은 의도적으로 가볍게 유지하고 무거운 기능들은 optional-dependencies 그룹으로 분리해 둔다. 사용자가 필요한 surface 만 골라 깔 수 있도록.

코어 의존성 (항상 깔림)

Optional Dependencies (필요할 때만 깔림)

외부 보안 도구 (시스템 PATH 에서 호출)

pentest-ai 자체에 포함되지 않은 200+ 외부 CLI 들. ptai setup --tier core 로 6 개 핵심만, --tier recommended 로 30 개, --tier full 로 전부 설치. 엔터프라이즈처럼 "모든 도구를 시스템에 깔지 못하게" 막혀 있어도 해당 도구를 호출하는 경로만 자동으로 건너뛰는 우아한 폴백이 있다.

• 네트워크 — nmap, masscan, naabu, rustscan, hping3
• 웹 — sqlmap, ffuf, gobuster, wpscan, nuclei(4000+ 템플릿), dalfox, xsstrike, nikto, wapiti, paramspider
• AD — enum4linux, ldapsearch, bloodhound-python, kerbrute, impacket suite(전체)
• 패스워드 — hydra, hashcat, john, medusa
• 클라우드 — prowler, scout-suite, trivy, kube-hunter
• 비밀 — trufflehog, gitleaks (코드 저장소 시크릿 스캔)
• OSINT — subfinder, amass, shodan-cli

3아키텍처 심화 분석

390 줄짜리 오케스트레이터 가 어떻게 17 에이전트를 굴리는가.

전체 흐름을 ASCII 로 그리면 이렇다. 화살표는 데이터 흐름이고, 각 박스는 별도 모듈이다.

┌──────────────────────────────────────────────────────────────┐
│  Claude Code / Cursor / Codex  (MCP client, LLM 두뇌 역할)     │
└────────────────────────────┬─────────────────────────────────┘
                             │ JSON-RPC over stdio
                             ▼
┌──────────────────────────────────────────────────────────────┐
│  mcp_server/server.py     FastMCP @mcp.tool() × 49 도구       │
│  start_engagement / list_tools / run_tool / run_probe / ...   │
└────────────────────────────┬─────────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────────┐
│  engine/orchestrator.py   AgentOrchestrator                   │
│  ─────────────────────────────────────────────────────────    │
│  PHASE_ORDER = [recon, web, ad, cloud, mobile, chaining,      │
│                 validation, detection, report]                │
│                                                                │
│  for phase in PHASE_ORDER:                                    │
│      agent.run(scope, rate_limiter, auth, llm)                │
└────────────────────────────┬─────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
   ┌─────────┐         ┌──────────┐        ┌──────────┐
   │ recon   │         │  web     │        │   ad     │
   │ agent   │         │  agent   │        │  agent   │
   └────┬────┘         └────┬─────┘        └────┬─────┘
        │                   │                   │
        ▼                   ▼                   ▼
   ┌─────────────────────────────────────────────────┐
   │  tools/registry.py    ToolRegistry (200+ wrap)  │
   │  + SecurityTool 데이터클래스 — command·parser    │
   │  + BLOCKED_ARG_KEYS — 인자 화이트리스트          │
   │  + intensity-aware cache                        │
   └────────────────────────┬────────────────────────┘
                            │ subprocess.run / asyncio
                            ▼
                   ┌──────────────────┐
                   │  외부 보안 도구   │
                   │ nmap, sqlmap,    │
                   │ hydra, impacket  │
                   └────────┬─────────┘
                            ▼
        ┌──────────────────────────────────────────┐
        │  engine/findings_db.py (aiosqlite)        │
        │  scope-guarded · deduplicated · evidence  │
        └────────────────────┬─────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌─────────┐    ┌──────────┐   ┌──────────┐
        │ chain   │    │ poc_val. │   │ detection│
        │ agent   │    │ agent    │   │ agent    │
        └────┬────┘    └────┬─────┘   └────┬─────┘
             └──────────────┼───────────────┘
                            ▼
                    ┌───────────────┐
                    │ report agent  │  md/html/pdf/SARIF/JUnit
                    └───────────────┘

핵심 설계 패턴 1 — Phase 순차 오케스트레이션

engine/orchestrator.py 의 PHASE_ORDER 리스트는 9 단계가 무조건 이 순서로 실행된다. 한 단계가 끝나야 다음 단계가 들어가고, 단계마다 findings DB 에 결과가 쌓인다. "recon 이 끝나야 web 이 의미가 있고, web 이 끝나야 chain 이 의미가 있다" 는 펜테스트 방법론이 코드 구조로 그대로 박혀 있다.

핵심 설계 패턴 2 — LLM-coordinated, not LLM-dependent

READme 의 다섯 강조점 중 가장 중요한 설계 결정. LLM 이 없어도 같은 60 개 프로브가 똑같이 돌아간다. LLM 은 "이 finding 으로 다음에 어디를 칠까" 같은 추론만 담당하고, 실제 탐지 로직은 사람이 큐레이션한 결정론적 파이썬 함수다.

핵심 설계 패턴 3 — Scope Enforcement (범위 강제)

오펜시브 도구의 가장 위험한 실패 모드는 "허락받지 않은 시스템을 공격해 버리는 것". pentest-ai 는 engine/scope.py 의 ScopeEnforcer 가 모든 도구 호출 직전에 타깃 호스트가 사전에 선언된 범위 안인지 검증한다. strict_scope=true 옵션을 켜면 HTTP 302 리다이렉트도 따라가지 않는다. 공격자가 http://victim.com/redirect?url=http://attacker.com 같은 트릭으로 스캔을 빼돌릴 수 없다.

핵심 설계 패턴 4 — Rate Limiter + Scan Profile

ScanProfile.from_intensity(intensity) 가 stealth/safe/normal/aggressive 4 단계 강도에 따라 RPS(초당 요청 수)·동시성·재시도 정책을 동적으로 잡아 준다. 운영 중인 서비스를 다운시키지 않으려는 안전장치. HTTP 429 응답을 받으면 Retry-After 헤더를 존중한다(0.15.1 새 기능).

핵심 설계 패턴 5 — Tool Argument Whitelist

tools/registry.py 의 BLOCKED_ARG_KEYS 집합은 LLM 이 도구에 절대 못 넣게 막아야 하는 위험한 인자들이다.

BLOCKED_ARG_KEYS = frozenset({
    "script", "script-args", "output", "oN", "oX", "oG", "oA",
    "exec", "eval", "command", "cmd", "shell", "system",
    "upload", "download", "write", "config",
})

LLM 이 nmap --script vulners {target} 처럼 임의의 NSE 스크립트를 실행하려 하면 차단된다. 키 이름 검증(^[a-zA-Z0-9_-]+$) 과 값 검증(;|&\`$ 등 셸 메타문자 거부) 까지 더해서 LLM 프롬프트 인젝션이 셸 인젝션으로 번지는 경로를 막는다.

핵심 설계 패턴 6 — HITL (Human-In-The-Loop) 텔레오퍼레이션

엔게이지먼트 진행 중 Ctrl+C 를 600 밀리초 안에 두 번 누르면 오케스트레이터가 멈추고 REPL 로 떨어진다. step(다음 한 phase 만), inspect findings, inject <instruction>(LLM 에 추가 지시), skip, resume, abort. 사람이 중간에 개입할 수 있게 명시적으로 설계되어 있다.

4디렉토리 구조 해부

35,000 줄짜리 코드베이스를 조감하면.

pentest-ai/
├── cli/                  # ptai CLI 진입점 (Typer)
│   ├── main.py            # 42개 서브커맨드 (3,154 줄)
│   ├── auth.py            # 인증 프로필 관리
│   ├── menu.py            # 비-LLM 사용자용 numeric 메뉴
│   ├── install_wizard.py  # 200 개 외부 도구 설치 마법사
│   └── mcp_setup.py       # 다른 MCP 클라이언트 자동 설정
│
├── mcp_server/           # FastMCP 서버 (LLM 노출 surface)
│   ├── server.py          # @mcp.tool() 전체 모듈 합산 약 57개 (1,821 줄)
│   ├── auth.py
│   └── security_tools.py
│
├── api/                  # FastAPI HTTP 대안
│   ├── server.py
│   └── static/            # 로컬 웹 대시보드
│
├── engine/               # 핵심 비즈니스 로직
│   ├── orchestrator.py    # 9-phase 코디네이터 (390 줄)
│   ├── agent_loop.py      # LLM 에이전트 루프 (456 줄)
│   ├── findings_db.py     # SQLite + evidence storage
│   ├── scope.py           # ScopeEnforcer
│   ├── auth_handler.py    # JWT/cookie/Basic auth 핸들링
│   ├── rate_limiter.py    # ScanProfile (stealth..aggressive)
│   ├── playbook.py        # YAML 플레이북 실행기
│   ├── hitl.py            # Ctrl+C 두 번 REPL
│   ├── cvss.py            # CVSS v3.1 점수 계산
│   ├── sarif.py           # SARIF 2.1.0 출력
│   ├── junit_xml.py       # JUnit XML 출력
│   ├── tracing.py         # OpenTelemetry 통합
│   ├── llm/               # LLM 클라이언트 (LiteLLM, Anthropic, OpenAI, Ollama)
│   └── probes/            # 60 개 큐레이션 프로브 (SPA-aware)
│
├── agents/               # 17 개 전문 에이전트
│   ├── base.py            # BaseAgent 추상 클래스
│   ├── recon/             # 정찰
│   ├── web/               # 웹 + spa_probes.py
│   ├── api_security/      # OpenAPI/GraphQL OWASP API Top 10
│   ├── ad/                # Active Directory
│   ├── cloud/             # AWS/Azure/GCP
│   ├── mobile/, wireless/, browser/
│   ├── credential_tester/
│   ├── privesc/           # 권한 상승
│   ├── vuln_scanner/
│   ├── exploit_chain/     # 멀티-스텝 공격 체인
│   ├── poc_validator/     # 비파괴 PoC 실행
│   ├── detection/         # Sigma/SPL/KQL 룰 생성
│   ├── llm_redteam/       # OWASP LLM Top 10
│   ├── social_engineer/   # phishing corpus
│   ├── report/            # 최종 보고서 (Jinja2 템플릿)
│   └── selection/         # 에이전트 라우팅
│
├── tools/                # 200+ 도구 래퍼
│   ├── registry.py        # ToolRegistry (1,578 줄)
│   ├── network/           # nmap, masscan, ...
│   ├── web/               # sqlmap, ffuf, ...
│   ├── osint/, cloud/, binary/, password/
│   ├── wordlists/         # 번들 폴백 단어사전
│   └── plugin_loader.py   # 외부 MCP 서버 합치기
│
├── playbooks/builtin/    # 3 개 기본 플레이북 (.yaml)
│   ├── external-recon.yaml
│   ├── web-app-quick.yaml
│   ├── llm-app-redteam.yaml
│   └── ...
│
├── config/               # 기본 설정 (pentest-ai.yaml)
├── benchmarks/           # 재현 가능 벤치마크 하니스
│   ├── challenges/        # 합법 타깃 정의 (Juice Shop 등)
│   ├── scripts/run_all.sh
│   └── results/2026-05-12/juice-shop/  # raw 출력 보관
│
├── docs/                 # 사용자 문서
│   ├── benchmarks/juice-shop.md
│   ├── ci-cd.md
│   ├── credentialed-scans.md
│   └── ROADMAP.md
│
├── tests/                # 1,000+ pytest (Python 3.10–3.13)
│   └── honeypot/          # 자체 honeypot 회귀 테스트 (10/10 강제)
│
├── pyproject.toml        # 의존성 + 도구 설정
├── Dockerfile            # multi-stage (prod / dev)
├── docker-compose.yml
├── AGENTS.md             # AI 코딩 에이전트용 기여 가이드
├── SECURITY.md           # 취약점 공개 정책
├── DISCLAIMER.md         # AUP 동의 텍스트
└── CHANGELOG.md          # 42KB, 릴리즈별 상세 기록

두 가지 주목 포인트.

5학습 포인트 (기술별)

이 레포에서 한 가지씩 떼어 가져갈 것.

6하드웨어 / 시스템 요구사항

실제로 돌리려면 뭐가 필요한가.

다행히 가볍다. 코어 자체는 Python 만 있으면 되고, 무거운 건 외부 보안 도구 쪽이다.

• OS — Linux, macOS, Windows(WSL2 권장). Kali Linux 가 가장 마찰 없음.
• Python — 3.10 이상. 3.10/3.11/3.12/3.13 모두 CI 매트릭스에서 테스트.
• 메모리 — 4 GB 면 코어 구동. 200 개 도구를 전부 깔고 동시에 돌리면 8 GB+ 권장.
• 디스크 — 코어 100 MB, full tier 설치 시 nuclei 템플릿 + 단어사전 포함 ~3 GB.
• 네트워크 — 활성 정찰을 하므로 타깃 도달 가능해야 함. 회사 네트워크에서 nmap 차단되면 일부 도구 폴백.
• 권한 — masscan 등 raw socket 쓰는 도구는 root/sudo 필요. 대부분 도구는 일반 사용자로 충분.
• GPU — 필요 없음. LLM 추론은 외부 API(Claude/OpenAI/Ollama) 가 담당.
• LLM — Path 1(MCP)이면 Claude Pro/Max 구독 하나면 됨. Path 3(Standalone)이면 ANTHROPIC_API_KEY, OPENAI_API_KEY, 또는 로컬 Ollama 중 하나.
• 비용 캡 — Path 3 의 자율 에이전트 루프는 폭주 방지로 엔게이지먼트당 $10 기본. PTAI_PRICE_LIMIT=25 같은 env 로 조정.

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

난이도별 5 개. 합법 타깃에서만 시도할 것.

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

8 주 코스로 보면.

9핵심 키워드 사전

레포 곳곳에 나오는 약자·전문 용어 정리.

10참고 링크

더 깊이 파고들 때 직접 열어 볼 1차 출처와 핵심 기술 문서.

• GitHub 레포 — 0xSteph/pentest-ai · 원문 소스 코드 · MIT 라이선스 · 본문에서 인용한 모든 파일(orchestrator.py, registry.py 등)의 출처.
• 공식 사이트 — pentestai.xyz · 설치·사용 가이드와 3가지 통합 경로(MCP / API / Standalone) 소개.
• PyPI 패키지 — ptai · pip install ptai 의 배포처. 릴리즈별 버전과 의존성 확인.
• 벤치마크 문서 — Juice Shop · ptai vs ZAP vs Nuclei 비교 수치와 재현 방법(본문 차별점 4의 근거).
• 관련 레포 — pentest-ai-agents · 같은 제작자가 만든 Claude Code 서브에이전트 모음(별도 프로젝트).
• MCP 공식 사양 — modelcontextprotocol.io · pentest-ai 가 LLM 에 도구를 노출하는 표준 프로토콜의 공식 문서(본문 4주차 학습 자료).
• FastMCP 문서 — gofastmcp.com · @mcp.tool() 데코레이터로 MCP 서버를 짜는 프레임워크 가이드(학습 포인트 1의 기술).
• OWASP Juice Shop · 실습 1·2에서 타깃으로 쓰는 합법 취약 웹 앱의 공식 레포.
• impacket (Fortra) · Kerberoasting·DCSync 등 AD 공격을 Python 으로 구현한 라이브러리(학습 포인트 4·5주차 로드맵).
• BloodHound (SpecterOps) · AD 권한 그래프를 시각화하는 도구의 공식 레포.
• OWASP Top 10 · 1주차 로드맵의 기준이 되는 웹 보안 취약점 표준 목록.