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 (Fuck All NPM Garbage Supply-chains) is an open-source tool that watches a list of npm packages, runs every new release inside an isolated Docker sandbox, and captures the full syscall and network activity from the host kernel via eBPF. Rather than trying to classify whether a package is malicious, FANGS compares each run against a rolling behavioral baseline and surfaces anything new — a delta detector built for catching supply-chain compromises before they reach production.

​
Why FANGS Exists

Modern supply-chain attacks exploit the trust developers place in packages they already depend on. A package that legitimately reads node_modules/lodash/* and connects to registry.npmjs.org every day for a year is not suspicious — until the day a new release also opens /root/.ssh/id_rsa and dials 1.2.3.4:31337. That single behavioral delta is a signal worth acting on, but no static scanner can reliably surface it because the change is in runtime behavior, not source code. FANGS captures behavior at the kernel level via eBPF probes so there is no user-space instrumentation to bypass, no agent injected into the sandbox, and no dependency on the package cooperating. Every syscall and every TLS handshake SNI is recorded from the outside.
FANGS is a delta detector, not a classifier. It tells you what changed, not whether a change is definitively malicious. An operator reviews deviations and decides whether to promote the new behavior into the baseline or escalate.

​
Core Concepts

Baseline

A rolling fingerprint set accumulated from runs with zero deviations. The first scan of a package automatically becomes its baseline. Zero-deviation subsequent runs extend it.

Deviations

Behavioral observations present in a new run but absent from the baseline — unexpected file reads, new network destinations, novel syscalls. Each deviation row carries a severity.

eBPF Sensor

A set of kernel probes loaded by the runner at startup. Probes attach to syscall entry/exit points and capture file paths, network endpoints, and cgroup ancestry without touching user-space code inside the sandbox.

Watcher

A goroutine inside the orchestrator that polls the npm registry every 5 minutes (configurable). When a new release is detected for a watched package, a scan job is submitted to an available runner automatically.

Differ

The orchestrator component that receives raw events from the runner after a scan completes, extracts normalized fingerprints, and computes the delta against the current baseline to produce deviation rows.

Notifier

Delivers deviation reports to configured webhook targets (Slack, Discord, generic SIEM) when new deviations are written. Supports HMAC signing, retry, and per-target minimum severity thresholds.

​
Architecture

FANGS is two long-running processes and one CLI. The orchestrator owns all state; the runner owns all kernel access. They communicate over plain HTTP by default (opt-in mTLS for production). 
operator (fangs CLI · /ui/)
        │ package add / deviation list
        ▼
┌───────────────────────────────┐        npm registry
│       fangs-orchestrator      │◄─── 5-minute poll
│  watcher · differ · notifier  │
│  HTTP API · /ui/ · /metrics   │
└──────────────┬────────────────┘
               │ jobs · events · result
               ▼
┌──────────────────────────┐
│      fangs-runner        │
│  eBPF sensor (probes)    │
│  Docker sandbox          │◄── attacker-supplied package code runs here
└──────────────────────────┘
         │
     kernel eBPF
The orchestrator and runner are connected by a simple HTTP polling protocol. The runner registers on startup, long-polls for jobs, and streams captured events back as a NDJSON batch upload. The orchestrator hands results to the differ, which writes deviations. The notifier fires webhooks when deviations appear.

​
The Three Binaries

fangs-orchestrator

The control-plane. Exposes the HTTP API, hosts the web dashboard at /ui/, serves Prometheus metrics at /metrics, runs the npm watcher, and persists everything to SQLite or PostgreSQL.

fangs-runner

The execution-plane. Loads eBPF probes at startup, registers with the orchestrator, polls for scan jobs, launches Docker sandboxes, and streams captured kernel events back. Requires CAP_BPF — run as root or with the capability granted.

fangs

The operator CLI. Queries the storage backend directly to list runs, deviations, baselines, and packages. Also submits one-off scans and manages the allowlist and notifiers.
bin/sensor-smoketest is a fourth binary produced by make build. It is a development tool for verifying that the eBPF probes load and fire correctly on the current kernel without running a full orchestrator stack.

​
Storage Backends

The orchestrator and CLI both support two persistence backends:
BackendFlag / DSNWhen to use
SQLite-storage sqlite · -sqlite-path PATHSingle host, default, zero config
PostgreSQL-storage postgres · -postgres-dsn DSN or $FANGS_PG_DSNMulti-runner, HA, production
Both backends are schema-migrated automatically on first start; no manual CREATE TABLE step is needed.

​
Configuration

The orchestrator accepts one optional YAML file (config/orchestrator.yaml by default). It controls two main sections: watched_paths (the file prefixes the sensor tracks inside the sandbox, including cred: true markers for paths like /root/.ssh/ that receive high-severity treatment) and allow (global suppression rules for CIDRs, SNIs, and path prefixes that are known-good across all packages). If the file is absent, hardcoded defaults apply. 
watched_paths:
  - prefix: "/etc/"
  - prefix: "/root/.ssh/"
    cred: true

allow:
  paths:
    - value: "/usr/lib/"
      note: "shared library loads"
  cidrs:
    - value: "10.0.0.0/8"
      note: "internal network"
  snis:
    - value: "registry.npmjs.org"
All runtime parameters — listen address, storage backend, TLS material, watcher cadence, retention horizon — are controlled via CLI flags and environment variables rather than the YAML file.

​
License

FANGS is released under the Apache-2.0 license. See the LICENSE file in the repository root.

Build docs developers (and LLMs) love

Get started for freeTalk to us