Tamper Detection and Enforcement

Control Zero includes a tamper detection pipeline that protects the integrity of policies, audit logs, and configuration from the moment they are created to the moment they are evaluated on each machine. This page explains how the pipeline works, the four enforcement modes, and how to recover when a tamper event fires.

How the pipeline works

Tamper detection operates at three layers:

1. Policy bundle signing

Every policy bundle published by the backend is cryptographically signed before it leaves the server. The signing key is generated per-org (lazily on first enrollment) and the corresponding public key is distributed to every enrolled machine during the enrollment handshake.

When the SDK pulls a policy bundle, it verifies the signature against the org's public key before loading any rules. If verification fails, the SDK treats the bundle as tampered and follows the org's configured tamper_behavior.

2. Audit log hash chain

Each audit log entry includes a hash of the previous entry, forming an append-only chain. The backend verifies chain continuity on ingest. If a gap or inconsistency is detected (entries deleted, reordered, or modified in transit), the backend flags the batch and records a tamper alert visible in the dashboard.

3. Bundle content verification

Beyond the outer signature, the SDK also checks an embedded content fingerprint inside each policy bundle. This fingerprint covers every rule definition, threshold, and scope in the bundle. Even if the outer signature were somehow replayed from an older bundle, the content fingerprint ensures the rules match what the backend actually published for the current policy_version.

The four `tamper_behavior` modes

The tamper_behavior setting controls what happens when the SDK detects a tamper event. It applies org-wide and is returned to each machine at enrollment time.

Mode	On tamper event
`warn`	Log a warning locally and report the event to the backend. Continue enforcing the last known good policy.
`deny`	Reject the tampered bundle and fall back to the last known good policy. Report the event to the backend.
`deny-all`	Reject all tool calls until a valid policy bundle is pulled. Report the event to the backend.
`quarantine`	Lock down the machine entirely: deny all tool calls and block further policy pulls until an admin intervenes.

The default mode is warn. Most orgs start here and tighten to deny or deny-all once they have confirmed their signing pipeline is stable.

Configuring tamper behavior

In policy YAML

Add a tamper_behavior field under settings in your policy file:

version: '1'
settings:
  tamper_behavior: deny

rules:
  - name: block-secrets
    effect: deny
    action: 'llm:generate'
    resource: '*'
    pattern: "(?i)(api[_-]?key|secret|password)\\s*[:=]"
    scopes: [sdk, gateway]

After editing the YAML, sign and publish the updated policy:

controlzero sign-policy policy.yaml
controlzero policy-pull

In the dashboard

Open Settings -> Security in the dashboard. Under the Tamper Detection card, select one of the four modes from the dropdown and click Save. The change takes effect on the next policy pull for every enrolled machine in the org.

Quarantine: what it does and how to recover

Quarantine is the strictest response. When a machine enters quarantine:

All tool calls are denied. The SDK returns a hard deny for every guard check, regardless of what the policy rules say.
Policy pulls are blocked. The SDK will not attempt to fetch new bundles until quarantine is cleared, preventing a potentially compromised machine from accepting further instructions.
A tamper alert is reported to the backend dashboard with the machine ID, timestamp, and the type of verification failure that triggered quarantine.

What triggers quarantine

Quarantine is only triggered when tamper_behavior is set to quarantine and one of the following occurs:

A pulled policy bundle fails signature verification.
The embedded content fingerprint does not match the declared policy_version.
The audit log hash chain has a detected break during batch submission.

Recovery paths

There are three ways to bring a quarantined machine back to normal operation:

1. Re-enroll the machine

controlzero enroll --token FRESH_TOKEN_HERE

Re-enrollment clears quarantine state, fetches the org's current signing public key, pulls a fresh verified policy bundle, and resumes normal enforcement. This is the recommended path for most situations.

2. Force a policy pull

controlzero policy-pull --force

This bypasses the quarantine block on policy pulls, fetches the latest bundle, and re-verifies it. If verification succeeds, quarantine is cleared automatically. If it fails again, the machine remains quarantined.

3. Re-sign the policy

If the tamper event was caused by a legitimate policy update that was not properly signed (for example, a manual edit to the YAML that skipped the signing step), re-sign and re-publish:

controlzero sign-policy policy.yaml

Then have the quarantined machine run controlzero policy-pull --force to pick up the correctly signed bundle.

Tamper alerts in the dashboard

Every tamper event -- regardless of the configured mode -- is reported to the backend and visible in the dashboard under Governance -> Alerts.

Each alert includes:

Field	Description
Machine ID	The enrolled machine that detected the event
Hostname	The machine's hostname at enrollment time
Event type	`signature_mismatch`, `content_fingerprint_mismatch`, or `hash_chain_break`
Timestamp	When the SDK detected the event
Action taken	What the SDK did in response (`warned`, `denied`, `quarantined`)
Bundle version	The `policy_version` of the suspect bundle (if applicable)

Alerts are retained in the immutable audit trail and cannot be deleted or modified after creation.

Recommendations by org size

Org size	Recommended mode	Rationale
Small (1-10)	`warn`	Low blast radius; visibility without disruption while establishing trust.
Medium (10-50)	`deny`	Automatic fallback to last known good policy prevents silent degradation.
Large (50+)	`deny-all`	Full lockdown on tamper; ensures no unverified policy is ever enforced.
Regulated	`quarantine`	Maximum protection for compliance-sensitive environments.

Start with warn, verify that policy signing and bundle delivery are working correctly across your fleet, then tighten incrementally.

How the pipeline works​

1. Policy bundle signing​

2. Audit log hash chain​

3. Bundle content verification​

The four tamper_behavior modes​

Configuring tamper behavior​

In policy YAML​

In the dashboard​

Quarantine: what it does and how to recover​

What triggers quarantine​

Recovery paths​

Tamper alerts in the dashboard​

Recommendations by org size​