AI agent framework for black-box security testing with autonomous multi-agent orchestration, built-in pentesting tools, and MCP integration for bug bounty, red-team, and penetration testing workflows.
https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975
# Clone
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent
# Setup (creates venv, installs deps)
.\scripts\setup.ps1 # Windows
./scripts/setup.sh # Linux/macOS
# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1 # Windows
source venv/bin/activate # Linux/macOS
pip install -e ".[all]"
playwright install chromium # Required for browser tool
프로젝트 루트에 .env 파일을 생성하세요:
ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514
또는 OpenAI 사용 시:
OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5
LiteLLM 지원 모델 모두 사용 가능합니다.
OPENAI_API_BASE를 통해 PentestAgent를 모든 OpenAI 호환 엔드포인트로 연결할 수 있습니다:
OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>
Anthropic 호환 엔드포인트는 ANTHROPIC_API_BASE를 대신 사용하세요.
전체 제공자 정보와 임베딩 옵션은 .env.example을 참조하세요.
pentestagent # TUI 실행
pentestagent -t 192.168.1.1 # 대상 설정 후 실행
pentestagent tui --docker # Docker 컨테이너에서 도구 실행
격리 및 사전 설치된 침투 테스트 도구를 위해 Docker 컨테이너 내에서 도구를 실행합니다.
# nmap, netcat, curl이 포함된 기본 이미지
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
-e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
ghcr.io/gh05tcrew/pentestagent:latest
# metasploit, sqlmap, hydra 등이 포함된 Kali 이미지
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
ghcr.io/gh05tcrew/pentestagent:kali
# 빌드
docker compose build
# 실행
docker compose run --rm pentestagent
# 또는 Kali 사용 시
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali
컨테이너는 PentestAgent를 Linux 침투 테스트 도구에 접근 가능한 상태로 실행합니다. 에이전트는 터미널 도구를 통해 nmap, msfconsole, sqlmap 등을 직접 사용할 수 있습니다.
Docker가 설치 및 실행 중이어야 합니다.
PentestAgent는 TUI에서 명령어를 통해 접근할 수 있는 세 가지 모드를 제공합니다:
| 모드 | 명령어 | 설명 |
|---|---|---|
| 보조 | /assist <task> | 도구 실행이 포함된 단일 1회성 명령 |
| 에이전트 | /agent <task> | 단일 작업의 자율 실행 |
| 크루 | /crew <task> | 다중 에이전트 모드. 오케스트레이터가 전문화된 작업자를 생성 |
| 대화형 | /interact <task> | 대화형 모드. 에이전트와 채팅하며 침투 테스트 과정을 안내받음 |
/assist <task> 단일 1회성 명령.
/agent <task> 작업에 대한 자율 에이전트 실행
/crew <task> 작업에 대한 다중 에이전트 크루 실행
/interact <task> 가이드 모드에서 에이전트와 채팅
/target <host> 대상 설정
/tools 사용 가능한 도구 목록
/notes 저장된 노트 보기
/report 세션에서 보고서 생성
/memory 토큰/메모리 사용량 표시
/prompt 시스템 프롬프트 표시
/conversations 저장된 대화 보기 및 복원
/mcp <list/add> MCP 서버 시각화 또는 추가
/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
TUI에서 수동으로 하위 MCP 에이전트 생성
/despawn <server_name>
이전에 생성된 하위 에이전트 종료 및 제거
/clear 채팅 및 기록 지우기
/quit 종료 (/exit, /q 도 가능)
/help 도움말 표시 (/h, /? 도 가능)
Esc를 눌러 실행 중인 에이전트를 중지하세요. Ctrl+Q로 종료합니다.
PentestAgent에는 블랙박스 보안 테스트를 위한 사전 구축된 공격 플레이북이 포함되어 있습니다. 플레이북은 특정 보안 평가에 대한 구조화된 접근 방식을 정의합니다.
플레이북 실행:
pentestagent run -t example.com --playbook thp3_web
PentestAgent는 내장 도구를 포함하며 확장성을 위해 MCP(Model Context Protocol)를 지원합니다.
내장 도구: terminal, browser, notes, web_search (TAVILY_API_KEY 필요), spawn_mcp_agent
spawn_mcp_agent)spawn_mcp_agent는 실행 중인 에이전트가 stdio를 통해 연결된 하위 MCP 서버로 자신의 복사본을 생성할 수 있게 해주는 내장 도구입니다. 하위 프로세스는 완전히 격리됩니다(자체 런타임, LLM 클라이언트, 대화 기록, 노트 저장소). 생성 후 하위 프로세스의 전체 도구 세트가 상위 에이전트의 사용 가능한 도구에 주입됩니다.
이를 통해 외부 오케스트레이션 없이 계층적 다중 에이전트 워크플로가 가능해집니다: 에이전트는 필요에 따라 생성한 하위 에이전트에 범위가 지정된 하위 작업을 위임하여 자체 구성됩니다.
| 인수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
target | string | — | 하위 에이전트에 전달할 침투 테스트 대상 |
scope | string[] | — | 하위 에이전트의 대상/CIDR 범위 |
model | string | 환경 변수 | 모델 식별자, 하위 에이전트의 PENTESTAGENT_MODEL 덮어쓰기 |
no_rag | boolean | false | 하위 에이전트에서 RAG 엔진 초기화 건너뛰기 |
no_mcp | boolean | true | 하위 에이전트에서 외부 MCP 서버 연결 건너뛰기 (권장) |
spawn_mcp_agent가 반환된 후, 하위 에이전트의 도구(run_task, run_task_async, await_tasks 등)는 다음 도구 호출에서 사용 가능합니다. 하위 에이전트의 서버 이름은 자동으로 할당되며 (예: child_agent_1) 결과에 반환됩니다.
예시 — 오케스트레이터가 두 하위 에이전트에 병렬 정찰을 위임:
# 1회차: 두 개의 격리된 하위 에이전트 생성
spawn_mcp_agent target="10.0.1.0/24" scope=["10.0.1.0/24"]
spawn_mcp_agent target="10.0.2.0/24" scope=["10.0.2.0/24"]
# 2회차: 하위 에이전트 도구 사용 가능 — 비동기로 작업 위임
child_agent_1__run_task_async task="전체 포트 스캔 및 서비스 열거"
child_agent_2__run_task_async task="전체 포트 스캔 및 서비스 열거"
# 3회차: 대기 및 수집
child_agent_1__await_tasks task_ids=["<id1>"] timeout_seconds=600
child_agent_2__await_tasks task_ids=["<id2>"] timeout_seconds=600
child_agent_1__get_task_result task_id="<id1>"
child_agent_2__get_task_result task_id="<id2>"
/spawn 및 /despawn)자동 spawn_mcp_agent 도구 외에도 TUI는 두 가지 명령어를 제공하여 실행 중인 에이전트 루프와 독립적으로 하위 에이전트를 수동으로 생성 및 종료할 수 있습니다.
/spawn/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]
stdio를 통해 새 하위 MCP 에이전트를 생성하고 현재 세션에 연결합니다. 하위 에이전트는 TUI 사이드바에 접을 수 있는 터미널 패널로 나타나며, 다음 도구 호출 시 상위 에이전트가 해당 도구를 사용할 수 있게 됩니다.
| 인수 | 설명 |
|---|---|
target | 하위 에이전트에 전달할 침투 테스트 대상 (위치 인수 또는 --target) |
--scope CIDR | 하나 이상의 범위 내 CIDR (반복 가능) |
--model MODEL | 하위 에이전트의 모델 덮어쓰기 |
--no-rag | 하위 에이전트에서 RAG 엔진 초기화 건너뛰기 |
--no-mcp | 하위 에이전트에서 외부 MCP 서버 연결 건너뛰기 |
예시:
/spawn 10.0.1.1
/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag
/despawn/despawn <server_name>
server_name (예: child_agent_1)으로 식별된 하위 에이전트를 종료하고, TUI에서 터미널 패널을 제거하며, 상위 세션에서 해당 도구를 연결 해제합니다. 현재 활성화된 모든 하위 에이전트의 이름을 보려면 /mcp list를 사용하세요.
예시:
/despawn child_agent_1
MCP 서버가 128개 이상의 도구를 노출하는 경우, PentestAgent는 전체 카탈로그를 단일 mcp_<server>_rag_optimizer 도구로 자동 대체합니다. 이 메타 도구는 임베딩 유사도(LiteLLM 사용, 기본값 text-embedding-3-small)를 사용하여 현재 작업에 가장 관련성 높은 도구를 검색하고 다음 에이전트 턴에 주입합니다. 이를 통해 컨텍스트 창을 관리 가능하게 유지하면서 전체 도구 세트에 대한 액세스를 잃지 않습니다.
최적화 도구는 에이전트에게 투명하게 작동합니다. 에이전트는 필요한 기능을 설명하는 집중된 자연어 쿼리로 RAG 도구를 호출하면, 일치하는 도구가 다음 턴에 직접 호출 가능해집니다.
에이전트 사용 지침:
| 인수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
queries | string[] | (필수) | 필요한 기능당 하나의 집중 쿼리. 구체적일수록 정확도 상승 |
top_k | integer | 20 | 쿼리당 검색할 도구 수 (최대 128). 결과는 병합 및 중복 제거됨 |
임베딩은 시작 시 한 번 계산되어 캐시되므로 반복 쿼리가 빠릅니다. 최적화 도구는 서버별로 구축되므로 대규모 카탈로그를 가진 각 MCP 서버는 자체 독립 인덱스를 가집니다.
팁: 모든 것을 하나의 쿼리로 결합하는 대신, 각각의 고유 기능에 대해 하나의 쿼리를 전달하세요.
["호스트의 열린 포트 나열", "프로세스 메모리 사용량 가져오기"]는["포트 및 메모리 및 CPU 나열"]보다 더 나은 결과를 생성합니다.
PentestAgent는 두 방향으로 MCP(Model Context Protocol)를 지원합니다: 소비 - 외부 MCP 서버를 도구 소스로 사용, 그리고 자체 노출 - MCP 서버로서 외부 클라이언트(Claude Desktop, Cursor 등)가 PentestAgent를 프로그래밍 방식으로 구동할 수 있도록 합니다.