# IZZO — Platform

**The backend of IZZO:** the autonomous agents that hunt X for supply-chain compromises, plus the
public MCP server that delivers confirmed intel to coding agents. One codebase, two roles — the
detection pipeline **writes** to Postgres; the MCP/REST server **reads** from it.

> **The problem.** Supply-chain attacks are one of the most prominent and damaging forms of
> cyber-attack in the age of AI-powered social engineering and vulnerability detection. Modern
> enterprises treat a published CVE as ground truth — too slow for this new age. Meanwhile
> engineering teams, paired with agents like Grok Build, Claude Code, and Codex, ship faster than
> ever with no real-time knowledge of which packages are compromised.
>
> **The insight.** The security and engineering communities on X identify and disclose critical
> supply-chain compromises *as they happen* — routinely hours to days ahead of security vendors
> and traditional vulnerability databases. That gap is the difference between a win and a loss.
> IZZO is built directly around it.

## The pipeline

IZZO runs as a pipeline of a few core agents, all driven by the **X API via its MCP tools**:

1. **Hunt.** Agent-driven search on two cadences — a **light sweep every 10 minutes** for anything
   critical just reported in that window, and a **deep sweep every hour** with full coverage
   across every major package ecosystem (npm, PyPI, crates, RubyGems, NuGet, Go, Docker,
   extensions), attack patterns, and known security-researcher accounts. The agent doesn't just
   run fixed queries — it **pivots off any finding** (package names, unique publishers, the X
   accounts that reported it). When a finding is confirmed, IZZO keeps **monitoring that account
   every hour** for new details or new vulnerabilities they report. → `agents/scout.py`

2. **Validate.** Every candidate is treated as a potential real attack. Validation leans both on
   and off X — pulling the linked security-firm advisory (Socket, Checkmarx, Snyk) for exact
   package names/versions/IOCs and cross-referencing OSV — to confirm authenticity. →
   `agents/validator.py`

3. **Analyze.** For confirmed incidents, IZZO **downloads the actual artifact** from the registry
   (**never executing it**), **diffs it against the last known-good version**, and statically
   scans for the payload — corroborating or invalidating the report. It then **pivots on the
   publisher** to surface sibling packages shipped in the same window. → `agents/analyst.py`,
   `tools/`

4. **Correlate across X.** With a full picture of the incident and its IOCs (publisher handles,
   C2 domains, wallets, PR authors), IZZO goes **back to the X API** to search for those exact
   indicators — pinning the earliest sighting and surfacing connections to other actors and
   campaigns that no single report has combined. → `agents/ioc_pivot.py`

5. **Deliver.** Confirmed incidents land in a structured database (incidents, IOCs, X users/posts,
   full activity trace), auto-post to **[@IZZOdetections](https://x.com/IZZOdetections)**, and are
   served through the **unauthenticated MCP server + REST API** below. → `pipeline.py`,
   `poster.py`, `server.py`

## The delivery layer — `server.py`

A read-only window onto the same database, for coding agents and the web:

**MCP server — `/mcp`** (streamable HTTP, no API key):
- `check_packages(["npm:left-pad","pypi:requests"])` — call before adding/upgrading a dependency
- `list_recent_incidents(days, ecosystem, only_confirmed)` · `get_incident(id)`

```bash
claude mcp add --transport http izzo https://izzo-api-…run.app/mcp/
```

**REST — `/api/v1`:** `vulnerabilities`, `vulnerabilities/{id}`, `packages/check`, `activity`
(the live call-trace of every X API query), `feed`, `stats`.

## Layout

```
src/izzo/
  agents/      scout (hunt), validator, analyst, context, ioc_pivot, schemas
  tools/       registry download (no-exec) + diff + static scanner + web fetch + OSV
  db/          SQLAlchemy models (the shared schema)
  pipeline.py  orchestration: hunt → validate → analyze → correlate → deliver
  poster.py    posts confirmed incidents to @IZZOdetections via the X API
  server.py    FastAPI: REST /api/v1 + mounted MCP server at /mcp
  cli.py       run-once, schedule, auth, drafts, vulns, announcements …
```

## Run

```bash
uv sync
cp .env.example .env     # OPENAI_API_KEY, X CLIENT_ID/SECRET/BEARER_TOKEN, IZZO_DATABASE_URL

# detection pipeline
uv run izzo auth         # one-time X OAuth for the posting account
uv run izzo run-once     # a single hunt → validate → analyze → correlate → deliver cycle
uv run izzo schedule     # continuous: light every 10m, deep every hour

# MCP + REST server
uv run uvicorn izzo.server:app --port 8080
```

The X API is reached through the hosted X MCP server (`api.x.com/mcp`): app-only bearer token for
search, user-context OAuth for posting. Package artifacts are only ever **downloaded and
statically analyzed — never executed.**

## Related repo

- **Interface (site):** the public live feed + activity call-trace + MCP docs — `izzo-interface`
- **Live:** https://izzo.ergonlabs.ai · detection feed: https://x.com/IZZOdetections

Deployed on GCP Cloud Run (a scheduled detection job + a public MCP/REST service) + Postgres.