Watchtower is a Python CLI that uses LLM agents built on LangGraph to plan, execute, and analyze nmap, nuclei, and 21 other security tools against targets you are explicitly authorized to test.
| Tool | fzn0x/watchtower — AI-powered penetration testing automation CLI orchestrated by LLM agents via LangGraph |
| Category | Agentic security automation / LLM-orchestrated pentest framework |
| Primary Use | Automating authorized web and network assessments by coordinating tools like nuclei, nmap, httpx, and ffuf, then exporting findings to a PDF report from SQLite memory |
| Safe Use | Explicitly restricted by the project's legal disclaimer to authorized penetration testing, security research, and educational environments with written permission |
| Telemetry Note | Highly noisy by design — masscan and ffuf traffic can trip edge protections and generate 403 responses; defenders will see classic tool signatures combined with unusual parallel scan cadences, and all findings persist locally in pentest_memory.db |
Watchtower is an AI-powered penetration testing automation CLI written in Python, and its core idea is deceptively simple: instead of a human operator sequencing recon, scanning, and validation tools by hand, a team of LLM agents does the sequencing. The project, published under the MIT license by fzn0x with 212 stars at time of writing, leans on LangGraph to model the engagement as a stateful graph of specialized nodes. The README leads with an explicit warning that penetration testing is a red-team activity requiring explicit permission, and the repository's contributing guidelines even ask developers not to remove guardrails that prevent out-of-scope testing — a framing consistent with its educational and authorized-assessment purpose.
The architecture is the most interesting part of the design. Three agents divide the labor: a Planner that analyzes the target and accumulated findings to strategize the next actions, a Worker that dynamically executes whichever tools the Planner requests, and an Analyst that parses tool stdout/stderr, filters false positives, and converts raw output into structured findings. This Planner/Worker/Analyst split mirrors how mature agentic frameworks handle tool use, and the roadmap shows it was built incrementally — the initial LangGraph architecture came first, then parallel tool execution, smart truncation, and authenticated testing support.
The tool arsenal is substantial: 23 security tools are integrated via Python subprocess wrappers, spanning network scanning (nmap, masscan), web recon (httpx, whatweb, wafw00f), subdomain enumeration (subfinder, amass, dnsrecon), vulnerability scanning (nuclei, nikto, sqlmap, wpscan, retire.js), TLS analysis (testssl.sh, sslyze), content discovery (gobuster, ffuf, arjun, kiterunner), and specialized analysis (xsstrike, gitleaks, cmseek, dalfox). Watchtower does not ship these binaries; it detects which are present on your PATH at launch and simply skips missing ones. An interactive checklist lets you toggle tools with <Space> before confirming with <Enter>, effectively narrowing what the LLM is allowed to invoke.
Setup is conventional for a Python 3.11+ project: clone the repository, create a virtual environment, and pip install -r requirements.txt. A bundled install_tools.sh script exists for installing the underlying binaries, and configuration is handled by copying .env.example to .env and populating a single provider key — OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY. Model defaults like gpt-4-turbo, gemini-1.5-pro, and anthropic/claude-3-opus can be overridden per provider in the same file.
Being LLM-agnostic is a deliberate design choice, and the README documents it thoroughly. Through LangChain and LiteLLM integrations, Watchtower supports Anthropic, OpenAI, OpenRouter, Amazon Bedrock, Mistral, Moonshot AI, and effectively any OpenAI-compatible HTTP endpoint via flags like --provider, --model, and --apikey. One thoughtful detail: the --apikey argument takes the name of a variable in your .env file rather than the raw key, keeping secrets out of shell history. The troubleshooting section is candid that model choice matters — free or experimental OpenRouter models frequently fail structured-output requirements or hit 429 rate limits, and a string-fallback parser exists for models without native structured output, though commercial models yield better reasoning.
State management is where Watchtower differentiates itself from a simple script wrapper. Every executed command, terminal output, and confirmed finding is persisted to a local SQLite database (pentest_memory.db), giving the Planner a historical record of observations across the engagement rather than a stateless per-invocation view. Because findings survive the session, you can export a formatted PDF report later without re-running anything: python -m watchtower.main --report "pentest_report.pdf". For consultants, that report-generation path alone could justify the tool in an authorized workflow.
Operational modes cover the realistic scenarios. A single target is passed with -t or --target; headless operation via --skip-ask-tools auto-runs everything available on PATH, which suits CI/CD integration; and authenticated testing is supported by passing --cookie or --header with session credentials, extending coverage to areas that anonymous scanning misses. Parallel reconnaissance means tools like httpx and whatweb can run concurrently, compressing assessment cycles — though the README warns this also concentrates the noise footprint considerably.
The Important Notes section deserves attention because it is unusually honest about agentic security tooling's failure modes. First, cost: the multi-agent loop consumes tokens rapidly as the Planner iterates over observations, so API budgets can balloon during active scanning. Second, hallucination: the Analyst filters false positives, but LLMs can still draw wrong conclusions from ambiguous tool output, and the README instructs users to always manually verify findings. Third, network behavior: masscan and ffuf are described as extremely noisy and may trip upstream edge protections such as Cloudflare, polluting observation logs with 403 responses.
From a defensive research perspective, Watchtower is a useful case study in what agentic offensive automation looks like. Defenders observing its use against authorized ranges will see classic tool signatures — nuclei templates, nmap fingerprints, gobuster wordlist patterns — but with an atypical cadence: dynamically resequenced tool calls driven by intermediate findings rather than a fixed playbook. That adaptability is precisely why blue teams should track it as a representative of the broader LLM-orchestrated scanning category, and why its SQLite-backed state model makes post-engagement review and auditing straightforward for the operator.
Limitations worth weighing: the project is a young MIT-licensed effort with a single maintainer, the roadmap still lists advanced business-logic analysis as unchecked, and Windows support is partial (WSL2 is recommended for some networking tools). The dependence on external LLM APIs also means target-derived data — URLs, headers, tool output — flows to whichever provider backs the agents, a data-handling consideration any professional should evaluate before pointing it at sensitive authorized environments. Within its stated scope of permitted testing, education, and research, Watchtower is a well-documented, thoughtfully guarded example of agentic pentest orchestration.
fzn0x/watchtower.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.