Malcolm Network Traffic Analysis Suite

repository·main·Indexed 19 days ago

https://github.com/idaholab/malcolm

Malcolm is a containerized network traffic analysis platform that automates the processing of PCAP files, Zeek logs, and Suricata alerts. It provides security visibility through OpenSearch Dashboards and Arkime, featuring GeoIP mapping, hardware manufacturer lookups, asset identification, and JA4 fingerprinting. The suite can be deployed as a dedicated sensor appliance or locally for incident response, including support for building and installing Hedgehog Raspberry Pi images.

Tokens
136.1K
Snippets
307
Records
556
Agent score
63%

What's inside Malcolm

  1. Overview of Malcolm's Network Traffic Analysis

    main

    Malcolm is a network traffic analysis platform that processes packet capture (PCAP) files and Zeek logs. It functions by parsing network session data and enriching it with metadata such as:

    • GeoIP mapping: Geographic location of IP addresses.
    • Hardware manufacturer lookups: Using MAC address OUIs.
    • Asset identification: Assigning names to network segments and hosts based on a user-defined asset inventory.
    • JA4 fingerprinting: Network fingerprinting for identification.

    Enriched data is stored in OpenSearch and is accessible via two primary interfaces:

    1. OpenSearch Dashboards: For flexible data visualization and protocol overviews using prebuilt dashboards.
    2. Arkime: A powerful tool for searching and identifying specific network sessions related to security incidents.

    Malcolm can be deployed as a dedicated sensor appliance or locally on a workstation for processing offline artifacts (Zeek logs, PCAPs) during incident response.

  2. Overview of the Malcolm REST API

    main

    Malcolm provides a REST API to programmatically query Malcolm's status and data. The API includes endpoints for managing and inspecting data, such as dashboard exports, document statistics, lookups, and field aggregations.

    Additionally, Malcolm acts as a proxy, forwarding requests to the APIs of its underlying components via specific URI prefixes.

  3. Overview of Malcolm components

    main

    Malcolm is a comprehensive network analysis platform built upon a collection of open-source tools. Its architecture integrates traffic capture, protocol analysis, metadata indexing, threat detection, and visualization.

    Key functional areas include:

    • Traffic Capture & Analysis: Uses Arkime (for PCAP processing and browsing), Zeek (network analysis framework), and Suricata (IDS/threat detection). For simpler deployments, netsniff-ng or tcpdump can be used.
    • Data Indexing & Search: Primarily uses OpenSearch (or Elasticsearch) for indexing session metadata, with OpenSearch Dashboards (or Kibana) for visualization. Logstash and Filebeat handle Zeek log ingestion.
    • Threat Hunting & File Scanning: Strelka provides container-based file scanning, utilizing tools like Yara, Capa, and ClamAV to identify malware and capabilities.
    • Intelligence & Enrichment: Integrates threat intelligence feeds (MISP, TAXII, Google, Mandiant) via the Zeek intelligence framework and uses NetBox for asset inventory enrichment.
    • Infrastructure & Orchestration: Deployed via Docker or Podman for local use, and Kubernetes (including the Malcolm Helm chart) for distributed or cloud environments.
  4. Overview of Malcolm network traffic analysis

    main

    Malcolm is a network traffic analysis tool suite designed for network security monitoring. It automates the normalization, enrichment, and correlation of network data to provide visibility into communications.

    Key Capabilities:

    • Data Ingestion: Accepts full packet capture (PCAP) files, Zeek logs, and Suricata alerts. Data can be uploaded via a browser-based interface or forwarded live using lightweight forwarders.
    • Analysis Interfaces:
      • OpenSearch Dashboards: Provides data visualization through prebuilt dashboards for protocol overviews.
      • Arkime: Used for deep session identification and investigating suspected security incidents.
    • Deployment Model: Operates as a cluster of software containers, making it suitable for both long-term SOC deployment on Linux servers and portable incident response on devices like MacBooks.
    • Security: All communications (UI and remote log forwarders) use industry-standard encryption.
  5. Overview of Malcolm's capabilities

    main

    Malcolm is a network traffic analysis tool suite designed for network security monitoring. It automates the normalization, enrichment, and correlation of network data to provide visibility into communications.

    Key capabilities include:

    • Data Ingestion: Accepts PCAP files, Zeek logs, and Suricata alerts via a browser-based interface or via lightweight forwarders for live capture.
    • Analysis Interfaces:
      • OpenSearch Dashboards: Provides data visualization and prebuilt dashboards for protocol overviews.
      • Arkime: Used for identifying and investigating specific network sessions during security incidents.
    • Deployment: Operates as a cluster of software containers, making it portable for both long-term SOC deployment on Linux servers or incident response on local machines (e.g., MacBook).
    • Security: Uses industry-standard encryption for all user interface and remote log forwarder communications.
  6. Current limitations of Malcolm Kubernetes deployment

    main

    Deploying Malcolm with Kubernetes is currently an experimental feature and does not support the full range of Malcolm features. Key limitations include:

    • Live Traffic Analysis: Network traffic artifacts must be provided via forwarding from a remote instance of Hedgehog Linux or via PCAP upload. Cloud-native network traffic monitoring is not yet implemented.
    • Horizontal Scaling: Services are currently configured with replicas: 1. Horizontal scaling is under investigation to ensure container compatibility.
    • Deployment Management: Deployment is managed via standard Kubernetes manifests located in the repository's kubernetes/ directory. A Helm chart is not yet available.
  7. Use malcolm-test for Malcolm system testing

    main

    malcolm-test is a Python package designed to perform system tests against a Malcolm system. It works by running an instance of Malcolm inside a virtual machine and verifying the results of the system tests executed against that instance.

    For detailed installation, usage instructions, and additional technical details, refer to the primary repositories:

    • Malcolm-Test: Core testing logic and package functionality.
    • Malcolm-Test-Artifacts: Supporting artifacts for the testing process.
  8. What is Hedgehog Linux?

    main

    Hedgehog Linux is Malcolm's dedicated Network Sensor operating system. It is a Debian-based OS designed to:

    • Monitor network interfaces.
    • Capture packets to PCAP files.
    • Detect file transfers in network traffic and extract/scan them for threats.
    • Generate and forward Zeek logs, Arkime sessions, and other metadata to a Malcolm instance.

    Note on Installation: As of Malcolm v25.12.0, Hedgehog Linux and Malcolm share a single codebase. The Hedgehog Linux installer ISO is a specific "flavor" of the Malcolm installer ISO, preconfigured to use the Hedgehog run profile. Consequently, installation and configuration procedures for both platforms are identical.

  9. Overview of Malcolm repository structure

    main

    The Malcolm source tree contains several key directories and files:

    • api: REST API service.
    • arkime: PCAP processing and Viewer application.
    • config: Environment variable files for configuration.
    • dashboards: Visualization and dashboarding service.
    • Dockerfiles: Build instructions for images.
    • file-upload: Web-based and SFTP upload service.
    • filescan: File scanning service (using Strelka).
    • logstash: Log parsing and forwarding.
    • opensearch: Database instance.
    • pcap-capture: Network traffic capture.
    • scripts: Control scripts (start, stop, etc.).
    • suricata: Suricata PCAP processing.
    • zeek: Zeek PCAP processing.
    • yara: Custom YARA rules.
    • docker-compose-dev.yml: Configuration for development environments.
    • docker-compose.yml: Configuration for packaged installations.
  10. Integrate Zeek logs with Arkime in Malcolm

    main

    Malcolm allows you to analyze Zeek logs using the same interface and processes used for native Arkime sessions. Malcolm maps Zeek log values to the Arkime session database schema and creates new "native" Arkime fields for any Zeek values that do not have an equivalent in Arkime.

    Key fields for distinguishing and filtering Zeek data in OpenSearch:

    • Data Source (event.provider): Use zeek to identify records from Zeek logs (vs arkime for native Arkime sessions).
    • Log Type (event.dataset): Corresponds to the specific Zeek .log file (e.g., conn, weird, dns).

    Example Queries:

    • Restrict to conn.log records: event.provider == zeek && event.dataset == conn
    • Restrict to weird.log records: event.provider == zeek && event.dataset == weird

    Note: While Zeek records appear in the Sessions view like native Arkime sessions, they do not contain full packet contents. Consequently, PCAP-related buttons (viewing/exporting) will not function for Zeek-sourced records.

  11. Run Malcolm with Podman

    main

    Malcolm can run on Podman as a rootless alternative to Docker. The same Malcolm runtime scripts (e.g., ./scripts/start, ./scripts/stop) are used for both.

    Important Considerations:

    • Compose Provider: It is highly recommended to use the docker-compose provider as a wrapper for podman compose rather than the podman-compose package, as the latter has known issues starting Malcolm.
    • Traffic Capture Limitation: If using rootless Podman, Malcolm cannot perform traffic capture on local network interfaces. In this configuration, you must forward network traffic metadata from a network sensor appliance (like Hedgehog) instead.
  12. Use the Malcolm Configuration Menu

    main

    When running the installer, you will first encounter the Malcolm Configuration Menu. This menu is used to set the runtime options for the local Malcolm installation.

    After selecting your desired configuration options, you must select s to Save and Continue to proceed to the installation options menu.

    --- Actions ---
      s. Save and Continue
      w. Where Is...? (search for settings)
      x. Exit Installer
    ---------------------------------
    
    Enter item number or action: s