yohannesgk/blacksmith: AI 기반 침투 테스트 프레임워크

[오픈 소스 (OPEN-SOURCE)] AI 기반 침투 테스트 프레임워크 (Penetration Testing Framework)

자동화된 보안 평가 및 침투 테스트를 위한 지능형 멀티 에이전트 시스템 (Multi-agent system).

로컬 설정 없이 빠르게 테스트할 수 있는 호스팅 버전이 제공됩니다. Blacksmith-AI

• 개요 (Overview)
• 아키텍처 (Architecture)
• 사전 요구 사항 (Prerequisites)
• 설치 (Installation)
• Makefile을 이용한 빠른 시작 (Quick Start with Makefile)
• 설정 (Configuration)
• 사용법 (Usage)
• 도구 및 기능 (Tools & Capabilities)
• 에이전트 워크플로우 (Agent Workflow)
• 문제 해결 (Troubleshooting)
• 문서 (Documentation)

BlacksmithAI는 여러 AI 에이전트를 활용하여 보안 평가를 자동화하는 오픈 소스 (opensource) 고급 침투 테스트 프레임워크입니다. 이 시스템은 통제된 환경에서 전문 보안 도구를 사용하여 정찰 (Reconnaissance)부터 침투 후 단계 (Post-exploitation)에 이르기까지 전체 침투 테스트 라이프사이클을 통해 특화된 에이전트들을 오케스트레이션 (Orchestrate)합니다.

멀티 에이전트 아키텍처 (Multi-Agent Architecture): 침투 테스트의 각 단계에 특화된 에이전트들
전문적인 도구 구성 (Professional Tooling): 업계 표준 보안 도구가 포함된 사전 구성된 Docker 이미지
유연한 LLM 제공자 (Flexible LLM Providers): OpenRouter, VLLM 및 사용자 정의 제공자 지원
웹 및 터미널 인터페이스 (Web & Terminal Interfaces): 현대적인 UI 또는 CLI 상호작용 중 선택 가능
자동화된 보고서 (Automated Reporting): 증거를 포함한 종합적인 보안 보고서 생성
안전 및 통제 (Safe & Controlled): AI 에이전트 실행을 위해 설계된 비대화형 (Non-interactive) CLI 도구

• 자동화된 보안 평가 (Automated security assessments)
• 지속적인 보안 모니터링 (Continuous security monitoring)
• 교육용 침투 테스트 (Educational penetration testing)
• 취약점 발견 및 검증 (Vulnerability discovery and validation)
• 보안 연구 및 개발 (Security research and development)

BlacksmithAI는 계층적 멀티 에이전트 시스템을 사용합니다.

오케스트레이터 (Orchestrator) - 명령 및 제어 센터

• 미션 계획 및 작업 위임 관리

• 서브 에이전트 (Subagents) 조정 및 최종 보고서 생성

특화된 서브 에이전트 (Specialized Subagents)
정찰 에이전트 (Recon Agent): 공격 표면 매핑 (Attack surface mapping) 및 정보 수집
스캔/열거 에이전트 (Scan/Enum Agent): 심층 스캔 및 서비스 열거 (Service enumeration)
취약점 분석 에이전트 (Vulnerability Analysis Agent): 취약점 매핑 및 위험 평가
익스플로잇 에이전트 (Exploit Agent): 개념 증명 (Proof-of-concept) 익스플로잇
침투 후 에이전트 (Post-Exploit Agent): 영향 평가 및 피벗 (Pivot) 분석

각 에이전트는 자신의 역할에 맞게 조정된 특정 도구에 접근할 수 있어, 효율적이고 집중된 운영을 보장합니다.

운영 체제 (Operating System): Linux (권장), macOS, 또는 WSL2를 사용하는 Windows
RAM: 최소 4GB (8GB 권장)
디스크 공간 (Disk Space): Docker 이미지를 포함하여 2GB 이상
Docker: Docker Compose를 포함한 20.10 이상
Python: 3.12 이상 (uv를 통해 관리됨)

우리는 다음 도구들에 의존합니다:

# Python 패키지 및 환경 관리자
uv
# 컨테이너화 (Containerization)
...

uv는 빠르고 현대적인 Python 패키지 관리자이자 환경 도구입니다. pip, pipx, 그리고 virtualenv를 터보차저로 결합한 것과 비슷합니다. ([GitHub][1])

# 공식 설치 스크립트를 통한 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

Python 패키지 버전을 선호하는 경우:

pip install uv
# 또는
pipx install uv

확인:

uv --version

참고 사항:

• 전체 기능과 자동 업데이트를 위해 독립형 (Standalone) 스크립트를 권장합니다. ([Astral Docs][2])
• Windows에서는 PowerShell을 사용하세요:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Docker를 사용하면 백엔드 서비스, 데이터베이스 등을 컨테이너화하여 실행할 수 있습니다.

sudo apt update
sudo apt install -y docker.io docker-compose

brew install --cask docker

설치 후, Docker Desktop을 시작하고 다음을 확인하세요:

docker --version
docker compose version

버전 출력이 보인다면 준비가 완료된 것입니다.

팁: Linux에서는 사용자를 docker 그룹에 추가하는 것이 좋습니다:

sudo usermod -aG docker $USER
# 그 다음 터미널을 재시작하세요

프론트엔드 툴링을 위해 Node.js를 사용합니다. 현대적인 pnpm 및 생태계 호환성을 위해 Node 18 이상이 필요합니다. ([docs.pyloid.com][3])

# NodeSource 설정을 사용 (정확한 버전을 위해 권장됨)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

Homebrew로 설치:

brew install node@18

확인:

node --version
npm --version

pnpm은 일관되고 빠른 설치와 예측 가능한 락파일 (lockfiles)을 위해 선호됩니다. ([pnpm.cn][4])

다음 방법 중 하나로 설치할 수 있습니다:

npm install -g pnpm

curl -fsSL https://get.pnpm.io/install.sh | sh -

corepack enable
corepack prepare pnpm@latest --activate

확인:

pnpm --version

다음 검사를 시도해 보세요:

uv --version
node --version
pnpm --version
...

만약 vLLM 로컬 모델을 사용하려면:

cd blacksmithAI/blacksmithAI
uv add vllm
uv add huggingface_hub
...

vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
--host 0.0.0.0 \
--port 8000 \
...

git clone https://github.com/yohannesgk/blacksmith.git

# uv를 사용하여 의존성 설치
cd blacksmithAI/blacksmithAI
uv sync

mini-kali 컨테이너는 안전하고 격리된 환경에서 모든 침투 테스트 도구를 제공합니다.

# 다음 명령어로 시작
cd blacksmithAI/blacksmithAI
docker compose up -d

터미널 전용 인터페이스를 사용하는 경우 이 단계는 건너뜁니다.

cd blacksmithAI/frontend
pnpm install
cd ../..

더 간단한 설정 경험을 위해 제공된 Makefile 명령어를 사용하세요. make help를 실행하여 사용 가능한 모든 명령어를 확인하세요.

make setup

이 명령어는 다음 작업을 수행합니다:

• Python 의존성 설치 (make install)
• Docker 이미지 빌드 (make docker-build)
• 프론트엔드 의존성 설치 (make frontend-install)

설정 또는 설치 후, 환경을 구성하세요:

# 1. 예시 환경 파일 복사
cp blacksmithAI/.env.example blacksmithAI/.env
# 2. API 키로 .env 편집
...

make start-cli
또는
uv run main.py

이 명령어는 다음을 수행합니다:

• mini-kali Docker 컨테이너 시작
• CLI 인터페이스 실행

웹 UI는 여러 개의 터미널을 필요로 합니다. 별도의 터미널에서 다음 명령어를 실행하세요:

# 터미널 1: Docker 컨테이너 시작
make docker-up
# 터미널 2: 프론트엔드 시작
...

그런 다음 다음 주소에 접속합니다: http://localhost:3000

# VLLM 설치
make vllm-install
# VLLM 서버 시작
...

명령어	설명
make help	사용 가능한 모든 명령어 표시
make install	Python 의존성 (dependencies) 설치
make setup	초기 설정 완료
make frontend-install	프론트엔드 (frontend) 의존성 설치
make docker-build	mini-kali Docker 이미지 빌드
make docker-up	Docker 컨테이너 시작
make docker-down	Docker 컨테이너 중지
make docker-logs	Docker 로그 확인
make vllm-install	로컬 LLM을 위한 VLLM 설치
make vllm-serve	VLLM 서버 시작 (123B 모델)
make vllm-serve-small	VLLM 서버 시작 (7B 모델)
make start-cli	CLI 모드 시작
make start-ui	Web UI 설정 안내 표시
make start-all	CLI 모드 퀵 스타트 (Quick start)
make stop	모든 서비스 중지
make clean	Docker 컨테이너 정리
make status	Docker 컨테이너 상태 표시
make check-deps	의존성 설치 여부 확인
make check-config	설정 파일 (configuration files) 확인
make quickstart	퀵 스타트 가이드 표시

# 최초 설정
make setup
cp blacksmithAI/.env.example blacksmithAI/.env
...

예제 파일을 사용하여 .env 파일을 생성합니다:

cp blacksmithAI/.env.example blacksmithAI/.env

.env 파일을 편집하고 API 키를 추가합니다:

OPENROUTER_API_KEY=your-openrouter-api-key-here

환경 변수 (environment variables)가 필요하지 않은 경우, VLLM 서버가 실행 중인지 확인하십시오:

# VLLM 서버 시작 예시
vllm serve <model-name> --port 8000

blacksmithAI/config.json을 편집하여 LLM 제공자 (providers) 및 모델을 구성합니다.

{
"defaults": {
"provider": "openrouter", // 또는 "vllm", 또는 커스텀(openai)
...

단순히 config.json을 편집하고 .env에 API 키를 추가함으로써 openai, claude,... 등 훨씬 더 많은 제공자를 지원할 수 있습니다.

예를 들어, openai 지원을 추가하려면 config.json의 providers에 다음과 같이 추가할 수 있습니다:
"openai": {
"base_url": "....",
...

위의 방법을 통해 쉽게 확장(scaleup)하고 더 많은 지원을 추가할 수 있습니다.

: 사용할 기본 LLM 제공자 defaults.provider

: 제공자의 API 엔드포인트 (endpoint) base_url

: LLM 모델 식별자 (model identifier) default_model

: 임베딩 (embeddings)용 모델 (벡터 DB에서 사용됨) default_embedding_model

: 선택된 모델의 컨텍스트 창 (Context window) 크기 (요약 시 컨텍스트 창 오버플로를 방지하기 위해 필요함) context_size

: 요청 실패 시 재시도 횟수 max_retries

: 응답의 최대 토큰 수 (null = 모델 기본값) max_tokens

에이전트의 완전한 제어를 통해 터미널에서 직접 상호작용합니다.

# mini-kali Docker 컨테이너 시작
docker run -i --rm -p 9756:9756 mini-kali-slim -d
or
...

# BlacksmithAI 실행
cd blacksmithAI/blacksmithAI && uv run main.py
or
...

프롬프트에 따라 침투 테스트 (penetration testing) 작업을 시작하십시오.

침투 테스트 관리를 위한 현대적이고 사용자 친화적인 인터페이스에 접속합니다.

# 터미널 1: mini-kali 컨테이너 시작
docker run -i --rm -p 9756:9756 mini-kali-slim -d
or
...

UI 접속 주소: http://localhost:3000

로컬 설정 없이 빠르게 테스트할 수 있는 호스팅 버전이 제공됩니다.

BlacksmithAI는 mini-kali Docker 컨테이너를 통해 전문적인 침투 테스트 도구에 대한 접근을 제공합니다. 모든 도구는 비대화형 (non-interactive), stdin/stdout 실행을 위해 설계되었으며, 이는 AI 에이전트에게 이상적입니다.

수동적 (passive) 및 능동적 (active) 정보 수집을 통해 공격 표면 (attack surface) 지도를 구축합니다.

도구	목적
assetfinder	서브도메인 및 자산 발견
subfinder	서브도메인 열거 (enumeration)
whois	도메인 등록 정보
dig	DNS 레코드 조회
nslookup	DNS 질의 도구
hping3	네트워크 스캐닝 및 패킷 분석
dnsrecon	DNS 열거 및 정찰 (reconnaissance)

발견된 대상에 대해 심층 분석하여 서비스와 취약점을 식별합니다.

도구	목적
nmap	네트워크 매퍼 및 포트 스캐너
masscan	고속 포트 스캐너
enum4linux-ng	SMB/Windows 열거
nikto	웹 서버 스캐너
whatweb	웹 기술 식별
fingerprintx	서비스 핑거프린팅 (fingerprinting)
gobuster	디렉토리 및 DNS 브루트포싱 (brute-forcing)
wpscan	WordPress 취약점 스캐너

알려진 취약점(vulnerabilities)에 서비스를 매핑하고 보안 위험을 평가합니다.

도구	목적
nuclei	빠르고 맞춤 설정이 가능한 취약점 스캐너 (vulnerability scanner)
sslscan	SSL/TLS 설정 분석기 (analyzer)

통제된 익스플로잇 (exploits)을 실행하고 취약점을 검증합니다.

도구	목적
sqlmap	자동화된 SQL 인젝션 (SQL injection)
hydra	비밀번호 브루트포싱 (brute-forcing)
medusa	병렬 네트워크 로그인 감사 도구 (auditor)
ncrack	네트워크 인증 크래킹 (authentication cracking)
python/go/perl/ruby	맞춤형 익스플로잇 스크립팅 (exploit scripting)

성공적인 익스플로잇 이후 영향을 평가하고 피벗 (pivot) 기회를 식별합니다.

도구	목적
netcat	네트워크 디버깅 및 데이터 전송
socat	다목적 릴레이 (relay)
ssh -D	SOCKS 프록시 터널링 (proxy tunneling)
impacket	Windows 프로토콜 조작 (psexec, secretsdump)

다양한 작업을 위한 지원 도구입니다.

도구	목적
curl	URL 구문을 사용한 데이터 전송
httpie	사용자 친화적인 HTTP 클라이언트 (client)
trufflehog	비밀 정보 및 자격 증명 스캐너 (credential scanner)

웹 브라우저 (Web Browser): 자동화된 웹 브라우징을 위한 MCP-Playwright
코드 인터프리터 (Code Interpreter): Python 실행을 위한 MCP 코드 인터프리터
익스플로잇 데이터베이스 (Exploits Database): 익스플로잇 스크립트를 위한 Exploit-DB 또는 기타 제공업체와의 통합
대화형 도구 (Interactive Tools): Metasploit 및 기타 대화형 프레임워크 지원

BlacksmithAI는 조율된 에이전트 실행을 통해 구조화된 침투 테스트 방법론을 따릅니다.

역할 (Role): 일반 사령관 (General Commander)

오케스트레이터 (orchestrator)는 다음과 같은 중앙 조정 지점입니다:

• 상위 수준의 미션 계획 유지
• 작업 할 일 목록 (todo list) 관리
• 전문화된 하위 에이전트 (subagents)에게 작업 위임
• 발견 사항, 심각도, 증거 및 해결 가이드가 포함된 구조화된 최종 보고서 생성

사용 가능한 도구 (Available Tools): 계획 도구 (planning tools), 파일 시스템 도구 (filesystem tools)

역할 (Role): 공격 표면 매핑 (Attack Surface Mapping)

대상 환경의 포괄적인 지도를 구축합니다:

Passive OSINT (수동적 OSINT): DNS 레코드, SSL 인증서, WHOIS 데이터
Active Network Scanning (능동적 네트워크 스캐닝): 포트 및 서비스 탐색
Tech Stack Fingerprinting (기술 스택 핑거프린팅): 기술 및 버전 식별

사용 가능한 도구 (Available Tools): 정찰 (Reconnaissance) 도구, 일반 유틸리티

역할 (Role): 심층 조사 (Deep Inspection)

공격 표면 매핑 (Attack Surface Mapping) 이후, 이 에이전트는 다음을 수행합니다:

• 사용자 열거 (User Enumeration) 수행
• API 및 엔드포인트 조사
• 버전 및 설정 오류 (Misconfigurations) 발견
• 잠재적 진입점 식별

사용 가능한 도구 (Available Tools): 스캐닝 및 열거 (Enumeration) 도구, 일반 유틸리티

역할 (Role): 위험 평가 (Risk Assessment)

스캐닝 결과를 분석하여 다음을 수행합니다:

• 서비스를 알려진 취약점 (CVE, 로직 결함)과 매핑
• 영향도, 익스플로잇 가능성 (Exploitability) 및 비즈니스 리스크에 따라 우선순위 지정
• 간결한 증거 요약 생성
• 공격 가설 수립

사용 가능한 도구 (Available Tools): 취약점 매핑 도구, 일반 유틸리티

역할 (Role): 개념 증명 (Proof-of-Concept) 실행