docs: update seccomp documentation by osamakader · Pull Request #4902 · opencontainers/runc

osamakader · 2025-09-26T20:11:54Z

Update seccomp documentation.

rata · 2025-09-29T10:12:49Z

 ```

-*TODO: seccomp work is being done to find a good default config*
+*Seccomp filtering is supported with configurable default profiles*


Not sure what you mean with a configurable default profile. There is no default profile AFAIK.

Also, considering how extensive this doc tends to be, maybe we can add some example seccomp profile here?

I was about to comment the same thing -- this is talking about the default configuration for runc, and we don't have a default seccomp profile. Upstream runtimes have their own profiles but we do not yet have a default one.

But yes, a better PR would be to provide an example (maybe just taking the Podman one? I wouldn't use the Docker one since it still suffers from the EPERM issue described in moby/moby#42871.).

cyphar

See my above comment.

"default" is misleading

AkihiroSuda · 2025-09-29T11:28:18Z

+
+**Example seccomp profile:**
+An example seccomp profile based on Podman's default configuration is available at:
+[examples/seccomp/podman-default.json](../examples/seccomp/podman-default.json)


I don't think this JSON has to be put in the repo.
You can just put a hyperlink

Also, OCI seccomp is different from libcontainer seccomp.
See how it is converted here

runc/libcontainer/specconv/spec_linux.go

Line 1139 in 00aec12

func SetupSeccomp(config *specs.LinuxSeccomp) (*configs.Seccomp, error) {

yes, going to do that.

AkihiroSuda · 2025-09-29T12:22:20Z

+Note: This is an OCI seccomp profile. Runc converts OCI seccomp profiles to libcontainer format
+using the `SetupSeccomp` function in `libcontainer/specconv/spec_linux.go`.
+
+**Example OCI seccomp format:**


A single example should suffice

rata

Thanks! Let's make the style more in-line with the rest of the file

rata

Mostly LGTM now, thanks! Left an important question, though

rata · 2025-09-29T15:33:07Z

+
+Seccomp can be used to filter the syscalls a container can use. The filter used is quite expressive. For example, a filter can allow only a syscall when used with a specific parameter is allowed, change the errno returned or even forward it to a user-space agent to act on it.
+
+Example OCI seccomp profile:


Have you tested this example?

yes, I built runc with seccomp tag, used runc spec then added that profile to it, and ran a container successfully.

rata · 2025-09-30T11:53:05Z

+The primary
+use-case is to provide an explicit allow-list of syscalls for a container, to


Line break is wrong here?

rata · 2025-09-30T11:53:32Z

+libcontainer
+does not currently provide a default filter, but higher-level runtimes tend to


rata · 2025-09-30T11:54:04Z

+libcontainer
+does not currently provide a default filter, but higher-level runtimes tend to
+define their own filters for use with runc. Here is an example OCI seccomp
+profile (see *the runtime specification* *oci-runtime-seccomp* for more


I guess this is intended to be a link but it's broken?

rata · 2025-09-30T11:55:26Z

 ```

-*TODO: seccomp work is being done to find a good default config*
+**seccomp** can be used to apply filters to the system calls used in


Here you broke the link too.

What @cyphar showed with the [ ] is a markdown syntax to put links. You removed it, but we want it like that for the links :)

osamakader · 2025-09-30T12:26:12Z

Thanks @rata for the clarification.

osamakader · 2025-10-06T08:41:17Z

@cyphar changes are done.

kolyshkin · 2025-10-08T00:14:25Z

+vulnerabilities, so a strong seccomp filter is highly recommended.
+
+libcontainer does not currently provide a default filter, but higher-level
+runtimes tend to define their own filters for use with runc. Here is an example


"Here is an example" is probably a leftover from earlier versions.

yes, thanks. done.

osamakader · 2025-10-08T20:25:54Z

@cyphar Do you mind adding you as co-author here? since the changes now almost yours.

kolyshkin · 2025-10-09T00:16:28Z

+libcontainer does not provide a default filter, but higher-level
+runtimes tend to define their own filters for use with runc (see
+[oci-runtime-seccomp](https://github.com/opencontainers/runtime-spec/blob/v1.2.1/config-linux.md#seccomp)
+for more information on how to write your own filters)


nit: missing period

Copilot

Pull Request Overview

This PR updates the seccomp documentation in the libcontainer specification by replacing a TODO placeholder with comprehensive information about seccomp functionality and usage.

Replaces a TODO comment with detailed explanation of seccomp functionality
Adds information about filter expressions, actions, and security benefits
Includes reference to OCI runtime seccomp documentation for filter creation guidance

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-12T00:56:07Z

+emitting a log entry, or permitting the syscall to execute).
+
+The primary use-case is to provide an explicit allow-list of syscalls for a
+container, to reduce the kernel API attack surface exposed the container.


Missing word 'to' - should read 'exposed to the container'.

Suggested change

container, to reduce the kernel API attack surface exposed the container.

container, to reduce the kernel API attack surface exposed to the container.

Replace outdated TODO comment with updated information about runc's seccomp support. Signed-off-by: Osama Abdelkader <osama.abdelkader@gmail.com>

lifubang

LGTM, thanks.

I think all your requested changes have been addressed.

AkihiroSuda previously approved these changes Sep 29, 2025

View reviewed changes

rata reviewed Sep 29, 2025

View reviewed changes

cyphar previously requested changes Sep 29, 2025

View reviewed changes

osamakader force-pushed the fix-outdated-seccomp-todo branch from b9cb4c8 to a221b17 Compare September 29, 2025 11:26

AkihiroSuda reviewed Sep 29, 2025

View reviewed changes

osamakader changed the title ~~docs: update outdated seccomp TODO comment~~ docs: add example seccomp profile based on Podman's default Sep 29, 2025

osamakader requested review from AkihiroSuda, cyphar and rata September 29, 2025 11:29

osamakader force-pushed the fix-outdated-seccomp-todo branch 2 times, most recently from 06ea960 to 43b3b58 Compare September 29, 2025 11:47

AkihiroSuda reviewed Sep 29, 2025

View reviewed changes

rata reviewed Sep 29, 2025

View reviewed changes

Comment thread libcontainer/SPEC.md Outdated

Comment thread libcontainer/SPEC.md Outdated

Comment thread libcontainer/SPEC.md Outdated

Comment thread libcontainer/SPEC.md Outdated

osamakader force-pushed the fix-outdated-seccomp-todo branch from 43b3b58 to f14c63e Compare September 29, 2025 14:31

osamakader requested a review from rata September 29, 2025 14:33

rata reviewed Sep 29, 2025

View reviewed changes

cyphar reviewed Sep 30, 2025

View reviewed changes

Comment thread libcontainer/SPEC.md Outdated

osamakader force-pushed the fix-outdated-seccomp-todo branch from f14c63e to f7e6cdc Compare September 30, 2025 11:24

osamakader requested a review from cyphar September 30, 2025 11:25

osamakader force-pushed the fix-outdated-seccomp-todo branch from f7e6cdc to 656677b Compare September 30, 2025 11:29

osamakader requested review from AkihiroSuda and rata September 30, 2025 11:34

rata reviewed Sep 30, 2025

View reviewed changes

osamakader force-pushed the fix-outdated-seccomp-todo branch from 656677b to 2fe8f87 Compare September 30, 2025 12:25

osamakader requested a review from rata September 30, 2025 12:26

AkihiroSuda reviewed Oct 6, 2025

View reviewed changes

Comment thread libcontainer/SPEC.md

osamakader force-pushed the fix-outdated-seccomp-todo branch from 2fe8f87 to e7ea570 Compare October 6, 2025 11:22

osamakader changed the title ~~docs: add example seccomp profile based on Podman's default~~ docs: update seccomp documentation Oct 6, 2025

kolyshkin reviewed Oct 8, 2025

View reviewed changes

Comment thread libcontainer/SPEC.md Outdated

kolyshkin reviewed Oct 8, 2025

View reviewed changes

osamakader force-pushed the fix-outdated-seccomp-todo branch from e7ea570 to 85582c1 Compare October 8, 2025 19:00

osamakader requested a review from kolyshkin October 8, 2025 19:02

osamakader requested a review from AkihiroSuda October 8, 2025 20:26

kolyshkin reviewed Oct 9, 2025

View reviewed changes

kolyshkin approved these changes Oct 9, 2025

View reviewed changes

osamakader force-pushed the fix-outdated-seccomp-todo branch from 85582c1 to afd8e4b Compare October 11, 2025 20:36

lifubang requested a review from Copilot October 12, 2025 00:55

Copilot AI reviewed Oct 12, 2025

View reviewed changes

lifubang added the area/docs label Oct 12, 2025

osamakader force-pushed the fix-outdated-seccomp-todo branch from afd8e4b to fb37d8f Compare October 12, 2025 11:01

lifubang reviewed Oct 13, 2025

View reviewed changes

Comment thread libcontainer/SPEC.md Outdated

docs: update seccomp documentation

e0632cc

Replace outdated TODO comment with updated information about runc's seccomp support. Signed-off-by: Osama Abdelkader <osama.abdelkader@gmail.com>

osamakader force-pushed the fix-outdated-seccomp-todo branch from fb37d8f to e0632cc Compare October 13, 2025 19:41

osamakader requested a review from lifubang October 13, 2025 19:42

lifubang approved these changes Oct 14, 2025

View reviewed changes

lifubang merged commit 721d066 into opencontainers:main Oct 14, 2025
36 checks passed


		Seccomp can be used to filter the syscalls a container can use. The filter used is quite expressive. For example, a filter can allow only a syscall when used with a specific parameter is allowed, change the errno returned or even forward it to a user-space agent to act on it.

		Example OCI seccomp profile:

		The primary
		use-case is to provide an explicit allow-list of syscalls for a container, to

		libcontainer
		does not currently provide a default filter, but higher-level runtimes tend to

	container, to reduce the kernel API attack surface exposed the container.
	container, to reduce the kernel API attack surface exposed to the container.

Conversation

osamakader commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cyphar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rata left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rata left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

osamakader commented Sep 30, 2025

Uh oh!

osamakader commented Oct 6, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

osamakader commented Oct 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Oct 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lifubang left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

osamakader commented Sep 26, 2025 •

edited

Loading