Trace — Incident Timeline Correlation Engine

Correlates IOCs, detection findings, phishing reports, and network anomalies into unified incident timelines. The top-level correlation layer of the iris ecosystem.

Quick Start

git clone https://github.com/makhembu/trace
cd trace
cp .env.example .env
npm install
npm run build
npm start
# Server running at http://localhost:3004

Architecture

flowchart LR
    Feeds["Threat Feeds"] --> Iris["iris<br/>IOC Aggregation<br/>Port 3000"]
    Iris --> Sentry["sentry<br/>Port 3001"]
    Iris --> PhishKit["phishkit<br/>Port 3002"]
    Iris --> PacketWatch["packetwatch<br/>Port 3003"]
    Sentry --> Trace["trace (this service)<br/>Incident Correlation<br/>Port 3004"]
    PhishKit --> Trace
    PacketWatch --> Trace
    Trace --> Nexus["nexus<br/>Dashboard & Gateway<br/>Port 3100"]

Loading

trace is the top-level correlation layer — it ingests events from all four upstream services and groups them into unified incident timelines.

Docker

# Build and run standalone
docker build -t trace .
docker run -p 3004:3004 trace

# Run the full ecosystem
docker compose -f ../nexus/docker-compose.yml up

Ingest from Ecosystem

# Ingest from all configured sources at once
curl -X POST http://localhost:3004/ingest/all

# Or per-source
curl -X POST http://localhost:3004/ingest/iris
curl -X POST http://localhost:3004/ingest/sentry
curl -X POST http://localhost:3004/ingest/phishkit
curl -X POST http://localhost:3004/ingest/packetwatch

API

Events

POST /events       { source, sourceEventId, eventType, severity, title, occurred_at }
POST /events/batch { events: [...] }
GET  /events?source=&severity=&incidentId=

Incidents

GET    /incidents?status=open&severity=high
GET    /incidents/:id
PATCH  /incidents/:id { status, title, description }

Correlation

POST /correlate

Export

GET /export
GET /dashboard

Correlation Rules

Events are correlated into incidents using configurable rules:

Rule	Source	Match	Group Window
IOC to Finding	iris	IOC value matches finding IOC value	60 min
Anomaly to IOC	packetwatch	Source matches IOC source	60 min
PhishKit URL to IOC	phishkit	URL matches IOC value	60 min

Why

Security tools generate isolated alerts. Trace connects them: an iris IOC becomes a timeline event, a sentry finding referencing the same value gets grouped into an incident, a packetwatch anomaly on the same source adds network context. Analysts get a single timeline instead of five dashboards.

Stack

• TypeScript
• Hono
• better-sqlite3
• Multi-source API ingestion
• Cloudflare Workers + D1 ready

Roadmap

• Event ingestion from iris, sentry, phishkit, packetwatch
• Incident auto-creation from correlated events
• Correlation rules engine
• Timeline export (JSON)
• Incident management (status, severity)
• MITRE ATT&CK mapping
• Timeline rendering (Gantt-style)
• Alert forwarding (email, Slack, PagerDuty)
• STIX export

Ecosystem

Part of the threat intelligence ecosystem. Trace is the top-level correlation layer that connects events from all other services into unified incident timelines:

Service	Port	Description
iris	3000	IOC aggregation
sentry	3001	Detection rules
phishkit	3002	Phishing analysis
packetwatch	3003	Anomaly detection
trace	3004	Incident correlation
nexus	3100	Dashboard & gateway

Use threat-stack.ps1 from the repo root to run all services: .\threat-stack.ps1 start