fraud-investigator

fraud-copilot-oss

An open-source, agentic fraud-investigation copilot with the auth, RBAC, and audit plumbing that regulated industries actually need.

Showcase & integrator docs: https://iceberg-security.github.io/fincrime-secured-mcp/

Most open-source MCP demos skip the load-bearing security layer. This one ships it: a Claude Cowork plugin talks through an MCP gateway that mints short-lived PASETO tokens, enforces declarative RBAC, audits every call, and federates to six downstream MCP servers — each wrapping a mock data source that an integrator swaps for their real backend.

Python everywhere. Apache 2.0. One docker compose up brings up the full 14+ service stack in under 30 seconds on an M-series MacBook.

Architecture (30-second tour)

┌─────────────────────┐     OIDC bearer      ┌─────────────────────┐
│   Cowork Plugin     │ ───────────────────▶ │  Auth Gateway       │
│ (orchestrator +     │                      │  (PASETO mint)      │
│  subskills +        │                      └──────────┬──────────┘
│  verify-output)     │                                 │ user PASETO (5 min)
└──────────┬──────────┘                                 ▼
           │  user PASETO + JSON-RPC      ┌─────────────────────────┐
           └─────────────────────────────▶│  MCP Gateway            │
                                          │  - PASETO verify        │
                                          │  - replay cache (jti)   │
                                          │  - RBAC enforce         │
                                          │  - re-sign service token│
                                          │  - audit emit           │
                                          └──────────┬──────────────┘
                                                     │ service PASETO (60s, separate keypair)
                                                     ▼
                              ┌──────────────────────────────────────────────┐
                              │   6 downstream MCP servers (FastMCP)         │
                              │   customer_data, transactions, kyc,          │
                              │   sanctions, osint, case_actions             │
                              └──────────┬───────────────────────────────────┘
                                         │ HTTP (loopback / cluster-local)
                                         ▼
                              ┌──────────────────────────────────────────────┐
                              │   6 mock APIs (FastAPI, in-memory)           │
                              │   ─ replaced by integrator's real backends   │
                              └──────────────────────────────────────────────┘

Audit rows land in SQLite (default) or ClickHouse (opt-in). OpenTelemetry spans correlate every hop via the PASETO trace_id claim. The threat model walks the trust boundaries; the ADR index explains every load-bearing choice.

The full architecture and design rationale lives in tasks/prd-fraud-investigator-plugin.md (see §5 for the canonical diagram).

Quickstart

Five minutes to a running investigation against the mock stack:

make install        # create virtualenv and install dependencies
make gen-keys       # one-off: generate Ed25519 PASETO keypairs under config/keys/
make compose-up     # build the shared image and start every service
make compose-ps     # all services should be 'healthy' within ~30 seconds
make load-fixtures  # seed the six scenario personas across the mock stack

Smoke test the full mock-oidc → auth-gateway → mcp-gateway → customer_data path:

TOKEN=$(curl -s "http://localhost:9000/[email protected]" | jq -r .access_token)
PASETO=$(curl -s -X POST http://localhost:8080/token \
             -H "Authorization: Bearer $TOKEN" | jq -r .access_token)
curl -s -X POST http://localhost:8000/mcp/customer_data \
     -H "Authorization: Bearer $PASETO" \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
          "params":{"name":"get_customer",
                     "arguments":{"customer_id":"cust-0001"}}}'

Tear down with make compose-down. The audit DB lives in a named volume (audit_data) so it survives restarts.

Local dev (no Docker) is just as fast:

make lint           # ruff
make typecheck      # mypy
make test           # pytest (>=600 cases, runs in <30s on a laptop)
make evals-smoke    # deterministic eval suite — no API key required

What's included

Mirroring PRD §6 of the source spec: