Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/irchaosclub/FANGS/llms.txt

Use this file to discover all available pages before exploring further.

The fangs run subcommands give visibility into individual sandbox executions. Every time FANGS installs an npm package in a Docker container, it creates a run record that tracks the job’s state through its lifecycle, records the total number of eBPF events captured, and stores every deviation the differ produces. Use fangs run list to find runs of interest and fangs run show to drill into the full detail of a specific run.

​
Subcommands

SubcommandDescription
fangs run listList recent sandbox runs across all packages or filtered by package
fangs run show <run_id>Show full metadata, event count, and deviations for a single run

​
fangs run list

fangs run list [flags]

​
Flags

​
-package
string
Filter results to runs for this package name only. Omit to list runs across all packages.
​
-limit
int
default:"50"
Maximum number of rows to return. Rows are ordered most-recent first.

​
Output Columns

ColumnDescription
RUN_IDShort hex prefix of the run’s full UUID
PACKAGEnpm package name (truncated to 24 characters)
VERSIONPackage version string
STATECurrent run state (see Run States below)
BASE★ if this run is part of the baseline, · otherwise
STARTEDUTC timestamp when the run entered building state, or - if not yet started

​
Run States

Runs progress through these states in order:
StateMeaning
pendingJob queued, waiting for a runner to pick it up
buildingRunner is pulling the Docker image and setting up the container
sandboxedContainer is running; eBPF sensor is capturing events
analyzedContainer has exited; differ is comparing events against the baseline
doneAnalysis complete; deviations (if any) have been written
failedAn error occurred at any stage; see failure_reason in run show

​
Examples

# List the 50 most recent runs across all packages
fangs run list

# List the 10 most recent runs for chalk
fangs run list -package chalk -limit 10

# JSON output — filter to only baseline runs
fangs -json run list | jq '.[] | select(.IsBaseline == true)'

# JSON output — find all failed runs
fangs -json run list -limit 100 | jq '.[] | select(.State == "failed")'

​
fangs run show

Displays the full record for a single run: all metadata fields, the total event count, and a table of every deviation produced by the differ. 
fangs run show <run_id>
<run_id> accepts either the full hex ID or any unique short prefix (the same short hex displayed in run list output).

​
Output Fields

FieldDescription
packagenpm package name
versionPackage version string
stateCurrent run state
attemptRetry attempt number (1 for first attempt)
baselineWhether this run is included in the package baseline
started_atUTC timestamp when the run started
finished_atUTC timestamp when the run completed (omitted if not yet finished)
failureFailure reason string (omitted if run succeeded)
eventsTotal number of raw eBPF events captured during the run
deviationsCount of deviations produced by the differ
When deviations are present, a table follows:
ColumnDescription
DEV_IDShort hex prefix of the deviation ID
SEVSeverity: info, warn, or crit
CATEGORYDeviation category (see Categories)
VALUEThe new fingerprint value (truncated to 60 characters)

​
Deviation Categories

CategoryWhat triggered it
net_new_destinationNew IP:port dialed, not seen in prior baseline runs
net_new_dnsNew hostname resolved via DNS
net_new_https_hostNew TLS SNI value in a ClientHello
fs_new_path_readNew file path opened for reading under a watched prefix
fs_new_path_writeNew file path opened for writing under a watched prefix
proc_new_execNew process executable path spawned

​
Output Examples

Run 3a9c12f4...
  package:    lodash
  version:    4.18.1
  state:      done
  attempt:    1
  baseline:   true
  started_at: 2025-01-15 09:23:11 UTC
  finished_at: 2025-01-15 09:24:03 UTC
  events:     1482
  deviations: 0

​
Next Steps After Reviewing a Run

# Inspect a specific deviation in full detail
fangs deviation show a1b2c3

# If the deviations are legitimate behavior changes, promote this run into the baseline
fangs baseline promote 7f2e90ab

# Suppress a recurring false-positive destination globally
fangs allow add -kind cidr -value 203.0.113.45/32 -note "known CDN"

# Suppress a path read globally
fangs allow add -kind path -value /root/.ssh/ -note "baseline infra reads"
The event_count field is a useful signal for diagnosing scan failures. A very low count (0–10 events) on a run that reached sandboxed state usually indicates the eBPF sensor lost cgroup tracking early in the container lifecycle. A very high count may indicate the sandbox duration was too short and the install was still in progress when the container stopped.

Build docs developers (and LLMs) love

Get started for freeTalk to us