|
| 1 | + |
| 2 | + |
| 3 | +# 🏰 Watchtower (AI-Powered Penetration Testing Framework) |
| 4 | + |
| 5 | +[](https://opensource.org/licenses/MIT) |
| 6 | +[](https://www.python.org/downloads/) |
| 7 | +[](https://langchain-ai.github.io/langgraph/) |
| 8 | +[]() |
| 9 | + |
| 10 | +**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. |
| 11 | + |
| 12 | +Penetration testing is red team activity and should be done with permission. |
| 13 | + |
| 14 | +<p align="center"> |
| 15 | + <br> |
| 16 | + <a href="#✨-core-features">Features</a> • |
| 17 | + <a href="#2-💻-installation">Installation</a> • |
| 18 | + <a href="#🚀-quick-start">Quick Start</a> • |
| 19 | + <a href="#❓-faq--troubleshooting">FAQ</a> • |
| 20 | + <a href="#📄-license">License</a> |
| 21 | +</p> |
| 22 | + |
| 23 | +## ⚠️ Legal Disclaimer |
| 24 | + |
| 25 | +**Watchtower is designed exclusively for authorized security testing and educational purposes.** |
| 26 | + |
| 27 | +- **Legal Use:** Authorized penetration testing, security research, educational environments. |
| 28 | +- **Illegal Use:** Unauthorized access, malicious activities, any form of cyber attack. |
| 29 | + |
| 30 | +You are fully responsible for ensuring you have explicit 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 equivalent international legislation. |
| 31 | + |
| 32 | +By using Watchtower, you agree to use it only on systems you own or have explicit authorization to test. |
| 33 | + |
| 34 | +## ✨ Core Features |
| 35 | + |
| 36 | +- **Multi-Agent Architecture**: |
| 37 | + - `Planner`: Analyzes the target and current findings to strategize the next sequence of actions. |
| 38 | + - `Worker`: Dynamically executes tools requested by the Planner. |
| 39 | + - `Analyst`: Parses tool stdout/stderr, filters false positives, and converts raw findings into structured schema data. |
| 40 | +- **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. |
| 41 | + - *Network*: `nmap`, `masscan` |
| 42 | + - *Web Recon*: `httpx`, `whatweb`, `wafw00f` |
| 43 | + - *Subdomain*: `subfinder`, `amass`, `dnsrecon` |
| 44 | + - *Vulnerability*: `nuclei`, `nikto`, `sqlmap`, `wpscan`, `retire.js` |
| 45 | + - *SSL/TLS*: `testssl.sh`, `sslyze` |
| 46 | + - *Content/Params*: `gobuster`, `ffuf`, `arjun`, `kiterunner` |
| 47 | + - *Security Analysis*: `xsstrike`, `gitleaks`, `cmseek`, `dalfox` |
| 48 | +- **State Management**: Uses `SQLite` locally to store a historical record of observations and findings. |
| 49 | +- **LLM Agnostic**: Seamlessly swap between OpenAI, Google Gemini, and OpenRouter APIs via `.env` files. |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +## 🚀 Quick Start |
| 54 | + |
| 55 | +### 1. 📋 Requirements & Prerequisites |
| 56 | + |
| 57 | +**Prerequisites:** |
| 58 | +- **OS**: Linux or macOS recommended (Windows supported via WSL2 for some networking tools). |
| 59 | +- **Python**: 3.11+ installed. |
| 60 | +- **API Keys**: An active API key for OpenRouter, OpenAI, or Gemini. |
| 61 | + |
| 62 | +**Tool Requirements:** |
| 63 | +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. |
| 64 | + |
| 65 | +### 2. 💻 Installation |
| 66 | + |
| 67 | +```bash |
| 68 | +git clone https://github.com/fzn0x/watchtower.git |
| 69 | +cd watchtower |
| 70 | + |
| 71 | +python -m venv venv |
| 72 | +source venv/bin/activate # On Windows: venv\Scripts\activate |
| 73 | +pip install -r requirements.txt |
| 74 | +``` |
| 75 | + |
| 76 | +### 3. ⚙️ Configuration |
| 77 | + |
| 78 | +```bash |
| 79 | +cp .env.example .env |
| 80 | +``` |
| 81 | +Populate `.env` with your API keys. You only need to fulfill **one** of the API setups: |
| 82 | +- `OPENAI_API_KEY=""` |
| 83 | +- `GEMINI_API_KEY=""` |
| 84 | +- `OPENROUTER_API_KEY=""` |
| 85 | + |
| 86 | +*(Optional)* Explicitly define which model strings the framework should use. Defaults are already configured: |
| 87 | +- `OPENAI_MODEL_NAME="gpt-4-turbo"` |
| 88 | +- `GEMINI_MODEL_NAME="gemini-1.5-pro"` |
| 89 | +- `OPENROUTER_MODEL_NAME="anthropic/claude-3-opus"` |
| 90 | + |
| 91 | +### 4. ▶️ Running the Framework |
| 92 | + |
| 93 | +You **must** specify a target URL or IP using the `-t` or `--target` flag. |
| 94 | + |
| 95 | +```bash |
| 96 | +python -m watchtower.main -t https://www.example.com |
| 97 | +``` |
| 98 | + |
| 99 | +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. |
| 100 | + |
| 101 | +**Headless Mode:** |
| 102 | +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 everything available on your PATH: |
| 103 | +```bash |
| 104 | +python -m watchtower.main -t https://www.example.com --skip-ask-tools |
| 105 | +``` |
| 106 | + |
| 107 | +## 📊 Generating Reports |
| 108 | + |
| 109 | +Watchtower automatically stores all executed commands, terminal outputs, and confirmed vulnerabilities in a local SQLite memory file (`pentest_memory.db`). |
| 110 | + |
| 111 | +You can extract all findings into a cleanly formatted PDF document without re-running the pentest: |
| 112 | +```bash |
| 113 | +python -m watchtower.main --report "pentest_report.pdf" |
| 114 | +``` |
| 115 | + |
| 116 | +### 5. 🔌 Custom Providers |
| 117 | + |
| 118 | +Watchtower dynamically supports almost any LLM provider on the market via LangChain and LiteLLM integrations. You can override the default models from the CLI using the `--provider`, `--model`, and `--apikey` flags. |
| 119 | + |
| 120 | +```bash |
| 121 | + python -m watchtower.main -t https://www.example.com --provider=https://api.dgrid.ai --model=anthropic/claude-opus-4.5 --apikey "API_KEY" |
| 122 | +``` |
| 123 | + |
| 124 | +Example response (using httpx tool): |
| 125 | + |
| 126 | +```bash |
| 127 | +INFO: ==> Node Executed: [WORKER] |
| 128 | +INFO: HTTP Request: POST https://api.dgrid.ai/api/v1/chat/completions "HTTP/1.1 200 OK" |
| 129 | +INFO: ==> Node Executed: [ANALYST] |
| 130 | +INFO: - Updated state 'findings': [{'title': 'Overly Permissive CORS Configuration', 'severity': 'Medium', 'description': 'The server is configured with Access-Control-Allow-Origin: * which allows any website to make cross-origin requests to this domain. This could potentially allow malicious websites to interact with the API on behalf of authenticated users, leading to data theft or unauthorized actions if sensitive endpoints exist.', 'evidence': 'Access-Control-Allow-Origin: *\naccess-control-allow-headers: *\naccess-control-allow-methods: GET, HEAD, OPTIONS'}, {'title': 'Missing Security Headers', 'severity': 'Low', 'description': 'The response is missing several recommended security headers including X-Frame-Options (clickjacking protection), Content-Security-Policy (XSS and injection protection), and Strict-Transport-Security (HSTS for enforcing HTTPS). While some headers like X-Content-Type-Options and Referrer-Policy are present, the absence of these headers reduces the overall security posture.', 'evidence': 'HTTP/1.1 200 OK\nDate: Fri, 27 Feb 2026 13:28:07 GMT\nContent-Type: text/html; charset=utf-8\n[Headers present: x-content-type-options: nosniff, referrer-policy: strict-origin-when-cross-origin]\n[Missing: X-Frame-Options, Content-Security-Policy, Strict-Transport-Security]'}] |
| 131 | +``` |
| 132 | + |
| 133 | +> ⚠️ **Disclaimer:** The `--apikey` argument requires the exact **property name** of the variable 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. |
| 134 | +
|
| 135 | +**Supported Providers Include:** |
| 136 | +- Anthropic |
| 137 | +- OpenAI |
| 138 | +- OpenRouter |
| 139 | +- Litellm |
| 140 | +- Amazon Bedrock |
| 141 | +- Vercel AI Gateway |
| 142 | +- Moonshot AI |
| 143 | +- Mistral |
| 144 | +- MiniMax |
| 145 | +- OpenCode Zen |
| 146 | +- GLM Models |
| 147 | +- Z.AI |
| 148 | +- Synthetic |
| 149 | +- Qianfan |
| 150 | +- **Any custom HTTP URLs** (Acts as a drop-in OpenAI-compatible endpoint, automatically routing requests via LangChain's `ChatOpenAI` client) |
| 151 | +- Others: https://docs.litellm.ai/docs/providers |
| 152 | + |
| 153 | +**Example CLI Execution (Custom Endpoint):** |
| 154 | +```bash |
| 155 | +python -m watchtower.main -t https://example.com --provider=https://api.dgrid.ai/api/v1 --model=anthropic/claude-opus-4.5 --apikey "API_KEY" |
| 156 | +``` |
| 157 | + |
| 158 | +--- |
| 159 | + |
| 160 | +## 🗺️ Roadmap |
| 161 | + |
| 162 | +- [x] Initial LangGraph Planner/Worker architecture. |
| 163 | +- [x] Integrate core web and network reconnaissance tools. |
| 164 | +- [x] Add Pydantic structured output fallback for open-source OpenRouter models. |
| 165 | +- [ ] Add support for authenticated pentesting workflows (e.g cookie injection). |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## 📌 Important Notes |
| 170 | + |
| 171 | +- **API Costs**: The multi-agent workflow consumes tokens rapidly during active scanning as the Planner loops through observations. Be mindful of your API budgets. |
| 172 | +- **Hallucinations**: While the Analyst agent filters false positives, LLMs can still hallucinate conclusions based on ambiguous tool outputs. **Always manually verify findings.** |
| 173 | +- **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 observation logs with 403s. |
| 174 | + |
| 175 | +--- |
| 176 | + |
| 177 | +## ❓ FAQ & Troubleshooting |
| 178 | + |
| 179 | +### Q: `model: [model_name] does not support feature: structured-outputs` |
| 180 | +This error occurs when using experimental, free, or unsupported models via OpenRouter (e.g. some Qwen or DeepSeek variants). 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: |
| 181 | +- `anthropic/claude-3.5-sonnet` |
| 182 | +- `openai/gpt-4o` |
| 183 | +- `google/gemini-1.5-pro` |
| 184 | +- `meta-llama/llama-3.1-70b-instruct` |
| 185 | + |
| 186 | +*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.* |
| 187 | + |
| 188 | +### Q: `429 Too Many Requests: [model]:free is temporarily rate-limited upstream` |
| 189 | +This means you are using an explicitly `:free` model tier on OpenRouter, and the upstream providers (like Venice 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. |
| 190 | + |
| 191 | +--- |
| 192 | + |
| 193 | +## 📄 License |
| 194 | + |
| 195 | +This project is licensed under the **MIT License**. See the `LICENSE` file for details. |
| 196 | + |
| 197 | +By using this software, you agree to the conditions outlined in the [Legal Disclaimer](#-legal-disclaimer). Watchtower's developers assume no liability for the misuse of this tool. |
| 198 | + |
| 199 | +--- |
| 200 | + |
| 201 | +## 🙏 Author & Acknowledgements |
| 202 | + |
| 203 | +Created and maintained by **[fzn0x](https://github.com/fzn0x)**. |
| 204 | + |
| 205 | +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 developers who built and maintain the underlying penetration testing and reconnaissance tools that power the core worker engine. Thank you for making security accessible. |
0 commit comments