Argus

Quick Start

# Install
git clone https://github.com/cotcollective/argus.git
cd argus
python3 -m venv venv --copies
./venv/bin/pip install -e .

# Run a single module
./venv/bin/argus dns example.com
./venv/bin/argus whois github.com
./venv/bin/argus subdomains target.com
./venv/bin/argus crawl https://target.com
./venus/bin/argus github username
./venv/bin/argus ipgeo 8.8.8.8
./venv/bin/argus dorks target@email.com
./venv/bin/argus paste target@email.com
./venv/bin/argus email target@example.com
./venv/bin/argus username johndoe
./venv/bin/argus phone +15145551234
./venv/bin/argus breach email@example.com
./venv/bin/argus network 10.0.0.1

# AI-chained investigation (requires Ollama)
./venv/bin/argus investigate "investigate johndoe@gmail.com"

# Interactive REPL
./venv/bin/argus

# JSON output
./venv/bin/argus dns example.com --json

# List all modules
./venv/bin/argus modules

AI Chaining

Argus uses Ollama for local AI-powered tool chaining. The AI agent:

1. Analyzes your target (email, username, domain, IP, URL, phone)
2. Selects which modules to run based on input type
3. Chains modules on findings (email → breach → username pivot → platform enum)
4. Generates a Markdown + JSON report automatically

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model (qwen2.5:7b recommended — native tool-calling support)
ollama pull qwen2.5:7b

# Run an investigation
./venv/bin/argus investigate "investigate the domain github.com"
./venv/bin/argus investigate "who is edoardottt?"
./venv/bin/argus investigate "find everything about john@example.com"

No Claude, no Anthropic API, no OpenAI. 100% local inference.

MCP Server

Argus exposes all 13 modules as MCP tools. Connect it to any MCP-compatible client (Hermes Agent, Claude Code, Cursor, etc.):

# Hermes Agent config (~/.hermes/config.yaml)
mcp_servers:
  argus:
    command: "/path/to/venv/bin/python3"
    args: ["-m", "argus.mcp_server"]
    timeout: 300

After restart, tools appear as mcp_argus_dns, mcp_argus_whois, mcp_argus_crawler, etc.

Architecture

argus/
  cli.py              # Click CLI + prompt-toolkit REPL
  config.py           # Environment-based configuration
  core/
    base.py           # BaseModule ABC + Finding dataclass
    registry.py       # Module registry + auto-discovery
    report.py          # Markdown + JSON report builder
  modules/
    email_recon.py     # 58 services, async, pure Python
    username_enum.py   # 52 platforms, async, pure Python
    subdomain_enum.py  # crt.sh + DNS brute force
    crawler.py         # cariddi Go binary wrapper
    network_recon.py   # nmap XML parser
    dns_recon.py       # dnspython + SPF/DMARC/DKIM
    whois_lookup.py    # python-whois
    breach_check.py    # local SQLite DB
    github_recon.py    # GitHub REST API
    phone_recon.py     # libphonenumber
    ip_geolocation.py  # GeoLite2 + ipinfo.io fallback
    dork_generator.py  # 12 dork URL templates
    paste_search.py    # psbdmp.ws API
  ai/
    chain.py           # Ollama tool-chaining agent
  mcp_server.py        # MCP server (stdio transport)

Optional Enhancements

📦 GeoLite2 (100% offline IP geolocation)

# Free MaxMind account: https://www.maxmind.com/en/geolite2/signup
# Download GeoLite2-City.mmdb, place at ~/.argus/
./venv/bin/pip install maxminddb

📦 Breach Database (local breach compilation)

sqlite3 ~/.argus/breaches.db \
  "CREATE TABLE breaches (email TEXT, breach_name TEXT, date TEXT, data_classes TEXT)"
# Import breach compilations via your preferred method

📦 Phone full analysis

./venv/bin/pip install phonenumbers

📦 Cariddi (web crawler engine)

# cariddi is the crawler engine (optional — crawler module won't work without it)
git clone https://github.com/edoardottt/cariddi.git
cd cariddi && go get ./... && go build -o /usr/local/bin/cariddi ./cmd/cariddi/
# Or set ARGUS_CARIDDI env var to the binary path

Configuration

All config via environment variables (all optional):

| Variable | Default | Description | |----------|---------|-------------| | ARGUS_OLLAMA_HOST | http://127.0.0.1:11434 | Ollama API host | | ARGUS_OLLAMA_MODEL | qwen2.5:7b | Ollama model for AI chaining | | ARGUS_CARIDDI | cariddi | Path to cariddi binary | | ARGUS_GEOLITE2_DB | ~/.argus/GeoLite2-City.mmdb | MaxMind GeoLite2 database path | | ARGUS_BREACH_DB | ~/.argus/breaches.db | Local breach SQLite database | | ARGUS_REPORT_DIR | ./reports | Report output directory | | ARGUS_GITHUB_TOKEN | (none) | GitHub token (raises rate limit to 5000/hr) | | ARGUS_PROXY | (none) | HTTP proxy URL | | ARGUS_CONCURRENCY | 20 | Concurrent request limit | | ARGUS_TIMEOUT | 30 | HTTP request timeout (seconds) |

Integration with other tools

Argus complements offensive security tools:

• T3MP3ST — red-team harness for CVE hunting, CTF, exploit chains
• cariddi — the crawler engine inside Argus
• nmap — the network scanner inside Argus

Natural chain: Argus cartographie la target → T3MP3ST attaque.

Philosophy

• Local-first: Everything runs on your machine. No cloud calls except target websites.
• Zero API keys: Every module works without paid API keys. Replace HIBP, Shodan, Censys, IP2Location with local equivalents.
• No hallucination: AI proposes tool calls, code executes real binaries. Findings are real.
• Modular: Each module is independent. Run standalone or chained via AI.
• Open source: MIT license. Built on open-source tools.

Legal Disclaimer

> Argus is intended for legal and authorized use only. > > Users are solely responsible for ensuring their use complies with all applicable laws and regulations. The authors accept no liability for misuse. > > Argus is an OSINT (Open Source Intelligence) framework designed for security researchers, penetration testers, bug bounty hunters, and analysts conducting authorized investigations using publicly available information. > > Do not use Argus to: > - Stalk, harass, or intimidate individuals > - Access systems or data without explicit authorization > - Violate terms of service of any platform > - Conduct unauthorized surveillance > > Always obtain proper authorization before investigating any target. When in doubt, consult legal counsel.

Credits

Argus is built by the COT Collective with AI collaboration.

Powered by:

• cariddi by @edoardottt — web crawler + secret hunter
• dnspython — DNS toolkit
• python-whois — WHOIS lookup
• Ollama — local LLM inference
• MCP — Model Context Protocol

License

MIT — see [LICENSE](LICENSE) file.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cotcollective
• Source: cotcollective/argus
• License: MIT

Install and usage instructions live in the source repository linked above.