SLIRP: server sockets and pidfd_getfd

[jserv]

Rationale

The current codebase delivered outbound SLIRP networking including sendmsg routing and
shell-level TCP integration tests (wget under --net). Three gaps remain:

(a) Server sockets: bind() is implemented, but listen() and accept()/accept4() are not. The AF_UNIX socketpair bridge architecture does not support inbound connections -- each accepted connection would need a new socketpair + ADDFD injection into the tracee.

(b) sendmsg allow-list removal: sendmsg is BPF allow-listed because the supervisor uses SCM_RIGHTS for pre-exec FD passing. Guest sendmsg with msg_name (unconnected UDP destination) bypasses the supervisor entirely and the destination address is lost on the AF_UNIX socketpair. Control-message semantics are also affected.

(c) Dedicated TCP regression test: integration tests exercise TCP via shell-level wget, but no dedicated guest test binary validates the connect/send/recv path directly in CI.

Proposed Changes

Phase 1 -- TCP regression test (low risk, immediate CI value):

• Add net-tcp-test.c guest binary: connect to a known TCP endpoint (e.g., SLIRP gateway), send request, verify response.

Phase 2 -- pidfd_getfd migration:

• Replace SCM_RIGHTS with pidfd_getfd() (Linux 5.6+) or /proc/<pid>/fd/ for pre-exec FD passing, removing the need to BPF allow-list sendmsg.
• Intercept sendmsg in the dispatcher, extract msg_name and control messages, forward to LKL for unconnected UDP and ancillary data.

Phase 3 -- Server sockets:

• Implement forward_listen(): forward to LKL, register listening socket with SLIRP event loop.
• Implement forward_accept()/forward_accept4(): on LKL accept, create new socketpair, register with event loop, inject into tracee via ADDFD.
• Add SLIRP port forwarding configuration (host:port -> guest:port mapping).

Considerations

• Phase 1 is self-contained and can land independently
• Phase 2 requires pidfd_getfd (Linux 5.6+); verify this aligns with kbox's minimum supported kernel version
• Phase 3 is architecturally complex: N concurrent bridges per listening socket, accept queue backpressure, event loop scaling
• MAX_SHADOW_SOCKETS=64 in net-slirp.c is a scaling constraint for server workloads with many concurrent connections; Phase 3 may need to raise or dynamically grow this
• ICMP: SLIRP can synthesize localhost replies without special capabilities; external ping requires CAP_NET_RAW

References

• src/seccomp-dispatch.c : shadow socket bridge architecture comment; forward_bind() (already implemented); socket syscall dispatch table (no listen/accept entries)
• src/seccomp-bpf.c : sendmsg allow-list with SCM_RIGHTS justification
• src/net-slirp.c : MAX_SHADOW_SOCKETS=64
• tests/guest/net-dns-test.c : existing UDP DNS test
• scripts/run-tests.sh : shell-level TCP coverage via wget

[frank0988]

Phase 1 — TCP Test

NEW: kbox/tests/guest/net-tcp-test.c

after net-dns-test.c:

• socket(AF_INET, SOCK_STREAM, 0) -> connect() to the SLIRP gateway (10.0.2.2:80)

• Send a minimal HTTP GET request

• recv() response, verify HTTP status line prefix (e.g. HTTP/1.)

• Uses poll() with a timeout (3-5 seconds) to avoid hanging on failure

• Same CHECK() macro pattern as net-dns-test.c

• Prints PASS: net_tcp_test on success, exits non-zero on failure

MODIFY: kbox/scripts/run-tests.sh

Add net-tcp-test

Phase 2 — sendmsg Interception

Replace SCM_RIGHTS with pidfd_getfd() for pre-exec FD passing, then intercept sendmsg in the dispatcher.

MODIFY: kbox/src/seccomp-supervisor.c

Try cal pidfd_open(),if -ENOSYS, then use proc//fd

MODIFY: kbox/src/seccomp-bpf.c

• Remove sendmsg from the allow-list

MODIFY: kbox/src/seccomp-dispatch.c

• Add state tracking for socket types. Intercept socket() to record whether an FD is . This avoids relying solely on msg_namefor UDP sockets.

• Add forward_sendmsg() handler:

• Extract msg_name and msg_control (ancillary data) from tracee memory.

• Traverse the shadow_list to lookup the FD and determine its sock_type.

• For SOCK_DGRAM sockets (UDP): forward to LKL via kbox_lkl_sendto() (pass msg_name if present, or NULL if it is a connected UDP socket).

• For SOCK_STREAMsockets (TCP): forward via existing socketpair bridge (connected sockets).

• Forward any control messages (ancillary data) appropriately.

• Register forward_sendmsg() in the socket syscall dispatch table.

Phase 3 — Server Sockets (listen + accept)

Replace the fixed-size shadow_sockets[64] array with a Linux kernel-style linked list. Add a list.h header (kernel list_head macros) and embed a struct list_head in each shadow_socket. Each accept() dynamically allocates a new entry — no fixed upper bound.

• register: malloc + list_add().

• deregister: list_del() + free().

• event loop pump: list_for_each_entry_safe(). O(N_active), no scanning of empty slots.

NEW: include/kbox/list.h

Linux kernel-style list_head macros。

MODIFY: kbox/src/net-slirp.c

• Remove shadow_sockets[MAX_SHADOW_SOCKETS] flat array and MAX_SHADOW_SOCKETS constant

• Add struct list_head member to shadow_socket, add LIST_HEAD(shadow_list) global

• Rewrite kbox_net_register_socket(): malloc a shadow_socket, list_add() into shadow_list

• Rewrite kbox_net_deregister_socket(): list_del() + close supervisor_fd + free

• Rewrite pump_shadow_sockets(): list_for_each_entry_safe() instead of scanning fixed array

• Add SLIRP port-forwarding configuration (host:port -> guest:port mapping) for inbound connections

MODIFY: kbox/src/seccomp-dispatch.c

Add two new dispatch handlers:

forward_listen():

• Forward listen() to LKL via kbox_lkl_listen()

• Register the listening socket with the SLIRP event loop for incoming connection events

forward_accept()/ forward_accept4():

• Call kbox_lkl_accept() on the LKL-side listening socket → new_lkl_fd

• Create a new socketpair(AF_UNIX, SOCK_STREAM)

• Inject one end into the tracee via SECCOMP_IOCTL_NOTIF_ADDFD (Unified kernel-native mechanism)

• kbox_net_register_socket(new_lkl_fd, sp[0], SOCK_STREAM): Call malloc and list_add() to register the new socket into the shadow_list.

• Return the injected FD to the tracee

MODIFY: kbox/src/lkl-wrap.c / kbox/src/lkl-wrap.h

Add LKL wrappers:

• kbox_lkl_listen() — forward listen syscall

• kbox_lkl_accept() / kbox_lkl_accept4() — forward accept syscalls

MODIFY: kbox/src/net.h

Add API for listening socket registration and port-forwarding configuration.

---

Verification Plan

Phase 2

• Verify the BPF allow-list no longer includes sendmsg (new BPF program length matches ALLOW_COUNT=2)

• Verify pre-exec FD handshake works without SCM_RIGHTS (all existing tests pass)

• Test UDP sendmsg with destination address via a guest test

Phase 3

• Test bind() + listen() + accept() in a guest test binary: start a server socket, connect from same guest process via loopback

• Verify port-forwarding config: host connects to forwarded port, guest accepts

• Stress test with more than 64 connect

[jserv]

Phase 1 — TCP Test

• socket(AF_INET, SOCK_STREAM, 0) -> connect() to the SLIRP gateway (10.0.2.2:80)
• Send a minimal HTTP GET request
• recv() response, verify HTTP status line prefix (e.g. HTTP/1.)
• Uses poll() with a timeout (3-5 seconds) to avoid hanging on failure
• Same CHECK() macro pattern as net-dns-test.c
• Prints PASS: net_tcp_test on success, exits non-zero on failure

As network performance is a key factor for kbox, it is vital to validate it through experiments using iperf3 and netperf, along with CI/CD integration.

[frank0988]

TCP TEST amendment

Existing tcp test only use wget to fetch a file from the internet. To enhance the test and performance validation, we will add a iperf3 test and netsurf test.

Test Architecture (SLIRP Topology)

 +---------------------------------------------------------------+
 |                        kbox process                           |
 |                                                               |
 |  [ Guest / Tracee ]            [ Seccomp Supervisor ]         |
 |  +--------------+              +---------------------------+  |
 |  | iperf3 -c    |              | LKL Netstack (10.0.2.15)  |  |
 |  | netsurf      |              |          |                |  |
 |  +--------------+              |      [ SLIRP ]            |  |
 |         | (syscall intercept)  |          |                |  |
 |         v                      +----------+----------------+  |
 |  [ seccomp dispatch ]---------------------+                   |
 +-------------------------------------------|-------------------+
                                             | (Host Sockets)
                                             v
                                  +---------------------------+
                                  | Host (Native CI Runner)   |
                                  | [10.0.2.2 -> 127.0.0.1]   |
                                  |                           |
                                  | iperf3 -s                 |
                                  | python3 http.server       |
                                  +---------------------------+

iperf3 Test

• Host Start iperf3 -s -p 5201 -j natively on the CI runner in the background.
• Guest Cliet Run kbox -- iperf3 -c 10.0.2.2 -p 5201 -t 5 to connecting to the SLIRP gateway.

iperf3 will output a json showing the data transferred and the average bitrate . In CI, we can parse this bitrate to validate the performance .

netsurf TCP Validation

• Host Server: Start a lightweight native web server on the CI runner hosting a static test page and assets.
• Guest Clien: Run kbox -- netsurf http://10.0.2.2:8080/ to fetch page
• netsurf will fetch the HTML page via multiple concurrent TCP connections. If the complex TCP state machine in LKL/SLIRP has bugs, netsurf will hang or crash.

[jserv]

TCP TEST amendment
Existing tcp test only use wget to fetch a file from the internet. To enhance the test and performance validation, we will add a iperf3 test and netsurf test.

Replace 'netsurf' with netperf.

[frank0988]

Thanks for the clarification，using netsurf was really confusing

netperf TCP Validation

• Host Server: Start netserver natively on the CI runner in the background.
• Guest Client: Run kbox -- netperf -H 10.0.2.2 -t TCP_RR to perform TCP request/response tests..netperf will stress and test latency.

[jserv]

Go ahead and proceed with completing the implementation.

[frank0988]

I have implemented the TCP regression tests，and then iperf3 currently returns Function not implemented due to kbox missing interceptions for the select syscall, and netperf times out because it hits a known UBSAN misaligned address issue inside minislirp/tcp_input.c." Is both issue tolerated in test?

[jserv]

iperf3 currently returns Function not implemented due to kbox missing interceptions for the select syscall, and netperf times out because it hits a known UBSAN misaligned address issue inside minislirp/tcp_input.c." Is both issue tolerated in test?

Resolve pre-existing issues as your incoming contributions. We are here solving problems in real-world.