Skip to content
All posts
2 min readtebakopackagingtutorial

Advanced payloads: Trace: see what your payload touches (1 of 5)

The advanced payloads series: trace: see what your payload touches.

The Tebako team

github.com/tamatebako
Note

Post 1 of 5 in the series Advanced payloads.

● ○ ○ ○ ○

  1. Advanced payloads: Trace: see what your payload touches (this post)

  2. Advanced payloads: Jails and profiles: decide what it may touch

  3. Advanced payloads: The image toolbox

  4. Advanced payloads: Runtimes and native code

  5. Advanced payloads: packed-mn: one download, any document
Note

Reference guide: Trace a packaged app.

The advanced series picks up where the basics ended. Its first subject is the question every packaged application eventually raises: what the payload actually touches on the machine. The tebako trace commands answer it with evidence rather than guesses.

trace cover and payload checks tebako trace cover — what escaped the mounts inside stream TEBAKO_TRACE=*.jsonl outside capture retrace / procmon tebako trace cover outside minus inside escapes: files touched below the mounts, straight on the host exit 0 = no escapes · exit 1 = the list tebako check — does the payload work the manifest declares checks: entry, fixtures, expect tebako check runs the real entrypoint PASS behavior is right SKIP prerequisite missing FAIL exit 79, reason named a check fails only when its prerequisites are present and its behavior is wrong verification proves the bytes — a check proves the payload works

Figure 1 — Trace cover compares an outside capture with the inside stream, and a payload check declares its own acceptance test (covered in the publish post of the basics series).

Arm the stream

One environment variable records every decision the runtime makes — each mount, open, dlopen, exec, and jail verdict — as structured JSON, identically on Linux, macOS, and Windows:

$ TEBAKO_TRACE=/tmp/capture.jsonl ./myapp build

Tracing can never change how an application runs: if the capture channel fails, tebako prints a warning and nothing else happens.

Draft a policy from a real run

tebako trace run records a run and drafts the manifest fragment — the host paths touched, the files read through raw descriptors, the libraries loaded:

$ tebako trace run ./myapp --capture run.jsonl --out draft.yaml -- build
$ cat draft.yaml
needs:
  host:
    - path: $HOME/.fontist
      access: rw
      why: ""

The draft is commented YAML. The operator reviews it, adjusts read and write access, and fills in every why — exactly the grant grammar that the next post binds.

Name the failing step

When a run misbehaves, tebako trace explain replays the capture through the chain of steps a file access passes — mount, manifest read, resolve, materialize, OS bind — and names the first step that failed. Exit 0 is a clean chain; exit 1 names the step.

What you can do now

This post has shown what a payload touches, drafted its policy from a real run, and diagnosed a failure to a named step. The next post binds that policy.

Note

Continue with part 2 of 5: Jails and profiles: decide what it may touch.