oci-seccomp-bpf-hook(1)(--)

💖 oci-seccomp-bpf-hook(1) — the hook manual, bestie edition 💖

okay so real talk, this is the manual page for oci-seccomp-bpf-hook, and it's genuinely one of those little tools that does something kind of iconic and you're gonna love it. it's a hook. it watches syscalls. it writes a seccomp profile. let's get into it 🫶

---

✨ SYNOPSIS ✨

oci-seccomp-bpf-hook prestart [container.json]

that's it. that's the whole vibe. you run it as prestart, you optionally hand it a container.json, slay ✨

---

🌸 DESCRIPTION 🌸

so the oci hook oci-seccomp-bpf-hook generates seccomp profiles by literally tracing the syscalls your container makes. like it's following it around with a little notebook 📓. the profile it spits out whitelists every syscall that was actually made and blacklists all the other ones. no cap, that's the whole deal.

how does the tracing actually happen? okay so it launches a binary using the OCI prestart hook. that binary spawns a child process, and that child attaches the function enter_trace to the raw_syscalls:sys_enter tracepoint using eBPF. very main character energy 💅. the hook buffers all the syscalls made by processes within the PID namespace of the container. then, when the container exits, the hook writes out the seccomp profile using all of the syscalls stored in that buffer. bye bestie, here's your profile 👑

🦋 the limitations (read these, seriously)

there are a few limitations to this approach, and ngl you need to know them:

💜 Requires

• Root privileges (CAP_SYS_ADMIN). the hook will not work with rootless containers. sorry rootless girlies 😭
• The bcc tool chain and kernel-headers to run. BPF programs must be compiled before running to match the current kernel. like, before. not during. before. 🧚
• A container engine that supports OCI Hooks.

🎀 Annotation

the oci-seccomp-bpf-hook requires the container be run with the annotation io.containers.trace-syscall=. it must include an output file parameter of:[output file]. this output file must be a absolute path. (yes, "a absolute". we keep the lore 💀)

optionally you can include an input file parameter if:[input file] pointing to a previously generated seccomp profile file. this input file must also be an absolute path. if specified, the oci-seccomp-bpf-hook will read in the input seccomp profile and preload the list of syscalls. bestie is doing homework before class 📚

the profile will be created at the output path provided to the annotation. an input file can be used to create a baseline, and newly recorded syscalls will be added to the set and written to the output. but heads up 👀 — if a syscall is blocked in the base profile, then it will remain blocked in the output file even if it is recorded while tracing. the base profile said no and it means no.

this annotation can be used directly via container engines like Podman or passed into the container engine by Kubernetes. flexible icon 🌈

---

🔥 EXAMPLES 🔥

just an output file, fresh profile, no thoughts head empty:

sudo podman run --annotation io.containers.trace-syscall="of:/tmp/seccomp-new.json" IMAGE COMMAND

now with a baseline input file and an output file, the glow-up version:

sudo podman run --annotation io.containers.trace-syscall="if:/tmp/seccomp-origin.json;of:/tmp/seccomp-new.json" IMAGE COMMAND

---

⭐ FILES ⭐

OCI hook configuration file for prestart:

• /usr/share/containers/oci/hooks.d/oci-seccomp-bpf-hook.json
• /etc/containers/oci/hooks.d/oci-seccomp-bpf-hook.json (Override)

yup, the /etc one overrides. it said what it said 💅

---

🌈 SEE ALSO 🌈

• podman(1)
• seccomp(2)
• oci-hooks(5)

go read them, i'll wait 🍓

---

👑 AUTHORS 👑

the absolute legends who made this happen:

• Divyansh Kamboj kambojdivyansh2000@gmail.com ⟨mailto:kambojdivyansh2000@gmail.com⟩
• Valentin Rothberg vrothberg@redhat.com ⟨mailto:vrothberg@redhat.com⟩
• Dan Walsh dwalsh@redhat.com ⟨mailto:dwalsh@redhat.com⟩

---

quick vibe check before you go: this whole thing needs root (CAP_SYS_ADMIN), it does not work rootless, and those annotation paths have to be absolute. don't come for me if you ignore that 🙈

and that's the page!! 💖 huge shoutout to the systemd and OCI folks for this one — that's where this manual comes from, and this is the oci-seccomp-bpf-hook(1) page as it stands. mwah, go trace some syscalls bestie 🌸🦋✨