THMP — Threat Hypothesis Management Platform

Open-source, self-hostable hunting workbench for OpenCTI: SOC analysts manage the lifecycle of threat hypotheses (ingest → hunt → evidence → ATT&CK → findings) while OpenCTI remains the TIP/knowledge plane (and, over time, the hunting system of record). Co-deploy both on one IP — see docs/architecture/opencti-one-ip.md.

This README summarizes the product vision from the THMP Full System Build Plan (THMP_Full_Build_Plan.docx in the repository) and documents what is implemented in this codebase today.

Vision (build plan)

• Composable stack — Services are independently deployable (Docker Compose for labs; Kubernetes/Helm envisioned for production).
• Primary users — SOC analysts (hypotheses, evidence, hunts); TI teams (structured intel, ATT&CK).
• Core capabilities (target architecture) — Full hypothesis workflow (draft → active → in-hunt → validated → closed/archived), ATT&CK mapping and Navigator-style coverage, evidence store, RBAC/workspaces, audit logging, pluggable connector integrations (SIEM, STIX/TAXII, SCM, scanners, etc.).

The build plan also describes additional components (e.g. dedicated search tier, GraphQL, Celery-heavy ingestion) as the platform matures.

What is implemented here

Area	Status
API gateway	Traefik v3 routes /api/v1/... to services
Auth & users	JWT, registration/login, workspaces, roles (user-service)
Hypotheses, hunts, evidence, findings	CRUD via hypothesis-service; with OpenCTI profile + OPENCTI_NATIVE_SOR, OpenCTI is SoR (ADR 0015)
Audit	Internal event ingestion + admin-visible event list (audit-service)
ATT&CK catalogue	STIX sync, techniques/tactics, Navigator layer JSON export (attack-service)
Reporting (Phase 5)	Templates, async report jobs (PDF + STIX), export history, schedules (reporting-service)
Integrations (Phase 3)	Per-workspace integration config (encrypted secret_ref when configured), thmp-cdk, first-party connectors under connectors/, ingestion-service (POST /api/v1/ingest/batch on port 8005 in Compose), internal dedupe, Test connection from Integrations UI
OpenCTI	Co-deploy + hunting SoR cutover (ADR 0014, ADR 0015): opencti-bridge-service BFF, SPA facades, poll/webhook/publish, deep links — see opencti-one-ip.md
Object storage & search	MinIO/S3 evidence store; OpenSearch cross-entity /api/v1/search
Auth	JWT + optional OIDC (JIT provisioning)
Frontend	Single SPA: hypotheses, hunts, kanban, evidence hub, ingestion triage, ATT&CK navigator + suggest, integrations, global search

Stack in this repo: Python 3.12, FastAPI, SQLAlchemy/asyncpg, PostgreSQL 16, Redis 7, Node 20.

Detailed setup, env vars, ingest URLs, and migrations: docs/development.md.

Connector contract: connector-spec.md.

Architecture decisions: docs/adr/ (connector adapter pattern, ATT&CK service, ingestion auth/dedupe 0008, single SPA 0009, object storage + search 0010, OIDC 0011).

Security reporting: SECURITY.md.

Quick start

cp .env.example .env
# Edit secrets in .env for anything beyond local dev defaults.

docker compose up --build

# Optional: ATT&CK suggest sidecar (heavy ML deps)
# docker compose --profile ml up -d attack-suggest-service

# Recommended: prod SPA + local OpenCTI on one Traefik IP (prod MUST be last)
# docker compose -f docker-compose.yml -f docker-compose.opencti.yml -f docker-compose.prod.yml --profile opencti up -d --build
# Vite lab + OpenCTI (no prod overlay):
# docker compose -f docker-compose.yml -f docker-compose.opencti.yml --profile opencti up -d --build
# Live cutover gate: REQUIRE_OPENCTI_LIVE=1 python3 scripts/smoke_opencti_federation.py

• API (via Traefik): http://localhost (port 80, /api/v1/...)
• UI (dev): http://localhost:5173 (Vite; proxies /api to Traefik)
• UI (prod + OpenCTI): http://localhost/ — nginx static SPA; OpenCTI at http://localhost/opencti
• OpenCTI (profile): hunting SoR when OPENCTI_NATIVE_SOR=true — see opencti-one-ip.md
• Direct service docs (OpenAPI): see docs/development.md (ports 8001–8005)

Without docker-compose.prod.yml or the OpenCTI overlay, Traefik / has no SPA router — use Vite on :5173.

Smoke test against a running stack:

SMOKE_BASE_URL=http://127.0.0.1 python3 scripts/smoke_api.py

Repository layout (high level)

Path	Purpose
backend/thmp_common/	Shared JWT and crypto helpers
backend/thmp_cdk/	Connector Development Kit (types, ConnectorAdapter, test helpers)
backend/user_service/	Auth, users, workspaces, integrations API
backend/hypothesis_service/	Hypotheses, hunts, evidence, findings; internal ingest
backend/attack_service/	ATT&CK STIX sync and catalogue APIs
backend/reporting_service/	Reporting templates, jobs, schedules; PDF/STIX exports
backend/audit_service/	Audit log
backend/ingestion_service/	Batch ingest (connectors → hypotheses)
backend/opencti_bridge_service/	OpenCTI federation bridge (poll, publish, webhooks, intel context)
connectors/	First-party connector packages (webhook, SIEM, TI, notifications, …)
frontend/	Web UI
docs/	Development guide, ADRs, architecture notes

Contributing

See docs/contributing.md and SECURITY.md for vulnerability reporting.

What’s next (Phase 5+)

• Harden connector OAuth device flows and vendor-specific webhook replay protection in production.
• Background workers (Celery/Redis) for ingestion back-pressure and search index repair.
• SOAR playbook templates and optional Kubernetes Helm charts.

License

The THMP Full System Build Plan describes an Apache 2.0 licensing intent. Add a LICENSE file at the repository root when you publish releases.

---

Product direction and phased roadmap: internal THMP Full System Build Plan (THMP_Full_Build_Plan.docx).