100% free and open source · every tool, every host, no licence key · read the licence
Secronyx
Get started

Reference

Configuration reference

Every command-line flag and environment variable the Secronyx binary accepts, grouped by function, with types, defaults and the HTTP listener validation rules.

Secronyx is configured entirely on the command line. There is no configuration file for the main binary: every setting is a flag on secronyx, and a small set of SECRONYX_* environment variables provide fallbacks for the values you would rather keep out of a process listing. This page lists every flag defined in cmd/secronyx/main.go, grouped by what it controls, followed by the validation rules the HTTP listener applies before it opens a socket.

Flags use the Go standard flag package. --name value, --name=value and a single leading dash are all accepted. Boolean flags are switched on by writing them bare (--enable-sensitive) and off with an explicit value (--rate-limit=false). Durations use Go syntax (30s, 5m, 24h). List-valued flags take one comma-separated string; items are trimmed and empty items dropped.

The subcommands apikey, ssh-sign and service are dispatched before any flag is parsed and take their own options; they are documented on the Command line page.

Startup order

A few settings interact, so it helps to know the order in which main() applies them:

  1. --help and --version print and exit.
  2. Redaction is enabled, or with --no-redact disabled with a logged warning.
  3. The file-read path policy and the connectivity-probe policy are installed.
  4. Audit logging is configured. With --audit-verify the log is verified and the process exits.
  5. --logout and --login run and exit.
  6. --query runs a single collector and exits.
  7. The MCP server is created with the scope policy, the result cap is set, and tools are registered. Tools outside the policy are never registered, so they are neither listed nor callable on any transport.
  8. If --mode is polling or hybrid, or an API key is present and --mode is empty (which selects hybrid), the agent starts and the transport flags are ignored.
  9. Otherwise the transport starts: stdio or http.

Environment variables

Each variable is a fallback for a flag. The flag wins when both are set, except for the two =1 switches, where either source enables the behaviour.

Variable Read when Effect
SECRONYX_TOKEN --token is empty Static bearer token for the HTTP transport; also the token for polling and hybrid modes.
SECRONYX_API_KEY --api-key is empty SaaS API key. Its presence selects hybrid mode when --mode is empty; on the HTTP transport it selects SaaS agent mode.
SECRONYX_SCOPES --scopes is empty Comma-separated scopes to register.
SECRONYX_ENABLE_SENSITIVE value is 1 Registers sensitive-scope tools, the same as --enable-sensitive.
SECRONYX_ALLOW_UNAUTHENTICATED value is 1 Same as --allow-unauthenticated.
SECRONYX_DEVICE_TOKEN --device-token is empty in hybrid mode Device token for the wake-up service and WebSocket.
SECRONYX_AGENT_ID polling mode Agent identifier; defaults to agent-<hostname>-<pid>.

SSH_AUTH_SOCK is read by secronyx ssh-sign --agent, and NOTIFY_SOCKET by service run under systemd; neither configures the server itself.

Transport

Flag Type Default Meaning
--transport string stdio stdio serves JSON-RPC on stdin and stdout; http opens a listener. Any other value exits with Error: unknown transport: <value>.
--listen string 127.0.0.1:8080 Address the HTTP transport binds. Whether it is a loopback address drives the validation rules below.
--server-url string derived Public URL advertised in the OAuth protected-resource metadata and in WWW-Authenticate challenges. When empty it becomes http://<listen>, or https://<listen> when --tls-cert is set; in SaaS agent mode it defaults to the callback URL.
--tls-cert string PEM certificate file. Together with --tls-key it makes the listener serve HTTPS.
--tls-key string PEM private key for --tls-cert.
--cors-origin list none Browser origins allowed to call the HTTP transport. Empty sends no CORS headers at all. See JSON-RPC API.
--trust-proxy-headers bool false Take the client IP for audit events and rate limiting from X-Forwarded-For (first entry) or X-Real-IP. Set it only when the listener is reachable solely through a trusted reverse proxy; otherwise any caller can forge the address written to the audit log.
--rate-limit bool true Per-client token bucket, global concurrency cap and brute-force lockout on the HTTP transport. Disabling it logs WARNING: HTTP rate limiting and brute-force lockout are DISABLED.

When TLS is on, the listener accepts TLS 1.2 and later with AEAD suites only: ECDHE key exchange with AES-GCM or ChaCha20-Poly1305, ECDSA or RSA authentication. The HTTP server applies a 10 s read-header timeout, 30 s read and write timeouts, a 60 s idle timeout and a 64 KiB header limit. The rate limiter defaults are 20 requests per second sustained, a burst of 40, 32 requests in flight across all clients, and a 15-minute lockout after 10 401 responses to one address within 15 minutes; up to 10,000 client addresses are tracked. None of these values is exposed as a flag.

Authentication

Authentication applies to the HTTP transport only; stdio relies on operating-system controls over who can start the process. The configured methods form a chain. Chain entries are consulted in this order: API key, SSH signature, mutual TLS. The first one that recognises a credential of its kind decides the outcome. If none does, the legacy bearer-token path runs: static token, then the SaaS JWKS validator, then OIDC, then OAuth introspection, whichever is configured. Each method is described on the Authentication page.

Static bearer token

Flag Type Default Meaning
--token string $SECRONYX_TOKEN Shared secret presented as Authorization: Bearer <token>. Must be at least 32 characters. A matching token is granted the wildcard scope *.

API keys and SSH signatures

Flag Type Default Meaning
--api-keys-file string JSON store of hashed API keys, created and maintained with secronyx apikey. Keys are presented as X-API-Key: <key> or Authorization: ApiKey <key>. The file must not be readable by other users and is reloaded when it changes.
--ssh-authorized-keys string OpenSSH authorized_keys file whose keys may sign requests. Supported per-line options are scopes="...", expires=..., from="..." and, on CA lines, principals="..."; any other option is rejected when the file loads.
--ssh-ca-keys string Trusted SSH certificate-authority keys in the same format. Requests then carry an SSH certificate issued by one of these CAs.

Mutual TLS

Flag Type Default Meaning
--tls-client-ca string PEM bundle of client CAs. When set, the TLS handshake requires a client certificate chaining to one of them. Requires --tls-cert and --tls-key.
--tls-client-cert-optional bool false Verify a client certificate only if one is presented, for migrations where some callers still use another method. A request without a certificate is passed to the remaining methods and, if none accepts it, rejected.
--mtls-identity-file string JSON file mapping certificates (spki_sha256, spiffe_id, dns, cn or ou) to a name and scopes. Requires --tls-client-ca. Re-read when its modification time changes.
--mtls-default-scopes list none Scopes granted to a verified certificate with no identity-file entry. Empty means such certificates are denied; a wildcard is never implied.
--mtls-require-mapping bool false Deny any certificate absent from the identity file, even when --mtls-default-scopes is set.
--mtls-trust-domain list none SPIFFE trust domains accepted from client certificates. When set, a certificate without a SPIFFE ID is denied.
--mtls-crl string Certificate revocation list (PEM or DER) checked on every request; re-read when it changes.

OIDC (local JWT validation)

Flag Type Default Meaning
--oidc-issuer string Issuer URL. Enables OIDC: the server fetches the issuer's JWKS and validates tokens locally. Takes precedence over --auth-server when both are set.
--oidc-audience string Expected aud claim. Required with --oidc-issuer; otherwise the server exits with Error: --oidc-audience required with --oidc-issuer.
--oidc-require-jti bool false Reject JWTs without a jti claim so every token can be replay-checked.
--oidc-max-token-lifetime duration 24h Reject JWTs whose exp - iat exceeds this.

OAuth 2.1 token introspection

Flag Type Default Meaning
--auth-server string Authorization server URL. The introspection endpoint is <auth-server>/introspect. Used only when --oidc-issuer is not set.
--client-id string Client ID sent as HTTP basic auth to the introspection endpoint. Required with --auth-server.
--client-secret string Client secret for the same. Required with --auth-server.
--introspection-cache-ttl duration 60s How long a successful introspection is reused before the authorization server is asked again; 0 disables the cache. Failures and inactive tokens are never cached, and a cached entry never outlives the token's own exp.

Exposure override

Flag Type Default Meaning
--allow-unauthenticated bool false, or $SECRONYX_ALLOW_UNAUTHENTICATED=1 Permit an HTTP listener on a non-loopback address without authentication, or with authentication but without TLS. Development only; the server logs a SECURITY WARNING line when it takes effect.

Authorization

Flag Type Default Meaning
--scopes list $SECRONYX_SCOPES, else every scope except sensitive Only tools in these scopes are registered. Listing sensitive here is not sufficient on its own; --enable-sensitive is still required.
--enable-sensitive bool false, or $SECRONYX_ENABLE_SENSITIVE=1 Register the nine sensitive-scope tools: environment variables, process environments, user accounts, sudo, SSH configuration, certificates, authentication logs, MAC status and macOS TCC permissions. Logs WARNING: sensitive-scope tools are enabled.
--max-result-bytes int 4194304 (4 MiB) Cap on the text a single tools/call may return. Values below 1024 are raised to 1024; 0 or a negative value keeps the default. A result above the cap is replaced by an isError result.

The scopes in the current inventory, with the number of tools each registers, are alerts (3), analytics (4), compliance (5), consumer (24), core (8), enhanced (27), hardware (25), hooks (16), logs (5), network (25), report (2), resources (11), security (40), sensitive (9), software (115), state (38), storage (23), triage (25) and windows (125). Registration-time policy decides which of these exist; request-time policy on the HTTP transport then compares the caller's granted scopes with each tool's scope. See Scopes and authorization.

At startup the server logs how many tools the policy excluded, for example Scope policy: 9 tools not registered (sensitive=false, scopes="").

Data handling

Redaction

Flag Type Default Meaning
--redact bool true Redact secrets in collector output.
--no-redact bool false Disable redaction. Either --no-redact or --redact=false disables it and logs WARNING: output redaction is DISABLED; secrets in system state will be returned verbatim.
--redact-provider string default Redaction provider: default or gitguardian.

Redaction is applied inside the collectors, so it covers --query output as well as tool results. See Redaction.

File and network reach

Flag Type Default Meaning
--allowed-paths list built-in allowlist Directories that tools taking a caller-supplied path (lock files, application configuration) may read from. Setting it replaces the built-in roots entirely.
--probe-allow-loopback bool false Let connectivity probes (get_network_latency) target 127.0.0.0/8 and ::1.
--probe-allow-hosts list none Switches probes to allowlist mode: only these hosts, IPs or CIDRs may be targeted.
--probe-deny-hosts list none Hosts, IPs or CIDRs that probes must never target, applied on top of the built-in denials.

The built-in path allowlist is /etc, /opt, /usr/local/etc, /srv, /var/lib, /var/www and /app on Unix-like systems, and C:\ProgramData, C:\inetpub, C:\Program Files and C:\Program Files (x86) on Windows. A deny list of credential locations (**/.ssh/**, **/.aws/**, **/.kube/**, /etc/shadow* and others) and a 1 MiB file-size cap apply regardless of --allowed-paths. The default probe policy allows private ranges, refuses loopback and link-local addresses (which is where cloud metadata services live), and times out after 5 s. Probes are connect-only: they open a TCP connection to the vetted address and never issue an HTTP request, so no redirect can be followed. See Network and path policy.

Audit

Flag Type Default Meaning
--audit bool true Write an audit event for every authentication decision and tool call.
--no-audit bool false Disable audit logging; logs WARNING: audit logging is DISABLED. Ignored when --audit-verify is set.
--audit-output string /var/log/secronyx/audit.jsonl JSON-lines audit file. If it cannot be opened, events go to stderr and a WARNING names the reason; the process does not exit.
--audit-buffer-size int 100 Events buffered before an asynchronous write; 0 writes synchronously.
--audit-flush-interval duration 5s How often the buffer is flushed.
--audit-max-file-size int64 104857600 (100 MiB) File size that triggers rotation.
--audit-max-files int 10 Rotated files kept.
--audit-sync-write bool false fsync after every write.
--audit-verify bool false Verify the hash chain of --audit-output and exit: 0 on success, 1 on failure.

The hash chain is always on; there is no flag to disable it. See Audit logging.

Agent, hybrid and SaaS modes

These flags apply when the binary runs as an agent that reaches out to a backend rather than as a listener. The modes themselves are described under Hybrid and SaaS mode.

Flag Type Default Meaning
--mode string empty polling or hybrid. Empty with an API key present selects hybrid; empty otherwise means run a transport. Any other value is not rejected: it falls through to the transport.
--saas-url string https://api.secronyx.com Backend URL for registration, login and polling.
--api-key string $SECRONYX_API_KEY Backend API key. With --mode empty its presence selects hybrid mode, so the agent starts and no transport is opened. The HTTP transport's SaaS agent path — a certificate generated under --config-dir, registration with the backend, incoming requests validated against the backend's JWKS — is therefore reached only when --mode holds a value other than polling or hybrid.
--callback-url string https://<listen> URL at which the backend can reach this agent in SaaS agent mode.
--config-dir string ~/.secronyx Directory for generated certificates and stored credentials.
--email string Account email for --login and consumer polling mode.
--password string Account password for --login; prompted on stdin when empty.
--login bool false Authenticate with email and password, register this device, store the credentials and exit.
--logout bool false Delete stored credentials and exit.
--ws-url string wss://ws.secronyx.com/v1 WebSocket endpoint for hybrid mode.
--wakeup-url string https://wakeup.secronyx.com Wake-up service polled in hybrid mode. Set it to an empty string to fall back to SQS.
--notifications-queue-url string SQS queue URL for hybrid mode; legacy, used only when --wakeup-url is empty.
--instance-id string Agent instance ID. Required for hybrid mode unless an API key or stored credentials supply one.
--device-token string $SECRONYX_DEVICE_TOKEN Device token for the wake-up service and WebSocket.
--poll-timeout duration 10s Wake-up service long-poll timeout.
--idle-timeout duration 30s WebSocket idle time before the agent returns to polling.
--ws-reconnect-delay duration 1s Initial WebSocket reconnect delay.
--ws-reconnect-max duration 60s Maximum WebSocket reconnect delay.
--debug bool false Verbose agent logging.

Direct query mode

These flags matter only with --query, which runs one collector and exits without starting a server. The Command line page lists which query names consume each one.

Flag Type Default Meaning
--query string Query name to run, for example get_cpu_info.
--json bool false Print bare JSON instead of a titled block.
--pid int 0 Process ID for get_process_environ and get_capabilities.
--image-id string Image ID for get_docker_image_history.
--path string Path for lock-file queries and get_app_config.
--service string Service name for get_service_log_view.
--limit int 0 Row limit for queries that support it.
--hours int 0 Window for get_auth_failure_summary and get_audit_trail.
--days int 0 Window for get_recently_installed_software.
--lines int 0 Line count for get_service_log_view.
--period string 1h, 24h or 7d for get_historical_metrics and get_trend_analysis.
--framework string cis, pci-dss, hipaa or stig for get_compliance_check.
--hive string HKLM Registry hive for the get_registry_* queries.
--regpath string Registry key path for the same.
--max-depth int 3 Recursion depth for get_registry_tree.
--appid string DCOM AppID for get_dcom_permissions.
--site-name string IIS site for site-scoped IIS queries.
--app-pool string IIS application pool for pool-scoped IIS queries.

Miscellaneous

Flag Type Default Meaning
--help bool false Print usage and exit.
--version bool false Print version, commit, build date, Go version and platform, then exit.

HTTP listener validation

HTTPConfig.Validate in internal/mcp/http.go runs before the socket is opened. It is pure: it reads no files and opens no connections, so a refused configuration fails immediately at startup rather than at first request. The rules, in order:

  1. Token length. A static bearer token shorter than 32 characters is refused with bearer token is N characters; a static token must be at least 32 characters of random data.
  2. Mutual TLS needs TLS. --tls-client-ca without both --tls-cert and --tls-key is refused with a client CA bundle (mutual TLS) requires --tls-cert and --tls-key.
  3. Loopback is always allowed. If --listen names a loopback address, validation stops here and any combination of authentication and TLS is accepted. Loopback means the host part is localhost (case-insensitive) or parses as a loopback IP (127.0.0.0/8, ::1). An empty host, 0.0.0.0, :: and any other hostname are treated as exposed, because their resolution cannot be verified.
  4. Exposed without authentication. If no authentication method is configured and --allow-unauthenticated is not set, the server refuses with refusing to listen on "<addr>" without authentication: bind to 127.0.0.1, or configure --token/--oidc-issuer/--auth-server, or pass --allow-unauthenticated for an isolated development network. With the override set, it starts and logs SECURITY WARNING: serving "<addr>" WITHOUT AUTHENTICATION because --allow-unauthenticated is set; anyone who can reach this port can read system state.
  5. Exposed with authentication but no TLS. If authentication is configured but TLS is not, and the override is not set, the server refuses with refusing to listen on "<addr>" with authentication but without TLS: credentials would cross the network in plaintext; add --tls-cert/--tls-key, bind to 127.0.0.1 behind a TLS-terminating proxy, or pass --allow-unauthenticated for an isolated development network. With the override set, it logs SECURITY WARNING: serving "<addr>" over plaintext HTTP because --allow-unauthenticated is set; bearer tokens are exposed to anyone on the network path.

"Authentication configured" means any of: a bearer token, the SaaS JWKS validator, OIDC, introspection, at least one chain authenticator (API keys, SSH signatures or mTLS), or a client CA bundle without --tls-client-cert-optional.

Three further checks happen in main.go before Validate runs, each exiting with status 1: --oidc-issuer without --oidc-audience; --auth-server without both --client-id and --client-secret; and --mtls-identity-file without --tls-client-ca. Failure to load an API key store, SSH key file, identity file, CRL or client CA bundle is also fatal at startup.

Examples

Loopback development listener, no authentication (permitted only because the address is loopback):

secronyx --transport http --listen 127.0.0.1:8080

Exposed listener with a static token and TLS:

secronyx --transport http --listen 0.0.0.0:8443 \
  --tls-cert /etc/mcp/cert.pem --tls-key /etc/mcp/key.pem \
  --token "$(openssl rand -hex 32)"

API keys plus mutual TLS, sensitive tools off, results capped at 1 MiB, audit to a custom path:

secronyx --transport http --listen 0.0.0.0:8443 \
  --tls-cert /etc/mcp/cert.pem --tls-key /etc/mcp/key.pem \
  --tls-client-ca /etc/mcp/clients-ca.pem \
  --mtls-identity-file /etc/mcp/identities.json --mtls-require-mapping \
  --api-keys-file /etc/secronyx/keys.json \
  --max-result-bytes 1048576 \
  --audit-output /var/log/secronyx/audit.jsonl

OIDC against an enterprise identity provider, with replay protection required:

secronyx --transport http --listen 0.0.0.0:8443 \
  --server-url https://mcp.example.com \
  --tls-cert /etc/mcp/cert.pem --tls-key /etc/mcp/key.pem \
  --oidc-issuer https://enterprise.okta.com --oidc-audience secronyx \
  --oidc-require-jti --oidc-max-token-lifetime 1h

Stdio for a desktop AI client, restricted to two scopes:

secronyx --scopes core,logs

For complete deployments see Remote access over HTTP, Docker and Compose and Kubernetes and Helm.

Built 2026-09-19. Source: levantar-ai/secronyx. Found a mistake? Tell us.