sapper-v2란?
sapper-v2는 승인된 침투 테스트를 위해 설계된 자율 다중 에이전트 시스템입니다. 점점 더 복잡해지는 단일 에이전트에 의존하는 대신, 여러 AI를 하나의 군단으로 구성하여 작업을 분담하고, 발견 사항을 공유하며, 에이전트 교체 후에도 지식을 보존합니다.
이 프로젝트는 제3회 Tencent Cloud Intelligent Attack-Defense Challenge 온라인 예선에서 우승했으며, GeekCon 2026 AI Challenge에서 1위를 차지했습니다. Tencent 대회에서는 8시간 동안 무인으로 실행되었고, 약 10억 개의 토큰을 사용해 85개의 플래그를 찾으며 80.18점을 기록했습니다.
sapper-v2는 소유하거나 테스트에 대한 명시적 허가를 받은 시스템에서만 사용하세요. 설치 또는 운영 전에 DISCLAIMER.md를 검토하세요.
시스템 작동 방식
이 프로젝트는 세 가지 핵심 기능을 중심으로 구축되었습니다.
- 생성: 시스템은 tmux에서 새로운 AI 세션을 열어 필요에 따라 전문 작업자를 생성할 수 있습니다.
- 언어: 에이전트는 서로의 입력 세션에 메시지를 입력하여 통신합니다.
- 기록: 발견 사항은 하나의 에이전트 컨텍스트에 남겨 두는 대신 계층형 사실-의도 그래프에 저장됩니다.
기록 시스템은 제목, 요약, 증거 문서의 세 계층으로 구성됩니다. 에이전트는 먼저 간결한 제목을 읽고, 더 많은 맥락이 필요하면 요약을 확인한 뒤, 상세한 검증을 위해 증거를 열 수 있습니다. 이 설계는 컨텍스트 소비를 줄이고 부정확한 사실로 인한 피해를 제한합니다.
런타임 역할
런타임에서 sapper-v2는 조정, 실행, 가용성을 분리합니다.
- 사령관: 보드를 읽고 대상을 평가하며 작업을 배정합니다. 직접 공격을 실행하지는 않습니다.
- 장군: 어려운 공격을 담당하며 자체 부대를 모집할 수 있습니다.
- 정찰병: 짧은 정찰을 수행하고 대상에 대규모 실행이 필요한지, 심층 조사가 필요한지 판단하는 데 도움을 줍니다.
- 병사: 할당된 작업을 병렬로 수행합니다.
- 신호병: 한곳에서 보고되지 않은 플래그를 수집해 제출합니다. 이 역할은 사전에 코딩된 것이 아니라 운영 중에 등장했습니다.
- 감시자: 전략이 없는 스크립트로,
--continue를 사용해 중단된 사령관을 재시작하고, 키를 교체하며, 실행 종료 처리를 담당하여 시스템이 계속 작동하도록 합니다.
README에는 사령관, tmux 창에서 실행되는 AI 군단, 감시자라는 세 개의 주요 런타임 창이 설명되어 있습니다.
주요 기능
- 병렬 업무 분담: 정찰병, 병사, 장군, 사령관이 서로 다른 책임을 맡아 작업합니다.
- 지속적인 조직 메모리: 개별 에이전트가 교체되어도 지식이 유지됩니다.
- 컨텍스트 순환: 컨텍스트가 포화된 에이전트는 후임자에게 전달할 서면 교훈을 남길 수 있습니다.
- 모델 계층화: 대회 구성에서는 사령관과 장군에 GLM-5.3을, 정찰병과 병사에 DeepSeek V4.1 Flash를 사용했습니다.
- 운영 복원력: 감시자는 전략적 결정을 내리지 않고도 사령관을 재시작하고, 키를 교체하며, 연속성을 유지할 수 있습니다.
- 챌린지 간 전이: 사령관은 구조적으로 유사한 챌린지군을 식별하고 성공적인 플레이북을 새로 배정된 에이전트에게 전달할 수 있습니다.
- 사실-의도 CLI: 프로젝트는 그래프를 운영하고 여러 챌린지 워크플로를 실행하기 위한 명령과 지침을 제공합니다.
sapper CLI 설치
빠른 시작 설치 프로그램은 sapper CLI를 적절한 위치에 연결합니다. README에 따르면 CLI는 표준 라이브러리만 사용하며 추가 종속성이 없습니다.
저장소 루트에서 다음을 실행하세요.
bash install.shREADME에는 추가적인 로컬 사전 요구 사항이나 플랫폼별 설치 단계가 나와 있지 않습니다. 명령을 실행해도 셸에서 sapper를 사용할 수 없다면 install.sh를 확인하고 심볼릭 링크 대상 경로가 실행 파일 경로에 포함되어 있는지 확인하세요.
승인된 평가 시작
sapper setup으로 새 평가를 생성하세요. 다음 예시는 프로젝트의 빠른 시작 안내에서 가져온 것입니다.
sapper setup --goal "assess http://target" --agentshttp://target은 서면 승인을 받은 엔드포인트로만 바꾸세요. 에이전트가 모호하지 않은 임무를 받을 수 있도록 목표에 승인된 범위를 명확하게 설명해야 합니다.
--agents 옵션은 프로젝트에 제시된 에이전트 중심 워크플로를 시작합니다. 설정이 끝나면 보드와 현재 프런티어를 확인하세요.
sapper status상태 화면은 작업 진행 상황을 확인하는 기본 빠른 시작 명령입니다. 사령관은 평가 작업을 직접 수행하는 대신 보드를 사용해 대상을 판단하고 전문 에이전트를 배정합니다.
최소 CLI 워크플로
- 승인 확인: 도구 외부에서 대상, 시간 범위, 승인된 기법, 중단 조건을 문서화합니다.
- CLI 설치: 복제한 저장소에서
bash install.sh를 실행합니다. - 목표 정의: 승인된 대상을 사용해
sapper setup --goal "assess http://target" --agents를 실행합니다. - 보드 모니터링:
sapper status를 실행해 보드와 프런티어를 검토합니다. - 보존된 지식 검토: 단일 그래프 작업이나 여러 챌린지에 대한 일괄 점검이 필요할 때는 SKILL.md에 문서화된 사실-의도 워크플로를 사용합니다.
Docker로 전체 군단 실행
저장소에는 전체 commander 기반 legion을 위한 Dockerfile이 포함되어 있습니다. 저장소 루트에서 이미지를 빌드하세요:
docker build -f docker/Dockerfile.commander -t sapper:latest .컨테이너를 시작하기 전에 docker/ENV.md에 설명된 모델 게이트웨이, 키 풀, 예산 환경 변수를 구성하세요. 아키텍처가 서로 다른 모델 계층에 서로 다른 책임을 할당하고 키 순환 및 예산 인식 방식으로 동작하므로 이러한 설정은 중요합니다.
README에서는 컨테이너 실행을 개략적으로 다음과 같이 제시합니다:
docker run -d --name sapper ... sapper:latest줄임표는 그대로 실행할 수 있는 실제 인자가 아닙니다. 저장소의 환경 문서에 따라 필요한 환경 변수와 기타 Docker 옵션으로 바꾸세요. 안전한 시크릿 관리 방법을 사용할 수 있다면 프로덕션 자격 증명을 추측하거나 셸 기록에 시크릿을 직접 남기지 마세요.
commander의 원칙 이해하기
commander의 운영 원칙은 docker/commander/SKILL.md에 저장되어 있습니다. README에서는 다음과 같은 몇 가지 원칙을 강조합니다:
- 쉬운 작업 우선 병렬 스케줄링: 처리하기 쉬운 대상은 동시에 해결할 수 있도록 작업을 배정하여 전체 legion이 하나의 어려운 경로를 거치도록 강제하지 않습니다.
- 병목 시간대의 salvage: 작업이 끝나갈 무렵에는 기존 증거로 빠르게 결과를 얻을 수 있는 부분 해결 대상들을 다시 검토합니다.
- 손실 제한 규율: 진전이 없는 작업에 시간이나 토큰을 무제한으로 소비하지 않습니다.
- 역할 분리: 직접 실행보다 보드 확인, 판단, 작업 배정에 commander의 주의를 집중합니다.
정식 아키텍처 계약은 docker/commander/SPEC.md를 읽어 보세요. 시스템이 대회 중 어떻게 동작했는지 설명하는 회고는 BATTLE-REPORT.md를 참조하세요.
고급 운영 팁
승인된 범위에 맞는 목표 작성
설정 목표는 에이전트가 수행할 임무가 됩니다. 승인된 대상을 정확하게 명시하고, 관련 없는 호스트나 서비스를 탐색할 권한으로 해석될 수 있는 광범위한 표현은 피하세요. 외부 승인 문서를 최종 기준으로 삼아야 합니다.
지나치게 큰 요약 대신 계층화된 증거 사용
상위 수준의 사실은 간결하게 유지하되 그 아래에 상세한 증거를 보존하세요. 제목은 핵심을 전달하고, 요약은 관련성을 설명하며, 증거 문서는 검증을 뒷받침해야 합니다. 이는 sapper-v2의 설계를 따르며 모든 세부 정보를 에이전트 컨텍스트에 반복해서 불러오는 일을 방지합니다.
에이전트 교체 중 교훈 보존
프로젝트는 캠페인 중 병사의 컨텍스트 포화가 약 260,000토큰에 이른 것으로 측정했습니다. 이에 대한 대응으로 작업자를 교체하되 후임자를 위한 플레이북은 남겼습니다. 작업 결과를 검토할 때는 검증된 발견 사항, 시도한 접근법, 해결되지 않은 질문, 재사용 가능한 절차가 담긴 명시적인 인수인계 기록을 우선하세요.
전략과 가용성 분리
watchdog에는 의도적으로 전략적 역할이 없습니다. 복구 동작, 키 순환, 프로세스 재시작을 대상과 전술에 관한 결정과 분리하세요. 이렇게 하면 어떤 동작이 commander에서 비롯되었고 어떤 동작이 keep-alive 자동화에서 비롯되었는지 더 쉽게 파악할 수 있습니다.
토큰 및 모델 비용 관리
sapper-v2의 대회 아키텍처는 상위 수준의 의사 결정에는 더 강력한 모델을, 대량 정찰 및 실행에는 더 가벼운 모델을 할당했습니다. 문서화된 구성을 재현한다면 Docker 환경 지침에 따라 게이트웨이, 키 풀, 예산을 설정하고 승인된 실행 전반에서 사용량을 모니터링하세요.
전달된 지식을 신뢰하기 전에 증거 확인
대상이 구조를 공유할 때 챌린지 간 지식 전달로 작업을 가속할 수 있지만, 유사성이 검증을 대신해서는 안 됩니다. 상속된 플레이북을 다른 챌린지에 적용하기 전에 계층화된 그래프를 사용하여 요약과 뒷받침 증거를 확인하세요.
안전하고 책임 있는 사용
sapper-v2는 공격적 보안 도구이므로 승인되지 않은 접근에 사용해서는 안 됩니다. README는 AI가 공격적 도구로 인한 피해를 증폭할 수 있다고 명시적으로 경고합니다. 관련 법률을 준수하고, 명시적인 허가를 받으며, 대상 범위를 제한하고, 예산과 중단 조건을 설정하고, 환경에 적합한 수준의 인간 감독을 유지하세요.
이 프로젝트는 또한 향후 taggant 메커니즘을 제안합니다. 이는 공격용 하니스에 결합된 표식으로, 불법 침입 중 피해자에게 식별 정보를 유출하고 귀속을 지원할 수 있습니다. README는 이를 암호학적 및 커뮤니티 차원의 설계가 필요한 제안으로 제시하며, 현재 사용자가 의존할 수 있는 기존 보호 기능으로 제시하지는 않습니다.
결론
sapper-v2는 자율 보안 평가에 대한 협력적 접근 방식을 보여 줍니다. commander가 작업을 위임하고, 전문가들이 병렬로 작업하며, watchdog가 연속성을 유지하고, 계층화된 사실 그래프가 조직의 지식을 보존합니다. 가벼운 CLI부터 시작하고 sapper status로 보드를 모니터링한 뒤, 전체 legion이 필요할 때 Docker 설정을 사용하세요. 모든 실행이 명시적인 승인 범위와 프로젝트의 고지 사항 안에 있도록 항상 관리하세요.