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-orchestrator and fangs-runner are configured entirely through command-line flags and an optional YAML file. Every flag has a sensible default so a plain ./bin/fangs-orchestrator works out of the box; the YAML file lets you override watched filesystem paths and populate the global Differ allowlist without touching flags. Changes to the YAML file require an orchestrator restart — live reload is not yet wired.
Orchestrator flags
These flags are parsed bycmd/fangs-orchestrator/main.go at startup. Flag values always win over YAML config values.
Network & identity
TCP address the orchestrator listens on. Set to
0.0.0.0:8443 to accept connections from remote runners.Stable identifier sent to runners in the registration acknowledgement. Runners display this in their logs to confirm they are talking to the right control plane.
Storage
Storage backend to use. Accepted values:
sqlite, postgres, none. See Storage Backends for a full comparison.Path to the SQLite database file. The parent directory is created automatically on startup. Only used when
-storage sqlite.PostgreSQL connection string. Accepts both URL form (
postgres://user:pass@host:5432/dbname) and keyword form (host=... dbname=...). If unset, the orchestrator falls back to the $FANGS_PG_DSN environment variable. Only used when -storage postgres.npm registry watcher
Enable the autonomous npm registry watcher. When enabled, the orchestrator polls the npm registry for new releases of every watched package and automatically submits a sandbox scan job.
How often the watcher polls the npm registry. Standard Go duration syntax:
30s, 5m, 1h.Web dashboard
Serve the read-only web dashboard at
/ui/. Silently disabled when -storage none is set — the UI requires a storage backend to read scan history from.Notifications
Optional path to a JSON file declaring webhook targets. Entries are upserted into the database at startup so they survive restarts. Ignored when
-storage none.Metrics
Expose Prometheus-compatible metrics at
/metrics on the same listen address as the API.Retention
Delete raw events older than this many days. Set to
0 to disable pruning entirely. Deviation-evidence events are pinned and are never deleted regardless of this value.How often the retention pruner runs. A one-shot also fires 30 seconds after startup so you can confirm the wiring works in the logs before the first scheduled run.
TLS
Path to a PEM-encoded server certificate. When set together with
-tls-key, the orchestrator switches from plain HTTP to HTTPS. See TLS / mTLS for setup instructions.Path to the PEM-encoded private key that pairs with
-tls-cert.Path to a PEM CA bundle used to verify runner client certificates. Setting this flag enables mutual TLS — every incoming connection must present a cert signed by this CA. Requires
-tls-cert and -tls-key to also be set.Config file
Path to the optional YAML config file. A missing file is not an error — hardcoded defaults apply for all sections. See The orchestrator.yaml file below.
Runner flags
These flags are parsed bycmd/fangs-runner/main.go. The runner must be started as root (or with CAP_BPF) because it attaches eBPF probes.
Base URL of the orchestrator the runner should connect to. Change the scheme to
https:// when the orchestrator is configured with TLS.Stable identifier for this runner instance. When left empty (the default), the runner uses the machine hostname. The orchestrator uses this ID to route jobs, so it must be unique across all runners pointing at the same orchestrator.
Per-request timeout applied to all control-plane calls (register, heartbeat, poll). Does not affect the duration of individual scan jobs.
Path to a PEM CA bundle the runner uses to verify the orchestrator’s server certificate. Required when the orchestrator is running with a self-signed or private CA cert.
Path to the PEM client certificate the runner presents to the orchestrator. Required for mTLS.
Path to the PEM private key that pairs with
-tls-cert.The orchestrator.yaml file
The YAML file is entirely optional. Omitting a section keeps the hardcoded defaults for that section; you only need to include what you actually want to change. The file is read once at startup — sendSIGTERM and restart to apply edits.
watched_paths
Thewatched_paths section defines the filesystem prefixes the eBPF sensor reports for every scan job that does not supply its own path list. Entries marked cred: true tag matching events with EVENT_TAG_CRED_ACCESS, causing the UI to render them with a red row and a CRED badge and elevating their severity to high.
The kernel-side LPM trie resolves the longest-matching prefix per event, so a cred: true entry always wins over its parent prefix even if the parent appears earlier in the list.
These are the default paths shipped in
config/orchestrator.yaml. The same values are compiled in as hardcoded defaults, so your deployment will behave identically whether or not you supply the config file — until you edit it.allow
Theallow section populates the global Differ allowlist. There are three kinds of entries: cidrs, snis, and paths. All three suppress matching observations from becoming deviations. The hardcoded CDN allowlist (Cloudflare, GitHub, Google, Fastly, CloudFront CIDRs) applies underneath — entries here are additive.
Config-managed entries get deterministic IDs prefixed with cfg so fangs allow list clearly distinguishes YAML-sourced entries from CLI-added ones. Removing a config-managed entry via fangs allow remove works, but the entry reappears on the next restart unless you also delete the corresponding YAML line.
- paths (default)
- cidrs
- snis