CAPEv2 Reporting Formats: Complete Guide to JSON, MAEC, HTML, and PDF Output

CAPEv2 generates eight distinct reporting formats—from raw JSON dumps and standardized MAEC bundles to interactive HTML pages and printable PDFs—each implemented as a specialized module in modules/reporting/ that processes the analysis dictionary through the inherited run(self, results) method.

The open-source malware analysis sandbox CAPEv2 (kevoreilly/capev2) provides flexible CAPEv2 reporting formats to support diverse downstream workflows, from threat intelligence platforms requiring standardized schemas to analysts needing visual reports. Each format is implemented as a Python class inheriting from lib.cuckoo.common.abstracts.Report, writing output to storage/<task_id>/reports/ after processing completes.

Understanding the CAPEv2 Reporting Architecture

All reporting modules follow a consistent pattern defined in the abstract base class. When an analysis finishes, the processing pipeline invokes run(self, results) on each enabled reporter, passing the complete results dictionary. Individual modules extract relevant subsets and serialize them to their target format.

The configuration file conf/reporting.conf controls which formats are active. Each section corresponds to a module in modules/reporting/, such as [jsondump], [maec5], or [reporthtml].

Machine-Readable CAPEv2 Reporting Formats for Automation

For integration with security orchestration platforms and automated pipelines, CAPEv2 offers both schema-strict and schema-free JSON outputs.

JSON Dump: Raw Python Dictionary Export

The JSON dump format (modules/reporting/jsondump.py) performs a direct UTF-8 serialization of the internal results dictionary. It offers no schema enforcement, making it ideal for custom scripts that consume CAPEv2 data directly.

Key characteristics:

• Optional acceleration: Uses orjson library if available; falls back to standard json module
• Compression support: Configurable via store_compressed = yes in reporting.conf
• File location: storage/<task_id>/reports/report.json

MAEC 4.1: Legacy STIX/MAEC Interoperability

The MAEC 4.1 format produces MAEC 4.1 Bundle XML (or JSON via the maec library) designed for threat-sharing platforms using older STIX/MAEC specifications. Implementation resides in modules/reporting/maec41.py.

Requirements and features:

• Dependencies: Requires maec>=4.1.0, mixbox, and cybox Python packages
• Mapping: Converts Cuckoo API calls to MAEC actions using the internal api_call_mappings dictionary
• Object deduplication: Optionally deduplicates CybOX objects to reduce bundle size
• Output: report_maec41.xml or JSON variant

MAEC 5.0: Modern Standardized Bundles

The MAEC 5.0 format (modules/reporting/maec5.py) generates MAEC 5.0 JSON bundles using updated vocabularies and more granular objects. This is the preferred format for modern threat intelligence exchanges.

Key differences from MAEC 4.1:

• Schema version: Implements MAEC 5.0 specification with improved object granularity
• JSON native: Outputs .json files directly without XML conversion overhead
• Dependencies: Requires maec 5.0 alongside mixbox and cybox

Human-Readable CAPEv2 Reporting Formats for Analysis

Security analysts reviewing individual samples require rich, navigable interfaces that surface screenshots, behavioral summaries, and API call logs.

Full HTML Report: Interactive Visual Analysis

The HTML report module (modules/reporting/reporthtml.py) generates a rich, single-page HTML document using Jinja2 templating. The template resides at data/html/report.html and includes:

• Embedded media: Screenshots base64-encoded directly into the HTML
• Custom filters: Registers template filters like flare_capa_* and malware_config for processing indicators
• Complete logs: Full API call traces and behavioral data

Configuration requires enabled = yes under [reporthtml] in reporting.conf and the Jinja2 package installed.

HTML Summary and PDF Generation

For lighter weight distribution, CAPEv2 provides HTML summary, which uses the same ReportHTML class but sets summary_report = True. This omits heavy sections like complete API logs while retaining behavioral overviews and screenshots.

The PDF report format leverages the HTML summary, invoking wkhtmltopdf to render a portable document. This requires:

• reporthtmlsummary enabled in configuration
• The wkhtmltopdf executable installed on the system
• Output written to report.pdf in the task reports directory

Specialized CAPEv2 Reporting Formats

Beyond standard JSON and HTML outputs, CAPEv2 supports minimal text reports and visual graphing.

Lite Report: Configurable Text Output

The Lite report module (modules/reporting/litereport.py) generates a plain-text or markdown-style summary containing only specific keys defined in the keys_to_copy configuration list. This format incurs minimal overhead by deliberately excluding screenshots, memory dumps, and heavy behavioral objects.

Ideal for:

• Low-resource environments
• Quick automated triage requiring only filenames, hashes, and scores
• Integration with log aggregation systems

BinGraph: Visual Process Analysis

The BinGraph module (modules/reporting/bingraph.py) creates graphical network representations of process trees and API call relationships, outputting PNG or SVG files. This requires Graphviz or tkinter dependencies installed on the analysis host.

Configuring CAPEv2 Reporting Formats

Enable and customize formats by editing conf/reporting.conf. Each format has a dedicated section with an enabled flag and format-specific options.

Example configuration enabling MAEC 5.0 and full HTML:

[maec5]
enabled = yes

[reporthtml]
enabled = yes
screenshots = yes
apicalls = no

After modifying the configuration, restart the CAPEv2 web interface or processing workers for changes to take effect.

Working with CAPEv2 Reports: Practical Examples

Submit a sample and locate generated reports:

# Submit via API

curl -X POST -F "file=@sample.exe" http://localhost:8000/api/submit/

# Locate reports for task ID 42

ls storage/42/reports/

# report.json        (JSON dump)

# report.html        (HTML report)

# report_maec5.json  (MAEC 5.0)

# report.pdf         (PDF summary)

Parse the JSON dump programmatically:

import json

with open('storage/42/reports/report.json') as f:
    results = json.load(f)
print(results['target']['file']['sha256'])

Load a MAEC 5.0 bundle:

from maec.bundle import Bundle

bundle = Bundle.from_json_file('storage/42/reports/report_maec5.json')
for subject in bundle.malware_subjects:
    print(f"{subject.id}: {subject.title}")

Summary

• CAPEv2 reporting formats include JSON dump, MAEC 4.1/5.0, HTML (full/summary), PDF, Lite text, and BinGraph visualizations
• All formats inherit from lib.cuckoo.common.abstracts.Report and implement run(self, results) to process the analysis dictionary
• JSON dump (modules/reporting/jsondump.py) provides raw, schema-free output ideal for custom pipelines
• MAEC 5.0 (modules/reporting/maec5.py) offers standardized JSON bundles for modern threat intelligence platforms
• HTML reports (modules/reporting/reporthtml.py) generate interactive Jinja2-based pages with embedded screenshots
• PDF generation depends on HTML summary output and requires wkhtmltopdf installation
• Lite report (modules/reporting/litereport.py) produces minimal text for low-overhead scenarios
• Configuration occurs in conf/reporting.conf with individual enable flags per format

Frequently Asked Questions

What is the difference between MAEC 4.1 and MAEC 5.0 in CAPEv2?

MAEC 4.1 produces bundles following the older specification, typically outputting XML format for legacy STIX/MAEC interoperability, while MAEC 5.0 uses updated JSON vocabularies with more granular objects. According to the source code in modules/reporting/maec5.py, MAEC 5.0 is preferred for modern threat exchanges, though both require the maec, mixbox, and cybox Python libraries.

How do I enable PDF reporting in CAPEv2?

PDF generation requires enabling both reporthtmlsummary and reportpdf in reporting.conf. The ReportHTML class handles PDF conversion internally by invoking wkhtmltopdf on the HTML summary after generation. You must install the wkhtmltopdf binary separately on your analysis host.

Which CAPEv2 reporting format is best for automated scripting?

The JSON dump format (jsondump) is optimal for automation because it serializes the raw Python dictionary without schema constraints, allowing direct ingestion by Python scripts using the standard json library. For standardized exchange with threat intelligence platforms, use MAEC 5.0 instead.

Can I reduce HTML report size for quicker generation?

Yes, enable reporthtmlsummary instead of reporthtml. This sets the summary_report flag to True in the same ReportHTML class, omitting heavy sections like full API call logs while retaining behavioral overviews and screenshots. Alternatively, use litereport for plain-text output with only configurable key fields.

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