landlock-genprof

README

landlock-genprof

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

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).

See §8 — Example output for a real generated profile.

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.1.2. 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

kubectl landlock-genprof apply-proposal nginx-demo

Observe, review, apply — that's the whole 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.

---

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, copy-pasteable straight out of kubectl get securityprofileproposal nginx-demo -o yaml into a kubectl apply -f -.

---

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. License

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