# How CAPEv2 Integrates with Suricata for Comprehensive Network Traffic Analysis

> Discover how CAPEv2 integrates with Suricata for advanced network traffic analysis. Learn how it captures, parses, and exposes IDS data for better threat detection.

- Repository: [Kevin O'Reilly/capev2](https://github.com/kevoreilly/capev2)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/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.

```python

# 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`](https://github.com/kevoreilly/capev2/blob/main/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.

```python

# 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`](https://github.com/kevoreilly/capev2/blob/main/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.

```python
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`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/modules/processing/suricata.py) component parses [`eve.json`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/modules/processing/suricata.py) reads the [`eve.json`](https://github.com/kevoreilly/capev2/blob/main/eve.json) file from this location.

### How does CAPEv2 distinguish between different network event types?

The processing module in [`modules/processing/suricata.py`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/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`](https://github.com/kevoreilly/capev2/blob/main/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".