containerguard/containerguard-agent repository overview

The ContainerGuard Agent is the host-based enforcement and observability component of the ContainerGuard security platform. It runs as a privileged container on your Docker or Podman hosts to provide real-time discovery, network segmentation, and threat detection for all other containers running on that host.

More information about ContainerGuard can be found at https://containerguard.net⁠

⁠Features

Real-time Discovery: Automatically detects running containers, images, and metadata. Network Enforcement: Applies Zero Trust firewall policies (allow/deny) directly at the host level using iptables/nftables. Live Observability: Streams container logs, events (start/stop/exec), and resource usage to the ContainerGuard dashboard. File Integrity Monitoring: Detects filesystem changes within containers (requires access to /var/lib/docker). Host Health: Reports CPU, memory, and disk usage for the underlying host.

⁠Prerequisites

Engine: Docker Engine (v20.10+) or Podman. Network: Must have connectivity to your ContainerGuard server. Privileges: Requires NET_ADMIN capability to manage firewall rules and access to the Docker socket.

⁠Quick Start

Run the agent on your host using the following command. Replace http://your-backend-ip:5000⁠ with the actual URL of your ContainerGuard server.

sudo docker run -d \
  --name containerguard-agent \
  --privileged \
  --pid=host \
  --network=host \
  --restart=unless-stopped \
  -e CONTAINERGUARD_API_URL="http://your-containerguard-server:5000" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/containerguard-agent:/var/lib/containerguard \
  -v /:/host:ro \
  -v /var/lib/docker:/var/lib/docker:ro \
  -v /sys/kernel/debug:/sys/kernel/debug:rw \
  -v /sys/kernel/tracing:/sys/kernel/tracing:rw \
  -v /sys/fs/bpf:/sys/fs/bpf:rw \
  -v /var/log/journal:/var/log/journal:ro \
  -v /run/log/journal:/run/log/journal:ro \
  -v /lib/modules:/lib/modules:ro \
  -v /usr/src:/usr/src:ro \
  -v /etc/machine-id:/etc/machine-id:ro \
  containerguard/containerguard-agent:latest

⁠Volume Mounts Explained

• /var/run/docker.sock: Allows the agent to query the Docker API for container discovery and events.
• /var/lib/docker: Read-only access is required for File Integrity Monitoring (tracking changes to container files).
• /var/log/journal & /run/log/journal: Allows the agent to read kernel firewall logs via journald to report blocked/allowed connections.
• /etc/machine-id: Used to generate a stable, persistent ID for the agent.
• /var/lib/containerguard-agent: Keeps the adoption credential and queued telemetry when the container is replaced.
• /sys/kernel/debug and /sys/kernel/tracing and /sys/fs/bpf: Provide the kernel interfaces used by eBPF observability and enforcement.
• /lib/modules and /usr/src: Make host kernel modules and headers available to the agent.
• /: Supply read-only host, filesystem, and logging context for inventory and telemetry.

⁠Environment Variables

⁠Troubleshooting

To view the agent logs:
docker logs -f containerguard-agent

To check the agent's status and connectivity from within the container:
docker exec -it containerguard-agent cg-agent diagnostics run