s0ld13rr/pentestcode

PentestCode - Multi-agent AI penetration testing system with persistent engagement state, strategic coordination, and parallel autonomous operations.

PentestCode란 무엇인가요?

PentestCode는 터미널에서 실행되는 자율 모의 해킹 어시스턴트입니다. 높은 수준의 목표(예: “gain domain‑admin on 10.10.10.5”)를 입력하면 AI 기반 에이전트 팀이 스캔 및 열거부터 자격 증명 스프레이, 익스플로잇, 사후 보고까지 전체 공격 체인을 조정합니다. 이 프로젝트는 OpenCode 코드 편집 AI의 하드 포크이며, 공격적 보안을 위해 재설계되었습니다.

작동 원리

구성 요소	역할
리드 “pentest” 에이전트	참여를 작업으로 나누고, 전체 계획을 유지하며, 다음에 무엇을 할지 결정합니다.
전문 하위 에이전트 (정찰, 스캔, 열거, 익스플로잇, AD‑identity, web‑app, 사후 익스플로잇 등)	특정 도구를 실행하고 출력을 파싱하며, 결과를 공유된 참여 상태에 피드백합니다.
공유 참여 상태	호스트, 서비스, 취약점, 자격 증명, 액세스 수준, AD 관계, 네트워크 세그먼트 및 계산된 공격 경로를 저장하는 구조화된 지식 베이스입니다. 세션 간에 지속됩니다.
LLM 제공자 계층	Vercel의 `ai-sdk`를 통해 20개 이상의 LLM(Anthropic, OpenAI, Google, Azure, Bedrock, Ollama 등)을 사용하여 프롬프트를 생성하고 도구 출력을 해석하며 다음 작업을 결정합니다.

에이전트는 이 상태를 통해 통신하므로 스캐너가 새 포트를 발견하면 열거자가 즉시 대응할 수 있습니다. 내장된 그래프 모델을 통해 시스템은 비용 최적의 공격 경로(Dijkstra + Yen’s K‑shortest)를 계산할 수 있습니다. 모든 작업은 사람이 읽을 수 있는 findings.md 파일에 기록됩니다.

주요 기능

멀티 에이전트 아키텍처 (13개 에이전트)가 작업을 병렬로 실행합니다.
지속적인 구조화 상태 (호스트, 서비스, 취약점, 자격 증명, 관계, AD 모델, 네트워크 토폴로지).
18개의 내장 파싱 도구 (예: nmap_parse, bloodhound_parse, cme_parse)가 자동으로 상태를 채웁니다.
**19개의 지식 팩(기술)**이 모의 해킹 단계, 서비스 세부 정보 및 플레이북을 다룹니다. 이는 일반 Markdown 파일이며 SKILL.md 파일을 추가하여 확장할 수 있습니다.
세 가지 운영 모드 – auto (완전 자율 실행), free (직접 명령 응답), guided (단계별 승인).
슬래시 명령 (/status, /vulns, /creds, /report, …)을 통한 실시간 검사 및 제어.
20개 이상의 LLM 제공자 지원 (ai-sdk 경유).
단일 바이너리 배포 (Linux/macOS (x64 & arm64)용, 선택적 AUR 패키지 제공).

설치

# npm (바이너리를 가져오는 CLI 래퍼 설치)
npm install -g pentestcode-ai

# 또는 사전 빌드된 바이너리를 다운로드하는 한 줄 스크립트
curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash

Arch Linux: paru -S pentestcode-bin

소스에서 빌드 (Bun 필요):

bun install
bun run build --single --skip-embed-web-ui   # 바이너리는 packages/opencode/dist/…에 생성됨

빠른 시작

# 선택한 LLM 제공자로 인증
pentestcode auth login

# 대화형 세션 시작
pentestcode

# REPL에 들어가지 않고 단일 명령 실행
pentestcode --prompt "scan 10.10.10.0/24 and enumerate all services"

세션 중에 실시간 상태를 쿼리할 수 있습니다:

/status – 호스트, 취약점, 자격 증명, 현재 단계의 대시보드
/vulns – 심각도별 발견 목록
/creds – 발견된 자격 증명 표시
/report – Markdown/JSON 모의 해킹 보고서 생성

일반적인 워크플로우 예시

you: pentest 10.10.10.5, goal is domain admin

1️⃣ Scan → nmap -sS -p- → 포트가 상태로 파싱됨
2️⃣ Recognize → 도메인 컨트롤러 식별 (포트 88, 389)
3️⃣ Enumerate → SMB 공유 목록, LDAP 사용자 덤프, Gobuster 웹 디렉토리
4️⃣ Attack → AS‑REP roast → 크랙 가능한 해시 → 첫 번째 자격 증명
5️⃣ Spray → SMB, WinRM, LDAP, RDP 전반에 자격 증명 스프레이
6️⃣ Exploit → WinRM 거점 → SAM/LSA/DPAPI 덤프
7️⃣ Result → 도메인 관리자 해시, 모든 단계 기록됨

에이전트는 목표가 달성되거나 중단될 때까지 발견된 모든 호스트에 대해 이 루프를 반복합니다.

구성

사용자별 설정은 ~/.pentestcode/pentestcode.jsonc에 저장됩니다. 모델 선택 예시:

{
  "provider": {
    "anthropic": { "model": "claude-sonnet-4-20250514" }
  }
}

Vercel의 ai-sdk에서 지원하는 모든 제공자를 유사하게 구성할 수 있습니다.

누가 사용해야 하나요?

전문 모의 해킹 담당자: AI 어시스턴트를 사용하여 반복적인 단계를 자동화하면서 제어권을 유지하려는 분.
CTF 참가자: 플래그를 추적하고 다중 대상 참여를 관리하며 다음 단계를 제안하는 도구를 찾는 분.
버그 바운티 헌터: 빠른 정찰과 체계적인 열거가 필요한 분.
보안 연구원: LLM 기반 공격 자동화 실험에 관심이 있는 분.

기여 및 지원

이 프로젝트는 베타 버전입니다. 버그가 발생할 수 있습니다. GitHub 이슈(대상 유형, 실패 설명, findings.md 발췌 포함) 및 풀 리퀘스트를 통한 기여를 환영합니다. 코드베이스는 Effect 라이브러리를 사용하여 TypeScript로 작성되었습니다.