AI 튜토리얼

ARTEX 입문: AI 자율 침투 테스트 시스템 구축과 이중 그래프 탐색 아키텍처 이해

이 글에서는 ARTEX의 핵심 기능, 설치 방법, 데이터베이스 및 LLM 구성, 작업 모니터링, 자산 동기화, 취약점 재검증과 업그레이드 절차를 소개하고, planner, worker 및 이중 그래프 모델을 기반으로 한 자율 탐색 메커니즘을 설명합니다.

2026년 10월 8일약 19분 소요

ARTEX 입문: AI 자율 침투 테스트 시스템 구축과 이중 그래프 탐색 아키텍처 이해

사용 범위를 먼저 확인하세요

ARTEX는 개인 학습, 코드 연구 및 로컬 격리 환경에서의 기술 검증 용도로만 사용할 수 있습니다. 프로젝트 설명에 따라 온라인 시스템, 웹사이트, 네트워크 연결 시스템 또는 운영 환경에 대해 스캔, 탐색, 익스플로잇 및 공격을 수행하는 데 사용할 수 없습니다. 대상이 본인 소유이거나 이미 허가를 받았더라도 마찬가지입니다. 시작하기 전에 프로젝트의 AGPL-3.0 라이선스, 소재지의 네트워크 보안 법규, 저장소의 사용 제한 및 면책 조항을 이해하고 준수하는지 확인하세요.

이 글에서는 로컬 배포와 안전한 격리 환경을 전제로 ARTEX 설치, PostgreSQL 및 LLM 구성, 인터페이스에서 작업 관찰, 자산 동기화와 취약점 재검증 등의 기능을 소개합니다.

ARTEX는 Go 백엔드와 Next.js 프런트엔드로 구성된 AI 멀티 에이전트 시스템입니다. 프로젝트는 상호작용 효과를 확인할 수 있는 온라인 Demo를 제공합니다. 실제 실행 시 프런트엔드는 Go의 go:embed를 통해 단일 바이너리에 내장할 수 있습니다.

ARTEX로 할 수 있는 작업

ARTEX는 자율 탐색, 작업 오케스트레이션 및 과정 기록을 중심으로 구성됩니다. 시스템에는 대시보드, 작업 목록, 세션 실행 과정, 탐색 경로, 발견 항목, 자산, 자산 커버리지 맵, 트래픽 기록, 휴먼 인 더 루프 대화, Agent 관리 및 LLM 구성 등의 화면이 포함되어 있습니다.

멀티 에이전트 탐색: goals, planner, worker 및 mainagent 등의 역할이 협력하여 작업을 진행합니다.
이중 그래프 모델: 자산 그래프는 작업 간 공유되는 자산 사실을 저장하고, 탐색 그래프는 개별 작업의 목표, 의도, 사실, 프롬프트 및 발견 항목을 기록합니다.
과정 단위 정보 교환: worker는 다른 worker의 실행 과정을 조회하고 그 관찰 결과를 재사용할 수 있습니다.
휴먼 인 더 루프: 대화와 가로채기 승인을 통해 도구 호출 및 주요 작업 결정에 참여할 수 있습니다.
실시간 활동 스트림: 백엔드는 SSE로 활동 정보를 푸시하며, 작업 실행 과정을 인터페이스에서 계속 관찰할 수 있습니다.
트래픽 기록: 기록형 MITM 프록시는 도구 실행을 위한 트래픽과 증거를 보존합니다.
자산 동기화: ScopeSentry에서 도메인, 서브도메인, IP, 포트, 사이트 및 엔드포인트 등의 자산을 동기화할 수 있습니다.
취약점 재검증: 기존 취약점에 대해 별도의 재검증 Agent 세션을 생성하고 결론, 증거 및 세션 링크를 저장할 수 있습니다.

ARTEX 설치

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

프로젝트에서 권장하는 설치 방법입니다. 스크립트가 Docker를 확인하거나 설치하며, 전체 Docker 실행 또는 로컬 컴파일 실행 중 하나를 선택할 수 있습니다.

대시보드

git clone https://github.com/Autumn-27/ARTEX.git
cd ARTEX
./install.sh

전체 Docker를 선택하면 PostgreSQL 비밀번호를 입력해야 하며, Enter 키를 눌러 스크립트가 임의의 비밀번호를 생성하도록 할 수도 있습니다. 이후 스크립트가 .env를 작성하고 docker compose up -d를 실행합니다.

로컬 실행을 선택하면 기존 데이터베이스에 연결하거나 Docker로 데이터베이스를 시작할 수 있습니다. 스크립트는 config.json을 생성하고 프런트엔드가 포함된 단일 바이너리를 컴파일한 뒤 서비스를 시작합니다.

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

방법 2: Docker Compose 수동 사용

git clone https://github.com/Autumn-27/ARTEX.git
cd ARTEX
cp .env.example .env
docker compose up -d

.env를 편집하여 최소한 POSTGRES_PASSWORD를 입력하세요. 환경 변수로 Anthropic을 구성하려면 ANTHROPIC_API_KEY도 입력할 수 있습니다. 컨테이너 이미지에는 일반적인 도구가 포함되어 있으며, ./skills와 ./data는 바인드 마운트를 통해 보존됩니다.

시작 후 http://localhost:8787에 접속하세요. 원격 MCP가 필요하면 시스템 설정에서 http 또는 sse를 선택할 수 있습니다. 이전 버전의 SSE는 일반적으로 /sse를 사용해 이벤트 스트림을 생성하고, 반환된 /message?sessionId=...를 통해 JSON-RPC 요청을 수신합니다. 인증 요청 헤더는 Authorization=Bearer <token>으로 구성합니다.

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

Releases에서 해당 플랫폼의 압축 패키지를 다운로드하고 압축을 해제하세요. 일반적으로 artex, start.sh 또는 Windows용 start.bat, skills/ 및 config.example.json이 포함되어 있습니다.

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

start.sh 또는 start.bat로 시작하고 ./artex를 직접 실행하지 마세요. 시작 스크립트는 프로세스를 관리하며, 페이지에서 원클릭 업데이트를 수행한 후 다시 실행하는 기능을 지원합니다. 백그라운드에서 실행하려면 다음을 사용할 수 있습니다.

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

방법 4: 소스에서 컴파일

프런트엔드가 내장된 단일 바이너리를 소스에서 빌드하려면 먼저 Next.js 정적 파일을 생성한 다음 백엔드의 내장 디렉터리로 복사합니다.

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

기본 구성 완료

PostgreSQL 구성

ARTEX는 PostgreSQL에 의존합니다. 로컬 실행 방식을 사용할 때는 config.json에 데이터베이스 연결 정보를 입력하거나 ARTEX_PG_DSN으로 설정을 덮어쓸 수 있습니다.

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

실행 과정

서비스는 시작할 때마다 데이터베이스 스키마 초기화와 마이그레이션을 멱등적으로 실행하며, 필요한 필드 및 인덱스 변경도 포함합니다. 업그레이드 전에는 데이터베이스와 ./data 디렉터리를 백업하는 것이 좋습니다.

LLM 구성

탐색 기능에는 LLM이 필요합니다. Anthropic 또는 OpenAI의 API Key를 사용하거나 인터페이스의 「LLM 구성」 페이지에서 입력할 수 있습니다.

export ANTHROPIC_API_KEY=sk-...

OPENAI_API_KEY도 설정할 수 있습니다. 또한 ARTEX_LLM_PROVIDER, ARTEX_LLM_MODEL, ARTEX_LLM_BASE_URL 및 ARTEX_LLM_PROXY를 통해 제공업체, 모델, 주소 및 프록시를 조정할 수 있습니다.

동시성 및 포트 조정

각 작업의 work agent 수는 「시스템 설정」에서 조정할 수 있으며 기본값은 3입니다. 시작 매개변수로 Web/API 주소와 트래픽 기록 프록시 포트를 설정할 수 있습니다.

./start.sh -addr :8787 -proxy :8788

시작 스크립트는 매개변수를 그대로 artex에 전달합니다.

Web 인터페이스 사용 시작

탐색 경로

1. 로그인하고 대시보드 확인

처음 방문할 때 관리자 비밀번호를 설정한 다음 대시보드에서 개요, Token 사용량 및 활동 스트림을 확인하세요. 대시보드는 현재 시스템이 정상적으로 실행 중인지, 작업에서 새로운 활동이 발생했는지 빠르게 판단하는 데 적합합니다.

2. 작업 및 실행 과정 확인

작업 목록에서 대상 작업을 선택하면 세션, 도구 호출, 활동 기록 및 탐색 경로를 확인할 수 있습니다. 실행 과정 페이지에는 agent의 작업 단계가 표시되고, 탐색 경로는 목표, 의도, 사실 및 발견 항목 간의 관계를 파악하는 데 사용됩니다.

이러한 페이지를 사용할 때는 먼저 로컬 격리 환경에서 흐름을 검증하고, 활동 기록과 트래픽 기록을 통해 agent가 실제로 어떤 단계를 실행했는지 확인해야 합니다.

3. 발견 항목 및 자산 확인

발견 페이지에는 작업에서 생성된 취약점 또는 기타 발견 항목이 모여 표시되고, 자산 페이지에는 시스템이 수집하고 통합한 자산 정보가 표시됩니다.

자산 커버리지 맵은 힘 기반 레이아웃으로 범위 내 자산을 표시하고 테스트가 완료된 노드를 강조할 수 있으며, 노드를 접거나 펼치는 기능을 지원합니다. 전체 관점에서 어떤 자산이 탐색되었고 어떤 자산이 아직 포함되지 않았는지 확인하는 데 적합합니다.

ScopeSentry 자산 동기화

이미 ScopeSentry에서 자산을 수집했다면 ARTEX의 「자산 동기화」 페이지에서 데이터 소스를 연결하여 중복 수집을 방지할 수 있습니다.

ScopeSentry 주소와 API Key를 입력하여 데이터 소스를 연결합니다.
프로젝트 또는 작업별로 동기화할 대상을 선택합니다.
도메인, 서브도메인, IP, 포트, 사이트 또는 엔드포인트 등 자산 유형을 선택합니다.
가져오기를 실행하여 ARTEX가 회사 자산 범위에 따라 데이터를 통합하도록 합니다.
자산 그래프에서 가져오기 결과를 확인하고 이후 탐색을 위해 agent에 제공합니다.

자산 그래프는 작업 간 공유되는 전역 자산 기준 저장소입니다. 프로그램이 부모-자식 관계와 중복 제거 키를 계산하며, agent는 원시 자산 정보를 제출합니다.

ARTEX의 이중 그래프 아키텍처 이해

자산 그래프: 어떤 자산이 있는지 설명

자산 그래프의 노드에는 root_domain, subdomain, ip, service, app, endpoint 등이 포함됩니다. 도메인, 하위 도메인, 서비스와 엔드포인트는 부모-자식 관계로 구성되며 해당 회사에 귀속됩니다.

탐색 그래프: 작업을 어떻게 진행하는지 설명

탐색 그래프는 작업별로 독립적으로 저장되며, 노드에는 goal, intent, fact, finding, hint가 포함됩니다. 시스템은 spawns, derived_from, yields, proves 등의 관계를 통해 진행 경로를 기록합니다.

두 그래프는 앵커를 통해 연결됩니다. 의도, 사실, 취약점은 특정 자산에 연결할 수 있으므로 탐색 방향에서 관련 자산을 확인하거나, 특정 자산에서 역으로 조회하여 현재 작업에서 어떤 방향으로 테스트되었는지 확인할 수 있습니다.

planner와 worker의 협업 방식

엔진은 이벤트 기반 폐쇄 루프로 동작합니다. 그래프가 변경되면 planner가 깨어나 현재 상황을 읽고 의도를 할당합니다. worker는 의도 하나를 가져와 도구를 사용해 실행한 뒤 새로운 자산, 사실 또는 발견 결과를 데이터베이스에 기록하며, 기록 작업이 다시 planner를 트리거합니다.

planner는 아직 다루지 않은 새로운 방향을 발견한 경우에만 의도를 할당합니다. worker는 자신이 가져온 의도를 완료하면 중지하여 여러 worker가 제한 없이 반복 실행하는 것을 방지합니다.

여러 단계로 구성되고 선후 의존성이 있는 탐색 경로의 경우, planner는 작업별로 유지되는 공유 todolist를 관리합니다. 선행 단계가 완료되고 해당 사실이 존재할 때만 다음 단계가 할당됩니다. 이 메커니즘은 전체 경로가 한 번에 병렬로 확장되는 것을 방지합니다.

다른 worker의 실행 과정 검색

후속 worker는 search_all_worker_traces(q)를 사용하여 현재 작업의 다른 work 실행 과정에서 키워드로 검색할 수 있습니다. 또한 list_worker_traces로 이미 실행된 work를 확인한 다음, get_worker_trace(intent_id, step_ids=[...])를 통해 지정된 단계의 전체 내용을 가져올 수 있습니다. 시스템은 현재 worker 자신의 의도를 자동으로 제외합니다.

이러한 과정 수준의 정보 교환은 agent가 아직 fact로 정식 기록되지 않은 관찰 결과를 재사용하도록 돕는 동시에, 각 worker가 자신에게 할당된 의도만 실행한다는 경계를 유지합니다.

트래픽 기록 및 승인

ARTEX는 트래픽 녹화 프록시와 도구 승인 게이트를 제공합니다. 트래픽 페이지에서는 도구 실행으로 생성된 기록을 확인할 수 있고, 차단 및 승인 페이지에서는 사람의 확인이 필요한 작업을 처리할 수 있습니다.

보안 검증 시에는 작업 세션, 도구 호출, 활동 스트림, 트래픽 기록을 함께 확인하여 시스템 동작이 예상과 일치하는지 검증하는 것이 좋습니다. 휴먼 인 더 루프 대화는 컨텍스트를 보완하고 승인 과정에 참여하는 데에도 사용할 수 있습니다.

취약점 재테스트 실행

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

자산 적용 범위 그래프

취약점 목록 또는 취약점 상세에서 「재테스트」를 클릭합니다.
필요에 따라 수정 버전, 테스트 조건 또는 제한 사항을 입력합니다.
독립적인 재테스트 Agent 세션을 시작합니다.
세션에서 재테스트 과정을 확인하고, 종료 후 결론과 증거를 확인합니다.

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

시스템에는 편집 가능한 「취약점 재테스트」retester Agent가 사전 구성되어 있습니다. Agent 관리에서 프롬프트, LLM, 실행 예산, 도구를 설정할 수 있습니다. 전용 LLM이 연결되지 않은 경우 전역 활성 설정을 사용합니다. 동일한 취약점을 재테스트하는 동안에는 기존 세션을 재사용하며, 중지, 실패 또는 서비스 재시작 후에는 다시 시작할 수 있습니다.

프로젝트 설명에 따르면 재테스트 이력은 아직 취약점 보고서 내보내기나 작업 보관 패키지에 포함되지 않으며, 트래픽 패키지와도 자동으로 연결되지 않습니다. 데모 모드에서는 명확히 표시된 시뮬레이션 기록만 생성하고 실제 대상에는 요청을 보내지 않습니다.

리버스 프록시 배포 핵심 사항

프런트엔드, API, SSE는 기본적으로 동일한 백엔드 포트에서 제공되므로 일반적으로 HTTPS 포트만 외부에 공개하고 ARTEX의 8787은 내부 네트워크에 유지하면 됩니다. 실시간 활동 스트림은 동일 출처 주소를 사용하므로 대개 NEXT_PUBLIC_SSE_BASE를 설정할 필요가 없습니다.

Nginx와 같은 리버스 프록시는 SSE 버퍼링을 비활성화하고 긴 읽기 시간 제한을 설정해야 합니다. 그렇지 않으면 브라우저가 연결에는 성공하지만 활동 이벤트를 계속 수신하지 못할 수 있습니다.

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 실행 시 정적 패키지에 고정되므로 컨테이너 실행 시 설정해도 적용되지 않습니다.

업그레이드 및 롤백

트래픽

ARTEX를 업그레이드하면 프로그램은 교체되지만 PostgreSQL 데이터 볼륨, ./data, ./skills는 보존됩니다. 시스템 설정 페이지의 「버전 및 업데이트」 카드에서 원클릭 업데이트를 실행하는 것이 좋습니다. 업데이트 과정에서는 현재 플랫폼용 릴리스 패키지를 다운로드하고, SHA256SUMS를 검증하며, 새 바이너리의 스모크 테스트를 실행한 뒤 시작 스크립트가 교체를 완료합니다.

검증 또는 스모크 테스트에 실패하면 임시 프로그램은 폐기됩니다. 새 버전이 연속 세 번 시작에 실패하면 자동으로 롤백됩니다. 이전 버전은 artex.old로 보존됩니다. 단, 데이터베이스 구조는 프로그램 롤백에 따라 되돌아가지 않으므로 업그레이드 전에 데이터베이스와 ./data를 백업해야 합니다.

업데이트하면 서비스가 재시작되고 실행 중인 작업이 중단되므로 한가한 시간에 수행해야 합니다. Docker 배포에서는 페이지 업데이트가 프로그램만 교체하고 이미지에 포함된 도구 체인은 교체하지 않는다는 점에도 유의해야 합니다. 이미지를 업그레이드하려면 다음을 실행합니다.

docker compose pull artex
docker compose up -d artex

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

cd ARTEX
./update.sh

로컬 개발 및 테스트

개발 환경에서는 dev.sh를 사용하여 백엔드, 트래픽 프록시, Next.js 개발 서버를 동시에 시작할 수 있습니다.

./dev.sh

기본 백엔드 포트는 8787, 트래픽 프록시 포트는 8788, 프런트엔드 개발 서버 포트는 5173입니다. 각각 별도로 실행할 수도 있습니다.

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

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

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

요약

ARTEX는 Go 모놀리식 백엔드, Next.js 인터페이스, PostgreSQL, LLM agent, 트래픽 기록, 승인 메커니즘, 자산 관리를 하나의 시스템으로 통합합니다. 처음에는 Docker 또는 설치 스크립트로 배포한 뒤 PostgreSQL과 LLM을 구성하고, 작업, 세션, 탐색 경로, 자산 적용 범위 그래프, 트래픽 기록을 차례로 살펴보며 시스템 동작을 이해할 수 있습니다.

자산 그래프와 탐색 그래프의 역할을 이해하는 것이 ARTEX를 익히는 핵심입니다. 자산 그래프는 “어떤 자산이 있는가”에 답하고, 탐색 그래프는 “작업이 어떻게 진행되는가”에 답합니다. 모든 테스트는 반드시 로컬 격리 환경과 프로젝트에서 허용한 학습 목적 내로 엄격히 제한하고, 프로젝트 고지, 오픈소스 라이선스 및 관련 법률을 준수해야 합니다.