git.stella-ops.org/docs/modules/scanner/operations/entrypoint-dynamic-analysis.md

Entry-Point Dynamic Analysis

When we have access to a running container (e.g., during runtime posture checks), Stella Ops augments the static inference with live signals. This document describes the Observational Exec Graph (OEG) that powers the dynamic mode.

1) Goals

• Capture the actual process tree and exec lineage after the container starts.
• Identify steady-state processes (long-lived, listening, non-wrapper) even when supervision stacks are present.
• Feed the same reduction and runtime-classification pipeline as the static analyser.

2) Observational Exec Graph (OEG)

2.1 Data sources

• Tracepoints / eBPF: sched_process_exec, sched_process_fork/clone, and corresponding exit events give us pid, ppid, namespace, binary path, and argv snapshots with minimal overhead.
• /proc sampling: for each tracked PID, capture /proc/<pid>/{exe,cmdline,cwd} and file descriptors (especially listening sockets).
• Namespace mapping: normalise host PIDs to container PIDs (NStgid) so the graph is stable across runtimes.

2.2 Graph model

public sealed record ExecNode(int HostPid, int NsPid, int Ppid, string Exe, string[] Argv, long StartTicks);
public sealed record ExecEdge(int ParentHostPid, int ChildHostPid, string Kind); // "clone" | "exec"

• Nodes represent exec() events (post-exec image) and contain the final argv.
• Edges labelled clone capture forks; exec edges show program replacements.

2.3 Steady-state candidate selection

For each node compute features:

Feature	Rationale
Lifetime (until sampling end)	Long-lived processes are more likely to be the real workload.
Additional execs downstream	Zero execs after start implies terminal.
Listening sockets	Owning LISTEN sockets strongly suggests a server.
Wrapper catalogue hit	Mark nodes that match known shims (tini, gosu, supervisord, etc.).
Children fan-out	Supervisors spawn multiple children and remain parents.

Feed these into a scoring function; retain Top‑K candidates (usually 1–3) along with evidence.

3) Integration with static pipeline

1. For each steady-state candidate, snapshot the command/argv and normalise via ResolvedCommand (as in static mode).
2. Run wrapper reduction and ShellFlow analysis if the candidate is a script.
3. Invoke runtime detectors to classify the binary.
4. Merge dynamic evidence with static evidence. Conflicts drop confidence or trigger the “supervisor” classification.

4) Supervisors & multi-service containers

Some images (e.g., supervisord, s6, runit) intentionally start multiple long-lived processes. Handle them as follows:

• Detect supervisor binaries from the wrapper catalogue.
• Analyse their configuration (/etc/supervisord.conf, /etc/services.d/*, etc.) to enumerate child services statically.
• Emit multiple TerminalProcess entries with individual confidence scores but mark the parent as type = supervisor.

5) Operational hints

• Sampling window: 1–3 seconds after start is usually sufficient; extend in debug mode.
• Overhead: prefer eBPF/tracepoints; fall back to periodic /proc walks when instrumentation isn’t available.
• Security: honour namespace boundaries; never inspect processes outside the target container’s cgroup/namespace.
• Failure mode: if dynamic capture fails, fall back to static mode and flag evidence accordingly ("Dynamic capture unavailable").

6) Deliverables

The dynamic reducer returns an EntryTraceResult populated with:

• ExecGraph containing nodes and edges for audit/debug.
• Terminals listing steady-state processes (possibly multiple).
• Evidence strings referencing dynamic signals ("pid 47 listening on 0.0.0.0:8080", "wrapper tini collapsed into /usr/local/bin/python").

Downstream modules (Policy, Vuln Explorer, Export Center) treat the result identically to static scans, enabling easy comparison between build-time and runtime observations.