Skip to content

Python API

Generated from docstrings with mkdocstrings.

stratum.pss

Kubernetes Pod Security Standards (baseline + restricted), latest (v1.37) semantics.

A pure-Python re-implementation of the checks in k8s.io/pod-security-admission, used in two places:

  • the Zero-Trust policy engine (workload-hardening controls ZT-WL-*), and
  • the conformance benchmark (stratum bench pss), which replays the upstream project's own pass/fail fixtures against this module.

Every check returns a list of human-readable violations; an empty list = pass. Check ids match the upstream fixture filename prefixes so results can be scored per check.

evaluate_pod(pod, level='restricted')

Return {check_id: [violations]} for every failing check at level.

highest_level(pod)

The strictest PSS level the pod satisfies: restricted | baseline | privileged.

legacy_check(pod)

The v0.1 MVP heuristic (privileged / root / hostNetwork), kept as a benchmark baseline.

Returns True when the pod would have been flagged.

stratum.syscall

Syscall-sequence anomaly models for the runtime sensor ("AI flags, the graph explains").

Evaluated on ADFA-LD (see stratum.bench.adfa). Three detectors, all trained on normal traces only (no attack labels are ever used for fitting):

  • :class:Stide - the classic baseline (Forrest et al., 1996): a database of length-n windows seen in normal traces; the anomaly score of a trace is the fraction of its windows missing from the database.
  • :class:NgramNovelty - STRATUM's frequency novelty model generalised from (process, event, port) tuples to syscall n-grams: the score is the mean surprisal -log P(window) under an add-k smoothed model of normal behaviour, so rare windows count as well as never-seen ones.
  • :class:NgramIsolationForest - an Isolation Forest over hashed, TF-IDF weighted 1..n-gram counts (needs scikit-learn; optional).

Traces are plain integer sequences.

bootstrap_ci(neg, pos, stat, n_boot=500, seed=0, alpha=0.05)

Stratified percentile bootstrap CI for stat(neg, pos) (normal and attack resampled separately).

fpr_at_tpr(neg, pos, tpr)

False-alarm rate needed to reach detection rate tpr (tie-interpolated ROC).

load_adfa(root)

{'train': [trace], 'val': [trace], 'attack': [(family, trace)]} from an ADFA-LD folder.

paired_bootstrap_diff(neg_a, pos_a, neg_b, pos_b, stat, n_boot=1000, seed=0, alpha=0.05)

Paired, stratified bootstrap of stat(A) - stat(B) for two detectors scored on the same traces. Returns the observed difference, its percentile CI and a two-sided bootstrap p-value, min(1, 2 (k + 1) / (B + 1)) with k the smaller tail count.

roc_auc(neg, pos)

Mann-Whitney U estimate of ROC-AUC (ties count 1/2); no sklearn needed.

roc_curve(neg, pos)

ROC vertices (FPR, TPR) for "score >= threshold", thresholds descending; tied scores form one diagonal segment, i.e. the curve a random tie-break gives in expectation.

tpr_at_fpr(neg, pos, fpr)

Threshold = the (1-fpr) quantile of normal scores; returns (TPR, realised FPR).

tpr_at_fpr_interp(neg, pos, fpr)

TPR at exactly fpr on the tie-interpolated ROC curve.

stratum.gatekeeper

Export stratum/policies/pss/pss.rego as an OPA Gatekeeper ConstraintTemplate + Constraint, and evaluate it with opa.

stratum/policies/pss/pss.rego re-implements 8 of the 19 Pod Security Standards checks (the ones that are plain field tests); tests/test_gatekeeper.py diffs it against :mod:stratum.pss on the upstream fixtures when an opa binary is available.

constraint(level='restricted', action='dryrun', exclude_ns=('kube-system',))

A constraint instance for one PSS level and enforcement action.

constraint_template()

The StratumPodSecurity ConstraintTemplate as a dict.

export_yaml(level='restricted', action='dryrun', exclude_ns=('kube-system',))

Template and constraint as one multi-document YAML string.

rego_violations(objs, opa=None)

Failing check ids per object according to the Rego policy (needs opa).

template_rego()

Rego source embedded in the Gatekeeper ConstraintTemplate.

stratum.opa

Evaluate stratum/policies/stratum.rego with a real opa binary and diff against the Python engine.

diff(ds, deny_bases=(), opa=None)

Compare Python-engine and Rego findings: counts, the pairs only one side reports, and equivalent.

find_opa()

Path of an opa binary (PATH, then $STRATUM_DATA/tools), or None if absent.

opa_findings(ds, deny_bases=(), opa=None)

Evaluate the Rego mirror with opa eval; returns the set of (control_id, subject) findings.

rego_input(ds, deny_bases=())

Serialise a dataset into the input document the Rego mirror evaluates.

stratum.provenance

Build provenance for real images: image -> (OCI labels) -> GitHub commit -> PR/author.

This is the "CI provenance" input of the lifecycle graph for images we did not build ourselves. The chain is only accepted when every hop is verified:

  1. the registry manifest for the tag resolves to a linux/amd64 digest,
  2. the image config carries org.opencontainers.image.source (a GitHub repo) and org.opencontainers.image.revision (a commit SHA), and
  3. that commit exists in that repo according to the GitHub API (author, date, message and associated PR are recorded).

cosign signature / attestation artefacts next to the digest are recorded as signed / attested (presence only - signatures are not verified cryptographically; see docs/adr/0004-provenance-sources.md).

add_tag_baseline(provs, gh)

Record what the tag->git-tag heuristic would say, for images whose repo is known.

github_token()

Opt-in token for api.github.com (rate limits only; public read access is enough).

Read from STRATUM_GITHUB_TOKEN (or GITHUB_TOKEN inside GitHub Actions). The gh CLI's own token is not picked up automatically, because it usually carries far broader scopes.

tag_commit(gh, repo, tag)

Naive baseline: the commit a same-named git tag points to (also tries a 'v' prefix).

to_dataset(provs, reports=None)

Images / builds / commits for the lifecycle graph.

Image node id == the exact ref string used in the manifests, so the graph joins manifests (workloads) to provenance without guessing.

stratum.ingest

Parsers for real sensor / scanner output.

  • :func:tetragon_events - Cilium Tetragon JSON export (tetra getevents -o json or the export-filename log) -> :class:RuntimeEvent.
  • :func:trivy_report - trivy image --format json --list-all-pkgs -> :class:ImageReport (vulnerability counts, KEV hits, shells, OCI labels).
  • :func:load_kev - CISA Known Exploited Vulnerabilities catalog -> set of CVE ids.

runtime_inventory(events, known=None)

Workloads/images observed only at runtime (pods not present in any manifest).

A pod seen by the sensor but absent from the declared cluster state is itself a drift signal; its image is keyed by the runtime digest so the lifecycle trace still reaches the exact image that ran.

stratum.incident

Trace detections to commit + failed control + blast radius; policy-as-prevention replay; metrics.

replay_with_policy(ds, namespace)

Apply the recommended egress policy and re-emulate external connects.