DOCA Argus Service Guide

This page provides installation, configuration, and usage instructions for the DOCA Argus Service.

Introduction

DOCA Argus is a service that runs on a supported NVIDIA® BlueField® DPU and provides real-time visibility into the attached Linux compute node. It uses hardware-level live machine introspection and NVIDIA DOCA DMA to read selected structures in volatile host memory and derive information about the host and its workloads. Because the service runs on the DPU in a trust domain separate from the host, it does not require a host-resident agent.

DOCA Argus evaluates collected activity with a policy engine and produces events and alerts for security and observability workflows. Its primary use cases include runtime workload threat detection, AI workload discovery, infrastructure mapping, and runtime observability across bare-metal, virtualized, and containerized environments. A single BlueField DPU running DOCA Argus can monitor the compute node to which it is attached.

Operation

DOCA Argus identifies the Linux kernel version running on the monitored host and applies a matching kernel-specific memory map to locate the structures it must inspect. The service supports hosts with x86 and Arm64 CPUs. Using DOCA DMA, it reads selected regions of host memory and decodes the raw data into logical information about processes, threads, execution states, and other system activity.

A policy engine filters the decoded activity and evaluates it against policy rules. Activity that matches one or more rules becomes meaningful activity that the service can report as an event or alert. DOCA Argus reports information about its own operational state as system activity messages.

Monitored Activity and Relationships

DOCA Argus can report the following workload and infrastructure information:

• Processes and threads, including execution state

• Executed binaries and loaded libraries, including SHA-256 hashes

• Execution paths and command-line arguments

• Process-level file access

• Process-level inbound and outbound network connections

• Exposed network services

• Workload type and deployment context, including bare-metal, virtual machine, and container environments

• Relationships among containers, Pods, virtual machines, the host operating system, processes, compute nodes, and GPUs

• Physical GPU attributes, including make, model, and serial number

• Mappings between workloads and physical or virtual GPUs

• Process-to-GPU utilization metrics and other GPU observability data

This information provides the common data foundation for the security, discovery, and observability use cases described below.

Events and Alerts

When raw activity matches one or more policy rules, DOCA Argus treats it as meaningful activity and includes it in one of the following message types:

• Event – One or more meaningful activities that describe the recorded operational state and provide situational awareness.

• Alert – One or more meaningful activities that indicate a threat or operational impact that requires investigation or response.

• System activity – Information about the operational state of the DOCA Argus service.

For details about message formats, local logging, telemetry delivery, and output fields, see the Log Types and Output sections.

Use Cases

DOCA Argus uses the monitored activity and relationships described above to support the following use cases.

Runtime Workload Threat Detection

Containerized AI applications are commonly instantiated from immutable images. Instances created from the same image should therefore exhibit consistent and predictable runtime behavior. DOCA Argus can compare observed activity with established behavioral profiles to identify deviations that may indicate compromise or malicious activity.

Relevant signals include executed binaries and loaded libraries, their associated hashes, execution paths, command-line arguments, process-level file access, and network connections. These signals can help detect integrity violations and suspicious behavior, including unexpected process execution, executed Bash commands, reverse shell activity, and unauthorized process execution.

External security platforms can combine DOCA Argus telemetry, events, and alerts with their own analytics, correlation logic, and threat intelligence.

AI Workload Discovery

DOCA Argus identifies how workloads are deployed and maps their relationships across the monitored compute node. It distinguishes workloads running on bare metal, in virtual machines, or in containers and can report relationships such as container-to-Pod, container-to-virtual-machine, and container-to-operating-system mappings.

DOCA Argus also reports container image hashes. External systems can correlate these hashes with public and private software repositories to help identify deployed AI software, AI models, large language models, and AI agents. DOCA Argus supplies the runtime and image-hash data used for this identification; repository correlation occurs outside the service.

Together with process, compute-node, and GPU relationship data, this information supports a current inventory and map of AI workloads and the infrastructure on which they run.

Runtime Observability

DOCA Argus provides operational visibility into how workloads execute and interact with memory, threads, the network, the file system, CPUs, and GPUs. It reports process-level network connections, file activity, exposed network services, and other runtime context.

For GPU observability, the service reports physical GPU attributes, maps workloads to physical or virtual GPUs, and provides process-to-GPU utilization metrics and related operational data. This information connects workload behavior to the compute and GPU resources used by each workload.

Requirements

• Operates only on BlueField-3 or later configured in DPU mode (see BlueField Modes of Operation).

• Requires firmware version 24.35.0388 or later.

• Supported BlueField image versions: 4.11.0 or later.

• The DOCA Argus service container must run in privileged mode to enable full-system DMA reads.

Limitations

• Tested against KVM-based hypervisors only.

• Supports Linux-based OSs (bare-metal, virtualization, containers).

• Kata Containers are supported only if NVIDIA-DPU support is enabled.

Prerequisites

1. Configure BlueField firmware. On BlueField, configure the PF BAR register:

   dpu> mlxconfig -d /dev/mst/<mst_device> s PF_BAR2_SIZE=2 PF_BAR2_ENABLE=1
   

   Replace <mst_device> with mt41692_pciconf0 for BlueField-3.

2. Enable IOMMU passthrough only if it is not already enabled.

   1. Edit the GRUB configuration:

      host> sudo vim /etc/default/grub
      

   2. Add the following value to GRUB_CMDLINE_LINUX_DEFAULT:

      iommu=pt <intel/amd>_iommu=on
      

   3. Apply the changes:

      • Ubuntu:

        sudo update-grub
        

      • CentOS or RHEL:

        sudo grub2-mkconfig -o /boot/grub2/grub.cfg
        

   4. Reboot the host.

3. Prepare the target system. DOCA Argus automatically generates the required symbol and memory-region configuration at runtime. Complete the remaining steps only if automatic generation fails.

4. For manual profile generation, install the required debug packages on the target:

   • Ubuntu:

     sudo tee /etc/apt/sources.list.d/ddebs.list << EOF
     deb http://ddebs.ubuntu.com/ $(lsb_release -cs) main restricted universe multiverse
     deb http://ddebs.ubuntu.com/ $(lsb_release -cs)-updates main restricted universe multiverse
     deb http://ddebs.ubuntu.com/ $(lsb_release -cs)-proposed main restricted universe multiverse
     EOF
     sudo apt install ubuntu-dbgsym-keyring
     sudo apt-get update
     sudo apt-get install linux-image-$(uname -r)-dbgsym
     

   • CentOS or RHEL:

     sudo yum install --enablerepo=base-debuginfo \
       kernel-devel-$(uname -r) \
       kernel-debuginfo-$(uname -r) \
       kernel-debuginfo-common-$(uname -m)-$(uname -r)
     

5. Make doca_apsh_config.py available on the target using one of the following methods:

   • If DOCA is installed on the target, use /opt/mellanox/doca/tools/doca_apsh_config.py and continue to the next step.

   • Otherwise, copy the script from BlueField:

     scp <bf-user>@<bf-ip>:/opt/mellanox/doca/tools/doca_apsh_config.py /tmp/
     

6. Download a dwarf2json release binary from volatilityfoundation/dwarf2json.

7. Create the JSON files:

   cd /opt/mellanox/doca/tools/
   pip3 install psutil pdbparse
   python3 doca_apsh_config.py --files memregions symbols --os <windows/linux> --path <path-to-dwarf2json>
   cp /opt/mellanox/doca/tools/*.* <shared-folder>
   dpu> scp <shared-folder>/* <path-to-app-shield-binary>
   

Service Deployment

• For DPU container deployment, see the DOCA Container Deployment Guide.

• For Argus-specific deployment, see the service container page.

• For offline deployment, see Offline Deployment in the DOCA Container Deployment Guide.

Service Configuration

Argus configuration is managed through SERVICE_CONFIG_FILE in the container YAML.

Service

• Immediate shutdown – Terminates immediately on SIGINT or SIGTERM and skips graceful shutdown.

• Service log level – Sets DOCA logging verbosity. The default is 50 (INFO). Supported values are 10 (DISABLE), 20 (CRITICAL), 30 (ERROR), 40 (WARNING), 50 (INFO), 60 (DEBUG), and 70 (TRACE).

• System scanner sleep time – Sets the delay between scans. Supported units are s, m, and ms.

DOCA Argus Configuration

• Auto Scan – Scans all available systems unless the systems section is defined.

• Profile generation – Automatically generates the required kernel data at runtime when no prebuilt data is available. Initialization can take longer when profile generation is required.

• Default – Defines configuration values that apply unless overridden under systems.

• Systems – Defines the monitored systems and their overrides.

Per-system Configurations

• Representor ID – Specifies the VU ID of the VF or PF to track.

  • PF:

    host> lspci -vv -s <PF_pci_address> | grep VU | cut -d " " -f 4
    

  • VF – Append VF<x> to the PF VU ID. For example: MT2333XZ06YAMLNXS0D0F0VF1.

• Memory regions path – Specifies a JSON file path, or auto, for the host OS memory map.

• OS symbol path – Specifies a JSON file path or directory, or auto.

• OS type – Specifies Linux or Windows.

• DMA device name – Matches the representor ID. List devices with:

  dpu> ibv_devinfo | grep 'hca_id' | awk '{print $2}'
  

• Service log level – Overrides the service logging verbosity.

• SDK log level – Sets SDK logging verbosity.

• Limits – Sets maximum values for string length, processes, file descriptors, threads, virtual memory areas, and kernel modules.

• Events

  • Container filter – Includes or excludes containerized processes.

  • Container enrichment – Enriches messages from containerized processes with container and Kubernetes Pod metadata. Enabled by default.

  • SBOM – Lists SHA signatures of approved executables and libraries.

Collection

• Events – Enables or disables each event type.

Output

• Log events to stdout – Enables logging to standard output.

• Log folder path – Specifies the directory for file logs.

• Log threshold size – Rotates logs when they reach this size.

• Log max files count – Sets the maximum number of rotated log files.

• Telemetry address – Specifies the aggregator address.

• Telemetry tag – Specifies the tag used by Fluent Bit.

• Telemetry format – Specifies JSON or syslog.

• Telemetry user data – Specifies custom metadata to include in telemetry records.

Log Types

Standard Output

Displays important service messages, including version information, successful startups, and startup failures.

Debug Log Output

Provides complete debug output, including partial event data, trace logs, and collection failures. These logs are stored in /var/log/doca_argus/.

Event Log Output

Stores the complete event log in JSON format in the configured log folder. For local storage, Linux logrotate manages log rotation. You can override the default configuration in /etc/cron.d/logrotate and /etc/logrotate.d/argus.

Telemetry Output

DOCA Argus can produce telemetry records in JSON or syslog format.

Telemetry is disabled by default. To enable it, set telemetry_address in the service configuration and ensure that telemetry_tag matches the tag in the telemetry pipeline configuration.

Fluent Bit

The DOCA Argus container page provides YAML configuration examples for Fluent Bit and Vector. Use the applicable YAML file as the starting point for your telemetry deployment.

Fluent Bit runs independently from the DOCA Argus service. To run Fluent Bit locally on the DPU, use an input configuration similar to the following:

[INPUT]
    Name                  tcp
    Tag                   <your_preferred_tag>
    Listen                0.0.0.0
    Port                  24224
    Format                json

For Splunk, add the following encapsulation filter:

[FILTER]
    Name                  nest
    Match                 *
    Operation             nest
    Wildcard              *
    Nest_under            event

The following example forwards telemetry to Elasticsearch:

[INPUT]
    Name                  tcp
    Tag                   elastic_forward_input
    Listen                0.0.0.0
    Port                  24224
    Format                json

[SERVICE]
    Log_Level             info

[OUTPUT]
    Name                  es
    Match                 *
    Host                  <elasticsearch_ip>
    Port                  <elasticsearch_port>
    Index                 argus
    Suppress_Type_Name    On
    Log_Level             info

Run Fluent Bit with the configuration:

docker run --rm --net=host -v <path_to_fluentbit_conf_file>:/fluent-bit/etc/fluent-bit.conf --name fluent_bit -it fluent/fluent-bit

For additional output plugins, see the Fluent Bit manual.

Vector

Vector is an observability data pipeline that can receive DOCA Argus telemetry over TCP, decode JSON records, and forward them to supported destinations such as Elasticsearch. Vector can run independently from the DOCA Argus service or as a sidecar container in the same Kubernetes Pod.

Set telemetry_address to the Vector listener address, such as 127.0.0.1:24224, and set telemetry_format to json. The following configuration receives JSON telemetry and forwards it to Elasticsearch:

data_dir: /vector-data-dir

sources:
  tcp_json_in:
    type: socket
    mode: tcp
    address: "127.0.0.1:24224"
    decoding:
      codec: json

sinks:
  elasticsearch_out:
    type: elasticsearch
    inputs: ["tcp_json_in"]
    endpoints:
      - "http://<elasticsearch_ip>:<elasticsearch_port>"
    bulk:
      index: "argus"

Start Vector with the configuration file:

vector --config /etc/vector/vector.yaml

For Kubernetes deployments, Vector can run alongside the DOCA Argus container and share a configuration volume. DOCA Argus sends telemetry to 127.0.0.1:24224, and Vector listens on the same Pod network and forwards records to the configured sink.

containers:
  - name: vector
    image: timberio/vector:0.43.1-alpine
    imagePullPolicy: IfNotPresent
    args: ["--config", "/etc/vector/vector.yaml"]
    volumeMounts:
      - mountPath: /etc/vector
        name: conf-vector-config

Ensure that the Vector configuration volume is populated before the Vector container starts. For additional source, transform, and sink options, see the Vector documentation.

Reported Activities

Naming Conventions

The message schema uses the following naming conventions:

• Parameter names use lowercase letters.

• Names are explicit.

• Underscores (_) separate words.

• Parameter names for measurements include the unit, such as average_packet_size_bytes.

• Enum values use uppercase letters and begin with a letter.

• Path values use Linux forward slashes (/) to avoid escaping. For example: /Users/askywalker.

• Timestamps use ISO 8601 format: YYYY-MM-DDTHH:MM:SS.nnnnnnnnn.

• Empty fields use null.

Message Type

Raw activities are collected from host memory and used to describe the operational state of a workload. The policy engine filters irrelevant raw activity and reports meaningful data. A raw activity that matches one or more policy rules can be reported as an event or alert.

• Event – One or more meaningful activities that describe the recorded state and provide situational awareness.

• Alert – One or more meaningful activities that indicate a threat or impact requiring investigation or response.

• System activity – Information about the operational state of the DOCA Argus service.

Message Structure

Every reported activity includes common message metadata, BlueField system information, workload information, and activity-specific data.

Schema

Example JSON Message

The following example illustrates the common message structure. Activity-specific fields vary by activity name.

{
  "vendor_name": "NVIDIA",
  "product_name": "DOCA_ARGUS",
  "product_version": "<version>",
  "message_type": "<EVENT | ALERT | SYSTEM_ACTIVITY>",
  "severity": "<INFO | ERROR | WARNING | MEDIUM | HIGH | CRITICAL>",
  "schema_version": "1.0",
  "message_id": "<unique_message_id>",
  "occurred_message_time_iso_8601_ns": "2024-10-31T17:20:10.123456789+02:00",
  "message_timezone": "UTC",
  "user_data": "<string>",
  "bluefield_system_information": {
    "bluefield_networking_interfaces": []
  },
  "workload_information": {
    "unique_identifier": "<identifier>",
    "os_version": "Linux kernel <version>",
    "boot_uuid": "<uuid>",
    "hostname": "<hostname>",
    "workload_networking_interfaces": [],
    "container_context": {
      "container_id": "<container_id>",
      "container_name": "<container_name>",
      "image_name": "<image_name>",
      "image_digest": "sha256:<digest>",
      "image_manifest_digest": "sha256:<digest>",
      "pod_name": "<pod_name>",
      "pod_uid": "<pod_uid>",
      "pod_ip_address": "<pod_ip_address>",
      "enrichment_status": "<complete | partial>"
    }
  },
  "activity_data": {
    "name": "<activity_name>",
    "<activity_details>": {}
  }
}

Alerts, Events, and System Activity Messages

This section is the reference for the messages that DOCA Argus can generate. The activity name is the literal value reported in activity_data.name. For definitions of the data objects included with each message, see Activity Data Reference.

Events and Alerts

Bash Shell

Only the bash shell is supported.

Containers

When container enrichment is enabled, container and Kubernetes metadata is reported in workload_information.container_context. See Message Structure.

File Descriptors

GPU Telemetry

Kernel Modules

Network Connections

Process Memory

Processes

Runtime Manifest

Threads

System Activity Messages

The following messages use the SYSTEM_ACTIVITY message type and report the operational state of the DOCA Argus service.

Service Lifecycle

Host Initialization and OS Discovery

OS Profile Processing

Resource Limits

Configuration and Data Collection

Activity Data Reference

The activity_data object contains information specific to the reported event, alert, or system activity. The fields included in a message depend on its activity name. See Alerts, Events, and System Activity Messages for the data objects associated with each message.

Bash Shell Command Data

Object: shell_command_details

Container Context

Container and Kubernetes metadata is reported in workload_information.container_context, not in a separate activity-data object. See Message Structure.

File Descriptor Data

Object: file_descriptor_details

GPU Telemetry Data

Field-level definitions for GPU telemetry messages are not currently documented in this section.

Kernel Module Data

Object: kernel_module_details

Network Connection Data

Object: network_connection_details

Process Data

Object: process_details

Process Memory Data

Object: process_memory_details

Runtime Manifest Data

Object: process_attestation_details

Expected Behavior Data

Object: expected_behavior

The following fields are included with Binary Executed Not as Intended, Foreign Binary Executed File Size Mismatch, and Foreign Library Loaded File Size Mismatch alerts.

Thread Data

Object: thread_details

Last updated: September 01, 2026