GH05TCREW/pentestagent

ghostcrew_demo.mp4

Python 3.10+
OpenAI, Anthropic 또는 기타 LiteLLM 지원 제공업체의 API 키

# Clone (복제)
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent
...

.env 파일 생성

프로젝트 루트(root)에서:

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 호환 엔드포인트(endpoint)로 지정할 수 있습니다:

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<your-relay-on-your-relay-model-name>

Anthropic 호환 엔드포인트를 사용하는 경우에는 대신 ANTHROPIC_API_BASE를 사용하십시오.

전체 제공업체 참고 사항 및 임베딩(embedding) 옵션은 .env.example을 참조하십시오.

pentestagent # TUI(Text User Interface) 실행
pentestagent -t 192.168.1.1 # 타겟과 함께 실행
pentestagent tui --docker # Docker 컨테이너에서 도구 실행

격리(isolation) 및 사전 설치된 침투 테스트(pentesting) 도구를 위해 Docker 컨테이너 내부에서 도구를 실행하십시오.

# nmap, netcat, curl이 포함된 베이스 이미지 (Base image)
docker run -it --rm \
-e ANTHROPIC_API_KEY=your-key \
...

# Build (빌드)
docker compose build
# Run (실행)
...

컨테이너는 Linux 침투 테스트 도구에 접근할 수 있는 상태로 PentestAgent를 실행합니다. 에이전트는 터미널 도구를 통해 nmap, msfconsole, sqlmap 등을 직접 사용할 수 있습니다.

Docker가 설치되어 있고 실행 중이어야 합니다.

PentestAgent에는 세 가지 모드가 있으며, TUI의 명령어를 통해 접근할 수 있습니다:

모드 (Mode)	명령어 (Command)	설명 (Description)
Assist	`/assist <task>`	도구 실행을 포함한 단일 샷(single-shot) 지침
Agent	`/agent <task>`	단일 작업의 자율적 실행
Crew	`/crew <task>`	멀티 에이전트(Multi-agent) 모드. 오케스트레이터(Orchestrator)가 특화된 워커(worker)를 생성
Interact	`/interact <task>`	대화형(Interactive) 모드. 에이전트와 채팅하며 침투 테스트 절차 동안 도움과 안내를 받음

/assist <task> 단일 샷 지침.
/agent <task> 작업에 대해 자율 에이전트 실행
/crew <task> 작업에 대해 멀티 에이전트 크루(crew) 실행
...

실행 중인 에이전트를 중지하려면 Esc를 누르세요. 종료하려면 Ctrl+Q를 누르세요.

PentestAgent는 블랙박스 보안 테스트 (black-box security testing)를 위한 사전 구축된 **공격 플레이북 (attack playbooks)**을 포함하고 있습니다. 플레이북은 특정 보안 평가에 대한 구조화된 접근 방식을 정의합니다.

플레이북 실행:

pentestagent run -t example.com --playbook thp3_web

PentestAgent는 내장 도구 (built-in tools)를 포함하며, 확장성을 위해 MCP (Model Context Protocol)를 지원합니다.

내장 도구: terminal, browser, notes, web_search (TAVILY_API_KEY 필요), spawn_mcp_agent

spawn_mcp_agent는 실행 중인 에이전트가 stdio를 통해 연결된 하위 MCP 서버로서 자신의 자식 복사본을 생성할 수 있게 하는 내장 도구입니다. 자식 프로세스는 완전히 격리되어 있으며 — 자체 런타임 (runtime), LLM 클라이언트, 대화 기록 및 노트 저장소를 가집니다 — 생성 후에는 전체 도구 세트가 부모 에이전트의 사용 가능한 도구로 다시 주입됩니다.

이를 통해 외부 오케스트레이션 (orchestration) 없이도 계층적 멀티 에이전트 워크플로우 (hierarchical, multi-agent workflows)가 가능해집니다. 즉, 에이전트가 필요에 따라 생성한 자식에게 범위가 지정된 하위 작업 (scoped subtasks)을 위임함으로써 스스로 조직화합니다.

인자 (Argument)	타입 (Type)	기본값 (Default)	설명 (Description)
`target`	string	—	자식에게 전달할 Pentest 대상
`scope`	string[]	—	자식의 범위 내 대상/CIDR
`model`	string	환경 변수 (env var)	모델 식별자, 자식의 `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), 결과에 포함되어 반환됩니다.

예시 — 오케스트레이터가 두 명의 자식에게 병렬 정찰 (parallel recon)을 위임하는 경우:

# 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"]
...

자동화된 spawn_mcp_agent 도구 외에도, TUI는 실행 중인 에이전트 루프와 독립적으로 자식 에이전트를 수동으로 생성하고 종료할 수 있는 두 가지 명령어를 제공합니다.

/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

stdio를 통해 새로운 자식 MCP 에이전트를 생성하고 현재 세션에 연결합니다. 자식 에이전트는 TUI 사이드바에 접기 가능한 터미널 패널로 나타나며, 해당 에이전트의 도구들은 다음 도구 호출(tool call) 시 부모 에이전트가 사용할 수 있게 됩니다.

인자 (Argument)	설명
`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 <server_name>

server_name(예: child_agent_1)으로 식별되는 자식 에이전트를 종료하고, TUI에서 해당 터미널 패널을 제거하며, 부모 세션으로부터 해당 도구들의 연결을 해제합니다. 현재 활성화된 모든 자식 에이전트의 이름을 확인하려면 /mcp list를 사용하세요.

예시:

/despawn child_agent_1

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

이 옵티마이저는 에이전트에게 투명하게 작동합니다. 즉, 에이전트는 필요한 내용을 설명하는 집중된 자연어 쿼리로 RAG 도구를 호출하며, 매칭된 도구들은 다음 턴에 직접 호출할 수 있는 상태로 제공됩니다.

에이전트를 위한 사용 가이드:

인자 (Argument)	타입 (Type)	기본값 (Default)	설명 (Description)
`queries`	string[]	(필수)	필요한 기능당 하나의 집중된 쿼리. 더 구체적일수록 정확도가 높아짐
`top_k`	integer	`20`	쿼리당 검색할 도구의 수 (최대 128). 결과는 병합 및 중복 제거됨

임베딩 (Embeddings)은 시작 시 한 번 계산되어 캐싱되므로, 반복적인 쿼리 수행 시 속도가 빠릅니다. 옵티마이저 (Optimizer)는 서버별로 구축되므로, 대규모 카탈로그를 가진 각 MCP 서버는 독립적인 자체 인덱스를 갖게 됩니다.

팁: 모든 것을 하나의 쿼리로 결합하기보다, 각 별개의 기능당 하나의 쿼리를 전달하세요.
["list open ports on a host", "get process memory usage"]가
["list ports and memory and CPU"]보다
더 나은 결과를 가져옵니다.

PentestAgent는 두 가지 방향으로 MCP (Model Context Protocol)를 지원합니다: 외부 MCP 서버를 도구 소스로 **사용 (consuming)**하는 것과, 외부 클라이언트 (Claude Desktop, Cursor 등)가 PentestAgent를 프로그래밍 방식으로 제어할 수 있도록 스스로를 MCP 서버로 **노출 (exposing)**하는 것입니다.

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

{
"mcpServers": {
"nmap": {
...

PentestAgent는 MCP 서버로 실행될 수 있으며, 이를 통해 모든 MCP 호환 클라이언트가 작업을 제출하고, 결과를 검사하며, 에이전트를 원격으로 제어할 수 있습니다. 두 가지 전송 방식 (Transports)이 지원됩니다:

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 전송 방식은 POST (요청), GET (서버 주도 푸시를 위한 지속적인 SSE 스트림), DELETE (세션 해제)를 지원하는 단일 /mcp 엔드포인트를 노출합니다. 세션은 Mcp-Session-Id 헤더를 통해 추적됩니다.

모든 mcp_server 플래그(flags):

플래그 (Flag)	기본값 (Default)	설명 (Description)
`--type`	(필수)	전송 방식 (Transport): `stdio` 또는 `sse`
`--host`	`0.0.0.0`	SSE 바인드 호스트 (bind host)
`--port`	`8080`	SSE 바인드 포트 (bind port)
`--target`	none	주요 침투 테스트 대상 (IP / 호스트 이름)
`--scope`	`[]`	범위 내 대상/CIDR (공백으로 구분)
`--model`	환경 변수 (env var)	모델 식별자, `PENTESTAGENT_MODEL`을 덮어씀
`--docker`	false	`LocalRuntime` 대신 `DockerRuntime` 사용
`--no-rag`	false	RAG 엔진 초기화 건너뛰기
`--no-mcp`	false	외부 MCP 서버 연결 건너뛰기

{
"mcpServers": {
"pentestagent": {
...

MCP 서버로 동작할 때, PentestAgent는 다음과 같은 도구(tools)를 노출합니다:

서버 상태 및 설정 (Server Status & Config)

도구 (Tool)	설명 (Description)
`get_server_status`	실시간 서버 상태: 준비 상태(readiness), 상태별 작업 수, 주요 대상/범위, 메모리 저장소 크기
`get_config`	주요 에이전트 설정: 대상, 범위, 최대 반복 횟수(max iterations), 도구 목록
`update_config`	이후의 모든 작업에 대해 대상, 범위 또는 최대 반복 횟수를 업데이트

작업 실행 (Task Execution)

도구 (Tool)	설명 (Description)
`run_task`	작업을 제출하고 완료될 때까지 차단(block)합니다. 전체 결과, 사용된 도구, 노트 스냅샷을 반환합니다
`run_task_async`	작업을 제출하고 `task_id`와 함께 즉시 반환합니다. `get_task_status`로 폴링(poll)하십시오

작업 검사 (Task Inspection)

도구 (Tool)	설명 (Description)
`list_tasks`	상태, 대상 및 요약과 함께 모든 작업을 나열합니다. 상태별로 필터링 가능합니다
`get_task_status`	작업의 현재 상태와 결과 미리보기를 폴링합니다
`get_task_result`	전체 작업 결과: 최종 출력, 사고 단계(thinking steps), 모든 도구 호출 및 결과, 노트 스냅샷
`await_tasks`	일련의 비동기 작업 ID들이 모두 완료될 때까지 차단합니다 (500ms마다 폴링, 구성 가능한 타임아웃)

작업 제어 (Task Control)

도구 (Tool)	설명 (Description)
`cancel_task`	ID를 통해 실행 중이거나 대기 중인 작업을 취소합니다

도구 관리 (Tool Management)

도구 (Tool)	설명 (Description)
`list_tools`	에이전트가 사용할 수 있는 모든 도구 목록을 나열합니다
`enable_tool`	기본 에이전트(primary agent)에서 지정된 이름의 도구를 활성화합니다
`disable_tool`	기본 에이전트(primary agent)에서 지정된 이름의 도구를 비활성화합니다

대화 기록 (Conversation History)

도구 (Tool)	설명 (Description)
`get_conversation_history`	작업(task) 또는 기본 에이전트(primary agent)의 메시지 기록을 반환합니다. `limit` 파라미터를 지원합니다
`reset_conversation`	작업(task) 또는 기본 에이전트(primary agent)의 대화 기록을 삭제합니다

메모리 (Memory)

도구 (Tool)	설명 (Description)
`store_memory`	키-값(key-value) 쌍을 프로세스 내 메모리 저장소(in-process memory store)에 영구 저장합니다
`retrieve_memory`	정확한 키로 검색, 부분 문자열(substring)로 검색, 또는 모든 키를 나열하여 검색합니다
`clear_memory`	특정 키를 삭제하거나 `scope='all'`을 사용하여 모든 메모리를 삭제합니다

관측 가능성 (Observability)

도구 (Tool)	설명 (Description)
`get_logs`	최근 실행 로그를 반환하며, 선택적으로 레벨(`info` / `warning` / `error`)에 따라 필터링할 수 있습니다
`get_metrics`	런타임 메트릭(Runtime metrics): 작업 횟수, 성공률, 총 도구 호출 횟수, 메모리 및 로그 크기

장시간 실행되는 정찰(recon) 작업의 경우, 비동기(async) 패턴을 사용하세요:

# 1. 차단(blocking) 없이 작업 제출
run_task_async task="Enumerate subdomains of example.com" target="example.com"
run_task_async task="Run nmap SYN scan on example.com" target="example.com"
...

pentestagent tools list # 모든 도구 목록 나열
pentestagent tools info <name> # 도구 상세 정보 표시
pentestagent mcp list # MCP 서버 목록 나열
...

TUI의 각 사용자 메시지에는 두 개의 인라인 액션 버튼인 rewind와 fork가 노출됩니다.

사용자 메시지에서 rewind를 클릭하면 UI와 에이전트의 인메모리(in-memory) 기록 모두에서 해당 메시지 직전으로 대화를 잘라냅니다(truncate). 이를 통해 버려진 경로를 저장하지 않고 처음부터 쿼리를 다시 시도할 수 있습니다.

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

현재의 전체 대화는 대화 저장소(conversation store)에 **저장(saved)**되며 짧은 스냅샷 ID가 표시됩니다. - 그 후 대화는 선택한 메시지 바로 직전까지만 잘립니다(truncated) (되감기(rewind)와 동일).

이를 통해 /conversations를 통해 원래 스레드를 다시 불러올 수 있는 상태를 유지하면서, 어느 지점에서든 대안적인 접근 방식을 시도할 수 있습니다.

PentestAgent는 모든 대화를 자동으로 유지(persist)하므로 과거 세션을 검토, 비교 및 복구할 수 있습니다.

**자동 저장(Auto-save)**은 각 /assist, /agent, /crew, /interact 작업 이후와 /clear 실행 전에 트리거됩니다. 최대 20개의 대화가 유지되며, 오래된 대화는 자동으로 정리(pruned)됩니다.

저장 위치(Storage location): 워크스페이스가 활성화된 경우 workspaces/<active>/memory/conversations/, 그렇지 않은 경우 conversations/

GH05TCREW/pentestagent

요약

핵심 포인트

ghostcrew_demo.mp4

댓글