Tetragon eBPF Runtime Security on AWS User Guide

Overview

This guide covers the deployment and use of Tetragon on AWS using cloudimg AWS Marketplace AMIs. Tetragon is Cilium's open source, eBPF-based runtime security observability and enforcement engine. It observes what actually happens on a host - process execution, file access and privileged system calls - directly from the Linux kernel using eBPF, with rich process context and negligible overhead.

Tetragon is usually run on Kubernetes, but it also runs standalone on a single host as a systemd service watching that host's kernel - and that is the appliance this image ships. You get kernel-level runtime security on one Linux instance without needing Kubernetes.

The cloudimg image ships Tetragon 1.7.0 (Apache-2.0 userspace with GPL-2.0 eBPF programs), installed from the official upstream release tarball verified against the project's published SHA256 checksum, and run as a standard systemd service. It is hardened out of the box: the gRPC control interface is a loopback-only unix socket, the health port is pinned to loopback and additionally guarded by an nftables rule, metrics and profiling endpoints are disabled, and there is no default credential of any kind. A default TracingPolicy set makes the appliance emit meaningful security events immediately, and a bundled self-test proves end to end that a monitored action produces the matching event. Backed by 24/7 cloudimg support.

Tetragon and Cilium are trademarks of their respective owners. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by the Cilium project or the Cloud Native Computing Foundation. It ships the free and open source software, unmodified.

What is included:

• Tetragon 1.7.0 (the daemon, the tetra CLI and the eBPF object library), installed from the checksum-verified upstream release as tetragon.service
• A default TracingPolicy set (file-monitoring and privileged-syscalls) that monitors reads of sensitive files, writes to system directories and setuid privileged syscalls, on top of Tetragon's always-on process execution and exit events
• Structured JSON event export to /var/log/tetragon/tetragon.log, ready for a log shipper, SIEM or CI to consume
• A hardened, loopback-only gRPC control socket and a health port pinned to loopback and guarded by an nftables rule (tetragon-firewall.service)
• A bounded self-test (tetragon-selftest) that triggers a monitored action and confirms the matching event is produced
• tetragon.service, tetragon-firewall.service and tetragon-firstboot.service as systemd units, enabled and active on boot
• No default login and no shipped secret: Tetragon has no web UI, API password or admin account, so nothing needs to be rotated and nothing is baked into the image
• Ubuntu 24.04 LTS base with the latest security patches applied at build time, booting the current HWE kernel so the eBPF programs load against the same kernel a fresh instance runs
• 24/7 cloudimg support

Prerequisites

• An active AWS account and an EC2 key pair in your target region
• A subscription to the Tetragon listing on AWS Marketplace
• A VPC and subnet, and a security group allowing inbound 22/tcp (SSH, from your admin network). Tetragon opens no other port - the control and health interfaces are loopback-only.

Recommended instance type: m5.large (2 vCPU, 8 GB RAM) is a sensible starting point. Tetragon's overhead is low, so a general-purpose instance is ample; size to match the workload of the host you are monitoring.

Connecting to your instance

This listing offers one or more operating-system variants. Connect over SSH as that variant's default login user, using your EC2 key pair:

Step 1: Subscribe and launch from AWS Marketplace

Sign in to the AWS Marketplace, search for Tetragon by cloudimg, and choose Continue to Subscribe, then Continue to Configuration and Continue to Launch. Pick your region, the m5.large instance type, your VPC and subnet, your EC2 key pair, and a security group that allows SSH (22) from your admin network. Launch the instance.

Step 2: Launch from the AWS CLI

You can also launch the AMI directly. Resolve the product AMI id for your region from the listing, then:

REGION="us-east-1"
AMI_ID="<ami-id>"          # the Tetragon AMI id for your region
KEY_NAME="your-key"
SG_ID="sg-xxxxxxxx"         # allows 22 from <your-mgmt-cidr>
SUBNET_ID="subnet-xxxxxxxx"
aws ec2 run-instances --region "$REGION" \
  --image-id "$AMI_ID" --instance-type m5.large \
  --key-name "$KEY_NAME" --security-group-ids "$SG_ID" --subnet-id "$SUBNET_ID" \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=tetragon}]'

Tetragon starts on boot and begins watching the host kernel with no extra configuration.

Step 3: Connect to your instance

ssh -i your-key.pem ubuntu@<public-ip>

Step 4: Confirm Tetragon is running

Tetragon runs as tetragon.service, with the nftables health-port guard (tetragon-firewall.service) and the first-boot provisioning unit (tetragon-firstboot.service). Confirm all three are active:

sudo systemctl is-active tetragon tetragon-firewall tetragon-firstboot

Expected output:

active
active
active

Step 5: Confirm the version and the default policies

Check the installed version and list the loaded TracingPolicies. The gRPC control interface is a loopback-only unix socket, so the tetra CLI addresses it with --server-address:

tetra version
sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock tracingpolicy list

Expected output (the two default policies are enabled):

CLI version: v1.7.0
ID  NAME                 STATE    SENSORS         MODE          NPOST
2   file-monitoring      enabled  generic_kprobe  monitor_only  172
3   privileged-syscalls  enabled  generic_kprobe  monitor_only  4

Step 6: Prove it works end to end

Do not take "the service is running" on faith. The image ships a bounded self-test that triggers a monitored action on this host - a read of /etc/shadow - and confirms Tetragon produces the matching security_file_permission event. Run it:

sudo tetragon-selftest

Expected output:

Tetragon self-test: proving a monitored action produces an event...
default TracingPolicy 'file-monitoring' is loaded
PASS: Tetragon observed the read of /etc/shadow. Matching event:
{"process_kprobe": ... "function_name":"security_file_permission" ... "policy_name":"file-monitoring"}

A PASS proves the eBPF programs loaded against the running kernel, the default policy attached, and the event export is working - a real end-to-end check, not a version string.

Step 7: Read live security events

Stream events as they happen from the loopback gRPC socket. In one shell, start the stream; in another, run a command Tetragon watches (for example cat /etc/shadow) and watch the events appear:

$ sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock getevents -o compact
* process ip-10-0-1-20 /usr/bin/cat /etc/shadow
* read    ip-10-0-1-20 /usr/bin/cat /etc/shadow
* exit    ip-10-0-1-20 /usr/bin/cat /etc/shadow 0

The full structured JSON for every event is also written to /var/log/tetragon/tetragon.log, which is the durable record your log shipper or SIEM consumes.

Step 8: The default monitoring policies

Two TracingPolicies ship enabled, under /etc/tetragon/tetragon.tp.d/:

• file-monitoring - reports reads of sensitive credential and authentication files (/etc/shadow, /etc/gshadow, /etc/sudoers, /etc/pam.d, /root/.ssh, /boot) and writes to system binary and configuration directories (/etc, /bin, /sbin, /usr/bin, /usr/local/bin, and more).
• privileged-syscalls - reports use of the setuid privileged syscall, so privilege changes on the host are visible.

Both run in monitor_only mode - they observe and report but do not block. Tetragon can also enforce (kill or override) when a policy matches; extend the shipped policies with enforcement selectors when you are ready.

Step 9: Add your own TracingPolicy

Tetragon reads every *.yaml file in /etc/tetragon/tetragon.tp.d/. Drop in your own policy and restart the service to load it. For example, a policy that watches writes under /var/www:

apiVersion: cilium.io/v1alpha1
kind: TracingPolicy
metadata:
  name: "watch-webroot-writes"
spec:
  kprobes:
  - call: "security_file_permission"
    syscall: false
    return: true
    args:
    - index: 0
      type: "file"
    - index: 1
      type: "int"
    returnArg:
      index: 0
      type: "int"
    selectors:
    - matchArgs:
      - index: 0
        operator: "Prefix"
        values: [ "/var/www" ]
      - index: 1
        operator: "Equal"
        values: [ "2" ]   # MAY_WRITE

Then load it and confirm it is listed (these commands modify the running configuration, so they are shown for reference rather than run automatically):

sudo cp watch-webroot-writes.yaml /etc/tetragon/tetragon.tp.d/
sudo systemctl restart tetragon
sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock tracingpolicy list

Step 10: Ship events to a SIEM or log pipeline

The JSON export at /var/log/tetragon/tetragon.log is a standard newline-delimited JSON file. Point your existing agent at it - for example a Fluent Bit or Vector tail input, the CloudWatch agent, or a Filebeat prospector - and forward it to your SIEM. Each line is a complete event with full process ancestry, so no extra enrichment is needed:

# Example Fluent Bit input (reference)
[INPUT]
    Name   tail
    Path   /var/log/tetragon/tetragon.log
    Tag    tetragon
    Parser json

Security model

Tetragon runs arbitrary eBPF programs in the kernel and exposes a control interface, so the appliance locks that surface down:

• The gRPC control interface is a loopback-only unix socket (unix:///var/run/tetragon/tetragon.sock) - it is never reachable over the network.
• The gRPC health server is pinned to localhost:6789 and an nftables guard (tetragon-firewall.service, table inet tetragon_guard) drops tcp/6789 from anywhere except loopback, so it cannot be reached off-box even if the bind address were changed.
• Metrics, gops and pprof endpoints are disabled.
• SSH is the only open port. Confirm the listener set - only sshd should listen off the loopback interface:

sudo ss -tlnp

• The image ships no credential of any kind - there is no web UI, API password or admin account. Per-instance uniqueness comes from the SSH host keys regenerated on first boot, not from any baked secret.

Managing the service

The following commands manage Tetragon (shown for reference; the restart and stop commands change the running state):

sudo systemctl status tetragon          # detailed status
sudo systemctl restart tetragon         # reload after changing config or policies
sudo journalctl -u tetragon -f          # follow the daemon log

File locations

Troubleshooting

tetra cannot reach the daemon

The control socket is loopback-only and owned by root. Always address it as root with the explicit socket path: sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock <command>. Confirm the daemon is up with sudo systemctl status tetragon.

No events appear on the stream

Events are produced by activity. Generate some (for example cat /etc/shadow or start a process) and they will appear immediately on the getevents stream. The buffered JSON file export at /var/log/tetragon/tetragon.log flushes on volume, so on a very quiet host it lags the live stream - use getevents for immediate feedback and the log file for durable records.

A policy does not load after I add it

Check the YAML is valid and restart the service (sudo systemctl restart tetragon), then run sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock tracingpolicy list and confirm the new policy is enabled and not in an error state.

Support

cloudimg provides 24/7 technical support for this product by email and live chat. Our engineers help with deployment, writing and tuning TracingPolicies, shipping events to your SIEM, and scaling.

• Email: support@cloudimg.co.uk
• Live chat: available 24/7

Tetragon is open source software (Apache-2.0, with GPL-2.0 eBPF programs). This image is produced by cloudimg and is not affiliated with or endorsed by the Cilium project or the Cloud Native Computing Foundation.