- Linux, macOS, 또는 WSL2가 설치된 Windows
- Docker 20.10+ 및 Docker Compose
- Python 3.12+
- Node.js 18+ (Web UI용)
- 4GB+ RAM (8GB 권장)
# macOS & Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 설치 확인
uv --version
# Ubuntu/Debian
sudo apt update && sudo apt install -y docker.io docker-compose
# macOS
brew install --cask docker
# 확인
docker --version && docker compose version
# Ubuntu/Debian - Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
# macOS - Node.js
brew install node@18
# pnpm 설치
npm install -g pnpm
# 또는
corepack enable && corepack prepare pnpm@latest --activate
# 저장소 복제
git clone https://github.com/yohannesgk/blacksmith.git
cd blacksmith
# Python 의존성 설치
cd blacksmithAI/blacksmithAI
uv sync
# mini-kali Docker 이미지 빌드
docker compose up -d
# 선택: 프론트엔드 의존성 설치
cd ../frontend && pnpm install
# 환경 템플릿 복사
cp blacksmithAI/.env.example blacksmithAI/.env
# .env 파일 편집
nano blacksmithAI/.env
# .env에 추가
OPENROUTER_API_KEY=your-openrouter-api-key-here
# VLLM 설치
cd blacksmithAI/blacksmithAI
uv add vllm huggingface_hub
# VLLM 서버 시작
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 8192 \
--gpu-memory-utilization 0.75
blacksmithAI/config.json 편집:
{
"defaults": {
"provider": "openrouter"
},
"providers": {
"openrouter": {
"base_url": "https://openrouter.ai/api/v1/chat/completions",
"default_model": "mistralai/devstral-2512:free",
"default_embedding_model": "openai/text-embedding-3-small",
"default_model_config": {
"context_size": 200000,
"max_retries": 3,
"max_tokens": null
}
},
"vllm": {
"base_url": "http://localhost:8000/v1/chat/completions",
"default_model": "mistralai/devstral-2512",
"default_embedding_model": "text-embedding-3-small",
"default_model_config": {
"context_size": 200000,
"max_retries": 3
}
}
}
}
# config.json의 providers 섹션에 추가
"openai": {
"base_url": "https://api.openai.com/v1/chat/completions",
"default_model": "gpt-4-turbo",
"default_embedding_model": "text-embedding-3-small"
}
# .env에 추가
OPENAI_API_KEY=your-openai-key
# defaults 업데이트
"defaults": { "provider": "openai" }
# 터미널 1: mini-kali 컨테이너 시작
cd blacksmithAI/blacksmithAI
docker compose up -d
# 터미널 2: BlacksmithAI CLI 실행
cd blacksmithAI/blacksmithAI
uv run main.py
# 또는 Makefile 단축키 사용
make start-cli
# 터미널 1: mini-kali Docker 컨테이너 시작
cd blacksmithAI/blacksmithAI
docker compose up -d
# 터미널 2: 프론트엔드 시작 (blacksmithAI/frontend 디렉토리에서)
pnpm build && pnpm start
# 터미널 3: LangGraph 개발 서버 시작 (blacksmithAI/blacksmithAI에서)
uv run langgraph dev
# http://localhost:3000에서 접속
# 컨테이너 시작
docker compose up -d
# 로그 보기
docker logs mini-kali-slim
# 컨테이너 중지
docker compose down
# 컨테이너 재시작
docker compose restart
# 모든 컨테이너 제거
docker compose down -v
- 역할: 중앙 명령 제어
- 기능: 미션 계획, 작업 위임, 보고서 생성
- 사용 가능한 도구: 계획 도구, 파일시스템 도구
- 목적: 수동 및 능동 정보 수집
- 도구: assetfinder, subfinder, whois, dig, nslookup, hping3, dnsrecon
- 출력: DNS 기록, 서브도메인, 네트워크 토폴로지
- 목적: 사용자 열거, API 탐사, 버전 발견
- 도구: nmap, masscan, enum4linux-ng, nikto, whatweb, fingerprintx, gobuster, wpscan
- 출력: 열린 포트, 서비스, 기술, 엔드포인트
- 목적: 서비스를 CVE에 매핑, 위험 우선순위 지정
- 도구: nuclei, sslscan
- 출력: 심각도 및 악용 가능성 점수가 있는 취약점 목록
- 목적: 제어된 악용으로 취약점 검증
- 도구: sqlmap, hydra, medusa, ncrack, 커스텀 스크립트 (Python/Go/Perl/Ruby)
- 출력: 증거가 있는 손상 증명
- 목적: 영향 범위 및 피벗 기회 평가
- 도구: netcat, socat, ssh 터널링, impacket
- 출력: 횡적 이동 경로, 자격증명 인벤토리, 비즈니스 영향
# 일반적인 워크플로우 순서
1. 대상 지정 (도메인/IP)
2. Orchestrator가 정찰 단계 시작
3. Recon 에이전트가 발견: 서브도메인, DNS 기록, 메일 서버
4. 결과를 Scan/Enum 에이전트로 전달
# 완전한 평가 워크플로우
Orchestrator (계획)
↓
Recon 에이전트 (공격 표면) → 출력: 서비스 & 기술
↓
Scan/Enum 에이전트 (심층 검사) → 출력: 포트 & 버전
↓
Vuln Analysis 에이전트 (위험 매핑) → 출력: 점수가 있는 CVE 목록
↓
Exploit 에이전트 (PoC 검증) → 출력: 작동하는 악용
↓
Post-Exploit 에이전트 (영향) → 출력: 횡적 이동 경로
↓
Orchestrator (치료법이 있는 최종 보고서)
# 대상 서비스를 취약점 분석으로 직접 지정
1. 서비스 정보 제공 (버전, 포트)
2. Vuln Analysis 에이전트가 CVE로 매핑
3. Exploit 에이전트가 높은 우선순위의 취약점 테스트
| 도구 | 명령 | 목적 |
|---|
| assetfinder | assetfinder target.com | 서브도메인 발견 |
| subfinder | subfinder -d target.com | 서브도메인 열거 |
| whois | whois target.com | 도메인 정보 조회 |
| dig | dig target.com | DNS 기록 쿼리 |
| dnsrecon | dnsrecon -d target.com | DNS 열거 |
| hping3 | hping3 -p 80 target.com | 네트워크 스캔 |
| 도구 | 명령 | 목적 |
|---|
| nmap | nmap -sV target.com | 포트 스캔 & 버전 감지 |
| masscan | masscan 0.0.0.0/0 -p80,443 | 고속 포트 스캔 |
| nikto | nikto -h target.com | 웹 서버 취약점 스캔 |
| gobuster | gobuster dir -u http://target.com -w wordlist.txt | 디렉토리/DNS 브루트포싱 |
| wpscan | wpscan --url target.com | WordPress 취약점 스캔 |
| whatweb | whatweb target.com | 웹 기술 식별 |
| 도구 | 명령 | 목적 |
|---|
| nuclei | nuclei -target target.com | 빠른 취약점 스캔 |
| sslscan | sslscan target.com:443 | SSL/TLS 구성 분석 |
| 도구 | 목적 |
|---|
| sqlmap | 자동화된 SQL 주입 테스트 |
| hydra | 비밀번호 브루트포싱 |
| medusa | 병렬 네트워크 로그인 감사 |
| ncrack | 네트워크 인증 크래킹 |
| 커스텀 스크립트 | Python/Go/Perl/Ruby 악용 개발 |
| 도구 | 목적 |
|---|
| netcat | 네트워크 디버깅 & 데이터 전송 |
| socat | 다목적 릴레이 |
| ssh -D | SOCKS 프록시 터널링 (피벗용) |
| impacket | Windows 프로토콜 도구 (psexec, secretsdump) |
# Orchestrator는 다음을 포함한 구조화된 보고서를 생성합니다:
- 행정 요약
- 심각도 등급이 있는 발견 사항
- 증거 및 개념 증명 세부 정보
- 영향을 받는 시스템 및 서비스
- 치료 지침
- 비즈니스 영향 평가
{
"mission_name": "침투 테스트 - Example Corp",
"target": "example.com",
"findings": [
{
"vulnerability": "로그인 양식의 SQL 주입",
"severity": "CRITICAL",
"affected_service": "웹 애플리케이션 v2.1",
"evidence": "SELECT version()이 데이터베이스 버전 반환",
"remediation": "준비된 명령문, 입력 검증 사용"
}
],
"timeline": "2025-03-10T14:30:00Z",
"tested_systems": ["web-server", "api-gateway", "database"]
}
{
"providers": {
"custom-provider": {
"base_url": "https://your-api-endpoint.com/v1/chat/completions",
"default_model": "your-model-name",
"default_embedding_model": "embedding-model",
"default_model_config": {
"context_size": 200000,
"max_retries": 3,
"max_tokens": null
}
}
}
}
# 소형 모델 (7B) - 더 빠름, 메모리 적게 필요
vllm serve mistralai/Mistral-7B-Instruct-v0.2 \
--host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.75
# 대형 모델 (123B) - 더 유능함
vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
--host 0.0.0.0 --port 8000 --max-model-len 8192
# HuggingFace의 커스텀 모델
uv run hf auth login # 먼저 HF에 로그인
vllm serve meta-llama/Llama-2-7b-chat-hf \
--host 0.0.0.0 --port 8000
# 설정 & 설치
make help # 모든 명령 표시
make setup # 전체 초기 설정
make install # Python 의존성만
make frontend-install # 프론트엔드 의존성
# Docker 관리
make docker-build # mini-kali 이미지 빌드
make docker-up # 컨테이너 시작
make docker-down # 컨테이너 중지
make docker-logs # 로그 보기
# VLLM 로컬 LLM
make vllm-install # VLLM 설치
make vllm-serve # VLLM 시작 (123B)
make vllm-serve-small # VLLM 시작 (7B)
# BlacksmithAI 실행
make start-cli # CLI 모드
make start-ui # Web UI (설정 표시)
make start-all # 빠른 시작 CLI
# 유틸리티
make status # Docker 컨테이너 상태
make check-deps # 의존성 확인
make check-config # 구성 확인
make clean # 컨테이너 정리
make stop # 모든 서비스 중지
# 외부 도구로 데이터 수집
assetfinder -subs-only target.com > subdomains.txt
# BlacksmithAI로 공급
# 에이전트가 발견된 서브도메인에 대해 대상 스캔 수행
- Nmap 출력 → 서비스 매핑을 위해 Vuln Analysis로 전달
- 서브도메인 목록 → Scan/Enum 에이전트의 대상 스캔
- API 엔드포인트 → 직접 취약점 테스트
- 인증 시스템 → 브루트포싱 & 악용 시도
# 에이전트 디렉토리에 커스텀 악용 스크립트 작성
# 에이전트가 Python/Go/Perl/Ruby 스크립트 실행 가능
# 예: 커스텀 SQL 주입 페이로드
cat > custom_exploit.py << 'EOF'
import sys
target = sys.argv[1]
# 커스텀 악용 로직
EOF
# 에이전트가 호출: python custom_exploit.py target.com
# 문면으로 범위 정의
- 대상 목록 (도메인/IP)
- 테스트 기간
- 인증된 시스템 & 공격 벡터
- 보고 요구사항
- 민감한 데이터 처리
# 법적 인증 검증
- 클라이언트/소유자의 서면 허락
- 계약 규칙 (RoE)
- NDA 및 기밀 유지 계약
# 권장 사항
1. 가능한 경우 격리된 테스트 환경 사용
2. 정찰만으로 시작
3. 취약점을 순차적으로 테스트, 병렬로 테스트하지 않기
4. 명시적 승인 없이 파괴적 페이로드 피하기
5. 악용 중 시스템 동작 모니터링
6. 모든 활동의 상세한 로그 유지
# 종합적인 발견 사항에 포함:
- 명확한 취약점 설명
- CVSS/심각도 점수
- 개념 증명 증거
- 영향을 받는 서비스 및 버전
- 비즈니스 영향 평가
- 우선순위가 지정된 치료 단계
- 악용의 타임라인
# 모델 선택이 결과에 영향:
- 더 빠른 모델: 빠른 정찰, 기본 스캔
- 더 큰 모델: 복잡한 분석, 더 나은 의사결정
- 로컬 VLLM: 개인정보 중심, API 의존성 없음
- OpenRouter: 비용 효율적, 다중 모델 옵션
# 권장: 복잡한 평가에 Sonnet/GPT-4 사용
- 테스트하기 전에 항상 서면 허락을 받으세요
- 계약 규칙에서 범위를 명확하게 정의하세요
- 명시적 서면 인증을 받은 자신이 소유하거나 시스템만 테스트하세요
- 법률 위반 (CFAA, GDPR 등)은 민사/형사 책임을 초래할 수 있습니다
# 테스트 후:
1. 심각도가 있는 모든 발견 사항 문서화
2. 취약점을 시스템 소유자에게 알리기
3. 패칭을 위한 합리적인 시간 허용 (일반적으로 90일)
4. 취약점 세부 정보의 기밀성 유지
5. 타사 제품이 영향을 받는 경우 공급업체에 보고
- 테스트 중 데이터 추출 최소화
- 모든 보고서 및 증거를 안전하게 저장
- 민감한 발견 사항에 암호화 사용
- 데이터 보호 규정 준수 (GDPR, HIPAA 등)
- 참여 완료 후 데이터 삭제
# 컨테이너가 시작되지 않음
docker ps # 실행 중인지 확인
docker logs mini-kali-slim # 오류 보기
# 포트 충돌
lsof -i :9756 # 포트 사용 확인
docker run -i --rm -p 9757:9756 mini-kali-slim -d # 다른 포트 사용
# OpenRouter 문제
# - API 키 확인: echo $OPENROUTER_API_KEY
# - 상태 확인: https://status.openrouter.ai/
# VLLM 문제
curl http://localhost:8000/v1/models # VLLM 실행 중인지 확인
# - 메모리 확인: free -h
# - GPU 사용 가능 여부: nvidia-smi
# 느린 응답
# - config.json에서 더 빠른 모델로 전환
# - 시스템 리소스 확인 (top, htop)
# 에이전트가 루프에 갇힘
# - 작업 복잡성 줄이기
# - 도구 출력에서 오류 확인
# - 무한 루프에 대한 에이전트 로그 검토
# 의존성 누락
cd blacksmithAI/blacksmithAI
uv sync # 재설치
