AI 튜토리얼

Autonomous Pentest Agent 로컬 배포 가이드: 설치 및 구성부터 자율 탐색과 재테스트까지

이 문서에서는 Autonomous Pentest Agent의 핵심 아키텍처, 설치 방법, LLM 및 PostgreSQL 구성, 작업 모니터링, 자산 동기화, 취약점 재테스트와 업그레이드 방법을 소개하고, 리버스 프록시 및 로컬 개발 시 주의사항을 설명합니다.

2026년 10월 9일약 18분 소요

Autonomous Pentest Agent 로컬 배포 가이드: 설치 및 구성부터 자율 탐색과 재테스트까지

먼저 프로젝트와 사용 범위를 이해하세요

Autonomous Pentest Agent는 LLM 기반 멀티 에이전트로 구동되는 자율 침투 테스트 시스템으로, Go 백엔드, Next.js 프론트엔드 및 PostgreSQL을 사용합니다. 프로젝트는 작업, 자산, 탐색 경로, 발견 결과, 트래픽 기록, 도구 승인 및 휴먼 인 더 루프 대화를 관리할 수 있습니다.

중요한 보안 및 규정 준수 안내: README에는 이 프로젝트를 개인 학습, 소스 코드 연구 및 로컬 격리 환경에서의 기술 검증에만 사용해야 하며, 어떠한 웹사이트, 온라인 서비스, 연결된 시스템, 운영 환경 또는 실제 침투 테스트에도 사용해서는 안 된다고 명시되어 있습니다. 사용자가 제어 권한을 가진 로컬 실습 환경에서만 사용하고, 해당 지역의 사이버 보안, 데이터 보호 및 컴퓨터 범죄 관련 법률과 규정을 준수하세요.

프로젝트는 상호작용 인터페이스를 확인할 수 있는 온라인 Demo를 제공하지만, 실제 배포와 검증은 반드시 로컬 격리 환경으로 제한해야 합니다.

핵심 기능 및 인터페이스

시스템 프론트엔드는 대시보드, 작업 목록, 실행 세션, 탐색 경로, 발견 결과, 자산, 자산 커버리지 맵, 트래픽 녹화, Agent 관리, LLM 구성, 가로채기 승인 및 백엔드 로그 등의 페이지를 제공합니다.

대시보드에서는 전체 상태, Token 사용량 및 활동 스트림을 확인할 수 있습니다. 작업 및 세션 페이지에서는 Agent 세션과 도구 호출을 포함한 작업 실행 과정을 보여 줍니다.

탐색 경로에서는 대상, 의도, 사실 및 발견 결과 간의 계보 관계를 확인할 수 있습니다. 발견 결과 페이지에서는 취약점과 증거를 확인하고, 자산 페이지에서는 시스템이 수집하고 통합한 대상 자산을 탐색할 수 있습니다.

대시보드

시스템 아키텍처 개요

시스템은 Next.js 정적 프론트엔드가 내장된 Go 모놀리식 백엔드, PostgreSQL, Agent 엔진 및 여러 지원 하위 시스템으로 구성됩니다. 백엔드는 REST API, JWT 인증 및 SSE를 통해 프론트엔드에 서비스를 제공하며, 작업 엔진은 planner와 여러 worker를 스케줄링합니다.

프로젝트는 이중 그래프 아키텍처를 사용합니다.

자산 그래프: 작업 간에 공유되는 자산 기준 저장소로, 루트 도메인, 하위 도메인, IP, 서비스, 애플리케이션 및 엔드포인트 등의 노드를 포함합니다.
탐색 그래프: 작업별로 대상, 의도, 사실, 프롬프트 및 발견 결과를 기록하고, 계보 관계를 통해 탐색 과정을 설명합니다.
앵커 관계: 탐색 노드를 특정 자산과 연결하여 자산 테스트 커버리지와 탐색 범위를 확인할 수 있게 합니다.

Planner는 탐색 상황을 읽고 의도를 배포합니다. Worker는 의도를 가져와 도구를 사용해 실행한 뒤 사실, 자산 및 발견 결과를 기록합니다. 그래프가 변경되면 Planner가 다시 활성화되어 이벤트 기반 폐쇄 루프를 구성합니다. 여러 Worker는 다른 Worker의 실행 과정도 검색할 수 있으며, 공유 todolist는 다중 라운드 계획이 종속성에 따라 연속 단계를 진행하도록 지원합니다.

설치 전 준비

프로젝트를 실행하려면 최소한 PostgreSQL이 필요합니다. 탐색을 실행하려면 LLM도 구성해야 하며, ANTHROPIC_API_KEY 또는 OPENAI_API_KEY를 사용할 수 있습니다. 나중에 Web 인터페이스의 「LLM 구성」 페이지에서 입력할 수도 있습니다.

데이터베이스와 애플리케이션을 빠르게 시작할 수 있도록 Docker를 준비하는 것을 권장합니다. 어떤 배포 방식을 선택하든 먼저 격리된 로컬 테스트 네트워크를 만들고, 중요한 데이터를 백업하며, 테스트 대상이 로컬 실험 환경에 속하는지 확인하세요.

방법 1: 원클릭 설치 스크립트 사용

README에서 권장하는 설치 방법입니다. 스크립트는 Docker를 확인하거나 설치한 뒤, 전체 Docker 배포 또는 로컬 컴파일 및 실행을 선택하도록 합니다.

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
./install.sh

전체 Docker 배포를 선택하면 스크립트에서 PostgreSQL 비밀번호를 입력하도록 요청합니다. 바로 Enter를 누르면 무작위 비밀번호를 생성한 뒤 .env에 기록하고 docker compose up -d를 실행합니다. 로컬 실행을 선택하면 기존 데이터베이스에 연결하거나 Docker로 데이터베이스를 시작할 수 있습니다. 스크립트는 config.json을 생성하고, 프론트엔드가 내장된 Go 단일 바이너리를 컴파일한 뒤 서비스를 시작합니다.

설치가 완료되면 http://localhost:8787에 접속하세요. 처음 접속하면 /setup을 열어 관리자 비밀번호를 설정합니다.

방법 2: Docker Compose 사용

환경을 직접 제어하려면 Compose를 사용할 수 있습니다.

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
cp .env.example .env
docker compose up -d

실행 과정

.env를 편집하여 POSTGRES_PASSWORD를 입력하고, 필요에 따라 ANTHROPIC_API_KEY를 구성하세요. 시작 후 http://localhost:8787에 접속합니다.

Docker 이미지에는 일반적으로 사용하는 도구가 포함되어 있으며, ./skills와 ./data는 바인드 마운트로 데이터를 저장합니다. 원격 MCP는 시스템 설정에서 Streamable HTTP 또는 이전 버전의 SSE를 선택할 수 있습니다. 이전 버전의 SSE를 사용할 때 URL에는 보통 /sse를 입력하고, 서비스 요구 사항에 따라 Authorization=Bearer <token> 요청 헤더를 설정합니다.

방법 3: 사전 컴파일된 바이너리 사용

Releases에서 해당 플랫폼용 압축 패키지를 다운로드할 수도 있습니다. 압축을 풀면 일반적으로 apagent, start.sh 또는 Windows용 start.bat, skills/ 및 config.example.json이 포함되어 있습니다.

cp config.example.json config.json
./start.sh

./apagent를 직접 실행하지 말고 start.sh 또는 start.bat를 사용하여 시작하세요. 시작 스크립트는 프로그램 종료 후 종료 코드에 따라 다시 실행할지 결정하며, 페이지의 원클릭 업데이트 기능도 이 메커니즘에 의존합니다. 백그라운드에서 실행하려면 다음을 사용할 수 있습니다.

nohup ./start.sh >apagent.log 2>&1 &

방법 4: 소스 코드에서 컴파일

탐색 경로

소스 코드에서 컴파일할 때는 먼저 프론트엔드 정적 파일을 빌드한 다음 백엔드의 내장 디렉터리에 복사하고, 마지막으로 embedui 태그를 사용하여 Go 프로그램을 컴파일해야 합니다.

cd web && npm ci && npm run build:static && cd ..
cp -r web/out server/webui/dist
CGO_ENABLED=0 go build -tags embedui -o apagent ./cmd/apagent
./start.sh

플랫폼별 릴리스 패키지를 빌드하려면 다음을 실행할 수 있습니다.

./build.sh --release

기본적으로 Linux, macOS 및 Windows용 여러 대상 패키지가 생성됩니다. APAGENT_TARGETS를 통해 대상 플랫폼을 직접 지정할 수도 있습니다. UPX는 기본적으로 활성화되지 않습니다. 압축된 자체 압축 해제 바이너리가 일부 Linux 커널, 가상화 환경 또는 보안 정책과 호환되지 않을 수 있기 때문입니다.

데이터베이스 및 LLM 구성

로컬 컴파일 또는 바이너리 실행 시 config.json에서 PostgreSQL을 구성할 수 있습니다.

{
  "database": {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "apagent",
    "password": "yourpass",
    "dbname": "apagent",
    "sslmode": "disable"
  }
}

발견 결과

APAGENT_PG_DSN을 사용하여 데이터베이스 연결 구성을 덮어쓸 수도 있습니다. LLM은 환경 변수로 구성할 수 있습니다.

export ANTHROPIC_API_KEY=sk-...
# 또는
export OPENAI_API_KEY=...

선택적 매개변수로는 APAGENT_LLM_PROVIDER, APAGENT_LLM_MODEL, APAGENT_LLM_BASE_URL 및 APAGENT_LLM_PROXY가 있습니다. 환경 변수를 사용하지 않으려면 UI의 「LLM 구성」 페이지에서 입력할 수 있습니다. 각 작업의 Worker 수는 「시스템 설정」에서 조정할 수 있으며 기본값은 3입니다.

기본 사용 흐름

초기화 완료: 로컬 서비스에 접속하여 /setup에서 관리자 비밀번호를 설정하고 데이터베이스 연결을 확인합니다.
LLM 구성: 시스템 환경 변수 또는 「LLM 구성」 페이지에서 사용 가능한 모델과 필요한 매개변수를 설정합니다.
로컬 대상 준비: 격리된 실험 환경에서 사용자가 제어하는 자산만 추가하고, 온라인 시스템이나 운영 서비스에 접근하지 않는지 확인합니다.
작업 생성 및 관찰: 작업 페이지에서 작업을 관리하고, 대시보드와 활동 스트림에서 실행 상태를 확인합니다.
탐색 결과 확인: 탐색 경로를 통해 의도, 사실 및 발견 결과 간의 관계를 확인하고, 자산 그래프에서 통합된 자산을 확인합니다.
실행 증거 확인: 세션, 도구 호출 및 트래픽 페이지에서 과정 기록을 확인합니다. 사람의 확인이 필요한 작업이 발생하면 가로채기 승인 페이지에서 처리합니다.

자산 커버리지 맵은 힘 기반 레이아웃으로 범위 내 자산과 테스트가 완료된 노드를 표시하며, 노드를 접거나 펼칠 수 있습니다. 로컬 실험 범위에서 어떤 자산이 이미 탐색되었는지 빠르게 판단하는 데 적합합니다.

ScopeSentry에서 자산 동기화

프로젝트는 ScopeSentry에서 자산을 동기화하여 중복 수집을 줄일 수 있습니다. 「자산 동기화」 페이지를 열고 ScopeSentry 주소와 API Key를 입력한 다음, 프로젝트 또는 작업별로 동기화할 대상과 자산 유형을 선택하세요.

범위에 따라 도메인, 하위 도메인, IP, 포트, 사이트 및 엔드포인트 등의 자산 유형을 선택할 수 있습니다.
가져온 후 회사의 자산 범위에 따라 통합됩니다.
동기화 결과는 Autonomous Pentest Agent의 자산 그래프에 반영되며, 이후 로컬 실험 작업에서 사용할 수 있습니다.

트래픽 기록 및 승인

시스템은 트래픽 녹화 프록시를 제공합니다. ./start.sh -addr :8787 -proxy :8788와 같은 방식으로 프런트엔드 및 API 주소와 트래픽 프록시 주소를 지정할 수 있습니다. Worker의 도구 실행 과정에는 활동 기록이 남으며, 가로채기 승인 메커니즘을 사용하면 필요한 경우 사람이 도구 작업을 확인하고 승인할 수 있습니다.

승인 기록은 전역 승인 기록, 작업 내 가로채기 승인 및 대화의 승인 카드에서 세부 정보를 펼쳐 볼 수 있습니다. 사용할 때는 작업 대상과 매개변수를 주의 깊게 확인하고, 항상 대상을 격리된 실험 환경으로 제한해야 합니다.

취약점 재테스트

작업 세부 정보의 「재테스트」탭에서는 취약점을 페이지 단위로 선택하고, 과거 결론과 증거를 확인하며, 독립적인 재테스트 Agent 세션을 시작할 수 있습니다. 취약점 목록, 취약점 세부 정보 및 자산 보기에서도 재테스트를 시작할 수 있습니다.

재테스트 결론에는 「여전히 재현 가능」, 「수정됨」 및 「확인할 수 없음」이 포함됩니다. 각 재테스트의 결론, 증거 및 세션 링크는 취약점 세부 정보에 저장됩니다. 재테스트에 성공하고 결론이 「수정됨」인 경우 시스템이 취약점 처리 상태를 자동으로 업데이트합니다. 실행 중, 실패, 중지 또는 기타 결론은 원래 상태를 자동으로 변경하지 않습니다.

백엔드는 처음 시작할 때 편집 가능한 「취약점 재테스트」Agent, 즉 retester를 미리 구성합니다. Agent 관리에서 프롬프트, LLM, 실행 예산 및 도구를 설정할 수 있습니다. 동일한 취약점을 재테스트하는 중이면 시스템은 기존 세션을 재사용합니다. 중지, 실패 또는 서비스 재시작 후에는 다시 시작할 수 있습니다. README에는 과거 재테스트 기록이 아직 취약점 보고서 내보내기나 작업 보관 패키지에 포함되지 않으며, 트래픽 패키지와도 자동으로 연결되지 않는다고 설명되어 있습니다.

자산 범위도

역방향 프록시 배포

프런트엔드, API 및 SSE는 기본적으로 동일한 백엔드 포트에서 제공되므로 일반적으로 NEXT_PUBLIC_SSE_BASE를 설정할 필요가 없습니다. Nginx를 통해 HTTPS를 노출하는 경우 SSE 버퍼링을 비활성화하고 읽기 시간 제한을 길게 설정해야 합니다.

server {
    listen 443 ssl;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

SSE가 페이지와 다른 출처를 사용하는 경우에만 빌드 시 NEXT_PUBLIC_SSE_BASE를 설정하면 됩니다. 이 변수는 next build 시 정적 패키지에 고정되므로 컨테이너 실행 시 설정해도 적용되지 않습니다.

업그레이드 및 데이터 보호

프로젝트를 업그레이드할 때 프로그램만 교체하며 PostgreSQL 데이터 볼륨, ./data 또는 ./skills를 능동적으로 삭제하지 않습니다. 애플리케이션 시작 시 데이터베이스 구조 초기화와 마이그레이션을 멱등적으로 실행하므로 일반적으로 마이그레이션 스크립트를 수동으로 실행할 필요가 없습니다. 하지만 업그레이드 전에 ./data와 데이터베이스를 백업해야 합니다.

시스템 설정 페이지의 「버전 및 업데이트」카드에서 업데이트를 실행하는 것을 권장합니다. 프로그램은 현재 플랫폼용 릴리스 패키지를 다운로드하고 SHA256을 확인한 뒤 스모크 테스트를 수행하며, 시작 스크립트가 교체를 완료합니다. 검증에 실패하면 임시 파일을 폐기하고, 새 버전이 연속으로 시작에 실패하면 자동으로 롤백합니다. 업데이트하면 서비스가 재시작되고 실행 중인 작업이 중단되므로 유휴 시간에 진행해야 합니다.

Docker로 배포할 때 페이지 업데이트는 프로그램만 교체하며 이미지에 포함된 Playwright, nmap 등의 도구 체인은 업데이트하지 않습니다. 이미지를 업데이트하려면 다음을 실행합니다.

트래픽

docker compose pull apagent
docker compose up -d apagent

저장소에 있는 업데이트 스크립트를 사용할 수도 있습니다.

./update.sh

로컬 개발 및 테스트

개발 모드에서는 백엔드, 트래픽 프록시 및 Next.js 개발 서버를 동시에 시작할 수 있습니다.

./dev.sh

기본 접속 주소는 http://localhost:5173입니다. 다음과 같이 각각 실행할 수도 있습니다.

go run ./cmd/apagent
cd web && npm run dev
go test ./...

-tags embedui를 사용하지 않으면 백엔드는 프런트엔드를 내장하지 않습니다. 백엔드를 시작하지 않고 프런트엔드만 미리 보려면 다음을 사용할 수 있습니다.

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

일반적인 주의 사항

PostgreSQL이 실행 중인지 확인하고 사용자 이름, 비밀번호, 데이터베이스 이름 및 포트를 점검합니다.
활동 스트림 연결에는 성공했지만 이벤트가 없으면 역방향 프록시에서 버퍼링을 비활성화했는지 확인하고 장기 연결 시간 제한이 충분히 긴지 확인합니다.
미리 컴파일된 버전을 사용할 때는 start.sh 또는 start.bat를 우회하지 마십시오. 그러면 페이지 업데이트 후 자동 교체 및 재시작 메커니즘이 정상적으로 작동하지 않을 수 있습니다.
프런트엔드 정적 리소스를 수정한 후에는 반드시 npm run build:static을 다시 실행하고, server/webui/dist에 복사한 다음 다시 컴파일해야 합니다.
업그레이드 전에 데이터베이스, ./data 및 ./skills를 백업합니다. 데이터베이스 구조는 자동으로 마이그레이션되지만 자동으로 되돌려지지는 않습니다.
실제 운영 자산, 운영 자격 증명 또는 민감한 데이터를 로컬 실험 시스템으로 가져오지 마십시오.

요약

Autonomous Pentest Agent는 Go 서비스, Next.js 인터페이스, PostgreSQL 이중 그래프 데이터 모델 및 LLM 멀티 Agent 스케줄링을 결합하여 작업 관리, 탐색 경로, 자산 범위, 트래픽 기록, 승인 및 취약점 재테스트 기능을 제공합니다. 먼저 Docker 또는 설치 스크립트를 사용해 로컬 격리 환경에서 시작한 다음 데이터베이스와 LLM을 구성하고, 마지막으로 작업, 자산 그래프 및 실행 세션을 통해 시스템 동작을 단계적으로 이해할 수 있습니다. 사용하는 동안 프로젝트에서 명시한 로컬 학습 목적과 모든 법률 및 규정 준수 요구 사항을 반드시 준수해야 합니다.

프로젝트는 AGPL-3.0 라이선스를 사용합니다. 수정한 후 네트워크를 통해 사용자에게 서비스를 제공하는 경우 라이선스 요구 사항에 따라 해당 전체 소스 코드를 공개해야 합니다. 자세한 구현 내용은 저장소의 소스 코드, norma SDK 및 프로젝트의 LICENSE 파일을 참조할 수 있습니다.