gVisor Support in the Upwind Agent

Overview

gVisor is a security-focused container runtime that provides enhanced isolation between applications and the host operating system. Unlike traditional container runtimes that rely on kernel namespaces and cgroups, gVisor implements a userspace kernel that acts as a "sandbox" for containers. This approach significantly reduces the attack surface and minimizes the potential impact of vulnerabilities, offering an additional layer of defense for sensitive workloads.

How gVisor Integration Works

The Upwind Agent integrates with gVisor's built-in tracing capabilities to monitor containerized applications running in gVisor sandboxes. gVisor provides support for streaming application actions (trace points) to external processes for validation and anomaly detection.

Architecture

When gVisor is enabled:

1. gVisor Sentry Kernel: Intercepts selected syscalls from the application
2. Trace Points: Available for all syscalls and important events (e.g., container start)
3. Unix Domain Socket: gVisor sends trace events to the Upwind Agent via a Unix domain socket using protobuf
4. Event Translation: The Upwind Agent translates gVisor payloads to existing event structures (e.g., ProcessEventEntry) and processes them alongside eBPF events

Unlike standard deployments where eBPF monitors syscalls directly from the kernel, gVisor-enabled deployments receive filtered syscalls from gVisor's userspace kernel, providing an additional security boundary.

Prerequisites

• gVisor runtime installed and configured in your container environment
• containerd as the container runtime. The Helm chart only mounts the gVisor root together with containerd, so gvisor.enabled fails validation when containerd.enabled is false.
• The standard Sensor build. There is no BCC build of the gVisor image, so gvisor.enabled fails validation when agent.bcc.enabled is true.
• Proper file permissions for Unix domain socket communication

Using gVisor-Enabled Agent Images

The Upwind Agent images with gVisor support use special tags with a -gvisor suffix to indicate that they include the necessary gVisor dependencies.

When you set gvisor.enabled to true, the Helm chart appends -gvisor to the agent image tag for you, so you don't need to change the image. This also applies when you pin image.tag, unless the tag already ends in -gvisor.

For example, the sensor then runs registry.upwind.io/images/agent:<VERSION>-gvisor instead of registry.upwind.io/images/agent:<VERSION>.

Configuration

Enabling gVisor in the Upwind Agent

To enable gVisor support, configure the following options:

--gvisor-tracing=true
--gvisor-root=/run/containerd/runsc/k8s.io/
--gvisor-trace-uds-path=/var/lib/containerd/gvisor_events.sock
--gvisor-trace-config=/etc/gvisor/session.json
--gvisor-remote-tracing-port=-1

Note: The default value for --gvisor-tracing is false. All other values shown are defaults.

Environment-Specific Settings

• Kubernetes: Use the default --gvisor-root=/run/containerd/runsc/k8s.io/
• Docker: Set --gvisor-root=/var/run/docker/runtime-runc/moby
• Remote Tracing: Use --gvisor-remote-tracing-port to send trace events via TCP instead of Unix domain socket (useful when UDS path cannot be mounted)

Helm Chart Configuration

When deploying via Helm, use the following values. With the Upwind Operator chart, nest them under agent.values, for example agent.values.gvisor.enabled.

Key	Type	Default	Description
gvisor.enabled	bool	false	Whether to enable gVisor integration
gvisor.remoteTracePort	int	-1	Port for gVisor remote tracing (optional)
gvisor.root	string	/run/containerd/runsc/k8s.io/	Path to the gVisor root on the host
gvisor.traceConfig	string	/etc/gvisor/session.json	Path to the gVisor trace config
gvisor.traceSession	string	""	Custom trace session JSON that replaces the session bundled with the chart. Pass it with --set-file
gvisor.traceUdsPath	string	/var/lib/containerd/gvisor_events.sock	Path to the gVisor socket. Must be under a path the sensor mounts from the host, such as containerd.root, gvisor.root or an extraVolumes.sensorMounts path

Automatic Trace Registration

The Upwind Agent automatically monitors the gVisor root directory for new sandboxed containers. When a new container is detected:

1. The agent registers a file watcher on the gVisor root directory
2. Upon container creation, it detects the new runsc sandbox socket
3. Tracing is automatically registered based on the provided session.json configuration

Manual Trace Configuration

To manually enable tracing for a gVisor container:

sudo runsc --root /var/run/docker/runtime-runc/moby trace create --config session.json ${CONTAINER_ID}

For Kubernetes environments, use /run/containerd/runsc/k8s.io as the root path.

Trace Session Configuration

The session.json file configures which events to send to the Upwind Agent. The Helm chart bundles a default session, mounts it at /etc/gvisor/session.json in the sensor container, and sets its sink endpoint to gvisor.traceUdsPath. To replace it, pass your own file with --set-file agent.values.gvisor.traceSession=session.json (or gvisor.traceSession when you install the agent chart directly). A custom file is not templated, so its endpoint must match gvisor.traceUdsPath.

Example configuration:

{
  "trace_session": {
    "name": "Default",
    "points": [
      {
        "name": "sentry/clone"
      },
      {
        "name": "sentry/execve",
        "context_fields": [
          "time",
          "group_id",
          "process_name",
          "container_id",
          "credentials"
        ]
      },
      {
        "name": "syscall/execve/enter",
        "context_fields": ["group_id", "process_name"]
      }
    ],
    "sinks": [
      {
        "name": "remote",
        "config": {
          "endpoint": "/var/lib/containerd/gvisor_events.sock"
        }
      }
    ]
  }
}

Available Context Fields

• time
• thread_id
• task_start_time
• group_id
• thread_group_id
• thread_group_start_time
• container_id
• credentials
• cwd
• process_name

Important: The endpoint in the remote sink section must correspond to the --gvisor-trace-uds-path option in the Upwind Agent.

Benefits

• Enhanced Security: Additional isolation layer between applications and host kernel
• Reduced Attack Surface: Userspace kernel limits potential exploit vectors
• Seamless Integration: Works alongside existing eBPF monitoring
• Automatic Detection: Monitors and registers new gVisor containers automatically
• Unified Event Processing: gVisor events are processed through the same pipeline as eBPF events

Additional Notes

• Ensure you have a valid trace session configuration file
• The Upwind Agent must have appropriate file permissions to access the Unix domain socket
• gVisor integration works alongside existing eBPF-based monitoring