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.

fangs scan submit lets you queue a sandbox scan for any package@version without waiting for the autonomous watcher to discover a new release. This is useful for investigating a specific version on-demand, re-scanning an older version against a newer baseline, or testing a new runner configuration before it enters the normal workflow. The CLI pre-flights the request against registry.npmjs.org by default, then POSTs a scan job to the orchestrator. The orchestrator assigns a run ID, places the job in the pending queue, and dispatches it to a runner. From that point the runner takes over: it pulls the Docker image, starts the sandbox, attaches the eBPF sensor, runs npm install, and streams events back to the orchestrator.

​
Usage

fangs scan submit -package <name> -version <version> [flags]
Both -package and -version are required.

​
Flags

​
-package
string
required
npm package name to scan. Must match the exact name on the registry.
​
-version
string
required
Package version to install. Must be an exact version string (e.g. 1.7.9), not a range. The pre-flight check resolves it against registry.npmjs.org to confirm it exists before dispatching.
​
-orchestrator
string
default:"http://127.0.0.1:8443"
Orchestrator base URL. fangs scan submit is one of the two subcommands that makes an HTTP call — it POSTs to <orchestrator>/v1/scans.
​
-runner
string
default:""
Target runner ID. When empty, the orchestrator dispatches the job to the first registered runner. Use this flag to pin a scan to a specific runner host (e.g. a runner with more memory for large packages).
​
-duration
duration
default:"60s"
Maximum sandbox duration. The runner stops the container after this deadline even if npm install is still running. Increase for large packages with slow postinstall scripts.
​
-skip-registry-validate
bool
default:"false"
Skip the pre-flight registry lookup. Useful in offline environments, private registries, or automated test pipelines where the package is known to exist.

​
How It Works

1

Pre-flight registry check

Unless -skip-registry-validate is set, the CLI calls registry.npmjs.org to resolve <package>@<version>. If the package does not exist, the error is ErrPackageNotFound. If the version does not exist, the error is ErrVersionNotFound. This prevents a typo from consuming a sandbox slot only to fail during npm install.
2

Build sandbox spec

The CLI calls watcher.BuildSandboxScan(package, version) to construct a SandboxSpec — the same builder used by the autonomous watcher. This ensures that manual scans and auto-scans produce identical Docker invocations for the same (package, version) pair, making their results directly comparable.
3

POST to orchestrator

Sends a JSON body to POST <orchestrator>/v1/scans:
{
  "target_runner": "<runner_id>",
  "Job": {
    "Kind": "sandbox_scan",
    "PackageName": "<package>",
    "Version": "<version>",
    "Duration": "<duration>",
    "Sandbox": { ... }
  }
}
WatchedPaths is intentionally omitted from the job — the orchestrator stamps its own configured defaults from config/orchestrator.yaml so the CLI and the watcher share a single source of truth.
4

Return run ID

The orchestrator responds with {"queued": true, "run_id": "<hex>"}. The CLI prints the run ID and a watch URL.

​
Output

queued scan run_id=3a9c12 package=lodash version=4.18.1
watch: http://127.0.0.1:8443/ui/runs/3a9c12f4...
  or:  fangs run show 3a9c12

​
Examples

# Scan lodash 4.18.1 using defaults
fangs scan submit -package lodash -version 4.18.1

# Scan a large package with a longer sandbox window
fangs scan submit -package webpack -version 5.99.0 -duration 180s

# Pin the scan to a specific runner
fangs scan submit -package axios -version 1.7.9 \
  -runner my-runner-host-01

# Skip registry validation (useful in CI or offline environments)
fangs scan submit -package my-pkg -version 2.0.0 \
  -skip-registry-validate

# Target a non-default orchestrator
fangs scan submit -package express -version 4.21.2 \
  -orchestrator https://fangs.internal.example:8443

# Queue a scan and immediately watch the result
fangs scan submit -package chalk -version 5.4.1 && \
  fangs run list -package chalk -limit 1

​
Following a Scan

After queuing a scan, use fangs run show to check its state and see any deviations once it completes: 
# Poll until state changes from pending → done/failed
fangs run show 3a9c12

# List deviations for the run
fangs deviation list -run-id 3a9c12
Run states in order: pending → building → sandboxed → analyzed → done (or failed at any stage). The dashboard at http://127.0.0.1:8443/ui/ updates in real time.
fangs scan submit and fangs package add are the only CLI subcommands that make HTTP calls to the orchestrator. All other subcommands read directly from the storage backend. If the orchestrator is not running, scan submit will fail with a connection error, but run list, deviation list, and all read-only commands will still work.

Build docs developers (and LLMs) love

Get started for freeTalk to us