AutoBB Analyst

🇷🇺 Русская версия

Autonomous bug bounty agent driven by autobb reconnaissance. A Telegram bot forwards alerts and chat messages to Claude Code CLI, which actively pentests targets using the host MongoDB (recon data) and a persistent knowledge wiki.

The agent doesn't just summarize — it picks targets, runs real probes, reports only verified findings, and keeps its own wiki of programs, hosts, tech, techniques, findings and dead-ends across sessions.

Requirements

• Python 3.12+ (only when running outside Docker)
• Docker (recommended)
• MongoDB with database autobbdb (populated by autobb) reachable from the host
• Claude Code CLI — installed and authenticated
• Telegram Bot Token (via @BotFather)

Quick Start (Docker, recommended)

1. Clone and configure

git clone https://github.com/rivalsec/autobb-analyst && cd autobb-analyst
cp config.dist.yaml config.yaml

Edit config.yaml:

db:
  uri: "mongodb://host.docker.internal:27017"
  database: "autobbdb"

telegram:
  token: "123456:ABC-DEF..."        # token from BotFather
  chat_id: "-1001234567890"         # chat/group ID
  autobb_bot_id: 1871687898         # autobb bot user ID
  ignore_patterns:                  # optional: skip noisy messages
    - "Is something wrong with nuclei templates?"

claude:
  cli_path: "claude"
  timeout: 300

2. Generate Claude Code auth token

claude setup-token
echo "CLAUDE_CODE_OAUTH_TOKEN=<your-token>" > .env

3. Build and run

docker build -t autobb-analyst .
docker run -d \
  --name autobb-analyst \
  --env-file .env \
  -v $(pwd)/config.yaml:/app/config.yaml:ro \
  -v $(pwd)/claude_workdir:/app/claude_workdir \
  --add-host=host.docker.internal:host-gateway \
  autobb-analyst

Check logs:

docker logs -f autobb-analyst

Host MongoDB is reachable from the container at host.docker.internal:<port>. The container is isolated from the rest of the host network (no --network host).

claude_workdir is mounted from the host so agent instructions, slash commands, persistent memory and the knowledge wiki survive restarts and are editable without rebuilding the image.

Running without Docker

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python bot.py

How it works

1. Alert from autobb → the bot automatically invokes Claude Code with /analyze-alert <alert text>. The agent consults the wiki, queries MongoDB, actively pentests, and reports only verified findings.
2. Free-form user message → passed to Claude Code as-is.
3. Reply / quoted message → the quoted content is included as context in the user prompt.
4. On startup → any pending Telegram updates accumulated while the bot was offline are batched into one /analyze-alert call (avoids spamming the chat with one response per queued alert).
5. .txt attachments → downloaded and used as the message text (caption is ignored).

The agent uses a stream-json Claude CLI output to log every tool use, thinking, and result in real time, and sends a "typing…" indicator in Telegram while working.

Included system tools inside the container

For active reconnaissance: nmap, dig / nslookup, whois, curl, wget, httpie, openssl, netcat, traceroute, ping, jq.

For JS-rendered pages, SPA apps, login flows and screenshots: Playwright (Python) with a bundled Chromium browser. The agent can drive a headless browser via inline Python when static HTTP tools aren't enough.

Agent workspace: claude_workdir/

Mounted from the host — persistent across container restarts. Contents:

• CLAUDE.md — the agent's system prompt (role, principles, available tools, wiki rules, response format).
• dbquery.py — CLI utility for MongoDB reads (also usable directly via pymongo).
• .claude/commands/ — slash commands:
  • /analyze-alert <text> — triggered on autobb alerts (wiki-first pentest flow).
  • /hunt [scope] — autonomous hunt cycle (pick a target, test, record).
• .memory/ — behavior rules (preferences, feedback).
• .wiki/ — domain knowledge base the agent maintains itself:
  • programs/ — per bug bounty program
  • hosts/ — per target host (tech stack, tested vectors, status)
  • tech/ — per technology (CVE status, common misconfigs)
  • techniques/ — reusable pentest playbooks
  • findings/ — archive of confirmed vulnerabilities (PoC required)
  • dead-ends/ — thoroughly tested hosts with nothing found (revisit rules)
  • INDEX.md — always-loaded root index with counts and rules

See claude_workdir/.wiki/<category>/README.md for each page template.

dbquery.py — MongoDB read utility

python dbquery.py scopes                                     # list scopes with stats
python dbquery.py recent --hours 24 --scope example.com       # recent findings
python dbquery.py vulns --severity critical                   # vulnerabilities
python dbquery.py host api.example.com                        # everything on a host
python dbquery.py search "admin.*example"                     # domain regex search
python dbquery.py probes --juicy 10 --hours 12                # interesting HTTP probes
python dbquery.py changes --hours 6                           # probes with diffs
python dbquery.py query domains --filter '{"scope":"example.com"}' --limit 10

For anything beyond these wrappers, the agent connects directly with pymongo (read-only).

MongoDB collections (autobbdb)

Collection	Description
domains	Subdomains (host, a[], cname[], scope, add_date, _diffs_history)
http_probes	HTTP services (url, status_code, title, tech[], tls{}, juicy_weight, juicy_info, _diffs_history)
ports	Open ports (host, ip, port, scope)
nuclei_hits	Active vulnerabilities from Nuclei
nuclei_passive_hits	Passive Nuclei findings

Configuration reference

db:
  uri: "mongodb://host.docker.internal:27017"
  database: "autobbdb"

telegram:
  token: "..."
  chat_id: "..."
  autobb_bot_id: 1871687898
  ignore_patterns:                 # substrings (case-insensitive) to ignore from autobb
    - "Is something wrong with nuclei templates?"

claude:
  cli_path: "claude"
  timeout: 300                     # Claude CLI timeout (seconds)