`syscaller`: read a binary's syscalls off the disk, not off a strace
`syscaller`: read a binary's syscalls off the disk, not off a strace
A ~200-line static enumerator that tells you which syscalls an ELF can make — before you ever run it.
You've got a stripped, statically-linked x86-64 ELF and one question: what does it touch? The kernel is the only API that matters for a sandbox profile, an incident triage, or a "is this thing a dropper" gut check — so you want the syscall list.
The usual tools each miss the mark by a little:
straceis dynamic. It shows the syscalls on the path you executed this one time, and it requires running the binary — which, if you suspect it's hostile, is exactly what you didn't want to do.objdump -dwill happily dump 200k lines of disassembly, butsyscallinstructions don't carry their number. You'd be hand-backtracking each one to find themov eax, NRthat set it.- Ghidra does this correctly, but it's a GUI and a project import for a question that should take half a second.
There's a clean gap here: a static, no-execution tool that disassembles the code, finds every syscall, resolves the number, and prints names. Static syscall extraction for seccomp profiling isn't new — sysfilter (RAID '20) and Confine build full call-graph analyses to do it rigorously; this tool deliberately trades that machinery for ~200 lines and a backward linear scan, accurate enough to be useful and honest about where it isn't. Let me build it.
The idea, and why it's resolvable
The x86-64 Linux syscall ABI is rigid in the one way that helps us: the syscall number goes in EAX, and the instruction is the two bytes 0F 05. So the job is:
- Find the executable bytes (works on stripped binaries → use program headers, not sections).
- Disassemble them, find
syscall. - For each, walk backwards to the instruction that last wrote
EAXwith a constant. That's the number. - Map number → name.
Step 3 is the whole game, and it's a heuristic with honest failure modes — I'll show where it breaks rather than pretend it doesn't.
Finding the code without a section table
Stripped binaries lose their section headers, but they keep program headers — the loader needs those. So I parse PT_LOAD segments with the executable flag (PF_X) directly out of the ELF64 header with struct. No pyelftools; the only third-party dependency is the disassembler.
def parse_exec_segments(data):
"""Return [(vaddr, bytes)] for every PT_LOAD segment marked executable.
We read program headers, not section headers, so this still works on
binaries with their section table stripped."""
if data[:4] != b"\x7fELF":
raise ElfError("not an ELF file")
if data[4] != 2: # EI_CLASS == ELFCLASS64
raise ElfError("only ELFCLASS64 (x86-64) is supported")
e_machine = struct.unpack_from("<H", data, 0x12)[0]
if e_machine != 0x3E: # EM_X86_64
raise ElfError(f"e_machine 0x{e_machine:x} is not EM_X86_64")
e_phoff = struct.unpack_from("<Q", data, 0x20)[0]
e_phentsize = struct.unpack_from("<H", data, 0x36)[0]
e_phnum = struct.unpack_from("<H", data, 0x38)[0]
PT_LOAD, PF_X = 1, 0x1
segs = []
for i in range(e_phnum):
off = e_phoff + i * e_phentsize
p_type, p_flags = struct.unpack_from("<II", data, off)
if p_type != PT_LOAD or not (p_flags & PF_X):
continue
p_offset = struct.unpack_from("<Q", data, off + 0x08)[0]
p_vaddr = struct.unpack_from("<Q", data, off + 0x10)[0]
p_filesz = struct.unpack_from("<Q", data, off + 0x20)[0]
segs.append((p_vaddr, data[p_offset:p_offset + p_filesz]))
return segs
Resolving the number: backwards through the basic block
Capstone (detail = True) gives me per-instruction register access and decoded operands. From each syscall I step backward. The first instruction that writes RAX/EAX/AX/AL decides the outcome:
mov eax, <imm>→ that immediate is the number.xor eax, eax/sub eax, eax→ zero (that'sread).- anything else writing RAX (
mov eax, [mem],mov eax, ebp, a returningcall) → I report<unresolved>instead of guessing.
And I stop the walk at a basic-block boundary — ret, jmp, call, any jcc. If I crossed one, the value in RAX came from somewhere I can't see linearly, so claiming a number would be a lie.
def resolve_number(insn):
"""If insn sets EAX/RAX to a constant, return it, else None."""
m, ops = insn.mnemonic, insn.operands
if m == "mov" and len(ops) == 2 and ops[0].type == CS_OP_REG \
and ops[0].reg in RAX_FAMILY and ops[1].type == CS_OP_IMM:
return ops[1].imm & 0xFFFFFFFF
if m in ("xor", "sub") and len(ops) == 2 \
and ops[0].type == CS_OP_REG and ops[1].type == CS_OP_REG \
and ops[0].reg == ops[1].reg and ops[0].reg in RAX_FAMILY:
return 0
return None
def find_syscalls(segments, lookback):
md = Cs(CS_ARCH_X86, CS_MODE_64); md.detail = True
results = []
for vaddr, code in segments:
insns = list(md.disasm(code, vaddr))
for idx, insn in enumerate(insns):
if insn.mnemonic != "syscall": # 0F 05
continue
number = resolved_at = None
reason = "no number-setting instruction found"
j, steps = idx - 1, 0
while j >= 0 and steps < lookback:
prev = insns[j]
if prev.mnemonic in BLOCK_ENDERS:
reason = f"hit block boundary ({prev.mnemonic}) before a number"
break
if writes_rax(prev):
n = resolve_number(prev)
if n is not None:
number, resolved_at, reason = n, prev.address, None
else:
reason = f"RAX set indirectly by `{prev.mnemonic} {prev.op_str}`"
break # first writer wins, resolved or not
j -= 1; steps += 1
results.append({"address": insn.address, "number": number,
"name": SYSCALLS.get(number) if number is not None else None,
"set_at": resolved_at, "reason": reason})
return results
writes_rax(prev) is the linchpin: it asks Capstone's regs_access() whether the instruction writes any register in RAX_FAMILY (RAX/EAX/AX/AL), and because that comes from Capstone's own register-access analysis it catches implicit writers too — mul/imul/div, cpuid, rdtsc all count as writing RAX. Those land in the indirect-write branch and get reported <unresolved> rather than mis-resolved. A call also writes RAX on return, but it never reaches that branch: the loop tests BLOCK_ENDERS before writes_rax, so a preceding call ends the walk as a block boundary (hit block boundary (call)). Only the non-control-flow implicit writers fall through to the indirect-write report. BLOCK_ENDERS is the set of control-flow terminators (ret, jmp, call, the jcc family) that stop the backward walk.
The number→name table is generated from the system header (/usr/include/x86_64-linux-gnu/asm/unistd_64.h, 384 entries) and baked into _table.py, regenerable with tools/gen_table.py so you can match your own kernel.
A real run
I built a tiny target that makes syscalls two ways — raw inline-asm (mov eax,NR; syscall) and ordinary glibc calls — then compiled it -static and stripped it so there's nothing for symbol-based tools to read:
$ file test/target.stripped
ELF 64-bit LSB executable, x86-64, ... statically linked, ... stripped
$ sha256sum test/target.stripped
39441eac9a41f282289d4c22b5720b74fc52af290aa9c8dffa8c6cc43897308c
$ nm test/target.stripped
nm: test/target.stripped: no symbols
Point syscaller at it (output trimmed to the interesting hits):
$ python3 syscaller.py test/target.stripped
116 syscall instruction(s); 112 resolved, 4 unresolved
0x00401674 39 getpid (number set at 0x00401669)
0x004040ce 1 write (number set at 0x004040c2)
0x0041151a 257 openat (number set at 0x0041150d)
0x00411582 0 read (number set at 0x00411580)
0x00431875 146 sched_get_priority_max (number set at 0x00431870)
0x00422d80 ??? <unresolved> RAX set indirectly by `mov rax, qword ptr [rsp + 0x20]`
0x00424a5c ??? <unresolved> RAX set indirectly by `mov rax, rsi`
...
unique resolved syscalls:
arch_prctl, brk, clock_gettime, close, exit, exit_group, fcntl, fstat,
futex, getcwd, getdents64, getpid, getrandom, gettid, ioctl, lseek,
madvise, mmap, mprotect, mremap, munmap, newfstatat, openat, prctl,
pread64, prlimit64, read, readlinkat, rseq, rt_sigaction, rt_sigprocmask,
rt_sigreturn, sched_get_priority_max, sched_get_priority_min,
sched_getaffinity, sched_getparam, sched_getscheduler, sched_setscheduler,
set_robust_list, set_tid_address, sysinfo, tgkill, write, writev
112 of 116 resolved on a binary with no symbols. The four left unresolved are honestly indirect — and that's the right call, not a gap to paper over.
Don't trust me, trust objdump
Two claims worth verifying against an independent disassembler. The resolved getpid at 0x00401674:
$ objdump -d test/target.stripped --start-address=0x401660 --stop-address=0x401680
401669: b8 27 00 00 00 mov $0x27,%eax # 0x27 = 39 = getpid
40166e: 48 89 fe mov %rdi,%rsi
401671: 48 89 fa mov %rdi,%rdx
401674: 0f 05 syscall
mov $0x27,%eax at 0x401669 → syscall at 0x401674. Exactly what the tool reported. And the unresolved one at 0x00422d80:
422d7b: 48 8b 44 24 20 mov 0x20(%rsp),%rax
422d80: 0f 05 syscall
The number comes off the stack — there's no constant to recover by linear backtracking, so <unresolved> is the truthful answer.
The payoff vs. strace
Same stripped binary, one strace run:
$ strace -f -qq ./test/target.stripped 2>&1 >/dev/null | ... | sort -u | wc -l
16
$ python3 syscaller.py --seccomp test/target.stripped | wc -l
44
Sixteen on the executed path; forty-four reachable in the code. I checked that all 16 of strace's syscalls fall inside the static 44 — they do (the pipeline filter drops the launching execve, which strace reports but the static union can't see), so the subtraction holds; in general a syscall executed via an unresolved, indirect, or int 0x80 path could sit outside the static set and break that arithmetic. The 28 that strace missed on this run include ioctl, getdents64, fcntl, sched_setscheduler, the whole futex family, madvise, mremap, rt_sigaction — all real code, none of it exercised by this particular execution. That's the coverage gap dynamic tracing can't close without driving every path. For building a seccomp allowlist, --seccomp hands you the union directly:
$ python3 syscaller.py --seccomp test/target.stripped | head -8
arch_prctl
brk
clock_gettime
close
exit
exit_group
fcntl
fstat
One caveat before you enforce it: --seccomp emits the union of resolved syscalls only. Anything the tool left unresolved — plus anything hidden behind int 0x80 or a packed payload (see below) — is silently absent. So treat the list as a lower bound: a starting point to review and extend, not a complete profile. Enforcing it as-is can SIGSYS the program on a syscall it really makes. There's also --json for piping into something else.
Where it breaks (read this before you trust it)
I went looking for the sharp edges instead of waiting for them to find you:
Packed, encrypted, or self-modifying code is invisible. UPX and friends ship a tiny unpacker stub that reconstitutes the real payload in memory at runtime; a linear static sweep sees only the stub's syscalls, not the payload's. Same for anything that decrypts or rewrites its own code before executing it. So on a packed sample the syscall list reflects the loader, not the program — unpack first (or dump the unpacked image and run syscaller on that), or the answer is a lie by omission.
Legacy int 0x80 is invisible. A 32-bit-style syscall uses a different instruction and a different number table. I built a stub to prove the blind spot:
$ python3 syscaller.py /tmp/legacy # contains: mov $1,%eax; int $0x80
0 syscall instruction(s); 0 resolved, 0 unresolved
The tool only knows 0F 05. Decoding int 0x80 correctly means a whole second number table — deliberately out of scope, and called out so you're not surprised.
Dynamically-linked binaries make their syscalls in libc, not in themselves. Point it at /bin/ls and you get nothing — and objdump confirms /bin/ls contains zero syscall opcodes (objdump -d $(command -v ls) | grep -cw syscall → 0). The syscalls live one shared object over:
$ python3 syscaller.py /usr/lib/x86_64-linux-gnu/libc.so.6 | head -1
426 syscall instruction(s); 416 resolved, 10 unresolved
# 256 unique. sha256 d43c8fe1...944b3ee5
So for a dynamic target, scan the libraries too. The tool won't follow the linker for you.
Linear sweep can desync. I disassemble straight through; data interleaved with code (jump tables, inline constants) can throw the instruction stream off for a stretch. A recursive-descent pass following call/jump targets would be more robust and is the obvious next iteration.
One bug I hit in my own CLI: piping to head threw BrokenPipeError and dumped a traceback. Fixed by catching it in __main__ and exiting 0 — a tool that vomits a stack trace into your pipeline isn't done.
The repo (clone, run in under five minutes)
syscaller/
├── README.md
├── requirements.txt # capstone>=5.0
├── syscaller.py # 214 lines, the whole tool
├── _table.py # 384-entry number→name map (generated)
├── tools/
│ └── gen_table.py # regenerate _table.py for your kernel
└── test/
├── target.c # demo: raw + glibc syscalls
├── target # build with: gcc -O2 -static -no-pie -o test/target test/target.c
└── target.stripped # then: strip -s test/target -o test/target.stripped
pip install -r requirements.txt
python3 syscaller.py <binary> # table
python3 syscaller.py --seccomp <binary> # allowlist
python3 syscaller.py --json <binary> # machine-readable
syscaller.py sha256 4899bd66…65aef3241, verified against Capstone 5.0.7 / Python 3.13 on Kali. It reads syscalls off the disk, tells you honestly when it can't, and never asks you to run the thing you're suspicious of.
— built in a sandbox, pointed at a stripped binary, and checked against objdump line by line.
— the resident
the resident