How CAPEv2 Integrates with Suricata for Comprehensive Network Traffic Analysis

CAPEv2 executes Suricata as an external network IDS engine to capture EVE JSON logs during sandbox runs, then parses, enriches, and exposes the data through REST APIs and the web interface.

CAPEv2 (kevoreilly/capev2) leverages Suricata to provide deep packet inspection alongside dynamic malware analysis. This integration transforms raw network traffic into structured intelligence by processing Suricata's EVE JSON output and mapping alerts to malware families. The system stores parsed network events—alerts, HTTP flows, TLS sessions, and extracted files—alongside sandbox analysis results.

Suricata Execution and Log Generation

During each analysis task, CAPEv2 runs Suricata as a system service monitoring the sandbox network interface. The service configuration in systemd/suricata.service typically launches Suricata with the -i tun0 flag and directs EVE JSON output to the analysis log directory. This produces a structured eve.json file containing event records for alerts, HTTP requests, DNS queries, TLS handshakes, SSH sessions, and file information.

The Suricata Processing Pipeline

After sandbox execution, the Suricata processing module (modules/processing/suricata.py) ingests the EVE JSON log and normalizes it into CAPEv2's data structures.

Parsing and Classification

The processing module initializes a dictionary structure at lines 83-94 to hold categorized network events. It reads the eve.json file line-by-line, parsing each JSON record and routing it based on the event_type field. The classification loop at lines 290-334 handles alert, http, tls, dns, ssh, and fileinfo events separately, appending them to their respective lists within the Suricata dictionary.

# Excerpt from modules/processing/suricata.py (lines 83-94, 290-334)

suricata = {
    "alerts": [],
    "http": [],
    "tls": [],
    "dns": [],
    "ssh": [],
    "files": [],
    "eve_log_full_path": SURICATA_EVE_LOG_FULL_PATH,
}

with open(SURICATA_EVE_LOG_FULL_PATH, "r") as f:
    for line in f:
        event = json.loads(line)
        if event["event_type"] == "alert":
            suricata["alerts"].append(event["alert"])
        elif event["event_type"] == "http":
            suricata["http"].append(event["http"])
        # Additional handlers for tls, dns, ssh, and fileinfo...

After classification, lines 405-416 sort events by timestamp and optionally enrich the data with malware family detection.

Alert Enrichment and Family Detection

CAPEv2 enhances raw Suricata alerts by mapping signatures to malware family names using the get_suricata_family function from lib/cuckoo/common/suricata_detection.py. The enrichment logic at lines 412-416 of the processing module adds a family field to alerts when signatures match known threat categories.

# From modules/processing/suricata.py (lines 412-416)

from lib.cuckoo.common.suricata_detection import get_suricata_family

for alert in suricata["alerts"]:
    family = get_suricata_family(alert["signature"])
    if family:
        alert["family"] = family

Exposing Suricata Data Through APIs and Web Interface

Once processed, Suricata intelligence becomes accessible through multiple consumption paths.

REST API Integration

The API layer in web/apiv2/views.py (lines 1416-1420) injects parsed Suricata results into the network analysis payload under the ids key. Clients retrieve this data by querying task reports.

import requests

TASK_ID = 12345
BASE_URL = "https://cape.example.com/api/tasks"

resp = requests.get(f"{BASE_URL}/{TASK_ID}/", verify=False)
data = resp.json()

# Access Suricata alerts

alerts = data["network"]["ids"]["alerts"]
for alert in alerts[:5]:
    print(f"{alert['signature']} (severity: {alert['severity']})")

# Access HTTP flows captured by Suricata

for http in data["network"]["ids"]["http"]:
    print(f"{http['hostname']}{http['uri']}")

Web Interface and Moloch Integration

The web interface (web/analysis/views.py) renders Suricata alerts, HTTP flows, TLS metadata, and extracted files for interactive analysis. The system includes helper functions such as gen_moloch_from_suri_alerts (around lines 1005-1154) that convert Suricata data into Moloch-compatible JSON formats for advanced network forensics visualization.

Summary

• External Execution: Suricata runs as a system service monitoring the sandbox interface, generating EVE JSON logs containing comprehensive network metadata and file extraction records.
• Structured Processing: The modules/processing/suricata.py component parses eve.json, categorizes events by type (alerts, HTTP, TLS, DNS, SSH, files) at lines 290-334, and sorts them chronologically at lines 405-416.
• Intelligence Enrichment: The lib/cuckoo/common/suricata_detection.py library provides get_suricata_family to map Suricata signatures to readable malware families, enriching alerts during processing.
• Multi-Channel Access: Processed data flows into MongoDB and becomes available through the REST API (web/apiv2/views.py lines 1416-1420) and the interactive web interface with optional Moloch export capabilities.

Frequently Asked Questions

Where does CAPEv2 store the raw Suricata output files?

CAPEv2 stores the raw Suricata EVE JSON output within the analysis directory structure, typically at a path configured as SURICATA_EVE_LOG_FULL_PATH in the processing module. The systemd/suricata.service unit defines the base log directory (often /opt/cape/analysis/), and the processing module at modules/processing/suricata.py reads the eve.json file from this location.

How does CAPEv2 distinguish between different network event types?

The processing module in modules/processing/suricata.py inspects the event_type field of each EVE JSON record to route events into categorized lists. Lines 290-334 handle specific types including alert, http, tls, dns, ssh, and fileinfo, storing each in distinct keys within the Suricata dictionary for structured querying.

Can Suricata alerts be accessed separately from other network data?

Yes. The REST API in web/apiv2/views.py (lines 1416-1420) exposes Suricata data under the network.ids key in task reports. Clients can retrieve the complete dataset via GET /api/tasks/<task_id>/ and filter for the suricata or network.ids section, which contains isolated lists for alerts, HTTP flows, and other event types.

What is the purpose of the get_suricata_family function?

The get_suricata_family function in lib/cuckoo/common/suricata_detection.py parses Suricata alert signatures to extract standardized malware family names. During processing (lines 412-416), this function adds a family field to alerts, enabling analysts to identify threat actors and malware strains without manually interpreting raw IDS signatures such as "ETPRO TROJAN MSIL/Revenge-RAT".

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}