fzn0x/watchtower

Watchtower는 LLM (Large Language Models)과 LangGraph를 활용하여 에이전트 워크플로우 (agentic workflows)를 오케스트레이션함으로써, 로컬에서 웹사이트를 테스트하는 데 사용할 수 있는 간단한 AI 기반 침투 테스트 (penetration testing) 자동화 CLI 도구입니다. 귀하의 웹사이트를 위한 유용한 침투 테스트 보고서를 생성합니다.

침투 테스트는 레드 팀 (red team) 활동이며 반드시 허가된 상태에서 수행되어야 합니다.

Watchtower는 오직 승인된 보안 테스트 및 교육적 목적으로만 설계되었습니다.

합법적 사용: 승인된 침투 테스트, 보안 연구, 교육 환경.
불법적 사용: 무단 액세스, 악의적인 활동, 모든 형태의 사이버 공격.

귀하는 시스템을 테스트하기 전에 명시적인 서면 허가를 받았는지 확인해야 할 전적인 책임이 있습니다. 컴퓨터 시스템에 대한 무단 액세스는 Computer Fraud and Abuse Act (CFAA), GDPR 및 이에 상응하는 국제 법률을 포함한 법률에 따라 불법입니다.

Watchtower를 사용함으로써, 귀하는 귀하가 소유하거나 테스트에 대한 명시적 권한을 가진 시스템에서만 이를 사용하는 것에 동의합니다.

멀티 에이전트 아키텍처 (Multi-Agent Architecture):
Planner (플래너):
대상을 분석하고 현재 발견된 사항을 바탕으로 다음 행동 순서를 전략화합니다.
Worker (워커):
Planner가 요청한 도구들을 동적으로 실행합니다.
Analyst (애널리스트):
도구의 stdout/stderr를 파싱하고, 오탐 (false positives)을 필터링하며, 가공되지 않은 발견 사항을 구조화된 스키마 (schema) 데이터로 변환합니다.

동적 도구 무기고 (Dynamic Tool Arsenal): Python subprocess 래퍼 (wrappers)를 사용하여 23개의 보안 도구와 통합되어 있습니다. 대화형 CLI는 귀하의 PATH를 자동 확인하며 도구를 동적으로 제외할 수 있게 해줍니다.
네트워크 (Network): nmap, masscan
웹 정찰 (Web Recon): httpx, whatweb, wafw00f
서브도메인 (Subdomain): subfinder, amass, dnsrecon
취약점 (Vulnerability): nuclei, nikto, sqlmap, wpscan, retire.js
SSL/TLS: testssl.sh, sslyze
콘텐츠/파라미터 (Content/Params): gobuster, ffuf, arjun, kiterunner
보안 분석 (Security Analysis): xsstrike, gitleaks, cmseek, dalfox

상태 관리 (State Management): SQLite를 사용합니다.

관측 및 발견 사항의 이력 기록을 로컬에 저장합니다.

병렬 정찰 (Parallel Reconnaissance): 평가 사이클을 가속화하기 위해 여러 도구(예: httpx, whatweb)를 동시에 오케스트레이션합니다.

스마트 절단 (Smart Truncation): 일반적인 로그보다 보안 취약점 및 중요한 발견 사항을 우선시하는 출력 인식형 클리핑 (Output-aware clipping)을 수행합니다.

LLM 불가지론 (LLM Agnostic): .env 파일을 통해 OpenAI, Google Gemini, OpenRouter API 간을 원활하게 전환할 수 있습니다.

사전 요구 사항 (Prerequisites):

OS: Linux 또는 macOS 권장 (일부 네트워킹 도구의 경우 WSL2를 통해 Windows 지원).
Python: 3.11 이상 설치 필요.
API 키 (API Keys): OpenRouter, OpenAI 또는 Gemini의 활성화된 API 키.

도구 요구 사항 (Tool Requirements):
AI의 모든 기능을 활용하려면 실제 CLI 바이너리가 설치되어 있고 시스템 PATH에서 접근 가능해야 합니다 (예: nmap, nuclei, httpx). 프레임워크는 어떤 도구가 누락되었는지 자동으로 감지하여 UI에서 해당 도구를 건너뜁니다.

모든 도구 설치:

./install_tools.sh # 또는 sudo와 함께 실행

git clone https://github.com/fzn0x/watchtower.git
cd watchtower
python -m venv venv
...

cp .env.example .env

.env 파일에 API 키를 입력합니다. API 설정 중 하나만 충족하면 됩니다:

OPENAI_API_KEY="" GEMINI_API_KEY="" OPENROUTER_API_KEY=""

(선택 사항) 프레임워크가 사용할 모델 문자열을 명시적으로 정의합니다. 기본값은 이미 구성되어 있습니다:

OPENAI_MODEL_NAME="gpt-4-turbo" GEMINI_MODEL_NAME="gemini-1.5-pro" OPENROUTER_MODEL_NAME="anthropic/claude-3-opus"

-t 또는 --target 플래그를 사용하여 대상 URL 또는 IP를 반드시 지정해야 합니다.

python -m watchtower.main -t https://www.example.com

실행 시, Watchtower는 대화형 CLI 체크박스 프롬프트를 표시합니다. 23개의 도구 중 귀하의 머신에 성공적으로 설치된 도구가 무엇인지 자동으로 강조 표시합니다. <Space>를 사용하여 특정 도구를 활성화/비활성화함으로써 LLM의 페이로드 (payload)를 좁게 집중시킬 수 있으며, <Enter>를 눌러 선택을 확정할 수 있습니다.

Headless Mode (헤드리스 모드):
대화형 메뉴를 건너뛰고 싶거나 Watchtower를 자동화된 CI/CD 파이프라인에 통합하려는 경우, --skip-ask-tools 플래그를 사용하여 사용자의 PATH에 있는 모든 도구를 사용하여 자동으로 실행할 수 있습니다:

python -m watchtower.main -t https://www.example.com --skip-ask-tools

Authenticated Pentesting (인증된 침투 테스트):
Watchtower는 세션 쿠키 (session cookies) 또는 커스텀 헤더 (custom headers)를 통해 인증된 워크플로우 (workflows)를 지원합니다.

python -m watchtower.main -t https://api.example.com --cookie "session=xyz123" --header "X-API-Key: secret-key"

Watchtower는 실행된 모든 명령, 터미널 출력, 그리고 확인된 취약점 (vulnerabilities)을 로컬 SQLite 메모리 파일(pentest_memory.db)에 자동으로 저장합니다.

침투 테스트를 다시 실행하지 않고도 모든 조사 결과 (findings)를 깔끔하게 서식화된 PDF 문서로 추출할 수 있습니다:

python -m watchtower.main --report "pentest_report.pdf"

Watchtower는 LangChain 및 LiteLLM 통합을 통해 시장에 있는 거의 모든 LLM 제공업체를 동적으로 지원합니다. CLI에서 --provider, --model, --apikey 플래그를 사용하여 기본 모델을 재정의할 수 있습니다.

python -m watchtower.main -t https://www.example.com --provider=https://api.dgrid.ai/api/v1 --model=anthropic/claude-opus-4.5 --apikey "API_KEY"

응답 예시 (httpx 도구 사용 시):

INFO: ==> Node Executed: [WORKER]
INFO: HTTP Request: POST https://api.dgrid.ai/api/v1/chat/completions "HTTP/1.1 200 OK"
INFO: ==> Node Executed: [ANALYST]
...

⚠️ 면책 조항: --apikey 인자는 API 키 문자열 자체를 입력하는 것이 아니라, .env 파일 내에 저장된 변수의 정확한 속성 이름(예: MY_GROQ_KEY)을 요구합니다. 이는 비밀 정보가 bash 히스토리 (bash history)에 유출되는 것을 방지합니다.

지원되는 제공업체 (Supported Providers):

• Anthropic
• OpenAI
• OpenRouter
• Litellm
• Amazon Bedrock
• Vercel AI Gateway
• Moonshot AI
• Mistral
• MiniMax
• OpenCode Zen
• GLM Models
• Z.AI
• Synthetic
• Qianfan

모든 커스텀 HTTP URL (OpenAI 호환 엔드포인트로 동작하며, LangChain의 ChatOpenAI를 통해 요청을 자동으로 라우팅합니다.)

client)- 기타: https://docs.litellm.ai/docs/providers

CLI 실행 예시 (커스텀 엔드포인트):

python -m watchtower.main -t https://example.com --provider=https://api.dgrid.ai/api/v1 --model=anthropic/claude-opus-4.5 --apikey "API_KEY"

• 초기 LangGraph Planner/Worker 아키텍처.
• 핵심 웹 및 네트워크 정찰 (Reconnaissance) 도구 통합.
• 오픈 소스 OpenRouter 모델을 위한 Pydantic 구조화된 출력 (Structured Output) 폴백 (Fallback) 추가.
• 병렬 도구 실행 및 스마트 절단 (Smart Truncation).
• 인증된 침투 테스트 (Pentesting) 지원 (쿠키/헤더).
• 고급 비즈니스 로직 분석 강화.

API 비용: 멀티 에이전트 워크플로우는 Planner가 관찰 결과 (Observations)를 반복 처리함에 따라 활성 스캔 중에 토큰을 빠르게 소비합니다. API 예산을 유의하십시오.

환각 (Hallucinations): Analyst 에이전트가 오탐 (False Positives)을 필터링하지만, LLM은 여전히 모호한 도구 출력에 기반하여 결론을 환각할 수 있습니다.

항상 발견 사항을 수동으로 검증하십시오.

네트워크 안정성: 일부 도구(masscan 또는 ffuf)는 매우 노이즈가 심합니다. 대상의 상위 엣지 보호 기능 (Cloudflare 등)을 트리거할 수 있으며, 이로 인해 관찰 로그가 403 오류로 오염될 수 있습니다.

이 오류는 OpenRouter를 통해 실험적, 무료 또는 지원되지 않는 모델(예: 일부 Qwen 또는 DeepSeek 변형 모델)을 사용할 때 발생합니다. Watchtower는 AI가 완벽하게 형식화된 JSON 객체를 반환하도록 강제하기 위해 LangChain의 구조화된 출력 (Structured Outputs) 메커니즘에 의존합니다. 이 오류가 발생하면 .env 파일의 OPENROUTER_MODEL_NAME을 다음과 같이 완전히 지원되는 모델로 변경하십시오:

anthropic/claude-3.5-sonnet
openai/gpt-4o
google/gemini-1.5-pro
meta-llama/llama-3.1-70b-instruct

참고: 이 프레임워크는 API 구조화된 출력을 기본적으로 지원하지 않는 모델을 위해 커스텀 문자열 폴백 (String-fallback) 파서를 포함하고 있지만, 지원되는 상용 모델을 사용하는 것이 침투 테스트 로직 측면에서 훨씬 더 나은 결과를 제공합니다.

이는 귀하가 명시적으로 :free를 사용하고 있음을 의미합니다.

OpenRouter의 모델 티어 (model tier) 문제이거나, 상위 제공업체 (Venice 또는 Novita와 같은)가 현재 높은 글로벌 트래픽으로 인해 무료 티어 (free-tier) 요청에 대해 속도 제한 (rate-limiting)을 적용하고 있기 때문입니다. 단순히 타임아웃 (timeout)이 발생할 때까지 기다리거나, 약간 다른 (또는 유료) 모델 엔드포인트 (endpoint)로 전환하면 됩니다.

이 프로젝트는 MIT License 하에 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

이 소프트웨어를 사용함으로써 귀하는 법적 면책 조항 (Legal Disclaimer)에 명시된 조건에 동의하게 됩니다. Watchtower의 개발자들은 이 도구의 오용에 대해 어떠한 책임도 지지 않습니다.

fzn0x에 의해 생성 및 유지 관리됩니다.

오픈 소스 보안 커뮤니티에 깊고 진심 어린 감사를 표합니다. Watchtower는 거인들의 어깨 위에 서 있습니다. 이 프레임워크는 핵심 워커 엔진 (worker engine)을 구동하는 기반 침투 테스트 (penetration testing) 및 정찰 (reconnaissance) 도구들을 구축하고 유지 관리하는 놀라운 개발자들이 없었다면 존재하지 않았을 것입니다. 보안을 접근 가능하게 만들어 주셔서 감사합니다.