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 /v1/scans endpoint is the HTTP entry point for queuing a one-off sandbox scan. It is used by fangs scan submit and fangs package add when a user or the watcher wants to inspect a specific npm package version. The endpoint wraps SubmitScan — the same internal function that the Watcher calls when it detects a new release — so manual and autonomous scans follow identical logic. The orchestrator validates that the named runner exists, applies defaults, stamps watched paths from the orchestrator config, creates a runs database row, and enqueues the job in the runner’s dispatch queue.

​
POST /v1/scans

Queues a sandbox scan job for a specific package@version on a named runner. Server-side processing When this endpoint is called, the orchestrator performs the following steps in order:
  1. Validates that target_runner is registered in the in-memory runner registry.
  2. Defaults job.kind to "sensor_only" if the field is empty.
  3. Defaults job.duration to 10s (10,000,000,000 ns) if the value is zero.
  4. Stamps defaultWatchedPaths onto job.watched_paths when the field is empty — loaded from the orchestrator’s config at startup so all scans share one authoritative path set.
  5. Generates a new run_id if the field is zero-value.
  6. Stamps dispatched_at with the current time.
  7. Creates a runs row with state = "pending".
  8. Enqueues the job for the target runner via the internal Dispatcher.
Request body 
{
  "target_runner": "prod-runner-1",
  "Job": {
    "kind": "sandbox_scan",
    "package_name": "axios",
    "version": "1.7.9",
    "duration": 60000000000,
    "sandbox": {
      "image": "node:20-slim",
      "command": [
        "sh", "-c",
        "cd /tmp && mkdir -p test && cd test && npm init -y >/dev/null 2>&1 && npm install axios@1.7.9 2>&1 | tail -3; sleep 2"
      ],
      "network_mode": "bridge",
      "pull_policy": "missing",
      "user": "0:0",
      "grace_period": 2000000000
    }
  }
}
​
target_runner
string
required
The runner_id of the registered runner that should execute this scan. The orchestrator returns 404 if this runner is not currently registered.
​
Job
object
required
The job definition. All sub-fields correspond directly to the proto.Job wire type.
Response — 202 Accepted 
{
  "queued": true,
  "run_id": "a1b2c3d4e5f60708090a0b0c0d0e0f10"
}
​
queued
boolean
Always true on a 202 response.
​
run_id
string
Hex-encoded 16-byte run identifier. Use this to query events, deviations, and run state. Supports git-style prefix lookups in the fangs CLI.
Error responses
StatusCondition
400target_runner field is missing or empty
404target_runner is not registered with the orchestrator
{"error": "missing target_runner"}

​
GET /v1/health

Returns a liveness signal confirming the orchestrator process is up and accepting connections. Used by container health checks, load balancers, and the fangs status command. Response — 200 OK 
{
  "status": "ok",
  "orchestrator_id": "fangs-orchestrator",
  "version": "dev"
}
​
status
string
Always "ok" when the process is alive.
​
orchestrator_id
string
Stable identifier configured at startup. Defaults to "fangs-orchestrator".
​
version
string
Build version string. "dev" in development builds; a semver tag in release builds.

​
Default sandbox command

When FANGS queues an npm package scan autonomously (via the Watcher or fangs package add), it uses the following standard command to run a clean install inside the container: 
cd /tmp && mkdir -p test && cd test \
  && npm init -y >/dev/null 2>&1 \
  && npm install <package>@<version> 2>&1 | tail -3; \
  sleep 2
This pattern initializes a throwaway package.json, installs the target package (which triggers all install-time lifecycle hooks), and then sleeps 2 seconds to let any async post-install work complete before the grace period begins. The sleep 2 combined with grace_period: 2000000000 gives the sensor approximately 4 seconds of observation time after the install finishes.
To scan a package with a custom install command — for example, to test a post-install script in a specific directory — supply the full sandbox.command array in your POST /v1/scans body. The default command is only applied when the watcher or fangs package add submits the job programmatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us