cotcollective/argus

What is this?

Argus is an OSINT (Open Source Intelligence) investigation framework that runs entirely on your machine. No API keys, no cloud services, no telemetry. Every module uses open-source tools and free endpoints.

The AI agent chains tools automatically — describe your target in plain English, Argus decides which tools to run and chains findings across modules. Powered by Ollama for local inference.

Modules

*GitHub: 60 req/min free without token, 5000 with optional token.

Note on breach_check: This module queries a local SQLite database that you populate yourself. It does not crawl the dark web, access Telegram channels, or query HIBP’s backend. If you need comprehensive breach data, HIBP and intelx are the right tools. The breach module is for researchers who already have breach compilations and want to query them locally without sending emails to a third-party API.

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 [email protected]
./venv/bin/argus paste [email protected]
./venv/bin/argus email [email protected]
./venv/bin/argus username johndoe
./venv/bin/argus phone +15145551234
./venv/bin/argus breach [email protected]
./venv/bin/argus network 10.0.0.1

# AI-chained investigation (requires Ollama)
./venv/bin/argus investigate "investigate [email protected]"

# 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 [email protected]"

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

Configuration

All config via environment variables (all optional):

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 file.