watchtower - Watchtower is a simple AI-powered penetration test

项目说明

!Watchtower

🏰 Watchtower (AI-Powered Penetration Testing Framework)

![License: MIT]()
![Python 3.11+]()
![Architecture]()
![LLMs]()

Watchtower is a simple AI-powered penetration testing automation CLI tool that le LLMs and LangGraph to orchestrate agentic workflows that you can use to test your websites locally. Generate useful pentest reports for your websites.

Penetration testing is red team activity and should be done with permission.

⚠️ Legal Disclaimer

Watchtower is designed exclusively for authorized security testing and educational purposes.

Legal Use: Authorized penetration testing, security research, educational en.

Illegal Use: Unauthorized access, malicious acti, any form of cyber attack.

You are fully responsible for ensuring you ha written permission before testing any system. Unauthorized access to computer systems is illegal under laws including the Computer Fraud and Abuse Act (CFAA), GDPR, and equi international legislation.

By using Watchtower, you agree to use it only on systems you own or ha authorization to test.

✨ Core Features

Multi-Agent Architecture:

- Planner: Analyzes the target and current findings to strategize the next sequence of actions.
- Worker: Dynamically executes tools requested by the Planner.
- Analyst: Parses tool stdout/stderr, filters false positives, and converts raw findings into structured schema data.

Dynamic Tool Arsenal: Integrated with 23 security tools using Python subprocess wrappers. The interactive CLI auto-checks your PATH and lets you exclude tools dynamically.

- *Network*: nmap, masscan
- *Web Recon*: httpx, whatweb, wafw00f
- *Subdomain*: subfinder, amass, dnsrecon
- **: 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: Uses SQLite locally to store a historical record of obser and findings.

Parallel Reconnaissance: Orchestrates multiple tools concurrently (e.g., httpx + whatweb) to accelerate assessment cycles.

Smart Truncation: Output-aware clipping that prioritizes security and critical findings o logs.

LLM Agnostic: Seamlessly swap between OpenAI, Google Gemini, and OpenRouter APIs via .env files.

---

🚀 Quick Start

1. 📋 Requirements & Prerequisites

Prerequisites:

OS: Linux or macOS recommended (Windows supported via WSL2 for some networking tools).

Python: 3.11+ installed.

API Keys: An active API key for OpenRouter, OpenAI, or Gemini.

Tool Requirements:
To utilize the AI's full capabilities, you must have the actual CLI binaries installed and accessible in your system PATH (e.g., nmap, nuclei, httpx). The framework will automatically detect which tools are missing and skip them in the UI.

Install all tools:

2. 💻 Installation

3. ⚙️ Configuration

Populate .env with your API keys. You only need to fulfill one of the API setups:

OPENAI_API_KEY=""

GEMINI_API_KEY=""

OPENROUTER_API_KEY=""

*(Optional)* Explicitly define which model strings the framework should use. Defaults are already configured:

OPENAI_MODEL_NAME="gpt-4-turbo"

GEMINI_MODEL_NAME="gemini-1.5-pro"

OPENROUTER_MODEL_NAME="anthropic/claude-3-opus"

4. ▶️ Running the Framework

You must specify a target URL or IP using the -t or --target flag.

Upon execution, Watchtower will display an interactive CLI checkbox prompt. It automatically highlights which of the 23 tools are successfully installed on your machine. You can use <Space> to enable/disable specific tools allowing you to narrowly focus the LLM's payload, or hit <Enter> to confirm the selection.

Headless Mode:
If you want to bypass the interactive menu or are integrating Watchtower into an automated CI/CD pipeline, use the --skip-ask-tools flag to auto-run with e a on your PATH:

Authenticated Pentesting:
Watchtower supports authenticated workflows cookies or custom headers.

📊 Generating Reports

Watchtower automatically stores all executed commands, terminal outputs, and confirmed in a local SQLite memory file (pentest_memory.db).

You can extract all findings into a cleanly formatted PDF document without re-running the pentest:

<img width="792" height="738" alt="image" src=" />

5. 🔌 Custom Pro

Watchtower dynamically supports almost any LLM provider on the market and LiteLLM integrations. You can o the default models from the CLI using the --provider, --model, and --apikey flags.

Example response (using httpx tool):

> ⚠️ Disclaimer: The --apikey argument requires the exact property name of the stored inside your .env file (e.g., MY_GROQ_KEY), *not* the raw API key string itself. This prevents your secrets from leaking into bash history.

Supported Pro Include:

Anthropic

OpenAI

OpenRouter

Litellm

Amazon Bedrock

AI Gateway

Moonshot AI

Mistral

MiniMax

OpenCode Zen

GLM Models

Z.AI

Synthetic

Qianfan

Any custom HTTP URLs (Acts as a drop-in OpenAI-compatible endpoint, automatically routing requests 's ChatOpenAI client)

Others:

Example CLI Execution (Custom Endpoint):

---

🗺️ Roadmap

[x] Initial LangGraph Planner/Worker architecture.

[x] Integrate core web and network reconnaissance tools.

[x] Add Pydantic structured output fallback for open-source OpenRouter models.

[x] Parallel tool execution and Smart Truncation.

[x] Support for authenticated pentesting (cookies/headers).

[ ] Ad business logic analysis enhancements.

---

📌 Important Notes

API Costs: The multi-agent workflow consumes tokens rapidly during acti as the Planner loops through obser. Be mindful of your API budgets.

Hallucinations: While the Analyst agent filters false positives, LLMs can still hallucinate conclusions based on ambiguous tool outputs. Always manually findings.

Network Stability: Some tools (like masscan or ffuf) are extremely noisy. You may trigger upstream edge-protections (Cloudflare) on your targets, which will pollute the obser logs with 403s.

---

❓ FAQ & Troubleshooting

Q: model: [model_name] does not support feature: structured-outputs

This error occurs when using experimental, free, or unsupported models (e.g. some Qwen or DeepSeek ). Watchtower relies on LangChain's Structured Outputs mechanism to force the AI to return perfectly formatted JSON objects. If you see this error, switch your OPENROUTER_MODEL_NAME in the .env file to a fully-supported model like:

anthropic/claude-3.5-sonnet

openai/gpt-4o

google/gemini-1.5-pro

meta-llama/llama-3.1-70b-instruct

*Note: The framework includes a custom string-fallback parser for models that don't natively support API structured outputs, but using supported commercial models yields significantly better pentesting logic.*

Q: 429 Too Many Requests: [model]:free is temporarily rate-limited upstream

This means you are using an explicitly :free model tier on OpenRouter, and the upstream pro (like or Novita) are currently rate-limiting free-tier requests due to high global traffic. You simply need to wait out the timeout or switch to a slightly different (or paid) model endpoint.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

By using this software, you agree to the conditions outlined in the Legal Disclaimer. Watchtower's de assume no liability for the misuse of this tool.

---

🙏 Author & Acknowledgements

Created and maintained by fzn0x.

A deep and sincere thank you to the open-source security community. Watchtower stands on the shoulders of giants—this framework would not exist without the incredible de who built and maintain the underlying penetration testing and reconnaissance tools that power the core worker engine. Thank you for making security accessible.

项目信息

开发语言：Python

Star 数：212

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Watchtower is a simple AI-powered penetration testing automation CLI tool that leverages LLMs and LangGraph to orchestrate agentic workflows that you can use to test your websites locally. Generate useful pentest reports for your websites.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。