Skip to content

docs(docs): A maintainer can find the system call that killed a grant worker - #33

Merged
sodre merged 2 commits into
mainfrom
docs/27-sigsys-syscall
Nov 20, 2026
Merged

sodre merged 2 commits into
mainfrom
docs/27-sigsys-syscall

Conversation

@sodre

@sodre sodre commented Nov 20, 2026

Copy link
Copy Markdown
Member

Closes #27

Summary

Nothing changes for anyone running Countersign. A maintainer whose grant worker was killed by the worker sandbox's filter can now find the system call that did it from one section of the developer guide, "A grant worker died of SIGSYS".

docs/develop.md
└── ## A grant worker died of SIGSYS
    ├── journalctl -k | grep type=1326      # the kernel's audit line: syscall=, arch=
    ├── strace -D -f under the runtime test # a wrapper script, and why -D
    ├── number → name per architecture      # ausyscall, or the kernel's tables
    └── where a new allow-list entry goes   # ALLOWED or conditional, with its reason

Choices the ticket left open, and where the section departs from its words:

  • The reason for -D. The ticket says the runtime test stops every descendant of the Gateway, and that without -D the tracer is one of them. The tree is the other way round: without -D the process the test starts is strace, the Gateway is its child, and the test stops the Gateway. The section states it as runtime.py has it.
  • A wrapper script. The runtime test starts the Gateway itself, so the strace command of the ticket is given as a wrapper passed to the test in place of the executable.
  • What a first reader would get wrong. The section also says that every audit line on a development host with comm="worker_sandbox-" is the containment test's deliberate kill, that a filter kill prints one +++ killed by SIGSYS +++ per thread, that the runtime test kills one grant worker with SIGSYS itself, and that installing auditd for ausyscall takes the audit lines out of the journal.
  • Branch. The worktree was on the merged branch of The allow-list tells a thread from a new process under clone3 #28, so the work is on a new branch from origin/main.

Evidence

Criterion Ticked Shown by
docs/develop.md has the section, with both commands and why -D is needed yes The section is in the page; the runtime test under strace, with and without -D
It says how to map a system call number to its name on x86-64 and arm64 yes The section is in the page; ausyscall aarch64 56 and ausyscall x86_64 56
mkdocs build --strict passes yes python -m mkdocs build --strict
Test Red Green
The section is in the page Before the edit, grep -c 'A grant worker died of SIGSYS|strace -D|ausyscall' docs/develop.md printed 0 and exited 1 ok: the heading is in docs/develop.md and in the built develop/index.html

All on the last commit's text, on an arm64 Ubuntu 24.04 host, kernel 6.17, strace 6.8:

  • python -m mkdocs build --strict, mkdocs 1.6.1 from requirements-docs.txt: Documentation built, exit 0.
  • journalctl -k | grep type=1326, as a member of adm, no root: audit lines with sig=31 arch=c00000b7 syscall=56. All of them had comm="worker_sandbox-".
  • The runtime test under strace, with and without -D: tests/runtime.py given a wrapper that runs strace -D -f -o <file> <gateway> "$@" passed its sidecar part and wrote traces that follow into the grant workers (execve("/worker", ["/worker", "grant-worker"]), then failed one timing assertion of the shared part, site.cutoff.wait(1). The Correctness reviewer's run of the section's wrapper passed whole and wrote three trace files. The same wrapper without -D ran until timeout 180 killed it. Untraced, the test passes.
  • strace -f of the worker_sandbox test binary: each thread of a killed process has its own +++ killed by SIGSYS +++ line, and the killed openat is in the lines before the first.
  • ausyscall aarch64 56 printed openat, ausyscall x86_64 56 printed clone and ausyscall x86_64 257 printed openat, from the auditd package of Ubuntu 24.04, unpacked and not installed. /usr/include/asm-generic/unistd.h has #define __NR_openat 56.
  • Both kernel links answer 200.

Not run: reading the x86-64 header at /usr/include/x86_64-linux-gnu/asm/unistd_64.h and an audit line with arch=c000003e, since the host is arm64 (the value is AUDIT_ARCH in worker_sandbox.rs); and installing auditd to watch the audit lines leave the journal.

Merge Danger

Door: two-way. A revert removes the section.

Blast Radius: the handbook's developer page.

The merge changes no source, image or workflow. The next version tag publishes the page with the handbook. No flag.

Reviews

Correctness, Standards and Spec, two rounds; Security once: 15 findings in round 1, none in round 2

Round 1 pinned b548f60, round 2 pinned 5dc63d9. Security ran because the repository has no list of security control paths to read; it reports nothing on documentation.

Correctness, round 1

  1. "The line above +++ killed by SIGSYS +++ is the killed call" is wrong for most threads, and the runtime test kills one grant worker with SIGSYS itself. Fixed: the section says a kill ends every thread, to look for the call the audit line named, and how the test's own kill is marked.
  2. Installing auditd for ausyscall starts the audit daemon, which takes the audit lines out of the journal. Fixed: the section says so, and gives the kernel's tables as the other way.
  3. The sample audit line is the containment test's, and nothing told a grant worker's line from those. Fixed: the section says whose line it is and that comm="worker_sandbox-" marks them.
  4. The x86-64 header exists only on an x86-64 host. Fixed: links to the kernel's two tables, for reading across architectures.
  5. The opening sentence left out clone3, and the last paragraph assumed a kill always means a missing entry. Fixed: clone3 is named, and a call already in conditional means an argument failed its test.
  6. The reason for -D had the process tree backwards. Fixed.
  7. python where the test's usage line says python3, and the test's other requirements were not named. Fixed.

Standards, round 1

  1. The reason for -D had the process tree backwards. Fixed.
  2. The opening sentence overstated the kill rule. Fixed.
  3. "The argument-checked list below it" named no identifier. Fixed: conditional, in allow_list.
  4. The sample audit line is not a grant worker's. Fixed.
  5. Bare "worker" where the glossary's term is grant worker. Fixed.
  6. python where the page uses python3. Fixed.
  7. The heading states a symptom, where the page's other headings are tasks. Pushed back: the ticket names the heading, and a maintainer searches for the symptom.

Spec, round 1

  1. The reason for -D is the wrong way round, as in the ticket's own words. Fixed.

Tracking

Epic: E1 Run grant workers in a filter sandbox on hosts without namespaces
Spec: #21 Run grant workers in a filter sandbox on hosts without namespaces
Ticket: #27 A maintainer can find which system call the worker sandbox's filter killed
Flag: none

🤖 Generated with Claude Code

sodre and others added 2 commits November 19, 2026 23:04
…illed (#27)

docs/develop.md gains "A grant worker died of SIGSYS": the kernel audit
line, tracing the Gateway under the runtime test with strace -D, mapping
the number to a name per architecture, and where a new allow-list entry goes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…trace and the journal hold (#27)

Review round 1: without -D the Gateway is the tracer's child, not the
other way round; a filter kill ends every thread; the sample audit line is
the containment test's; auditd takes the lines out of the journal; clone3
and argument-checked calls; the kernel's tables for a foreign architecture.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@sodre
sodre marked this pull request as ready for review November 20, 2026 04:12
@sodre
sodre merged commit 02dc75f into main Nov 20, 2026
33 of 34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A maintainer can find which system call the worker sandbox's filter killed

1 participant