Seccomp Endpoints - kguardian

These endpoints expose the per-workload seccomp profiles the broker builds from observed syscalls. See the Distributing Seccomp Profiles guide for the workflow. Every rendered profile is the effective profile: (observed ∪ override.add) \ override.remove, with defaultAction from the override or SCMP_ACT_LOG. The hash names that effective set — it changes when the observed union grows or when an override changes.

GET /seccomp/profiles

Every workload that has an aggregated syscall set, with its effective hash, profile path, distribution readiness, and any override. This is the list the controller’s distributor polls and the UI renders.

Response

[
  {
    "namespace": "prod",
    "kind": "Deployment",
    "name": "web",
    "hash": "a1b2c3d4e5f60718",
    "localhostProfile": "kguardian/prod/deployment-web-a1b2c3d4e5f60718.json",
    "defaultAction": "SCMP_ACT_LOG",
    "syscallCount": 73,
    "architectures": ["SCMP_ARCH_X86_64"],
    "distribution": { "ready": 12, "total": 12, "state": "Ready" },
    "recommendedSnippet": {
      "seccompProfile": {
        "type": "Localhost",
        "localhostProfile": "kguardian/prod/deployment-web-a1b2c3d4e5f60718.json"
      }
    },
    "override": null,
    "updatedAt": "2026-09-02T10:15:00"
  }
]

distribution.state is Ready when every live node (total) reports the current file, Partial when some do, and Pending when none do or no node has reported yet. When an override is set, override is:

{
  "add": ["clock_settime"],
  "remove": [],
  "defaultAction": "SCMP_ACT_ERRNO",
  "note": "weekly cron rotates the cert",
  "updatedBy": "alice",
  "updatedAt": "2026-09-03T09:00:00",
  "revision": 2
}

GET /seccomp/profiles///

One workload’s summary (as above) plus the rendered effective profile document.

Response

{
  "namespace": "prod",
  "kind": "Deployment",
  "name": "web",
  "hash": "a1b2c3d4e5f60718",
  "localhostProfile": "kguardian/prod/deployment-web-a1b2c3d4e5f60718.json",
  "defaultAction": "SCMP_ACT_LOG",
  "distribution": { "ready": 12, "total": 12, "state": "Ready" },
  "override": null,
  "profile": {
    "defaultAction": "SCMP_ACT_LOG",
    "architectures": ["SCMP_ARCH_X86_64"],
    "syscalls": [
      { "names": ["accept4", "read", "write", "..."], "action": "SCMP_ACT_ALLOW" }
    ]
  }
}

404 if the workload has no aggregate yet.

GET /seccomp/profile-file////

The bare effective SeccompProfile document, for a distributor to write to a node verbatim. Serves only the current hash — a stale hash returns 404 with stale hash; re-read /seccomp/profiles, which is the caller’s signal to re-read the list.

PUT /seccomp/profiles////override

Set or replace the operator override for a workload. Gated — returns 404 unless the broker is started with SECCOMP_OVERRIDES_ENABLED=true (Helm: seccomp.overrides.enabled). The override is stored separately from the observed union, which keeps accruing underneath. The effective hash is recomputed on the write, so a new hash-named file lands on every node within one distributor poll; the previous file is never deleted, so a DELETE (below) reverts cleanly.

Request

{
  "add": ["clock_settime", "clock_adjtime"],
  "remove": [],
  "defaultAction": "SCMP_ACT_ERRNO",
  "note": "cert rotation cron, runs weekly",
  "revision": 1,
  "dryRun": false
}

add / remove — syscall names, ^[a-z][a-z0-9_]{0,63}$, ≤ 512 each. A name in both is a 400. Names are not checked against a real syscall table yet (a typo that passes the format check produces a warning-free but useless profile).
defaultAction — one of SCMP_ACT_LOG, SCMP_ACT_ERRNO, SCMP_ACT_KILL; omit to keep SCMP_ACT_LOG.
revision — the revision the client last read. Omit (or null) to create; a mismatch with the stored revision is a 409.
dryRun — validate and render without persisting.
X-Kguardian-Actor header — recorded as updatedBy; defaults to unknown.

Response — `200`

{
  "dryRun": false,
  "revision": 2,
  "hash": "7f3c1a0b9d2e4658",
  "warnings": [
    "defaultAction SCMP_ACT_ERRNO blocks — a syscall the workload makes but kube-guardian has not yet observed will fail on the pod's next restart"
  ],
  "profile": { "defaultAction": "SCMP_ACT_ERRNO", "architectures": ["..."], "syscalls": [ ... ] }
}

Errors

Code	When
`404`	overrides not enabled, or no observed profile for the workload yet
`400`	bad syscall name, `add`/`remove` overlap, invalid `defaultAction`, list over cap
`409`	`revision` does not match the stored one — body carries `currentRevision`

DELETE /seccomp/profiles////override

Drop the override. The effective profile falls back to the pure observed set and the hash reverts to the pre-override value — and since that file was never deleted from any node, no redistribution is needed. Also gated behind SECCOMP_OVERRIDES_ENABLED. 404 if there was no override.

POST /seccomp/node-status

The distributor reports, after every pass, the full set of profile files present on its node. Replaces the node’s row wholesale — it is a snapshot, not a delta.

Request

{
  "node_name": "ip-10-0-1-42.ec2.internal",
  "paths": [
    "kguardian/prod/deployment-web-a1b2c3d4e5f60718.json",
    "kguardian/prod/cronjob-report-9f8e7d6c5b4a3021.json"
  ]
}

node_name is required; an empty paths is valid (the node has no profiles yet). Returns 200 with an empty body.

​GET /seccomp/profiles

​Response

​GET /seccomp/profiles///

​Response

​GET /seccomp/profile-file////

​PUT /seccomp/profiles////override

​Request

​Response — 200

​Errors

​DELETE /seccomp/profiles////override

​POST /seccomp/node-status

​Request

GET /seccomp/profiles

Response

GET /seccomp/profiles///

Response

GET /seccomp/profile-file////

PUT /seccomp/profiles////override

Request

Response — `200`

Errors

DELETE /seccomp/profiles////override

POST /seccomp/node-status

Request