Skip to main content

Fleet Policies, Rollouts, and Device Posture

This guide covers the three pillars of the Fleet MDM value story: centralized governance policies that control what AI agents can do on every enrolled machine, staged rollouts that update ssg across your fleet safely, and device posture that tells you which machines are actually protected.

What Fleet policies do​

A SigmaShake Fleet policy is a named, versioned set of .rules governance directives that the Fleet control plane compiles into a signed bundle and distributes to every enrolled agent.

When an agent receives a new policy bundle:

  • Its local ssg governance engine replaces the previous rules with the new bundle.
  • Every AI tool call from that point forward is evaluated against the new rules.
  • The agent reports policy compliance on its next heartbeat.

This gives you centralized governance — one change in the Fleet dashboard propagates to every enrolled machine within 5 minutes, without requiring any action from individual developers.

Authoring a policy​

1. Find a ruleset​

Fleet policies reference rulesets by their slug from the Hub Catalog. Browse hub.sigmashake.com or the Hub Catalog tab in the Fleet dashboard to find rulesets that match your risk profile.

Common starter choices:

Ruleset slugWhat it does
agent-safety-baselineDENY catastrophic actions (mass-delete, disk-wipe, credential-theft, ransomware loop) + ASK for irreversible ops
protect-databaseASK before any destructive schema or data operation
protect-secretsASK for reads of .env, credential files, and key material
safe-writesRestrict writes to sensitive system paths

2. Create the policy​

In the Fleet Dashboard → Policies → New policy:

  1. Enter a name (e.g., "Dev team baseline").
  2. Add one or more ruleset slugs from the Hub Catalog.
  3. Optionally add a description for audit clarity.
  4. Click Save as draft.

3. Submit and approve​

Policies follow a two-step change gate to prevent accidental fleet-wide changes:

  1. A policy_author or org_admin submits the policy for review.
  2. An org_admin approves it. Approved policies move to the active state.

4. Compile and distribute​

Click Compile policies (or call POST /api/v1/orgs/:org/policies/compile) to merge all active policies into a signed bundle. Agents pick up the bundle on their next heartbeat (≤ 5 minutes) or immediately if a real-time poke is sent.

Instant propagation

To push a policy change immediately without waiting for the heartbeat cycle, use the real-time poke:

# Via the Fleet API (requires org_admin bearer)
curl -X POST https://{SUBDOMAIN}.fleet.sigmashake.com/api/v1/orgs/{ORG_ID}/agents/poke \
  -H "Authorization: Bearer {SERVICE_ACCOUNT_KEY}"

This sends a reconcile signal to all connected agent WebSockets. Agents not currently connected will pick up the change on their next heartbeat.

Staged rollouts (MDM updates)​

Fleet's rollout system lets you update the ssg version on enrolled machines in controlled stages — the same model used by enterprise endpoint management platforms.

Creating a rollout​

In the Fleet Dashboard → Updates → New rollout:

  1. Target version — the ssg semver to deploy (e.g., 0.29.158). Must be a published version.
  2. Agent selector — choose a targeting strategy:
    • All agents in the org
    • A specific named group
    • A filter expression (e.g., os=linux AND version_lt=0.29.155)
  3. Submit. Each matched agent receives an update directive on its next heartbeat.

Rollout states per agent​

StateMeaning
dispatchedDirective sent; agent has not yet acknowledged
convergedAgent received and started the update
succeededAgent confirmed running the target version
failedAgent reported an error; see the agent detail for the error message
skippedAgent declined (e.g., SSG_FLEET_NO_REMOTE_UPDATE=1, or installed via brew/pip/winget)
sweptTask abandoned by the background sweep (agent went silent)

Rollout safety constraints​

  • The target version must be a strict semver string. Non-semver values (URL-like, git ref) are rejected to prevent package-manager injection (RCE vector). See Threat Model for details; the 2026-06-18 AI-assisted internal security review (Claude Opus 4.8, Anthropic) — not a third-party penetration test — confirmed this control.
  • Rollout steps are merkle-chained into the audit log (rollout.completed, agent.update.succeeded, etc.) — every state transition is evidence-grade.
  • Use cancel rollout to stop a rollout in progress if a bad version is deployed. Use retry failed to re-queue agents that errored.

Device posture​

Fleet's posture layer answers the question: are the machines that should be protected actually protected?

Coverage assurance​

The Coverage report (Agents → Coverage tab) compares:

  • Expected — the machines you declared via a coverage manifest (PUT /api/v1/orgs/:org/coverage/expected)
  • Enrolled — the machines that have an active agent

Machines in expected but not in enrolled are dark assets — machines that should be governed but are not. The coverage rate is enrolled_matching / expected_total.

Uploading a manifest:

{
  "expected": [
    { "ext_id": "laptop-001", "label": "Alice's MacBook", "os": "darwin" },
    { "ext_id": "laptop-002", "label": "Bob's Linux box", "os": "linux" },
    { "ext_id": "ci-runner-1", "label": "GitHub Actions runner", "os": "linux" }
  ]
}
curl -X PUT https://{SUBDOMAIN}.fleet.sigmashake.com/api/v1/orgs/{ORG_ID}/coverage/expected \
  -H "Authorization: Bearer {SERVICE_ACCOUNT_KEY}" \
  -H "Content-Type: application/json" \
  -d @manifest.json

Policy compliance posture​

The Health screen shows policy compliance rate — the percentage of active agents running the latest compiled policy bundle. An agent is non-compliant if it has not yet pulled the latest bundle (e.g., was offline during the compile window).

Lifecycle posture​

Agents age through a lifecycle state machine (active → idle@7d → stale@30d → offline@90d → tombstoned@180d) driven by heartbeat silence. The Health screen surfaces lifecycle breakdowns so you know how many machines are active vs. drifting toward stale.

Governance evidence for compliance​

Every policy approval, compile, and agent-pull is merkle-chained into the fleet audit log. The GET /api/v1/orgs/:org/audit/report endpoint generates a structured compliance report. The /soc2 endpoint produces a pre-formatted SOC 2 CC6/CC7 evidence export.

Audit events relevant to compliance:

EventWhen it fires
policy.compiledA new bundle was compiled and stored
policy.approvedA policy was approved by an org_admin
agent.policy.pulledAn agent downloaded the latest bundle
rollout.completedAll targeted agents have reached a terminal state
agent.lifecycle.purgedA stale agent record was hard-deleted after 180 days