Project Structure

tools/
  registry.py          # canonical platform/syscall registry (single source of truth)
  generate.py          # generates all derived files from registry
  stage_blobs.py       # copies bazel outputs into Python package tree
  fmt.py               # format all C and Python files
  lint.py              # ruff + lizard repo lint entrypoint
  quality_paths.py     # shared staged-file filtering for repo quality tools
  c_lint_check.sh      # clang-tidy wrapper for full C lint

src/
  include/picblobs/
    arch.h             # [generated] architecture trait macros
    types.h            # portable types (no libc)
    syscall.h          # [generated] dispatcher to per-arch asm
    syscall/           # per-arch syscall primitives (hand-written)
    section.h          # section placement macros + MIPS trampoline
    reloc.h            # MIPS GOT self-relocation
    picblobs.h         # [generated] convenience header
    os/                # OS selection headers (linux.h, freebsd.h, windows.h)
    sys/               # [generated] per-syscall modules
    win/               # Windows PEB/TEB walk, DJB2 hash, PE export parsing
    crypto/            # TweetNaCl header-only crypto (tweetnacl.h, randombytes.h)
  payload/             # blob source files (hello.c, hello_windows.c, nacl_*.c)
  linker/blob.ld       # custom linker script

tests/runners/
  linux/
    runner.c           # [generated] Linux test runner dispatcher
    start/             # per-arch _start stubs (hand-written, 9 arches)
  windows/
    runner.c           # [hand-written] mock TEB/PEB environment
    start/             # per-arch _start stubs (x86_64, i386, aarch64)
  freebsd/
    runner.c           # [generated] Linux-hosted FreeBSD syscall shim
    start/             # per-arch _start stubs

release/
  BUILD.bazel          # aggregate target: //release:full

python/
  picblobs/
    __init__.py        # public API: get_blob(), list_blobs(), BlobData
    _extractor.py      # runtime .bin + JSON sidecar loading
    runner.py          # QEMU execution orchestration
    _blobs/            # build-time staged .so files, consumed by extract_release.py
    blobs/             # runtime .bin + .json sidecar artifacts
    manifest.json      # runtime catalog (authoritative blob index)
  tests/
    conftest.py        # pytest config, fixtures, markers, env filters
    test_payload_*.py  # payload execution tests (per category)
    test_extractor.py  # sidecar loading tests
    test_freebsd_syscall_wrapper.py
    test_packaging_metadata.py
    test_python_api.py
    test_quality_paths.py
    test_release_loading.py
    test_runner.py     # QEMU runner tests
    test_sync.py       # registry sync/consistency tests

python_cli/
  picblobs_cli/
    cli.py             # click command tree for picblobs-cli
    _runners/          # bundled FreeBSD/Windows runners
    _test_binaries/    # verifier-only binaries, currently ul_exec fixtures
  tests/
    test_picblobs_cli.py

kernel/                # kernel-mode tools and exercises (red team lab)
  ebpf/
    loader.py          # eBPF userspace blob injection (ptrace + uprobe trigger)
    kernel_loader.py   # eBPF kernel-context injection (bpf_probe_write_user)
    kernel_mem.py      # kernel memory exploration (task walk, cred dump, KASLR)
    kernel_prog.py     # custom kernel programs (syscall monitor, XDP, keylog)
  kmod/
    pic_kmod.c         # PIC blob loader (kprobes symbol resolution, stealth)
    pic_kblob.c        # kernel blob loader helpers
    examples/
      kshell.c         # plaintext kernel reverse shell
      kshell_nacl.c    # NaCl-encrypted kernel reverse shell (embedded TweetNaCl)
      tweetnacl_kernel.h  # XSalsa20+Poly1305 for kernel (2.6+ compatible)
      blob_ctx.h       # context struct for PIC blobs (!kload callback API)
      pic_hook.c       # demo blob that sends output through kshell
      b64_kernel.h     # base64 decoder for kernel file transfer
      nop_sled.S       # minimal ring 0 test blob
      hello_ring0.S    # printk from ring 0
      who_am_i.S       # read task_struct from ring 0
  lp/
    listener.py        # operator listening post (plaintext + NaCl modes)
  vm/
    vm_harness.py      # hermetic QEMU VM test harness (Alpine + Ubuntu)
    patch_vermagic.py  # binary vermagic patcher for cross-version loading
  BUILD.bazel          # bazel VM test targets (ubuntu_suite, alpine_suite)
  lab.md               # full lab guide with 19+ exercises

spec/                  # requirements, architecture decisions, verification specs

testall                # run the full test suite
buildall               # build and stage all platforms
sourceme               # set up dev environment (source this)
lefthook.yml           # git hook policy for local formatting and lint