Repository navigation
docs(docs): A maintainer can find the system call that killed a grant worker - #33
Merged
Merged
Conversation
…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
marked this pull request as ready for review
November 20, 2026 04:12
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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".
Choices the ticket left open, and where the section departs from its words:
-D. The ticket says the runtime test stops every descendant of the Gateway, and that without-Dthe tracer is one of them. The tree is the other way round: without-Dthe process the test starts isstrace, the Gateway is its child, and the test stops the Gateway. The section states it asruntime.pyhas it.stracecommand of the ticket is given as a wrapper passed to the test in place of the executable.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 withSIGSYSitself, and that installingauditdforausyscalltakes the audit lines out of the journal.origin/main.Evidence
docs/develop.mdhas the section, with both commands and why-Dis neededstrace, with and without-Dausyscall aarch64 56andausyscall x86_64 56mkdocs build --strictpassespython -m mkdocs build --strictgrep -c 'A grant worker died of SIGSYS|strace -D|ausyscall' docs/develop.mdprinted0and exited 1docs/develop.mdand in the builtdevelop/index.htmlAll 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 fromrequirements-docs.txt:Documentation built, exit 0.journalctl -k | grep type=1326, as a member ofadm, no root: audit lines withsig=31 arch=c00000b7 syscall=56. All of them hadcomm="worker_sandbox-".strace, with and without-D:tests/runtime.pygiven a wrapper that runsstrace -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-Dran untiltimeout 180killed it. Untraced, the test passes.strace -fof theworker_sandboxtest binary: each thread of a killed process has its own+++ killed by SIGSYS +++line, and the killedopenatis in the lines before the first.ausyscall aarch64 56printedopenat,ausyscall x86_64 56printedcloneandausyscall x86_64 257printedopenat, from theauditdpackage of Ubuntu 24.04, unpacked and not installed./usr/include/asm-generic/unistd.hhas#define __NR_openat 56.Not run: reading the x86-64 header at
/usr/include/x86_64-linux-gnu/asm/unistd_64.hand an audit line witharch=c000003e, since the host is arm64 (the value isAUDIT_ARCHinworker_sandbox.rs); and installingauditdto 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
+++ killed by SIGSYS +++is the killed call" is wrong for most threads, and the runtime test kills one grant worker withSIGSYSitself. 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.auditdforausyscallstarts 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.comm="worker_sandbox-"marks them.clone3, and the last paragraph assumed a kill always means a missing entry. Fixed:clone3is named, and a call already inconditionalmeans an argument failed its test.-Dhad the process tree backwards. Fixed.pythonwhere the test's usage line sayspython3, and the test's other requirements were not named. Fixed.Standards, round 1
-Dhad the process tree backwards. Fixed.conditional, inallow_list.pythonwhere the page usespython3. Fixed.Spec, round 1
-Dis 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