# PROJECT ARGUS — Open-Source Intelligence Fusion Platform & MCP Server

> **UNCLASSIFIED // OPEN SOURCES ONLY // FOR RESEARCH & EDUCATION**

ARGUS pulls **71 live, public intelligence feeds** across **12 disciplines** into one
local SQLite store, renders them on an interactive **3D WebGL globe**, and exposes the
whole thing to LLM agents through a **Model Context Protocol (MCP) server** with
17 typed tools — so Claude, Gemini, or any MCP host can run multi-hop reconnaissance
over real-time global data instead of guessing from a training cutoff.

Everything runs on your own machine. The server binds to `127.0.0.1` only, the
database and credential vault live outside the source tree, and **60 of the 71
collectors need no API key at all.**

![ARGUS command deck — 3D globe with satellites, aircraft, cameras and ALPR overlays](docs/screenshots/command_deck.png)

---

## What's inside

| Layer | What it does |
|---|---|
| **Collectors** (`osint/collectors/`) | 71 pluggable collectors that normalise external feeds into a common event schema with lat/lon, severity, domain and provenance. Scheduled, rate-limited, TTL-cached. |
| **Store** (`osint/store.py`) | SQLite + FTS. Region / polygon / radius queries, country roll-ups, per-domain stats, event tracks. |
| **Command deck** (`static/`) | Vanilla JS + WebGL globe (no build step, no CDN at runtime). Layer toggles, time-slider, Google Earth / 2D map modes, click-any-dot provenance, watchboxes, link-analysis graph, alert rules. |
| **Analyst agent** (`osint/agent.py`) | Tool-calling LLM analyst (Anthropic / Gemini / OpenAI via plain REST, or a deterministic **offline** SITREP engine). The map selection is compressed into a grounding context before every call. |
| **MCP server** (`mcp_server.py`) | Stdio JSON-RPC 2.0, protocol `2024-11-05`. Exposes the same 17 tools the in-app analyst uses. |
| **BIOMINT** (`osint/biometrics.py`) | Local-only face detection (YuNet) + 128-D embeddings (SFace) for 1:1 verification and 1:N watchlist screening. Models ship in-repo; nothing is uploaded anywhere. |
| **God's Eye** (`osint/godseye.py`) | Public traffic / maritime / weather camera directory with viewshed cones, keyless cyber deep-scan (InternetDB, abuse.ch, CISA KEV…), watchlist + geofence alert rules, entity link graph. |

### The 12 disciplines

| Code | Discipline | Example collectors |
|---|---|---|
| GEOINT | Geospatial & physical | USGS/EMSC quakes, NASA FIRMS fires, GDACS, NHC storms, ADS-B military & emergency squawks, AIS vessels, NOTAMs, chokepoint queues, GPS-jamming detector |
| CTI | Cyber threat intel | CISA KEV, NVD, Feodo C2, ThreatFox, URLhaus, crt.sh, Shodan*, Censys* |
| SIGINT | Signals & network | RIPE BGP watch, IODA outages, submarine cables, PeeringDB datacenters, cell towers, Cloudflare Radar* |
| FININT | Financial & economic | World Bank, IMF WEO, FX/crypto, shadow-fleet tanker tracker, global supply-chain arteries |
| SOCMINT | Social & discourse | Mastodon tags, Lemmy, Hacker News, Bluesky*, Reddit* |
| DARKINT | Leaks & dark web | Ransomware leak sites, HIBP breaches, GitHub gist leak monitor, Pastebin |
| IMINT | Satellite & remote sensing | CelesTrak TLE catalogue, Sentinel-2 / Landsat STAC scenes, Sentinel Hub* |
| MEDIA | News & dispatch | GDELT, world RSS wires, Seattle / SF 911 dispatch |
| GOV | Government & legal | OFAC SDN sanctions |
| PROPUB | Academic | arXiv security/AI, Semantic Scholar |
| HEALTH | Health & biosecurity | WHO Disease Outbreak News, CDC feeds, Safecast radiation network |
| BIOMINT | Biometrics | Local watchlist, FBI Most Wanted notices |

\* needs a key — attach it in the **Keys** tab. Everything else works out of the box.

![Globe after a few minutes of collection — fires, quakes, vessels, aircraft, outages, cameras](docs/screenshots/live_feeds.png)

---

## Quick start

Requirements: **Linux or macOS, Python 3.10+**, ~500 MB disk (OpenCV + NumPy).

```bash
git clone https://github.com/Sockshare/project-argus.git
cd project-argus
./run.sh
```

`run.sh` creates a local `.venv`, installs `requirements.txt` into it, and opens
<http://127.0.0.1:8087>. First launch takes a minute; after that it's instant.

Manual equivalent:

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
python server.py
```

### First five minutes

1. **HOME** — the globe. Toggle layers on the left, click any dot for its source URL and raw record.
2. **Keys → "Auto-provision"** — attaches keyless open-bridges for every slot so all collectors run. Paste real keys later if you want Shodan, Google Earth tiles, ACLED, etc.
3. **Ask AI** — draw a box or pick a country, ask for a SITREP. With no LLM key attached you get the deterministic offline analyst; attach a Gemini/Anthropic/OpenAI key for tool-calling reasoning.
4. **Cameras** — public DOT/maritime/weather cams with viewshed cones; optional on-frame face screening against your local watchlist.
5. **Cyber Check** — IP / CVE / domain dossier with zero keys (InternetDB, abuse.ch, KEV, EPSS).

---

## Using ARGUS as an MCP server

```bash
python3 mcp_server.py --list            # print the 17 tools
python3 mcp_server.py --print-config    # ready-to-paste Claude Desktop / Gemini CLI snippets
```

Claude Desktop (`claude_desktop_config.json`) or Gemini CLI (`~/.gemini/settings.json`):

```json
{
  "mcpServers": {
    "argus": {
      "command": "/ABSOLUTE/PATH/project-argus/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/project-argus/mcp_server.py"]
    }
  }
}
```

Tools: `query_region`, `search_events`, `get_event`, `domain_summary`, `country_profile`,
`stats`, `lookup_ip`, `lookup_cve`, `search_sanctions`, `stac_search`, `aircraft_near`,
`quakes_near`, `geocode`, `reverse_geocode`, `list_collectors`, `run_collector`,
`compress_region`.

A typical agent pivot: suspicious domain → `lookup_ip` (ASN, abuse score, open ports) →
`search_sanctions` on the registrant → `aircraft_near` / `query_region` around the hosting
PoP → `compress_region` for a digest the model can reason over in one turn.

---

## Configuration

Everything is optional. Keys can be set as environment variables (see
[`.env.example`](.env.example)) **or** pasted into the Keys tab, which stores them in
`~/.config/osint_tester/vault.json` with `0600` permissions.

| Variable | Default | Purpose |
|---|---|---|
| `OSINT_PORT` | `8087` | HTTP port |
| `OSINT_HOST` | `127.0.0.1` | Bind address — keep on loopback |
| `OSINT_DATA_DIR` | `~/.local/share/osint_tester` | SQLite store + caches |
| `OSINT_CONFIG_DIR` | `~/.config/osint_tester` | Vault + settings |
| `OSINT_NO_SCHEDULER` | unset | Set to `1` to stop background collection |
| `GEMINI_API_KEY`, `SHODAN_API_KEY`, `GOOGLE_MAPS_API_KEY`, `ALPHAVANTAGE_API_KEY`, `MASTODON_TOKEN` | unset | Auto-attached to the vault on startup if present |

Run a single collector from the CLI:

```bash
.venv/bin/python -m osint.collectors usgs_quakes
```

---

## Project layout

```
project-argus/
├── server.py              FastAPI app: REST API, SSE stream, static UI
├── mcp_server.py          Stdio MCP server (JSON-RPC 2.0)
├── run.sh                 One-command launcher (creates .venv)
├── requirements.txt
├── osint/
│   ├── config.py          Paths, ports, the 12 disciplines
│   ├── store.py           SQLite + FTS event store
│   ├── scheduler.py       Collector scheduling, concurrency, TTL
│   ├── cache.py           HTTP cache + rate limiting
│   ├── vault.py           Credential vault + keyless "open bridges"
│   ├── keytests.py        Live key validation per provider
│   ├── tools.py           The 17 analyst/MCP tools
│   ├── compress.py        Selection → token-budgeted grounding context
│   ├── agent.py           LLM analyst (Anthropic / Gemini / OpenAI / offline)
│   ├── biometrics.py      YuNet + SFace local face engine
│   ├── godseye.py         Cameras, cyber deep-scan, alerts, link graph
│   ├── geo.py             Geocoding, MGRS/UTM, country reference data
│   ├── collectors/        71 collectors grouped by discipline
│   └── data/
│       ├── models/        ONNX face models (OpenCV Zoo, Apache-2.0)
│       └── samples/       Demo images for BIOMINT (see docs/SAMPLES.md)
├── static/                index.html, globe + UI JS, CSS (no build step)
├── deploy/                Dockerfile, docker-compose, nginx, PostGIS init
└── docs/                  Architecture, API contracts, collector rules, UI specs
```

Developer docs: [`docs/BACKEND_SPEC.md`](docs/BACKEND_SPEC.md) ·
[`docs/API_CONTRACT.md`](docs/API_CONTRACT.md) · [`docs/AGENT_SPEC.md`](docs/AGENT_SPEC.md) ·
[`docs/COLLECTOR_RULES.md`](docs/COLLECTOR_RULES.md) (how to add a collector in ~40 lines).

---

## Privacy, safety & responsible use

- **Local by default.** Loopback bind, local SQLite, local face models. Data only
  leaves your machine when a collector calls its public upstream API, or when you
  attach a cloud LLM key and press *Ask AI*.
- **Open sources only.** Every collector targets a public, documented endpoint and
  honours its rate limits. Nothing here bypasses authentication or scrapes behind
  logins.
- **Biometrics stay on-device.** The watchlist is a local SQLite table you populate
  yourself. Demo subjects are AI-generated or public-domain US Government photos —
  see [`docs/SAMPLES.md`](docs/SAMPLES.md). Facial recognition is regulated in many
  jurisdictions; it is your responsibility to use this feature lawfully.
- **No secrets in the repo.** Keys live in the vault or env vars. Please keep it that
  way in PRs.

This is a research and portfolio project, not a certified intelligence product.
Verify anything important against the primary source linked on every event.

## License

MIT — see [LICENSE](LICENSE). Face models © OpenCV Zoo (Apache-2.0).
Upstream data is subject to each provider's own terms.