Tetragon policies

Ampbase manages Tetragon the same way it manages a telemetry agent: policies are versioned configurations, rollouts are feature flags, and every apply is verified and audited. What is different is the stakes. A Tetragon policy can kill processes, and this page is mostly about the machinery that stands between you and doing that by accident.

If you have not enrolled a host yet, start with Install the supervisor — Tetragon is managed by the same ampbase supervisor as everything else, and needs no separate agent.

Where this runs. Standalone Linux hosts: servers, VMs and bare metal. Kubernetes is not supported yet — there, policies are CRDs and GitOps already distributes them, so the unmanaged segment is the one Ampbase covers first.

Before anything else: the blast radius

Two facts about Tetragon decide the shape of everything below.

A policy that kills is a fleet-wide outage button. Sigkill and Override actions do exactly what they say, on every process that matches, on every host that loads the policy. A selector that is one field too broad does not produce a noisy dashboard; it produces terminated processes. There is no undo for a killed process.

A policy the daemon cannot load takes the daemon down. Tetragon has no partial-load path: if one policy in the set fails to load — an unavailable kernel hook, a BTF mismatch, a construct your kernel does not support — the daemon exits at startup rather than running with a partial policy set. That host is unprotected until a corrected version reaches it. Kernel heterogeneity makes this a live concern rather than a theoretical one: a policy that loads on one host's kernel can fail on another's.

Ampbase mitigates both with the gate and the canary described below. Neither eliminates them. Deploy accordingly.

How policies are authored

Tetragon policies are authored as bundles, not as standalone configurations. A bundle is one deployable unit; each entry is one TracingPolicy document under its own key, and the key becomes the filename the supervisor writes into the managed policy directory.

• One policy document per entry. Tetragon's loader reads only the first YAML document in a file and silently ignores the rest, so Ampbase rejects an entry carrying more than one — dead bytes you believe are live policy are worse than an error.
• The reserved key daemon.conf carries daemon options rather than a policy. It renders to a drop-in in the daemon's config directory.
• Every entry is validated against the pinned upstream policy types before it is stored, and again before it is deployed. A document Ampbase cannot parse never reaches a host, because an unloadable policy is the outage above.

Bundles are the only authoring path for Tetragon: there is no single-config door. See Configurations for versioning and bundle mechanics, which are the same here as everywhere else.

Ampbase is the only writer. The managed daemon configuration pins Kubernetes CRD watching off. Policies loaded by another writer — a kubectl apply, a file dropped on the host — are reported back as externally-loaded rather than silently absorbed, and they are never folded into Ampbase's own rollout state. Two unreconciled writers of kill policies is not a supportable arrangement, so Ampbase does not pretend to support it.

Applying a policy is not free

Every apply reloads policy in the kernel. On the fast path a single changed policy is deleted and re-added over the daemon's local API — sub-second, and scoped to that policy. When that path is unavailable the daemon restarts and reloads its whole directory.

Either way there is a brief window in which the changed policy is not enforcing, and a restart briefly unloads all of them. There is no zero-gap policy edit, and rollback is an apply like any other: it takes effect through the same reload, not instantly.

An apply is only reported healthy once the kernel has accepted the policies — Ampbase polls the daemon's own enumeration and reports per-policy load state, so "the file was written" is never mistaken for "the policy is enforcing". When a policy fails to load, the daemon's own error (bad hook, kernel too old, BTF mismatch) appears on that agent in the fleet view.

The enforcement gate

A version whose policies carry an enforcement action is classified enforcing. Anything else is observe-only, and deploys with no extra friction at all.

Deploying an enforcing version requires two things:

1. A typed confirmation. You type back a phrase naming the actions and hook kinds the version arms — for example enforce sigkill on kprobe. The phrase is derived from the content, so changing the content changes the phrase. Above the input, Ampbase lists every enforcing construct it found: the policy, the action, the exact hook, the path in the document. You should never be typing the phrase without having read that list.
2. A staged rollout. An enforcing version reaches agents through a feature flag with a canary slice, not by being set as the channel default. The first step is capped at a canary-sized share of eligible agents, and widening past it requires the canary to be green: at least one host reporting the version applied, and no host reporting a config-apply error. "No news" is not green.

Both can be lifted only by an org admin holding the enforcement-rollout override, which is meant for incident response — pushing a kill policy against an active compromise cannot wait on a canary. The override never waives the typed confirmation, and every use writes an audit event naming the operator, the version, and the fleet slice it reached. See Feature flags for how canary slices are targeted.

If a classification cannot be made — an action string Ampbase does not recognize, a construct it cannot read — the version is treated as enforcing. Unknown never degrades to observe-only.

Observe first: the graduation path

The safe way to arm a policy is not to arm it. Derive a monitor variant first, let it run, and promote the real thing once you can see what it would have done.

   author the enforcing policy  (Sigkill on some hook)
              │
              │  "Derive the monitor variant"
              ▼
   monitor variant  ── same policies, enforcement suppressed
              │        in the kernel: nothing is killed, but
              │        the daemon still reports what WOULD
              │        have been
              │
              │  roll out through a flag with a canary slice
              ▼
   dry-run evidence accumulates
      "N matches on H hosts; K would have been killed"
              │
              │  promote the enforcing version through the
              ▼  same flag, same canary, same confirmation
   enforcing

The variant is a new version of the same bundle, derived mechanically: every enforcement action is kept, and the policy is put into the daemon's monitor mode. That distinction matters. A variant with the actions stripped out would also be safe — but its events would carry no enforcement action, so it could never tell you what enforcement would have done. Monitor mode keeps the numerator.

Because the actions are still in the document, a monitor variant is still classified enforcing: deploying it goes through the gate, the confirmation, and the canary exactly like the real thing. That is deliberate. Monitor mode is a runtime posture, not a safety property of the content.

The dry-run evidence

When you confirm an enforcing version, Ampbase shows what its monitor variant observed over the last seven days: how many times those policies matched, on how many hosts, how many of those matches would have reached a kill or an override, and roughly how many distinct binaries were involved.

Those numbers are counts and cardinality estimates. Ampbase never receives the underlying events — no binary paths, no arguments, no workload names, no event bodies leave your hosts. The supervisor reduces the daemon's event stream on the host and submits per-policy rollups. If you want the events themselves, they go to your own SIEM, over your own pipe.

That pipe can be one Ampbase manages too. Tetragon writes its events as JSON to /var/log/tetragon/tetragon.log; pair the Tetragon channel with a Fluent Bit or Vector channel whose config tails that file and ships it wherever you send security events. Same supervisor, same host, both agents versioned and rolled out the same way.

Evidence informs the decision; it does not gate it. You can always deploy an enforcing version with no dry-run evidence at all — judgment plus the gate is what graduation rests on when there is none.

Which is why the panel is careful about the difference between a zero and an absence. Each of these is a different sentence, and Ampbase will say which one it means:

An empty panel never means "safe". If Ampbase cannot tell you something, it says so rather than showing you a zero.

Findings are not alerts

Ampbase produces policy-hygiene findings about your Tetragon configuration, alongside the dry-run evidence:

• Dead policy — a policy that matched before and has matched nowhere in the fleet for two weeks, while every agent in the channel was reporting. Stated as either/or, because the data cannot distinguish the two readings: it is a removal candidate (less kernel-hook overhead, smaller audit surface), or it is evidence of a coverage gap.
• Noisy policy — a policy generating disproportionate event volume. Every match is a JSON event your own pipeline ingests and your SIEM bills, so this is a cost and tuning finding.

These ride the same webhook pipeline as every other Recommendation Ledger finding, which makes one distinction worth stating plainly:

A finding is not a detection, and it is not a security alert. A finding is evidence about your configuration — a policy version, its match volume, what enforcement would have done — computed from counts. "This policy would have killed 40 processes" is a statement about a config version you have not deployed yet. It is not a report that something happened on your hosts, and nothing in it should be routed to a security on-call rotation as though it were.

Ampbase is not a SIEM and does not try to be one. Detections are produced by your Tetragon policies, in your event pipeline, on your side of the line.

Every finding carries its evidence: the window it covers, how many hosts reported, how the number was computed, and what it does not cover — a policy whose match volume was measured on partial fleet coverage says so, and its counts are stated as lower bounds. See Telemetry intelligence for how the ledger works.

A workflow that holds

1. Author the policy as a bundle. Deploy it observe-only first; confirm it loads on every kernel in the fleet before you think about enforcement.
2. Add the enforcement actions in a new version. Do not deploy it.
3. Derive the monitor variant and roll that out through a flag with a canary slice, then widen it. Nothing is killed at any point.
4. Let it run. A week is the window the evidence is computed over.
5. Read the dry-run evidence. If it says something you did not expect, your selector is wrong, and you have just learned that for free.
6. Promote the enforcing version through the same flag and the same canary. Watch the canary's apply state before widening.

Step 3 is the one people skip. It is also the only step that can tell you what a policy will do before it does it.