Architecture

High-level overview

┌─────────────────────────────────────────────────────────────┐
│                       Interfaces                            │
│  CLI (osint-agent) │ MCP (44 tools) │ A2A (5 skills)       │
│  Claude Code (15 skills)  │  Python import                  │
├─────────────────────────────────────────────────────────────┤
│              OsintService  (unified facade)                 │
│             src/services/osint_service.py                   │
├──────────────────────────┬──────────────────────────────────┤
│   Threat Intelligence    │    Investigation Management      │
│                          │                                  │
│  ReAct Agent (LangGraph) │  InvestigationManager           │
│  Risk Dashboard (0-100)  │  EvidencePipeline               │
│  Threat Report (Markdown)│  EntityManager (12 types, FTM)  │
│  Auto-Pivot (2 levels)   │  ClaimTracker (traceability)    │
│                          │  AlertManager                   │
├──────────────────────────┴──────────────────────────────────┤
│  SQLite (OSINT cache)  │  SQLite (investigations, 8 tables)│
│  data/osint_cache.db   │  data/osint_ai.db                 │
│                        │  ChromaDB  data/chroma/           │
├─────────────────────────────────────────────────────────────┤
│       28 OSINT Tools + 3 Analysis Modules (async httpx)     │
│  VirusTotal │ AbuseIPDB │ AlienVault │ Shodan │ IPInfo     │
│  URLScan │ WHOIS │ DNS │ crt.sh │ Threat Feeds             │
│  GDELT │ RSS │ Financial │ ACLED │ AIS                     │
│  Pivot │ History │ anomaly_detector │ narrative_detector    │
└─────────────────────────────────────────────────────────────┘

Data flow

Threat Intelligence

User query
    ↓
ReAct Agent selects tools
    ↓
Async API calls (httpx)
    ↓
Results cached in SQLite
    ↓
Agent reasons over results
    ↓ (if related IOCs found)
Auto-pivot → new round of tools
    ↓
Dashboard + Markdown Report

Investigation Management

Create investigation
    ↓
Ingest evidence (PDF/URL/text)
    ↓
SHA-256 → extraction → chunks → ChromaDB embeddings
    ↓
Extract entities (FTM normalization)
    ↓
Register claims with traceability
    ↓
Semantic search
    ↓
Verify claims → audit quality
    ↓
Generate 9-section report

Bridge: investigate and store

The OsintService.investigate_and_store() method connects both workflows:

• Investigates an IOC with the ReAct agent
• Saves the result as evidence in the active investigation
• Automatically extracts entities
• Registers key claims with traceability