How AgentSight finds TLS attach targets in threaded Docker process trees

Direct answer: container identity is not TLS executable identity

For --binary-path docker://name, AgentSight first runs docker inspect to resolve the container's host init PID. It searches that process and its descendants for an executable embedding SSL or a loaded libssl.so, then returns an attach path for the TLS uprobe. This is necessary for a layout such as tini launching node: the wrapper itself does not contain the relevant SSL code.

The v1.0.35 fix in product PR #246 addresses a less obvious case. On Linux, /proc/<pid>/task/<tid>/children describes children forked by one particular thread. Reading only /proc/<pid>/task/<pid>/children can miss a worker's child even when it belongs to the same process. AgentSight now checks every thread's children file for each visited process.

This is a source-level study of released AgentSight v1.0.35 at product commit c1574366122a90c451bca6a84713e28813ab95e2, reviewed on 27 October 2026. It does not claim a new container experiment, live TLS capture, or measured coverage from this article's author.

From Docker reference to an SSL attach target

The resolver accepts docker://name,docker:name, and container IDs. Invalid empty and slash-separated Docker references fail validation. The Docker lookup uses docker inspect --format to read .State.Pid, rejecting PID zero as a stopped container. A running tree without any candidate produces a different no-SSL-target error.

For each queued PID, find_ssl_target_in_treefirst checks /proc/<pid>/exe for embedded SSL markers. If none match, it checks /proc/<pid>/maps for a mapped libssl.so and resolves the library path under /proc/<pid>/root. If neither matches, it appends the child PIDs. A VecDeque maintains the breadth-first walk and a HashSet prevents revisiting a PID.

The new helper child_pids enumerates numeric thread IDs under /proc/<pid>/task, sorts the main thread first, then reads each thread's children file. Unreadable entries are skipped. Main-thread-first ordering preserves the former single-threaded preference, but searching all threads prevents the leader-only omission. The output is the first SSL candidate found, not a comprehensive list of every TLS-using child.

Eight cases that change an empty-capture diagnosis

These are implementation-derived cases, not measured success rates. A resolved target alone does not prove that sslsniff attached to correct symbols or offsets, that the runtime used that particular TLS library, or that HTTP/LLM parsing succeeded.

What the worker-thread regression tests actually establish

Before product PR #246, the walker only read the leader's children list. The patch adds three tests: a synthetic process whose main thread forked nothing while worker threads forked children; an ordering and missing-file fixture; and a live local Linux test that spawns sleep from a worker thread. The last test verifies that leader-only enumeration misses the child while the all-thread helper finds it. It skips if the kernel lacks the required proc children interface.

These are first-party tests for process discovery. They do not assert an end-to-end Docker/OpenClaw TLS transaction, HTTP/2 decoding, or a completed model request. The change does not install a continuous process watcher, alter Docker's container API, or modify the subsequent TLS parser. A probe failure after selecting the correct PID is a separate issue.

A bounded, read-only check on your own Linux host

With authorization to inspect a disposable container, compare the container init leader's children against the children listed by all of its threads. This diagnostic illustrates one traversal level, not AgentSight's full recursive search.

# Run on an authorized Linux Docker host
init_pid=$(docker inspect --format '{{.State.Pid}}' openclaw)
printf 'init host PID: %s\n' "$init_pid"
printf 'leader children: '
cat "/proc/$init_pid/task/$init_pid/children" 2>/dev/null || true
for task in "/proc/$init_pid"/task/*; do
  [ -d "$task" ] || continue
  printf 'TID %s children: ' "$(basename "$task")"
  cat "$task/children" 2>/dev/null || true
  printf '\n'
done

Replace openclaw with a container you control. A child found under a worker thread but absent from the leader list reproduces the old discovery blind spot. Repeat while the agent is active: tasks may start or exit between /procreads, and access permissions can hide entries. No sample output is invented or presented as a run performed here.

For end-to-end recording, the pinned product README documents sudo agentsight record -c node --binary-path docker://openclaw. Check the resolved host PID and attach path before investigating decrypted traffic. Installation and detailed flags belong to the canonical AgentSight documentation.

Limits and boundaries that matter in a real audit

This discovery is a snapshot of the process tree. A child that starts later, exits, or has an unreadable task file can be missed. A multithreaded container may also have several possible SSL executables, while the resolver selects only its first match. Docker CLI availability, kernel permissions and supported TLS implementations determine whether attachment is possible.

Process selection is different from process-event scope. The PID namespace article explains scope filtering, while the Docker native-session article describes a separate container JSONL bridge without relying on the same TLS probe discovery. If an attach succeeded but paired HTTP requests are missing, consult the HTTP correlation reference.

Root-level process inspection and eBPF permissions remain sensitive; a docker:// reference is not a security isolation mechanism. Recorded runs may contain prompts, responses, file paths, headers and network targets. Keep raw captures out of public issues and search-facing pages.

Primary references and validation scope

All implementation claims are pinned to v1.0.35 and the merged all-thread traversal patch. This article introduces an eight-case interpretation matrix and a read-only diagnostic but does not claim to have executed that diagnostic or obtained new performance, security or compatibility measurements.

• AgentSight v1.0.35 binary resolver and regression tests
• PR #246: all-thread children traversal and test evidence
• AgentSight OpenClaw Docker target-discovery example
• AgentSight supported-agent command forms
• AgentSight Docker privileges and host process requirements
• AgentSight v1.0.35 release