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.

By default, FANGS listens on plain HTTP — convenient for local development but not suitable for any environment where the runner and orchestrator are on different hosts. FANGS supports two levels of transport security: server TLS, which encrypts the connection and authenticates the orchestrator to runners, and mutual TLS (mTLS), which additionally requires runners to present a client certificate before the orchestrator accepts them. Without mTLS, any process that can reach the orchestrator’s port can register as a runner and receive scan jobs.

​
Modes at a glance

Plain HTTP

No flags required. Development and single-host setups only. The orchestrator logs scheme: http.

Server TLS

Orchestrator uses -tls-cert + -tls-key. Runner uses -tls-ca. Connection is encrypted and the orchestrator’s identity is verified.

Mutual TLS

Server TLS plus orchestrator uses -tls-client-ca. Runner additionally uses -tls-cert + -tls-key. Both sides are authenticated.

​
TLS implementation details

The orchestrator’s TLS configuration is built by buildServerTLSConfig in internal/orchestrator/api/server.go:
  • Minimum TLS version: 1.2 (tls.VersionTLS12)
  • Server TLS: activated when both -tls-cert and -tls-key are non-empty; the server calls ListenAndServeTLS with the supplied cert/key pair
  • mTLS: activated when -tls-client-ca is additionally set; the server sets ClientAuth = tls.RequireAndVerifyClientCert and loads the CA pool from the supplied PEM bundle
The orchestrator logs which mode is active at startup: 
{"level":"INFO","msg":"orchestrator listening","addr":"0.0.0.0:8443","scheme":"https (mTLS)"}

​
Step 1 — Generate certificates

FANGS ships a convenience script at docs/scripts/gen-tls.sh that creates a self-signed CA, a server certificate with SANs, and a runner client certificate. Use it for development and testing; in production, issue certificates from your existing PKI.
1

Run the generator script

# Defaults: localhost + 127.0.0.1 SANs, CN=fangs-runner client cert
docs/scripts/gen-tls.sh
To add extra SANs or change the runner CN:
SERVER_HOSTS="fangs.internal 10.0.1.5" \
RUNNER_ID="prod-runner-1" \
DAYS=730 \
docs/scripts/gen-tls.sh
The script exits immediately if tls/ca.crt, tls/server.crt, and tls/runner.crt already exist. Delete the tls/ directory to regenerate.
2

Verify the output

tls/
├── ca.crt        # root CA — distribute to all runners as -tls-ca
├── ca.key        # root CA private key — keep offline in production
├── server.crt    # orchestrator server cert
├── server.key    # orchestrator server private key
├── runner.crt    # runner client cert
└── runner.key    # runner private key
All .key files are created with mode 600.

​
What the script does

The script runs the following openssl commands (abbreviated): 
# 1. Create a 4096-bit self-signed CA
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 \
    -subj "/CN=fangs-ca" -out ca.crt
The extendedKeyUsage constraints are intentionally set: serverAuth on the server cert and clientAuth on the runner cert. Go’s TLS stack enforces these during the handshake.

​
Step 2 — Configure the orchestrator

Runners must supply -tls-ca but do not need a client certificate.
./bin/fangs-orchestrator \
  -addr 0.0.0.0:8443 \
  -tls-cert tls/server.crt \
  -tls-key  tls/server.key

​
Step 3 — Configure the runner

sudo ./bin/fangs-runner \
  -orchestrator https://192.0.2.10:8443 \
  -tls-ca tls/ca.crt
Change the orchestrator URL scheme to https:// when TLS is enabled. A runner pointed at http:// against a TLS-enabled orchestrator will fail to connect — Go’s HTTP client does not auto-upgrade.

​
Multiple runners

Each runner can share the same client certificate, or you can issue per-runner certs from the same CA for stronger identity isolation. To issue an additional cert for a second runner: 
openssl genrsa -out tls/runner-2.key 4096
openssl req -new -key tls/runner-2.key -subj "/CN=prod-runner-2" -out runner-2.csr
openssl x509 -req -in runner-2.csr -CA tls/ca.crt -CAkey tls/ca.key -CAcreateserial \
    -out tls/runner-2.crt -days 365 -sha256 \
    -extfile <(printf "extendedKeyUsage=clientAuth\n")
rm runner-2.csr
The orchestrator trusts any cert signed by the CA in -tls-client-ca. It does not require separate registration per CN — the runner’s identity is the -runner-id flag, which is independent of the certificate CN.

​
Certificate rotation

1

Issue new certificates from the same CA

Run the openssl commands above with a new key and a fresh validity period. The CA key and ca.crt do not change.
2

Deploy the new cert and key to the orchestrator

Copy the new server.crt and server.key to the orchestrator host, then restart the orchestrator. Existing runner connections will reconnect and pick up the new cert automatically.
3

Deploy the new client cert to runners

Copy runner.crt and runner.key to each runner host, then restart the runner processes. Runners re-register automatically on startup.
Set DAYS=730 (or higher) in the gen-tls.sh invocation to reduce rotation frequency in stable environments. Keep the CA key offline and protected — rotating the CA requires updating every runner’s -tls-ca bundle.

Build docs developers (and LLMs) love

Get started for freeTalk to us