landlock-genprof

README

landlock-genprof

Trace a pod once. Get four confidence-annotated security policies — not four things to hand-write.

Version française pour les étudiants : README.etudiants.md. Student onboarding guide: HOW_TO_START.md (French version: COMMENT_COMMENCER.md). Installing against a cluster you already have? INSTALL.md.

Automatic Kubernetes security profile generator — Landlock, NetworkPolicy, seccomp, and Linux capabilities — built on observation of a running pod (a "training run") rather than manual rule authoring.

Container runs with broad, hand-guessed permissions
                    │
                    ▼
   landlock-genprof trace --pod nginx --duration 60s
                    │
                    ▼
    Observed runtime behavior — filesystem, network, syscalls
                    │
                    ▼
     Generated least-privilege profiles, confidence-annotated

  ✓ Filesystem  → PodLock LandlockProfile
  ✓ Network     → Kubernetes NetworkPolicy
  ✓ Syscalls    → seccomp (security-profiles-operator)
  ✓ Hardening   → securityContext fragment

This recording predates the v0.2 canonical demo. It shows a real run of trace → review → apply-proposal, not the current hero narrative ("SPO learns more, and still cannot self-authorize"). See demo/ to run or record the canonical demo.

Click the GIF for the interactive recording, or see demo/script.md for the full shot list to run it yourself.

Every rule above is annotated with how confident the tool is that it's correct — high if seen on every training run, low if seen once — right in the generated YAML, not a separate report you have to cross-reference. See §8 — Example output for what that looks like on a real profile.

Why: Kubernetes already provides strong least-privilege controls, but teams struggle to configure them correctly — policy authoring is manual, error-prone, and demands deep platform expertise. See docs/product-definition-v1.md for the full product definition (problem, value proposition, positioning against PodLock/SPO/static compliance scanners).

The name is a deliberate nod to aa-genprof / aa-logprof — the AppArmor profile generation tools. Landlock had no equivalent when this started, and filling that gap is where the name comes from — the tool itself has since grown to cover network, syscalls, and capabilities from the same training run, not just Landlock's own filesystem/network rights.

Status: the observe → synthesize → export pipeline is built and confirmed end to end on a live cluster (filesystem, network, seccomp, capabilities, cross-run confidence via --history), tagged v0.2.1. docs/roadmap.md tracks what's actually built, milestone by milestone — the source of truth over anything below. docs/product-definition-v1.md for where this is headed as a product. This started as a 3-student course project; that context (team, original risk plan, original milestone plan) moved to docs/pedagogy.md — real, but not what a reader evaluating the tool itself needs first.

Try it in 3 commands

No cluster yet? hack/init-vm.sh builds a disposable one (kind + Cilium + Inspektor Gadget + a test pod), see docs/test-environment.md for the step-by-step version. Already have a cluster? See INSTALL.md instead — same three commands below, once the CLI and its RBAC/CRDs are in place.

kubectl landlock-genprof trace --pod nginx-demo --namespace default \
  --binary /usr/sbin/nginx --duration 60s

kubectl landlock-genprof review nginx-demo

# Use the Candidate digest printed by review to bind explicit approval.
kubectl landlock-genprof approve nginx-demo \
  --expected-digest sha256:<candidate-digest-from-review>

kubectl landlock-genprof apply-proposal nginx-demo

Observe, review, approve the reviewed digest, then apply through apply-proposal — that's the governed loop. Full flag reference: docs/usage.md; every command's own options/examples: CLI reference.

Quick links

No cluster yet	docs/test-environment.md — disposable kind cluster, from nothing.
Install	INSTALL.md — already have a cluster? Start here.
Full usage reference	docs/usage.md — every trace flag, one section each.
Architecture	docs/architecture.md — data flow, sequence diagram, package deps.
Demo	demo/script.md — a 75s walkthrough script.
Contributing	CONTRIBUTING.md · GOVERNANCE.md · CODE_OF_CONDUCT.md
Enforcement prerequisites	docs/enforcement-prerequisites.md — what PodLock/SPO/a NetworkPolicy-capable CNI each need, including PodLock's real limitation on this project's own kind setup.

---

1. The problem

Kubernetes has several real least-privilege mechanisms — Landlock, seccomp, NetworkPolicy, Linux capabilities — but every one of them requires guessing in advance what an application actually needs, hand-authored, before anyone has observed it running:

• Too permissive → the policy protects nothing (everything is allowed to avoid breaking the app)
• Too restrictive → the application breaks in production on a rare code path

Landlock: the flagship example, and where the name comes from

Landlock is a Linux Security Module (LSM) introduced in kernel 5.13 that allows processes to confine themselves to a subset of the filesystem and network, without requiring root privileges. This is a rare and valuable property: whereas AppArmor, SELinux, or seccomp require system-wide configuration by an administrator, a process can arm Landlock itself.

The problem above is compounded for Landlock specifically, in a Kubernetes context:

• Landlock has no native integration in containerd/runc, so there is no standard K8s support (securityContext cannot arm Landlock)
• There is no equivalent of aa-genprof for Landlock, neither in the Security Profiles Operator nor in PodLock

That gap is why this project exists and where its name comes from — but the same "guess it by hand" problem is just as real for seccomp and NetworkPolicy, which is why landlock-genprof addresses all of them from the same training run, not Landlock alone: observe first, write the policy after.

The second problem: learning is not authorization

Observation solves the guessing problem, and other systems already solve it well — security-profiles-operator records syscalls with a production eBPF recorder, generates a SeccompProfile, installs it on every node and enforces it.

What no learner provides is a decision. A recorded profile describes what a workload did. Enforcing it is a statement about what it is allowed to do, and those are not the same claim.

LEARNED ≠ AUTHORIZED

landlock-genprof v0.2 is the authorization boundary between the two. What was learned — by SPO, or by this project's own tracer — becomes one reviewable candidate with one deterministic identity; a human's approval is bound to that exact content; and when the workload changes, the previous approval stops authorizing anything until someone reviews the change.

This is proven end to end against a real operator, not asserted:

real SPO ProfileRecording → derived policy → lineage + semantics validated
  → governed snapshot → CandidateDigest → human approval
  → stale authority refused → backend readiness → enforcement identity
  → workload binding LAST

Filesystem (PodLock/Landlock), network (NetworkPolicy) and syscalls (SPO SeccompProfile) travel as one candidate, one digest, one decision. SPO records none of the first two.

---

2. Positioning — PodLock, SPO, and native Kubernetes enforcement

landlock-genprof doesn't enforce anything itself — it feeds three existing, independent enforcement mechanisms, one per domain:

Domain	Enforced by	This project generates
Filesystem (Landlock)	PodLock (Kubewarden ecosystem)	LandlockProfile CRD
Syscalls (seccomp)	security-profiles-operator (SPO)	SeccompProfile CRD
Network	Any CNI implementing NetworkPolicy (e.g. Cilium)	Kubernetes NetworkPolicy

PodLock is the closest existing project overall — it provides the LandlockProfile CRD and the operator that enforces it at container startup, but doesn't generate the profiles: the user still has to author them by hand, precisely the problem addressed here.

                           ┌─────────────────────────────────┐
  landlock-genprof         │  PodLock (Kubewarden)            │
  ──────────────────       │  ─────────────────────────────── │
  observes the pod  ──────►│  LandlockProfile CRD             │
  generates YAML           │  K8s operator                    │
  (human review)    ──────►│  Runtime enforcement             │
                           └─────────────────────────────────┘

landlock-genprof is complementary to PodLock, SPO, and your CNI — not a competitor to any of them. It generates profiles in the formats each one already expects, upstream in the chain, for whichever domains a given training run actually observed.

Generating a correct LandlockProfile doesn't require PodLock's operator to be installed anywhere — but seeing it actually enforced does. See docs/enforcement-prerequisites.md before assuming this repo's own kind-based dev setup can demonstrate that end to end; short version: it can't, per PodLock's own docs — and the same doc covers SPO's and the CNI's own prerequisites too.

---

3. How it works

Five core steps — full detail, every optional flag, in docs/usage.md:

1. Training run — the target pod runs normally for a set duration (landlock-genprof trace --pod ... --duration 60s).
2. Capture — Inspektor Gadget gadgets observe filesystem, network, syscall, and capability activity via eBPF.
3. Synthesis — events are aggregated by directory, each rule gets a Confidence level (high/medium/low) based on how consistently it was observed.
4. Export — one package per output: PodLock LandlockProfile (always), NetworkPolicy, seccomp (plain JSON and/or an SPO SeccompProfile CR), a capabilities fragment, a composed securityContext, a Markdown review report — plus a SecurityProfileProposal cluster object combining the four directly-appliable artifacts, published on every run (mandatory, not opt-in). See §8 for real examples of each.
5. Human review — landlock-genprof never applies anything itself. Every artifact is a starting point for review, not a final result.

---

4. Technical stack

Component	Choice	Rationale
Language	Go 1.26	Native K8s ecosystem (client-go); Inspektor Gadget Go SDK
Tracer	Inspektor Gadget	Pre-written, CNCF-maintained eBPF gadgets — avoids writing eBPF from scratch
Output formats	PodLock LandlockProfile, NetworkPolicy, seccomp (JSON + SPO CR), capabilities, securityContext	Existing, upstream formats — complementary, not competing
Dev cluster	kind + Cilium	kind shares the host kernel (required for Landlock/eBPF); Cilium replaces kindnet so generated NetworkPolicy is actually enforceable
CI	GitHub Actions (ubuntu-24.04)	Kernel 6.8 — covers both FS and network Landlock; build-and-test + security (gosec, Trivy) both required checks
License	Apache-2.0 OR MIT	Dual license, recipient's choice — compatible with PodLock and the CNCF ecosystem

Key Go dependencies (all pinned to exact versions in go.mod, never @latest):

github.com/inspektor-gadget/inspektor-gadget  # tracer SDK (Linux-only, see internal/tracer)
sigs.k8s.io/yaml                               # YAML serialization
k8s.io/client-go                               # pod resolution
github.com/spf13/cobra                         # CLI

---

5. Repository layout

Full data-flow/sequence/package-dependency diagrams: docs/architecture.md, docs/sequence-diagram.md, docs/packages.md — the ASCII tree below is deliberately shallow; a deep hand-maintained one goes stale (this project's own past experience — see docs/roadmap.md).

landlock-genprof/
├── cmd/landlock-genprof/    CLI entry point — trace, review, version
├── internal/
│   ├── tracer/              Syscall event capture (Inspektor Gadget)
│   ├── policy/               Event aggregation → Behavior IR
│   ├── profile/              Behavior IR — independent of any output format
│   ├── exporter/             One package per output format (6 total)
│   ├── history/              TrainingHistory CRD (multi-run Confidence)
│   ├── proposal/             SecurityProfileProposal CRD
│   └── k8s/                  Pod resolution, --restart, --patched-manifest-out
├── pkg/                     Go types for PodLock/seccomp/SPO CRDs
├── examples/                Illustrative + real generated artifacts
├── docs/                    Architecture, usage, threat model, roadmap, ...
├── deploy/                  RBAC/CRD manifests + the Helm chart
├── demo/                    Demo script
├── hack/                    Dev VM/kernel-check scripts
└── .github/workflows/       CI (build-and-test, security)

---

6. Prerequisites

Linux kernel

landlock-genprof's only real requirement is the kernel version — not a specific distro. Nothing under hack/ calls a distro-specific package manager (apt/dnf/yum, ...); check-kernel.sh/init-vm.sh only use uname, curl, tar, and generic Linux tooling. Any distro shipping a kernel meeting the versions below should work.

Feature	Minimum kernel version	Notes
Landlock FS	≥ 5.13	File/directory confinement
Landlock network	≥ 6.4	TCP confinement (connect/bind)
eBPF (Inspektor Gadget)	≥ 5.8 recommended	BPF ring buffer

Actually tested (this is a "known to work" list, not a restriction — see above):

Distro	Kernel	Status
Ubuntu 24.04	6.8	✅ validated
Ubuntu 26.04	7.0	✅ validated

Check host prerequisites:

./hack/check-kernel.sh

Tools

go 1.26+        # Build and tests
kind            # Local K8s cluster (shares host kernel)
kubectl         # Cluster interaction
helm            # Installing this project's own chart, and Cilium below

Setting up kind and the dev cluster

# Install kind (pinned version, not @latest)
go install sigs.k8s.io/kind@v0.32.0

# Create cluster — CNI disabled here on purpose, see the note below
cat <<EOF | kind create cluster --name landlock-dev --config -
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  disableDefaultCNI: true
EOF

# Verify
kubectl cluster-info --context kind-landlock-dev

./hack/init-vm.sh (or make init-vm) automates this plus Helm, Cilium, kubectl, Inspektor Gadget, and a test pod in one idempotent script — see HOW_TO_START.md §2 for a detailed walkthrough of what it does. Cilium replaces kind's default CNI (kindnet) because kindnet doesn't implement NetworkPolicy at all — skip that step only if you don't care whether --network-out's output is actually enforceable. This gets you trace and profile generation end to end; actually enforcing what's generated needs more — see docs/enforcement-prerequisites.md.

---

7. Quick start

# Clone the repo
git clone git@github.com:idriss-eliguene/landlock-genprof.git
cd landlock-genprof

# Check kernel prerequisites
./hack/check-kernel.sh

# Build + install as a kubectl plugin (recommended invocation below —
# see INSTALL.md for the plain `go build`/`go run` alternative)
go test ./...
make install-plugin
kubectl plugin list   # confirms kubectl sees it

# Apply required CRDs/RBAC before the first trace run
kubectl apply -f deploy/rbac.yaml
kubectl apply -f deploy/crd-securityprofileproposal.yaml
kubectl apply -f deploy/rbac-proposal.yaml
# Required whenever this run composes securityContext data
# (commonly true in practice when syscalls are observed)
kubectl apply -f deploy/rbac-patched-manifest.yaml

# CLI (Trace() captures openat via Inspektor Gadget — Linux + a real
# cluster with Inspektor Gadget deployed required, see HOW_TO_START.md)
kubectl landlock-genprof trace --pod nginx --namespace default --binary /usr/sbin/nginx --duration 60s --out profile.yaml

This is the fastest path to a first result, on the disposable dev cluster from §6. For a Helm-based install, the kubectl-plugin build, or installing against a cluster you already have (not one you just spun up for this), see INSTALL.md instead of repeating all of that here.

---

8. Example output

Profile generated for an nginx pod after a 60 s training run. See examples/nginx-generated-profile.yaml.

apiVersion: podlock.kubewarden.io/v1alpha1
kind: LandlockProfile
metadata:
  name: nginx-demo
  namespace: default
spec:
  profilesByContainer:
    nginx:
      "/usr/sbin/nginx":
        readExec:
          - /lib
          - /lib64
        readOnly:
          - /usr/share/nginx        # confidence: high — seen on every run
        readWrite:
          - /tmp                    # confidence: high — seen on every run
          - /var/cache/nginx/proxy  # confidence: low — seen 1 out of 5 runs

The confidence annotation makes explicit what is reliable and what needs verification before production deployment.

The other five artifacts each get their own example too — same nginx-demo scenario, one file per domain:

Domain	Example
Network (--network-out)	examples/nginx-generated-networkpolicy.yaml
Syscalls, plain JSON (--seccomp-out)	examples/nginx-generated-seccomp.json
Syscalls, SPO custom resource (--seccomp-profile-out)	examples/nginx-generated-seccompprofile.yaml
Capabilities (--capabilities-out)	examples/nginx-generated-capabilities.yaml
Composed securityContext (--security-context-out)	examples/nginx-generated-securitycontext.yaml
Unified review report (--report-out)	examples/nginx-generated-report.md

Unlike nginx-generated-profile.yaml above (real M4 milestone output), these five are illustrative — adapted from docs/usage.md's own Step 4* sections rather than freshly captured from a live run. Their shape and field names are accurate; regenerating them from an actual trace run is tracked as good first issue #94.

The SecurityProfileProposal — the actual primary artifact

Every trace run publishes all four applyable artifacts together as one cluster object (docs/usage.md Step 12) — this, not the separate local files, is the artifact this tool is really built around: reviewable via kubectl/GitOps, one kubectl get -o yaml away instead of five separate files to track down.

See examples/nginx-generated-proposal.yaml for the complete object — spec.podLock/networkPolicy/ patchedManifest/spoSeccompProfile each hold the exact rendered YAML of the corresponding artifact as a plain string for review and inspection. Those strings are not independently authorized rollout artifacts. For the governed proposal workflow, obtain the Candidate digest from review, approve that digest explicitly, then apply with apply-proposal.

---

9. Threat model

The tracer needs elevated capabilities (CAP_BPF, CAP_SYS_ADMIN depending on kernel version) to observe a pod's syscalls — a real attack surface, documented and analyzed, not just flagged as a to-do. docs/threat-model.md covers:

1. Tracer attack surface — exact capabilities required, RBAC scope, whether the tracer should run permanently (it shouldn't).
2. Completeness of generated profiles — the false-negative risk a short training run carries, and how Confidence surfaces it.
3. Pentesting the operator / the generated profile — evasion: can a traced pod detect it's being observed and behave differently?
4. CI hardening — gosec/Trivy as required checks, not advisory.

---

10. Contributing

External contributions are welcome. See CONTRIBUTING.md for the development setup, code conventions, and what to check before opening a PR — also GOVERNANCE.md for how decisions get made and CODE_OF_CONDUCT.md for the expected conduct. For where the product is headed, see docs/product-definition-v1.md, docs/product-design-v1.md, and docs/product-roadmap-v1.md.

---

11. Upgrading to v0.2

Proposals generated before v0.2 must be regenerated. They embed the SPO v0.8.4 shape — a namespaced v1beta1 SeccompProfile and an operator/<namespace>/<name>.json localhost profile path. SeccompProfile became cluster-scoped at SPO v0.9.0, and the governed apply path refuses to reinterpret the old path rather than bind a workload to a profile whose readiness was never established. Such a proposal now fails closed.

There is no rewrite or re-approval migration, deliberately: rewriting a stored proposal would change the candidate and therefore invalidate its approved digest, which is the mechanism working, not a defect. Re-run trace to produce a fresh candidate and approve it.

What v0.2 does not claim

• mergeStrategy: Containers — refused. SPO's recording merger drops the container-id label the lineage contract requires, so merged profiles cannot be imported. Record one container at a time with mergeStrategy: None.
• Syscall coverage — reported as unknown. SPO v1.0.0 emits no coverage metadata; the value is recorded honestly rather than invented.
• Seccomp semantic diff — not implemented. diff compares Landlock candidates; seccomp changes are shown through provenance.
• Behavioral syscall enforcement — not proven. Nothing in the test suite attempts a denied syscall.
• SPO recording on kind — not supported. SPO's eBPF recorder resolves container pids through /proc, which cannot work when the node is itself a container. The D-MIN and demo suites use a real-node cluster.

---

12. License

Dual-licensed, recipient's choice: Apache-2.0 or MIT — see COPYRIGHT. Compatible with PodLock and the CNCF ecosystem.