PentestAgent

AI 침투 테스트

https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

요구 사항

• Python 3.10+
• OpenAI, Anthropic 또는 LiteLLM 지원 공급자의 API 키

설치

# 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 지원 모델 모두 사용 가능합니다.

릴레이 / 사용자 정의 API 베이스 사용

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

격리 및 사전 설치된 침투 테스트 도구를 위해 Docker 컨테이너 내에서 도구를 실행합니다.

옵션 1: 사전 빌드된 이미지 가져오기 (가장 빠름)

# 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

옵션 2: 로컬에서 빌드

# 빌드
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에서 명령어를 통해 접근할 수 있는 세 가지 모드를 제공합니다:

TUI 명령어

/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 클라이언트, 대화 기록, 노트 저장소). 생성 후 하위 프로세스의 전체 도구 세트가 상위 에이전트의 사용 가능한 도구에 주입됩니다.

이를 통해 외부 오케스트레이션 없이 계층적 다중 에이전트 워크플로가 가능해집니다: 에이전트는 필요에 따라 생성한 하위 에이전트에 범위가 지정된 하위 작업을 위임하여 자체 구성됩니다.

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 사이드바에 접을 수 있는 터미널 패널로 나타나며, 다음 도구 호출 시 상위 에이전트가 해당 도구를 사용할 수 있게 됩니다.

예시:

/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 RAG 도구 최적화

MCP 서버가 128개 이상의 도구를 노출하는 경우, PentestAgent는 전체 카탈로그를 단일 mcp_<server>_rag_optimizer 도구로 자동 대체합니다. 이 메타 도구는 임베딩 유사도(LiteLLM 사용, 기본값 text-embedding-3-small)를 사용하여 현재 작업에 가장 관련성 높은 도구를 검색하고 다음 에이전트 턴에 주입합니다. 이를 통해 컨텍스트 창을 관리 가능하게 유지하면서 전체 도구 세트에 대한 액세스를 잃지 않습니다.

최적화 도구는 에이전트에게 투명하게 작동합니다. 에이전트는 필요한 기능을 설명하는 집중된 자연어 쿼리로 RAG 도구를 호출하면, 일치하는 도구가 다음 턴에 직접 호출 가능해집니다.

에이전트 사용 지침:

임베딩은 시작 시 한 번 계산되어 캐시되므로 반복 쿼리가 빠릅니다. 최적화 도구는 서버별로 구축되므로 대규모 카탈로그를 가진 각 MCP 서버는 자체 독립 인덱스를 가집니다.

팁: 모든 것을 하나의 쿼리로 결합하는 대신, 각각의 고유 기능에 대해 하나의 쿼리를 전달하세요. ["호스트의 열린 포트 나열", "프로세스 메모리 사용량 가져오기"]는 ["포트 및 메모리 및 CPU 나열"]보다 더 나은 결과를 생성합니다.

MCP 통합

PentestAgent는 두 방향으로 MCP(Model Context Protocol)를 지원합니다: 소비 - 외부 MCP 서버를 도구 소스로 사용, 그리고 자체 노출 - MCP 서버로서 외부 클라이언트(Claude Desktop, Cursor 등)가 PentestAgent를 프로그래밍 방식으로 구동할 수 있도록 합니다.

외부 MCP 서버 소비 (클라이언트 모드)

mcp_servers.json을 구성하여 PentestAgent를 모든 외부 MCP 서버에 연결하세요. 예시 설정:

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

PentestAgent를 MCP 서버로 노출 (서버 모드)

PentestAgent는 MCP 서버로 실행되어 MCP 호환 클라이언트가 원격으로 작업을 제출하고, 결과를 검사하며 에이전트를 제어할 수 있도록 합니다. 두 가지 전송 방식이 지원됩니다:

STDIO — 로컬 클라이언트용 (예: Claude Desktop, Cursor):

pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker

SSE (HTTP) — 원격 또는 네트워크 클라이언트용:

pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker

SSE 전송은 단일 /mcp 엔드포인트를 노출하며, POST (요청), GET (서버 시작 푸시용 영구 SSE 스트림), DELETE (세션 종료)를 지원합니다. 세션은 Mcp-Session-Id 헤더를 통해 추적됩니다.

모든 mcp_server 플래그:

예시: Claude Desktop 설정 (claude_desktop_config.json)

{
  "mcpServers": {
    "pentestagent": {
      "command": "pentestagent",
      "args": ["mcp_server", "--type", "stdio"]
    }
  }
}

MCP 서버 도구 참조

PentestAgent가 MCP 서버로 작동할 때 다음 도구를 노출합니다:

서버 상태 및 설정

작업 실행

작업 검사

작업 제어

도구 관리

대화 기록

메모리

관측 가능성

비동기 작업 워크플로 예시

장기 실행 정찰 작업에는 비동기 패턴을 사용하세요:

# 1. 차단 없이 작업 제출
run_task_async  task="example.com의 하위 도메인 열거"  target="example.com"
run_task_async  task="example.com에 nmap SYN 스캔 실행"  target="example.com"

# 2. 둘 다 완료될 때까지 대기 (최대 5분)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. 전체 결과 검색
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

CLI 도구 관리

pentestagent tools list         # 모든 도구 나열
pentestagent tools info <name>  # 도구 세부 정보 표시
pentestagent mcp list           # MCP 서버 나열
pentestagent mcp add <name> <command> [args...]  # MCP 서버 추가
pentestagent mcp test <name>    # MCP 연결 테스트

대화 기록 제어

TUI의 각 사용자 메시지에는 두 개의 인라인 액션 버튼이 있습니다: 되감기 및 분기.

되감기

사용자 메시지에서 되감기를 클릭하면 UI와 에이전트의 메모리 내 기록 모두에서 해당 메시지 직전으로 대화가 잘립니다. 버린 경로 없이 처음부터 질문을 다시 시도할 때 사용하세요.

분기

사용자 메시지에서 >> 분기를 클릭하면 해당 지점에서 대화를 분기합니다:

1. 현재 전체 대화가 대화 저장소에 저장되고 짧은 스냅샷 ID가 표시됩니다.
2. 그런 다음 대화가 선택한 메시지 직전으로 잘립니다 (되감기와 동일).

이를 통해 원래 스레드를 유지하면서 모든 지점에서 대체 접근 방식을 시도할 수 있으며, /conversations를 통해 검색할 수 있습니다.

대화 기록

PentestAgent는 모든 대화를 자동으로 저장하여 과거 세션을 검토, 비교 및 복원할 수 있습니다.

자동 저장은 각 /assist, /agent, /crew, /interact 작업 후 및 /clear 전에 트리거됩니다. 최대 20개의 대화가 유지되며, 오래된 것은 자동으로 정리됩니다.

저장 위치: 작업 공간이 활성화된 경우 workspaces/<active>/memory/conversations/, 그렇지 않으면 프로젝트 루트의 conversations/입니다. 각 대화는 JSON 파일입니다.

/conversations로 탐색 및 복원:

/conversations 명령어는 TUI 내에서 분할 패널 모달을 엽니다:

• 왼쪽 패널 — 제목과 날짜가 포함된 저장된 대화 목록.
• 오른쪽 패널 — 메타데이터 미리보기와 처음 5개 메시지 (사용자 메시지는 파란색, 에이전트 응답은 녹색, 도구 호출은 노란색, 도구 결과는 회색). 추가 메시지 수를 보여주는 카운트가 표시됩니다.

대화를 선택하고 복원을 누르면 현재 세션으로 다시 불러오거나 닫기를 눌러 모달을 해제할 수 있습니다.

지식

• RAG: pentestagent/knowledge/sources/에 방법론, CVE 또는 워드리스트를 배치하면 자동 컨텍스트 주입이 가능합니다.
• 노트: 에이전트는 결과를 loot/notes.json에 카테고리와 함께 저장합니다 (credential, vulnerability, finding, artifact). 노트는 세션 간에 유지되며 에이전트 컨텍스트에 주입됩니다.
• 섀도우 그래프: 크루 모드에서 오케스트레이터는 노트에서 지식 그래프를 구축하여 전략적 인사이트를 도출합니다 (예: "호스트 X에 대한 자격 증명이 있습니다").

프로젝트 구조

pentestagent/
  agents/         # 에이전트 구현
  config/         # 설정 및 상수
  interface/      # TUI 및 CLI
  knowledge/      # RAG 시스템 및 섀도우 그래프
  llm/            # LiteLLM 래퍼
  mcp/            # MCP 클라이언트 및 서버 설정
  playbooks/      # 공격 플레이북
  runtime/        # 실행 환경
  tools/          # 내장 도구

개발

pip install -e ".[dev]"
pytest                       # 테스트 실행
pytest --cov=pentestagent    # 커버리지 포함
black pentestagent           # 포맷팅
ruff check pentestagent      # 린트

법적 고지

명시적 승인을 받은 시스템에 대해서만 사용하십시오. 무단 접근은 불법입니다.

라이선스

MIT