[보안 자동화] PentAGI + Colima + Gemini API: macOS에서 AI 침투테스트 에이전트 구축하기

AI가 스스로 침투테스트를 수행한다면 어떨까요? PentAGI는 GPT/Claude/Gemini 같은 LLM을 활용해 nmap, metasploit, sqlmap 등 20개 이상의 보안 도구를 자율적으로 조합하고 실행하는 AI 기반 자동화 침투테스트 에이전트입니다. macOS 환경에서 Docker Desktop 대신 가벼운 Colima를 사용하고, Google Gemini API로 구동하는 방법을 소개합니다.

---

PentAGI란?

PentAGI는 “Penetration testing Artificial General Intelligence”의 약자로, 보안 전문가와 연구자를 위한 완전 자율화 침투테스트 플랫폼입니다. GitHub Stars 14,000+를 기록하며 빠르게 성장하고 있는 오픈소스 프로젝트입니다.

PentAGI 웹 UI — AI 에이전트가 실시간으로 침투테스트를 수행하는 화면

핵심 특징

항목	내용
자율 실행	AI 에이전트가 공격 단계를 스스로 결정하고 실행
샌드박스 격리	모든 작업이 Docker 컨테이너 내에서 격리 수행
통합 보안 도구	nmap, metasploit, sqlmap, gobuster 등 20+ 도구 내장
장기 메모리	Neo4j 지식 그래프로 연구 결과 및 성공 전략 축적
다중 LLM 지원	OpenAI, Anthropic, Gemini, Ollama, DeepSeek 등 10+ 공급자
자동 보고서	취약점 상세 보고서 및 공격 가이드 자동 생성
완전 자체 호스팅	데이터 외부 유출 없이 온프레미스 운영

아키텍처

┌─────────────────────────────────────────────────────┐
│                    PentAGI Stack                    │
├─────────────┬────────────────┬──────────────────────┤
│  Frontend   │    Backend     │    Supporting        │
│  React+TS   │  Go+GraphQL   │   PostgreSQL+pgvec   │
│  Web UI     │  REST API      │   Neo4j (그래프DB)   │
└─────────────┴────────────────┴──────────────────────┘
         ↓ LLM 요청
┌─────────────────────────────────────────────────────┐
│            Gemini / OpenAI / Claude ...             │
└─────────────────────────────────────────────────────┘
         ↓ 도구 실행
┌─────────────────────────────────────────────────────┐
│     격리된 Docker 샌드박스 (보안 도구 컨테이너)       │
│     nmap / metasploit / sqlmap / gobuster / ...     │
└─────────────────────────────────────────────────────┘

---

사전 준비: Colima 설치 및 설정

macOS에서 Docker Desktop 없이 컨테이너를 실행하려면 Colima가 좋은 대안입니다. 가볍고 무료이며 Docker CLI와 완전히 호환됩니다.

Colima 설치

# Homebrew로 설치
brew install colima docker docker-compose

# Colima 시작 (PentAGI는 리소스를 꽤 사용하므로 넉넉하게 설정)
colima start --cpu 4 --memory 8 --disk 40

# 상태 확인
colima status
docker info

Tip: 매번 수동으로 시작하는 대신 macOS 부팅 시 자동 시작을 설정할 수 있습니다.

# 로그인 시 자동 시작
brew services start colima

Docker Compose 플러그인 확인

docker compose version
# Docker Compose version v2.x.x 이상이어야 합니다

---

Gemini API 키 발급

PentAGI를 Gemini로 구동하려면 Google AI Studio에서 API 키를 발급받아야 합니다.

1. Google AI Studio 접속
2. “Create API key” 클릭
3. 프로젝트 선택 또는 새 프로젝트 생성
4. 발급된 키 복사 (AIza... 형태)

무료 티어에서도 Gemini 1.5 Flash/Pro 사용 가능하며, 침투테스트 에이전트 실습 수준에는 충분합니다.

---

PentAGI 설치

1. 작업 디렉토리 생성 및 환경 파일 다운로드

mkdir pentagi && cd pentagi

# 환경변수 템플릿 다운로드
curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example

# docker-compose 파일 다운로드
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml

2. .env 파일 설정

.env 파일을 열어 Gemini API 키와 필수 설정을 입력합니다.

# macOS에서 편집
nano .env
# 또는
code .env

필수 변경 항목:

# ─── LLM 공급자: Gemini 설정 ───────────────────────────────
GEMINI_API_KEY=AIzaSy...your_gemini_api_key_here...

# 기본 모델을 Gemini로 지정 (선택)
# MAIN_MODEL_PROVIDER=gemini
# MAIN_MODEL=gemini-1.5-pro

# ─── 보안 설정 (반드시 변경 권장) ────────────────────────────
COOKIE_SIGNING_SALT=여기에_랜덤_문자열_입력

# ─── PostgreSQL 패스워드 ──────────────────────────────────────
PENTAGI_POSTGRES_PASSWORD=강력한_패스워드_입력

# ─── Neo4j 패스워드 ───────────────────────────────────────────
NEO4J_PASSWORD=강력한_패스워드_입력

# ─── 서버 주소 (로컬 사용 시 기본값 유지 가능) ───────────────
PUBLIC_URL=https://localhost:8443

선택: 검색 엔진 통합 (AI 에이전트 정보 수집 강화)

# DuckDuckGo는 키 없이 사용 가능
DUCKDUCKGO_ENABLED=true

# Tavily (선택, 더 정확한 보안 정보 검색)
# TAVILY_API_KEY=tvly-...

# Perplexity (선택)
# PERPLEXITY_API_KEY=pplx-...

3. Colima에서 Docker 소켓 경로 확인

Colima는 기본 Docker 소켓 경로가 다를 수 있습니다. .env에서 Docker 소켓 설정을 확인합니다.

# Colima의 Docker 소켓 위치 확인
ls -la ~/.colima/default/docker.sock

# 환경변수로 설정 (필요한 경우)
export DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock

.env 파일에 Docker 호스트 설정이 있다면 Colima 소켓 경로로 변경합니다.

# .env 내 Docker 설정
DOCKER_HOST=unix:///Users/your_username/.colima/default/docker.sock

또는 셸 프로파일에 영구 등록합니다.

# ~/.zshrc 또는 ~/.bashrc에 추가
echo 'export DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock' >> ~/.zshrc
source ~/.zshrc

---

실행

# 컨테이너 시작 (백그라운드)
docker compose up -d

# 로그 확인
docker compose logs -f

# 서비스 상태 확인
docker compose ps

모든 서비스가 running 상태가 되면 브라우저에서 접속합니다.

https://localhost:8443

자체 서명 인증서를 사용하므로 브라우저에서 “고급 → 안전하지 않음으로 이동” 클릭이 필요합니다.

기본 로그인 정보:

항목	값
이메일	admin@pentagi.com
패스워드	admin

최초 로그인 후 반드시 패스워드를 변경하세요.

---

첫 번째 침투테스트 플로우 실행

웹 UI에서 플로우 생성

1. 로그인 후 “New Flow” 클릭
2. 타겟 정보 입력 (예: Scan 192.168.1.0/24 for open ports and identify services)
3. LLM 공급자로 Gemini 선택
4. “Start” 클릭

AI 에이전트가 자동으로:

• 정보 수집 단계 계획 수립
• nmap 스캔 실행
• 발견된 서비스에 대한 취약점 분석
• 추가 공격 벡터 탐색
• 최종 보고서 생성

API 토큰으로 자동화

웹 UI Settings → API Tokens에서 토큰 생성 후 GraphQL API 활용:

# 실행 중인 플로우 목록 조회
curl -X POST https://localhost:8443/api/v1/graphql \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -k \
  -d '{"query": "{ flows { id title status } }"}'

---

운영 팁

리소스 모니터링

PentAGI는 여러 컨테이너를 동시에 운영하므로 Colima 리소스를 모니터링합니다.

# Colima 내 리소스 사용량
docker stats

# 필요 시 Colima 리소스 조정 (재시작 필요)
colima stop
colima start --cpu 6 --memory 12 --disk 60

컨테이너 관리

# 서비스 중지
docker compose down

# 설정 변경 후 재시작
docker compose down
docker compose up -d --force-recreate

# 볼륨 포함 완전 초기화 (데이터 삭제 주의)
docker compose down -v

Gemini 모델 선택 가이드

모델	추천 용도	비고
gemini-1.5-flash	빠른 정보 수집, 간단한 분석	저비용, 높은 처리량
gemini-1.5-pro	복잡한 공격 체인 계획	더 깊은 추론 능력
gemini-2.0-flash	최신 모델, 빠른 응답	2026년 기준 권장

---

주의 사항

이 도구는 반드시 허가된 환경에서만 사용해야 합니다.

• 본인 소유 또는 명시적 허가를 받은 시스템에만 사용
• 실제 프로덕션 환경 대상 무단 스캔 및 공격은 불법
• CTF, 취약점 랩(HackTheBox, TryHackMe), 내부 테스트 환경에 적합
• 모든 활동 로그가 PostgreSQL에 저장되므로 감사 추적 가능

---

마무리

PentAGI는 침투테스트의 반복적이고 시간 소모적인 정보 수집 및 기초 분석 작업을 AI로 자동화하여 보안 전문가가 더 복잡한 분석에 집중할 수 있게 해줍니다. macOS에서 Docker Desktop 없이 Colima로 가볍게 구동하고, Gemini API로 비용 효율적으로 운영할 수 있다는 점이 큰 장점입니다.

보안 자동화에 관심 있는 분들께 좋은 출발점이 될 것입니다.

---

설치 문서 공유

PentAGI Mac(Colima) 맞춤 설치 가이드 및 아키텍처

본 문서는 현재 시스템에 실제로 수행되었던 맞춤형 PentAGI 설치 과정과 아키텍처 변경점을 기록한 가이드입니다.

일반적인 공식 설치 문서는 현재 열려 있는 README.md의 [## Architecture] 와 [## Quick Start] 부분에 정의되어 있으나, 현재 사용자님의 환경(Docker Desktop 사용 불가 방침, 사내망 인증서 가로채기 환경)에 걸맞게 커스터마이징된 내용은 다음과 같습니다.

---

1. 실제 구동된 아키텍처 (Modified Architecture)

공식 아키텍처는 여러 모니터링 모듈이 포함되지만 이번 로컬 환경 구성을 위해 필수 핵심 모듈만 남기고 아키텍처를 슬림화했습니다.

1-1. 코어 컨테이너 구성

• PentAGI (Main Application)
  • 사용자의 요청을 받아 LLM(대규모 언어 모델)과 통신하고 AI 펜테스터를 가동하는 메인 백엔드 서버입니다.
• PGVector (Database)
  • 과거 진단 이력, 프롬프트 히스토리 등을 벡터 형태로 기록하고 조회하기 위한 메인 저장소입니다. 기본 postgres 이미지가 아닌 벡터 검색 확장(pgvector)이 포함된 이미지(vxcontrol/pgvector)를 사용합니다.
• Scraper (Web Crawler)
  • AI가 필요할 때마다 외부 인터넷이나 타겟 웹을 안전하게 렌더링하고 가져올 수 있게 해주는 격리된 크롤링 엔진입니다. (vxcontrol/scraper)

1-2. 제거된 모듈 (우회 구성)

• Postgres-Exporter (quay.io/...)
  • 내부 DB 모니터링을 위해 작동하는 부가 기능입니다. quay.io 레지스트리를 통한 다운로드 시 사내망 TLS 인증서 가로채기(SSL Inspection)로 인해 x509 에러가 발생하여 docker-compose.yml 에서 제거되었습니다.

---

2. 실제 수행된 설치 방법 (Custom Execution Log)

방금 어시스턴트를 통해 순차적으로 실행된 핵심 설치 단계입니다.

2-1. 코드 초기화

빈 폴더로 남아있던 파일들을 공식 GitHub 저장소에서 정상적으로 모두 가져와 작업 디렉토리를 복구했습니다.

git reset --hard && git pull origin main

2-2. Colima(Docker 데몬) 시작 및 연결

Docker Desktop이 금지된 환경이므로 대체재인 Colima를 가동했습니다.

colima start

2-3. 환경 변수(.env) 설정 및 소켓 경로 수정

Colima가 생성한 도커 소켓 경로를 컨테이너가 정상적으로 바라볼 수 있도록 파일 수정 작업을 거쳤습니다.

1. .env.example을 복사하여 .env 생성
2. .env 파일 내부의 주석문이 Docker Compose 파싱 과정에서 충돌을 일으키지 않도록 perl 명령어로 모든 내부 주석을 제거.
3. .env 내부에 Colima 소켓을 입력: PENTAGI_DOCKER_SOCKET=/Users/wm-it-25-0177/.colima/default/docker.sock

2-4. 호스트 경로 충돌 해결 (docker-compose.yml)

docker-compose.yml 환경변수 세팅에서 외부 터미널의 환경변수가 로컬 호스트 경로로 치환되어 문제를 일으키는 것을 막기 위해, DOCKER_HOST를 내부 고정값으로 강제매핑했습니다.

# 수정 전
- DOCKER_HOST=${DOCKER_HOST:-unix:///var/run/docker.sock}
# 수정 후
- DOCKER_HOST=unix:///var/run/docker.sock

2-5. 사내망 인증서 충돌 모듈 제거

DB 모니터링 모듈이 사내망 방화벽 문제로 에러를 내뿜자 docker-compose.yml에서 pgexporter 서비스 정의 부분을 통째로 지웠습니다.

2-6. 서비스 실행 및 찌꺼기 제거

.env 파일에 섞여있던 주석 문자로 인해 생성되었던 잘못된 로컬 DB 볼륨을 삭제하고 초기 실행했습니다.

docker-compose down
docker volume rm pentagi_pentagi-postgres-data
docker-compose up -d

이후 3개의 메인 코어 서비스가 포트 8443 으로 문제없이 기동되었습니다.

---

참고 링크

• PentAGI GitHub
• Colima GitHub
• Google AI Studio (Gemini API 키 발급)