Back to Integrations
TheHive & Cortex Integration
Enrich every ip observable in TheHive with ipinsights.io via a
small Cortex analyser.
Overview
TheHive
/ Cortex
is the de-facto open-source SOAR for incident-response teams. A Cortex analyser is a small
Python program that takes a single observable as input and returns enriched JSON; TheHive
surfaces both the verdict (info / safe / suspicious / malicious) and the raw output in the
case timeline.
Prerequisites
- Cortex 3.x with shell-out / python3 enabled
- Python 3.8+ on the Cortex host with the
cortexutils package installed
(pip install cortexutils)
- An ipinsights.io API key — your
profile page
Step 1 — Analyser Layout
In your Cortex analysers directory (typically /opt/Cortex-Analyzers/analyzers) create:
IPInsights/
├── IPInsights.json # analyser manifest
└── ipinsights.py # analyser code (executable)
Step 2 — Manifest
{
"name": "IPInsights",
"version": "1.0",
"author": "your-team",
"url": "https://ipinsights.io",
"license": "AGPL-V3",
"description": "Enrich IP observables with IP Insights threat intelligence.",
"dataTypeList": ["ip"],
"baseConfig": "IPInsights",
"command": "IPInsights/ipinsights.py",
"config": {
"service": "lookup"
},
"configurationItems": [
{
"name": "api_key",
"description": "IP Insights API key",
"type": "string",
"multi": false,
"required": true
}
]
}
Step 3 — Analyser Code
ipinsights.py (make it executable: chmod +x ipinsights.py):
#!/usr/bin/env python3
"""Cortex analyser — IP Insights threat-intel lookup."""
import requests
from cortexutils.analyzer import Analyzer
API_URL = "https://ipinsights.io/api/v1/lookup"
class IPInsightsAnalyzer(Analyzer):
def __init__(self):
Analyzer.__init__(self)
self.api_key = self.get_param("config.api_key", None, "Missing IP Insights API key")
def summary(self, raw):
data = raw.get("data", {}) or {}
score = data.get("threat_score", 0) or 0
if data.get("is_tor") or score >= 80:
level = "malicious"
elif score >= 50:
level = "suspicious"
elif score > 0:
level = "info"
else:
level = "safe"
return {
"taxonomies": [
self.build_taxonomy(level, "IPInsights", "score", str(score)),
self.build_taxonomy(
"info", "IPInsights", "country",
data.get("country_code", "??") or "??",
),
]
}
def run(self):
if self.data_type != "ip":
return self.error("IPInsights only supports the ip data type")
ip = self.get_data()
try:
r = requests.get(
API_URL,
params={"ip": ip},
headers={"X-API-Key": self.api_key},
timeout=10,
)
r.raise_for_status()
except requests.RequestException as exc:
return self.error(f"IP Insights request failed: {exc}")
self.report(r.json())
if __name__ == "__main__":
IPInsightsAnalyzer().run()
Step 4 — Enable in Cortex
- Restart Cortex so the new analyser folder is picked up.
- Open the Cortex web UI → Organisation → Analyzers, find
IPInsights_1_0, click Enable and paste your API key.
- In TheHive open any case with an
ip observable and click
Run analyzer → IPInsights.
Step 5 — Verify
Test from the command line without going through TheHive:
echo '{"data":"185.220.101.1","dataType":"ip","config":{"api_key":"YOUR_KEY"}}' \
| /opt/Cortex-Analyzers/analyzers/IPInsights/ipinsights.py
A JSON document with a summary.taxonomies block and the raw
full.data payload should be printed.
API Key: Required — store it inside the analyser configuration in Cortex.
Find your key on your profile page.
Request Higher API Limit
Running a high-volume TheHive & Cortex deployment? If the default rate limit isn't
enough for your environment, submit a request below and we'll review it.