DFIR Platform + TheHive: Automated IOC Enrichment for Case Management

TheHive is one of the most widely deployed open-source case management platforms in security operations. Its strength is organizing investigations — tracking observables, linking cases, and coordinating analyst workflows. But case management without context is just bookkeeping. When an analyst adds a suspicious IP or domain to a case, they need enrichment data to make triage decisions. That is where TheHive IOC enrichment integrations become critical, and where DFIR Platform's multi-source API fits into the architecture.

This guide walks through integrating DFIR Platform as a Cortex analyzer for TheHive, so every observable added to a case is automatically enriched with data from 14+ threat intelligence sources — without manual lookups, without switching tools, and without managing a dozen upstream API keys.

Why TheHive Needs External IOC Enrichment

TheHive itself does not perform IOC analysis. It stores observables — IPs, domains, hashes, URLs — and provides a structured interface for managing them within investigations. The analysis layer is delegated to Cortex, TheHive's companion project, which runs "analyzers" against observables and writes results back into the case.

Out of the box, Cortex ships with analyzers for individual sources: VirusTotal, Shodan, PassiveTotal, AbuseIPDB, and others. Each analyzer queries one source, returns one result, and requires its own API key configuration. For a SOC team that wants comprehensive enrichment, this means:

• Managing API keys for 8-12 different services
• Monitoring rate limits and quotas across each service independently
• Waiting for sequential analyzer execution (or configuring parallel runs)
• Manually correlating results from multiple analyzer reports per observable

DFIR Platform collapses this into a single API call. One analyzer, one API key, 14+ sources queried in parallel, one normalized response. The result is faster enrichment, simpler configuration, and lower operational overhead.

Architecture Overview

The integration follows TheHive's standard analyzer pattern:

[TheHive Case]
    |
    v
[Observable Added] --> [Cortex Analyzer Triggered]
                              |
                              v
                    [DFIR Platform API]
                     api.dfir-lab.ch/v1
                              |
                              v
                    [14+ Sources Queried]
                    (AbuseIPDB, Shodan, PassiveDNS,
                     Spamhaus, VirusTotal, etc.)
                              |
                              v
                    [Normalized Response]
                              |
                              v
                    [Report Written to TheHive Case]

The Cortex analyzer acts as the bridge. When an analyst adds an observable to a case and runs analysis, Cortex calls the DFIR Platform IOC enrichment API, receives the aggregated result, and formats it as a Cortex report that appears directly in TheHive's case view.

Prerequisites

Before setting up the integration, you need:

• TheHive 4.x or 5.x installed and running
• Cortex 3.x installed and configured as an analysis backend for your TheHive instance
• Python 3.8+ on the Cortex server (for running the custom analyzer)
• DFIR Platform API key — sign up at platform.dfir-lab.ch (free tier includes 100 credits/month, no credit card required)
• Network connectivity from the Cortex server to api.dfir-lab.ch on port 443

Getting Started

If you do not yet have a DFIR Platform account, create one at platform.dfir-lab.ch. The free tier provides 100 credits per month, which covers approximately 20-33 IOC enrichment lookups (3-5 credits per lookup depending on IOC type). No credit card is required.

Once registered, generate an API key from the dashboard. You will need this key for the Cortex analyzer configuration.

Building the Cortex Analyzer

Cortex analyzers are Python modules that follow a specific structure. Each analyzer lives in its own directory with a Python script and a JSON descriptor. Below is a complete implementation.

Directory Structure

DFIRPlatform_IOCEnrichment/
  DFIRPlatform_IOCEnrichment.py
  DFIRPlatform_IOCEnrichment.json
  requirements.txt

Analyzer Descriptor (DFIRPlatform_IOCEnrichment.json)

1{
2  "name": "DFIRPlatform_IOCEnrichment",
3  "version": "1.0",
4  "author": "DFIR Lab",
5  "url": "https://dfir-lab.ch",
6  "license": "MIT",
7  "description": "Multi-source IOC enrichment via DFIR Platform API (14+ sources)",
8  "command": "DFIRPlatform_IOCEnrichment/DFIRPlatform_IOCEnrichment.py",
9  "dataTypeList": ["ip", "domain", "hash", "url"],
10  "configurationItems": [
11    {
12      "name": "api_key",
13      "description": "DFIR Platform API key from platform.dfir-lab.ch",
14      "type": "string",
15      "multi": false,
16      "required": true
17    },
18    {
19      "name": "api_url",
20      "description": "DFIR Platform API base URL",
21      "type": "string",
22      "multi": false,
23      "required": false,
24      "defaultValue": "https://api.dfir-lab.ch/v1"
25    }
26  ]
27}

Analyzer Script (DFIRPlatform_IOCEnrichment.py)

1#!/usr/bin/env python3
2"""Cortex analyzer for DFIR Platform IOC enrichment."""
3 
4import requests
5from cortexutils.analyzer import Analyzer
6 
7 
8class DFIRPlatformAnalyzer(Analyzer):
9    """Query DFIR Platform API for multi-source IOC enrichment."""
10 
11    def __init__(self):
12        Analyzer.__init__(self)
13        self.api_key = self.get_param(
14            "config.api_key", None, "DFIR Platform API key is required"
15        )
16        self.api_url = self.get_param(
17            "config.api_url", "https://api.dfir-lab.ch/v1"
18        )
19 
20    def run(self):
21        data_type = self.data_type
22        observable = self.get_data()
23 
24        # Map TheHive data types to DFIR Platform IOC types
25        type_map = {
26            "ip": "ip",
27            "domain": "domain",
28            "hash": "hash",
29            "url": "url",
30        }
31 
32        ioc_type = type_map.get(data_type)
33        if not ioc_type:
34            self.error(f"Unsupported data type: {data_type}")
35            return
36 
37        headers = {
38            "X-API-Key": self.api_key,
39            "Content-Type": "application/json",
40        }
41 
42        payload = {
43            "type": ioc_type,
44            "value": observable,
45        }
46 
47        try:
48            response = requests.post(
49                f"{self.api_url}/ioc/enrich",
50                headers=headers,
51                json=payload,
52                timeout=30,
53            )
54            response.raise_for_status()
55            result = response.json()
56 
57            self.report({
58                "risk_score": result.get("risk_score", 0),
59                "verdict": result.get("verdict", "unknown"),
60                "sources_queried": result.get("sources_queried", 0),
61                "sources_flagged": result.get("sources_flagged", 0),
62                "enrichment": result.get("enrichment", {}),
63                "tags": result.get("tags", []),
64                "raw": result,
65            })
66 
67        except requests.exceptions.RequestException as e:
68            self.error(f"DFIR Platform API request failed: {str(e)}")
69 
70    def summary(self, raw):
71        taxonomies = []
72        level = "info"
73        risk_score = raw.get("risk_score", 0)
74 
75        if risk_score >= 75:
76            level = "malicious"
77        elif risk_score >= 40:
78            level = "suspicious"
79        elif risk_score > 0:
80            level = "safe"
81 
82        taxonomies.append(
83            self.build_taxonomy(
84                level, "DFIRPlatform", "RiskScore", risk_score
85            )
86        )
87        taxonomies.append(
88            self.build_taxonomy(
89                "info",
90                "DFIRPlatform",
91                "Sources",
92                f"{raw.get('sources_flagged', 0)}/{raw.get('sources_queried', 0)}",
93            )
94        )
95 
96        return {"taxonomies": taxonomies}
97 
98 
99if __name__ == "__main__":
100    DFIRPlatformAnalyzer().run()

Requirements (requirements.txt)

cortexutils
requests

Installing the Analyzer in Cortex

1. Copy the DFIRPlatform/ directory to your Cortex analyzers path (typically /opt/cortex/analyzers/ or the path configured in application.conf).

2. Install dependencies:

1cd /opt/cortex/analyzers/DFIRPlatform
2pip3 install -r requirements.txt

3. In the Cortex web interface, navigate to Organization > Analyzers and enable DFIRPlatform.

4. Configure the analyzer with your API key from platform.dfir-lab.ch.

5. Restart Cortex if necessary (depends on your version and configuration).

Using the Integration in TheHive

Once the analyzer is configured in Cortex, it appears in TheHive's analysis options for any observable. The workflow is straightforward:

Manual Analysis

1. Open a case in TheHive.
2. Navigate to the Observables tab.
3. Add or select an observable (IP, domain, hash, or URL).
4. Click Analyze and select DFIRPlatform.
5. The enrichment report appears in the observable's analyzer results within seconds.

The report includes the risk score, the number of sources that flagged the indicator, and the full enrichment data from all queried sources.

Automated Analysis on Observable Creation

TheHive supports auto-analysis — running specific analyzers automatically when observables are added to a case. To enable this:

1. In Cortex, set the DFIRPlatform analyzer to auto-run for the relevant data types.
2. Every observable added to any case will be enriched automatically without analyst intervention.

This is particularly valuable for cases created from automated alert ingestion (SIEM alerts, email reports, SOAR playbooks), where observables arrive in bulk and need immediate context.

Standalone Python Integration

If you are not using Cortex, or if you want to enrich observables before they reach TheHive, you can call the DFIR Platform API directly and push results to TheHive via its REST API.

1#!/usr/bin/env python3
2"""Enrich IOCs via DFIR Platform and add results to TheHive case."""
3 
4import requests
5 
6DFIR_API_KEY = "your-dfir-platform-api-key"
7DFIR_API_URL = "https://api.dfir-lab.ch/v1"
8THEHIVE_URL = "https://your-thehive-instance"
9THEHIVE_API_KEY = "your-thehive-api-key"
10 
11 
12def enrich_ioc(ioc_type: str, value: str) -> dict:
13    """Query DFIR Platform for IOC enrichment."""
14    headers = {
15        "X-API-Key": DFIR_API_KEY,
16        "Content-Type": "application/json",
17    }
18    response = requests.post(
19        f"{DFIR_API_URL}/ioc/enrich",
20        headers=headers,
21        json={"type": ioc_type, "value": value},
22        timeout=30,
23    )
24    response.raise_for_status()
25    return response.json()
26 
27 
28def add_enrichment_to_thehive(case_id: str, observable_id: str, enrichment: dict):
29    """Add enrichment data as a case task log in TheHive."""
30    headers = {
31        "Authorization": f"Bearer {THEHIVE_API_KEY}",
32        "Content-Type": "application/json",
33    }
34 
35    risk_score = enrichment.get("risk_score", 0)
36    verdict = enrichment.get("verdict", "unknown")
37    sources = enrichment.get("sources_queried", 0)
38    flagged = enrichment.get("sources_flagged", 0)
39 
40    note = (
41        f"## DFIR Platform Enrichment\n\n"
42        f"**Risk Score:** {risk_score}/100\n"
43        f"**Verdict:** {verdict}\n"
44        f"**Sources Queried:** {sources}\n"
45        f"**Sources Flagged:** {flagged}\n\n"
46        f"Full enrichment data attached as JSON."
47    )
48 
49    # Add a task log with the enrichment summary
50    requests.post(
51        f"{THEHIVE_URL}/api/v1/case/{case_id}/comment",
52        headers=headers,
53        json={"message": note},
54        timeout=15,
55    )
56 
57    # Update observable tags based on verdict
58    if risk_score >= 75:
59        tag_update = {"tags": ["dfir:malicious", f"dfir:score:{risk_score}"]}
60    elif risk_score >= 40:
61        tag_update = {"tags": ["dfir:suspicious", f"dfir:score:{risk_score}"]}
62    else:
63        tag_update = {"tags": ["dfir:clean", f"dfir:score:{risk_score}"]}
64 
65    requests.patch(
66        f"{THEHIVE_URL}/api/v1/observable/{observable_id}",
67        headers=headers,
68        json=tag_update,
69        timeout=15,
70    )
71 
72 
73def process_case_observables(case_id: str):
74    """Enrich all observables in a TheHive case."""
75    headers = {
76        "Authorization": f"Bearer {THEHIVE_API_KEY}",
77        "Content-Type": "application/json",
78    }
79 
80    # Fetch observables from the case
81    response = requests.post(
82        f"{THEHIVE_URL}/api/v1/query",
83        headers=headers,
84        json={
85            "query": [
86                {"_name": "getCase", "idOrName": case_id},
87                {"_name": "observables"},
88            ]
89        },
90        timeout=15,
91    )
92    response.raise_for_status()
93    observables = response.json()
94 
95    type_map = {"ip": "ip", "domain": "domain", "hash": "hash", "url": "url"}
96 
97    for obs in observables:
98        data_type = obs.get("dataType", "")
99        ioc_type = type_map.get(data_type)
100        if not ioc_type:
101            continue
102 
103        value = obs.get("data", "")
104        obs_id = obs.get("_id", "")
105 
106        print(f"Enriching {data_type}: {value}")
107        enrichment = enrich_ioc(ioc_type, value)
108        add_enrichment_to_thehive(case_id, obs_id, enrichment)
109        print(f"  Risk score: {enrichment.get('risk_score', 'N/A')}")
110 
111 
112if __name__ == "__main__":
113    process_case_observables("case-id-here")

This script fetches all observables from a TheHive case, enriches each one via the DFIR Platform API, and writes the results back as case comments with appropriate tags. It can be triggered manually, from a cron job, or from a SOAR playbook.

TheHive IOC Enrichment Workflow: End-to-End Example

Here is a concrete scenario showing how the integration works in practice.

Scenario: A phishing email is reported by an employee. The SOC creates a case in TheHive and adds the observables extracted from the email: a sender IP, two URLs from the email body, and a SHA-256 hash of an attached PDF.

Step 1 — Observable ingestion. The analyst (or an automated playbook) adds the four observables to the case.

Step 2 — Auto-analysis triggers. The DFIRPlatform Cortex analyzer runs automatically against all four observables.

Step 3 — API enrichment. For each observable, the DFIR Platform API queries 14+ sources in parallel. The sender IP is checked against abuse databases, IP reputation feeds, and passive scan data. The URLs are checked for phishing indicators, redirect chains, and domain reputation. The hash is checked against malware repositories and sandbox results.

Step 4 — Results appear in case. Within seconds, each observable in TheHive shows a Cortex report with a risk score and source breakdown. The analyst sees at a glance: the sender IP has a risk score of 82 (flagged by 9 of 14 sources), one URL scores 91 (known phishing page), the second URL scores 12 (legitimate CDN), and the hash scores 67 (detected by 4 AV engines in sandbox analysis).

Step 5 — Triage decision. The analyst escalates the case, blocks the high-risk IP and phishing URL at the perimeter, and submits the PDF hash for deeper sandbox analysis. Total time from observable ingestion to triage decision: under three minutes.

Configuration Best Practices

Credit management. Each enrichment lookup consumes 3-5 credits. If you are running auto-analysis on high-volume alert ingestion, monitor your credit usage in the DFIR Platform dashboard. The free tier (100 credits/month) is suitable for evaluation and low-volume teams. For production SOC use, the Starter plan (500 credits/month at $29/mo) or Professional plan (2,500 credits/month at $79/mo) provides adequate capacity.

Rate limiting. The DFIR Platform API handles rate limiting server-side. If you exceed your plan's rate, requests return a 429 status with a Retry-After header. The Cortex analyzer handles this gracefully — it reports the error rather than failing silently.

Observable deduplication. TheHive can ingest the same observable across multiple cases. Configure Cortex to cache analyzer results for a configurable TTL (e.g., 1 hour) to avoid re-enriching the same IOC repeatedly and burning credits on duplicate lookups.

Network security. Ensure the Cortex server can reach api.dfir-lab.ch over HTTPS. If your SOC operates in an air-gapped or heavily firewalled environment, whitelist the API endpoint in your egress rules.

Conclusion

TheHive provides the structure for managing investigations. DFIR Platform provides the intelligence to drive decisions within those investigations. The combination — either through the Cortex analyzer or the direct API integration — gives SOC teams automated, multi-source IOC enrichment without the operational overhead of managing a dozen individual threat intelligence subscriptions.

The Cortex analyzer takes under 15 minutes to deploy. The standalone Python integration can be adapted to any workflow that touches TheHive's API. Both approaches use the same DFIR Platform API key and credit pool.

Sign up for a free account at platform.dfir-lab.ch to get your API key — 100 credits per month, no credit card required. Use code LAUNCH50 for 50% off your first paid month on Starter or Professional plans.