Get Started with FANGS in Under 10 Minutes

This guide walks you through getting FANGS operational end-to-end on a single Linux host: starting the orchestrator, starting the runner, adding your first npm package to the watch list, and triaging what comes back. By the end you will have a live deviation report in your terminal and the web dashboard. All commands are taken directly from the source — nothing is invented.

Complete the Installation step first. You need bin/fangs-orchestrator, bin/fangs-runner, and bin/fangs built and ready in your working directory.

Overview

FANGS requires three concurrent processes: the orchestrator (control-plane), the runner (execution-plane), and optionally the CLI for operator interactions. Open three terminal windows in the repository root before you begin.

Step 1 — Start the Orchestrator

The orchestrator owns all persistent state, exposes the HTTP API, runs the npm watcher, and serves the web dashboard. Start it in Terminal A:

./bin/fangs-orchestrator

With no flags, it binds to 127.0.0.1:8443, stores data in var/lib/fangs/fangs.db (created automatically), enables the npm watcher on a 5-minute poll interval, and serves the dashboard at /ui/. The startup log is JSON-structured and written to stderr:

{"time":"...","level":"INFO","msg":"storage ready","backend":"sqlite","path":"var/lib/fangs/fangs.db"}
{"time":"...","level":"INFO","msg":"ui enabled","url":"http://127.0.0.1:8443/ui/"}
{"time":"...","level":"INFO","msg":"metrics enabled","url":"http://127.0.0.1:8443/metrics"}

Orchestrator Flag Reference

The most commonly adjusted flags at startup:

Flag	Default	Description
`-addr`	`127.0.0.1:8443`	HTTP listen address
`-storage`	`sqlite`	Storage backend: `sqlite` \| `postgres` \| `none`
`-sqlite-path`	`var/lib/fangs/fangs.db`	SQLite database file path
`-postgres-dsn`	(empty)	PostgreSQL DSN; also reads `$FANGS_PG_DSN`
`-watch`	`true`	Enable the npm registry watcher
`-watch-interval`	`5m`	How often the watcher polls npm
`-ui`	`true`	Serve the web dashboard at `/ui/`
`-metrics`	`true`	Expose Prometheus metrics at `/metrics`
`-config`	`config/orchestrator.yaml`	YAML config for watched paths and allowlist
`-retention-days`	`90`	Prune raw events older than N days (0 = never)
`-retention-interval`	`24h`	How often the retention pruner runs
`-notifiers-file`	(empty)	Path to a JSON file of webhook targets upserted at startup
`-id`	`fangs-orchestrator`	Identifier reported to runners on registration

For a quick local experiment without touching any YAML file, the defaults are sufficient. Edit config/orchestrator.yaml when you need to customize which file paths the sensor tracks or suppress known-good destinations.

Step 2 — Start the Runner

The runner loads the eBPF sensor probes at startup and registers with the orchestrator. It needs CAP_BPF and Docker socket access, so run it with sudo in Terminal B:

sudo ./bin/fangs-runner

The runner contacts the orchestrator at http://127.0.0.1:8443 by default, adopts the system hostname as its runner ID, attaches all eBPF probes once (before any container starts), and enters a job-poll loop:

{"time":"...","level":"INFO","msg":"sensor attached"}
{"time":"...","level":"INFO","msg":"registered with orchestrator","runner_id":"your-hostname"}
{"time":"...","level":"INFO","msg":"entering poll loop"}

Runner Flag Reference

Flag	Default	Description
`-orchestrator`	`http://127.0.0.1:8443`	Orchestrator base URL
`-runner-id`	(hostname)	Stable identifier for this runner
`-tls-ca`	(empty)	PEM CA bundle for verifying the orchestrator’s TLS cert
`-tls-cert`	(empty)	Client cert for mTLS
`-tls-key`	(empty)	Private key paired with `-tls-cert`
`-timeout`	`30s`	Per-request timeout for orchestrator control-plane calls

The runner executes attacker-supplied package code in a Docker sandbox. It must be treated as potentially compromised. In production, run it on a dedicated host with no access to sensitive credentials or internal networks.

Step 3 — Add a Package and Trigger a Scan

With both processes running, use the CLI in Terminal C to add an npm package to the watch list. This simultaneously registers it for ongoing watcher polling and queues an immediate scan of the current latest version:

./bin/fangs package add axios

The orchestrator receives the request, looks up the latest version of axios on npm, and dispatches a sandbox_scan job to the registered runner. In Terminal B you will see the runner pick up the job:

{"time":"...","level":"INFO","msg":"starting job","kind":"sandbox_scan","package":"axios","version":"1.x.x"}
{"time":"...","level":"INFO","msg":"fangs cgroup parent created"}
{"time":"...","level":"INFO","msg":"sandbox container exited","exit_code":0}
{"time":"...","level":"INFO","msg":"scan result posted","status":"ok","events":142,"dropped":0}

The first completed scan automatically becomes axios’s baseline — there is nothing to compare against yet, so zero deviations are written.

Subsequent releases of axios detected by the watcher will be scanned automatically. Runs that produce deviations appear in fangs pending; runs that match the baseline extend it silently.

Step 4 — Submit a One-Off Scan

You can queue a scan of any specific version without waiting for the watcher:

./bin/fangs scan submit -package axios -version 1.6.0

This targets a specific historical version and compares it against the baseline established in Step 3.

Step 5 — Check the Run List

See all scans that have been executed:

./bin/fangs run list

RUN_ID          PACKAGE    VERSION   STATE   BASE   STARTED
18b1f8a3...     axios      1.7.9     ok      ★      2 min ago
c4d2e901...     axios      1.6.0     ok      ·      1 min ago

To focus on one package:

./bin/fangs run list -package axios -limit 10

Step 6 — View Deviations

Check what behavioral differences were found:

./bin/fangs deviation list

Filter by severity or package:

./bin/fangs deviation list -package axios -severity warn -limit 20

Each deviation row shows the kind of event (file read, network connection, syscall), the specific value (path, IP:port, SNI), and the severity. Paths marked cred: true in watched_paths config (e.g. /root/.ssh/) render with critical severity and appear in red in the dashboard.

Step 7 — Inspect the Triage Queue

Any run that produced at least one deviation lands in the triage queue, waiting for an operator decision:

./bin/fangs pending

SEVERITY   RUN          PACKAGE   VERSION   FINDINGS   DETECTED    PROMOTE
warn       c4d2e901...  axios     1.6.0     3          2m ago      fangs baseline promote c4d2e901...

Step 8 — Promote or Reject

When deviations are examined and judged to represent legitimate behavior changes (a new CDN endpoint, an updated dependency path), promote the run’s full fingerprint set into the baseline:

./bin/fangs baseline promote c4d2e901...

The run is removed from pending, its fingerprints are merged into the baseline, and future scans of this package will treat those behaviors as expected.

Step 9 — Open the Dashboard

Everything visible in the CLI is also available as a live web view. Open:

http://127.0.0.1:8443/ui/

The dashboard shows registered runners, recent runs, deviation rows (with cred: true paths highlighted in red), the pending triage queue, and the current watcher status. Prometheus metrics are available at:

http://127.0.0.1:8443/metrics

Common CLI Commands at a Glance

# Add a package to the watcher (queues immediate scan)
./bin/fangs package add axios

# List all watched packages
./bin/fangs package watched

# Remove a package from the watcher
./bin/fangs package remove axios

Next Steps

Add Notifiers

Wire up Slack, Discord, or a generic SIEM webhook so deviations push to your team instead of waiting on a dashboard refresh. Use fangs notifier add.

Configure Watched Paths

Customize config/orchestrator.yaml to track the file prefixes that matter most and mark credential paths with cred: true for high-severity treatment.

Enable mTLS

In production, pass -tls-cert, -tls-key, and -tls-client-ca to the orchestrator to prevent unauthorized runners from registering.

Switch to PostgreSQL

Use -storage postgres and -postgres-dsn (or $FANGS_PG_DSN) to move to a PostgreSQL backend for multi-runner or high-availability deployments.

Get Started

Architecture

Configuration

Operations

Security

Get Started with FANGS in Under 10 Minutes

Overview

Step 1 — Start the Orchestrator

Orchestrator Flag Reference

Step 2 — Start the Runner

Runner Flag Reference

Step 3 — Add a Package and Trigger a Scan

Step 4 — Submit a One-Off Scan

Step 5 — Check the Run List

Step 6 — View Deviations

Step 7 — Inspect the Triage Queue

Step 8 — Promote or Reject

Step 9 — Open the Dashboard

Common CLI Commands at a Glance

Next Steps

Add Notifiers

Configure Watched Paths

Enable mTLS

Switch to PostgreSQL

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

Operations

Security

Documentation Index

​Overview

​Step 1 — Start the Orchestrator

​Orchestrator Flag Reference

​Step 2 — Start the Runner

​Runner Flag Reference

​Step 3 — Add a Package and Trigger a Scan

​Step 4 — Submit a One-Off Scan

​Step 5 — Check the Run List

​Step 6 — View Deviations

​Step 7 — Inspect the Triage Queue

​Step 8 — Promote or Reject

​Step 9 — Open the Dashboard

​Common CLI Commands at a Glance

​Next Steps

Add Notifiers

Configure Watched Paths

Enable mTLS

Switch to PostgreSQL

Build docs developers (and LLMs) love

Overview

Step 1 — Start the Orchestrator

Orchestrator Flag Reference

Step 2 — Start the Runner

Runner Flag Reference

Step 3 — Add a Package and Trigger a Scan

Step 4 — Submit a One-Off Scan

Step 5 — Check the Run List

Step 6 — View Deviations

Step 7 — Inspect the Triage Queue

Step 8 — Promote or Reject

Step 9 — Open the Dashboard

Common CLI Commands at a Glance

Next Steps