# ajaxontheway/threat-mapper architecture

> Architecture diagram of the GitHub repository ajaxontheway/threat-mapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ajaxontheway/threat-mapper
- Repository: https://github.com/ajaxontheway/threat-mapper

## Overview

ThreatMapper is a FastAPI threat-intelligence service. Its main workflow validates an IOC, queries reputation providers, calculates a confidence verdict, persists the result, and returns it. Separate capabilities manage tenant organizations and watchlists, periodically rescan watched IOCs, send qualifying alerts to Splunk, and export watchlisted IOCs as STIX 2.1. The scheduler and SIEM dispatch are visible in sampled source; other subsystem links are limited to the shown calls and README, which names no further capabilities.

Main entry points: [`backend/main.py`](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py) (FastAPI endpoints), [`backend/jobs.py`](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/jobs.py) (Background rescans), [`backend/models.py`](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/models.py) (Persistence models), [`backend/database.py`](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/database.py) (Database sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and exports"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_stix["STIX 2.1 export<br/>[main.py]"]
end

subgraph group_analysis["IOC analysis"]
  node_validation["IOC normalization<br/>[engine.py]"]
  node_connectors["Threat feeds<br/>[connectors.py]"]
  node_scoring["Confidence scoring<br/>[engine.py]"]
  node_vt["VirusTotal"]
  node_abuse["AbuseIPDB"]
end

subgraph group_monitoring["Monitoring and SIEM"]
  node_watchlist["Watchlist management<br/>[main.py]"]
  node_scheduler["Background rescans<br/>[jobs.py]"]
  node_siem_dispatch["Alert dispatch<br/>[siem.py]"]
  node_splunk["Splunk HEC"]
end

subgraph group_persistence["Tenant data"]
  node_tenants["Organization and SIEM config<br/>[main.py]"]
  node_models["Persistence models<br/>[models.py]"]
  node_database[("Database sessions<br/>[database.py]")]
end

node_client(("API consumer"))

node_client -->|"requests"| node_api
node_api -->|"normalizes"| node_validation
node_api -->|"queries feeds"| node_connectors
node_connectors -->|"queries"| node_vt
node_connectors -->|"queries"| node_abuse
node_api -->|"scores results"| node_scoring
node_api -->|"persists lookup"| node_database
node_api -->|"queries models"| node_models
node_api -->|"serves routes"| node_watchlist
node_api -->|"serves routes"| node_tenants
node_api -->|"serves export"| node_stix
node_watchlist -->|"reads and writes"| node_database
node_watchlist -->|"uses records"| node_models
node_tenants -->|"reads and writes"| node_database
node_tenants -->|"uses records"| node_models
node_stix -->|"loads watch item"| node_models
node_api -->|"starts scheduler"| node_scheduler
node_scheduler -->|"loads watchlist"| node_database
node_scheduler -->|"queries records"| node_models
node_scheduler -->|"queries feeds"| node_connectors
node_scheduler -->|"scores results"| node_scoring
node_scheduler -->|"sends alerts"| node_siem_dispatch
node_siem_dispatch -->|"posts events"| node_splunk
node_models -->|"inherits base"| node_database

click node_api "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py"
click node_validation "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/engine.py"
click node_connectors "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/connectors.py"
click node_scoring "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/engine.py"
click node_watchlist "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py"
click node_scheduler "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/jobs.py"
click node_siem_dispatch "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/siem.py"
click node_stix "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py"
click node_tenants "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py"
click node_models "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/models.py"
click node_database "https://github.com/ajaxontheway/threat-mapper/blob/main/backend/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_stix toneBlue
class node_validation,node_connectors,node_scoring,node_vt,node_abuse toneAmber
class node_watchlist,node_scheduler,node_siem_dispatch,node_splunk,node_client toneMint
class node_tenants,node_models,node_database toneRose
```

## Components

### API and exports

- [FastAPI endpoints](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py): `backend/main.py`
- [STIX 2.1 export](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py): `backend/main.py`

### IOC analysis

- [IOC normalization](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/engine.py): `backend/engine.py`
- [Threat feeds](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/connectors.py): `backend/connectors.py`
- [Confidence scoring](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/engine.py): `backend/engine.py`
- **VirusTotal**
- **AbuseIPDB**

### Monitoring and SIEM

- [Watchlist management](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py): `backend/main.py`
- [Background rescans](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/jobs.py): `backend/jobs.py`
- [Alert dispatch](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/siem.py): `backend/siem.py`
- **Splunk HEC**

### Tenant data

- [Organization and SIEM config](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/main.py): `backend/main.py`
- [Persistence models](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/models.py): `backend/models.py`
- [Database sessions](https://github.com/ajaxontheway/threat-mapper/blob/main/backend/database.py): `backend/database.py`

### Other components

- **API consumer**

## Connections

- API consumer → FastAPI endpoints: requests (evidence: `backend/main.py`)
- FastAPI endpoints → IOC normalization: normalizes (evidence: `backend/main.py`)
- FastAPI endpoints → Threat feeds: queries feeds (evidence: `backend/main.py`)
- Threat feeds → VirusTotal: queries (evidence: `backend/connectors.py`)
- Threat feeds → AbuseIPDB: queries (evidence: `backend/connectors.py`)
- FastAPI endpoints → Confidence scoring: scores results (evidence: `backend/main.py`)
- FastAPI endpoints → Database sessions: persists lookup (evidence: `backend/main.py`)
- FastAPI endpoints → Persistence models: queries models (evidence: `backend/main.py`)
- FastAPI endpoints → Watchlist management: serves routes (evidence: `backend/main.py`)
- FastAPI endpoints → Organization and SIEM config: serves routes (evidence: `backend/main.py`)
- FastAPI endpoints → STIX 2.1 export: serves export (evidence: `backend/main.py`)
- Watchlist management → Database sessions: reads and writes (evidence: `backend/main.py`)
- Watchlist management → Persistence models: uses records (evidence: `backend/main.py`)
- Organization and SIEM config → Database sessions: reads and writes (evidence: `backend/main.py`)
- Organization and SIEM config → Persistence models: uses records (evidence: `backend/main.py`)
- STIX 2.1 export → Persistence models: loads watch item (evidence: `backend/main.py`)
- FastAPI endpoints → Background rescans: starts scheduler (evidence: `backend/main.py`)
- Background rescans → Database sessions: loads watchlist (evidence: `backend/jobs.py`)
- Background rescans → Persistence models: queries records (evidence: `backend/jobs.py`)
- Background rescans → Threat feeds: queries feeds (evidence: `backend/jobs.py`)
- Background rescans → Confidence scoring: scores results (evidence: `backend/jobs.py`)
- Background rescans → Alert dispatch: sends alerts (evidence: `backend/jobs.py`)
- Alert dispatch → Splunk HEC: posts events (evidence: `backend/siem.py`)
- Persistence models → Database sessions: inherits base (evidence: `backend/models.py`)
