osctrl-api
osctrl-api is the API service for osctrl.
Execute ./osctrl-api help to show the main help of the program:
$ ./osctrl-api helpNAME: osctrl-api - API service for osctrl, a fast and efficient osquery management
USAGE: osctrl-api [global options] [command [command options]]
DESCRIPTION: API service for osctrl, a fast and efficient osquery management
COMMANDS: help config-validate, config-verify Validate YAML configuration file config-generate Generate an example configuration file using the current flag values
GLOBAL OPTIONS: --config, -c Provide service configuration via YAML file [$SERVICE_CONFIG] --config-file FILE, -C FILE Load service configuration from FILE (default: "./config/api.yml") [$SERVICE_CONFIG_FILE] --listener string, -l string Listener for the service (default: "127.0.0.1") [$SERVICE_LISTENER] --port int, -p int TCP port for the service (default: 9000) [$SERVICE_PORT] --host string, -H string Exposed hostname the service uses (default: "osctrl.net") [$SERVICE_HOST] --log-level string Log level for the service (default: "info") [$SERVICE_LOG_LEVEL] --log-format string Log format for the service (default: "json") [$SERVICE_LOG_FORMAT] --audit-log, --audit Enable audit log for the service. Logs sensitive actions (logins, env mutations, query/carve runs, etc.). Disable only for local dev — production deployments MUST keep this on so SoC tooling has a stream to alert on. [$AUDIT_LOG] --trusted-proxies string Comma-separated CIDR list whose X-Real-IP / X-Forwarded-For headers will be honored. Empty (default) ignores forwarding headers and uses RemoteAddr verbatim — prevents header-spoofed rate-limit bypass and audit-log poisoning. [$SERVICE_TRUSTED_PROXIES] --base-path string Public URL prefix the SPA and API are served under (e.g. /osctrl). The reverse proxy must strip it before forwarding; it is used for cookie paths, redirects and login URLs. Empty (default) serves at the root. [$SERVICE_BASE_PATH] --geoip-db string Path to a MaxMind GeoLite2-Country .mmdb file. When set, node IP addresses are resolved to country codes (shown as flag emojis in the SPA). Empty (default) disables GeoIP entirely. [$SERVICE_GEOIP_DB] --posture-enabled Enable the security and compliance posture system. Disabled by default; when enabled osctrl-tls ingests posture query results and osctrl-api exposes posture endpoints to the SPA. [$SERVICE_POSTURE_ENABLED] --alerts-enabled Enable the alerting subsystem: rule matching on ingested logs and dispatch through configured channels. Disabled by default; when enabled osctrl-tls evaluates alert rules on the log ingest path. Requires a service restart to change. [$SERVICE_ALERTS_ENABLED] --events-enabled Enable best-effort query/carve change notifications (API and TLS). [$SERVICE_EVENTS_ENABLED] --events-namespace string Shared API/TLS event namespace, unique per deployment within Redis (required when enabled). [$SERVICE_EVENTS_NAMESPACE] --health-enabled Enable the health/system-status subsystem: component health, service heartbeats and runtime stats in the SPA. Disabled by default; when enabled osctrl-tls writes a heartbeat row every 60s and osctrl-api serves /api/v1/health/status. Requires a service restart to change. [$SERVICE_HEALTH_ENABLED] --vuln-enabled Enable vulnerability monitoring: osctrl-tls stores software inventory from osctrl:vuln: scheduled queries and osctrl-api matches it against OSV and CISA KEV data. Disabled by default; when off no tables are created and nothing is downloaded. Requires a service restart to change. [$SERVICE_VULN_ENABLED] --service-config-enabled Serve the service-config API and show the matching section in the SPA. Disabled by default: the YAML sections are still seeded into the database at every boot and resolved back at startup, but none of the /api/v1/service-config routes are registered — change the rows or the YAML file directly instead. [$SERVICE_CONFIG_ENABLED] --log-sinks-enabled Serve the log-sinks API and show the matching section in the SPA. Independent of --service-config-enabled. Set false to hide the log-sinks management UI. [$LOG_SINKS_ENABLED] --auth-providers-enabled Serve the auth-providers API and show the matching section in the SPA. Independent of --service-config-enabled. Set false to hide the auth-providers management UI. [$AUTH_PROVIDERS_ENABLED] --mfa-required Require a second authentication factor (TOTP, passkey or security key) for password logins. Users without one enroll at their next login. Service accounts and federated logins are unaffected. [$SERVICE_MFA_REQUIRED] --mfa-issuer string Label shown next to the account in authenticator apps. Defaults to "osctrl". [$SERVICE_MFA_ISSUER] --mfa-rpid string WebAuthn Relying Party ID — the registrable domain passkeys and security keys are bound to, no scheme or port. Empty uses --host. Changing it invalidates every registered credential. [$SERVICE_MFA_RPID] --mfa-origins string Comma-separated origins the SPA is served from, with scheme and any non-default port. Empty uses https://<host>. A browser refuses a WebAuthn ceremony whose origin is not listed. [$SERVICE_MFA_ORIGINS] --posture-query-prefix string Prefix for scheduled query names whose results are ingested as node posture data when --posture-enabled is true. (default: "osctrl:posture:") [$SERVICE_POSTURE_QUERY_PREFIX] --vuln-osv-url string Base URL of the OSV data bucket, or of an internal mirror with the same layout (air-gapped deployments). (default: "https://osv-vulnerabilities.storage.googleapis.com") [$VULN_OSV_URL] --vuln-kev-url string CISA Known Exploited Vulnerabilities JSON feed, or a mirror of it. (default: "https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json") [$VULN_KEV_URL] --vuln-ecosystems string Comma-separated OSV ecosystem directories to sync (e.g. Debian,Ubuntu,PyPI). Empty syncs the ecosystems the fleet reports. [$VULN_ECOSYSTEMS] --vuln-sync-hours int Hours between advisory feed refreshes. (default: 6) [$VULN_SYNC_HOURS] --vuln-retention-days int Days a resolved vulnerability finding is kept. (default: 90) [$VULN_RETENTION_DAYS] --vuln-max-download-mb int Size cap in MiB for any single advisory feed download. (default: 2048) [$VULN_MAX_DOWNLOAD_MB] --vuln-nvd-enabled Match Windows programs, macOS apps, Homebrew and Chocolatey packages against NVD CPE data. Matches are possible findings: shown, never alerted on or scored. [$VULN_NVD_ENABLED] --vuln-nvd-url string NVD CVE API 2.0 endpoint, or a mirror serving the same responses. (default: "https://services.nvd.nist.gov/rest/json/cves/2.0") [$VULN_NVD_URL] --vuln-nvd-api-key string Optional NVD API key for ten times the request rate. Prefer the environment variable: a flag value shows in the process list. [$VULN_NVD_API_KEY] --auth none, -A none Authentication mechanism for the service (jwt|none — none requires OSCTRL_INSECURE_NO_AUTH=1) (default: "jwt") [$SERVICE_AUTH] --logger string, -L string Logger mechanism to handle status/result logs from nodes (default: "db") [$SERVICE_LOGGER] --loggers string Logger mechanisms to handle status/result logs from nodes as a comma-separated list [$SERVICE_LOGGERS] --logger-db-same Use the same DB configuration for the logger [$LOGGER_DB_SAME] --always-log, -a, --always Always log status and on-demand query logs from nodes in database [$ALWAYS_LOG] --redis-connection-string string Redis connection string, must include schema (<redis|rediss|unix>://<user>:<pass>@<host>:<port>/<db>?<options> [$REDIS_CONNECTION_STRING] --redis-host string Redis host to be connected to (default: "127.0.0.1") [$REDIS_HOST] --redis-port int Redis port to be connected to (default: 6379) [$REDIS_PORT] --redis-pass string Password to be used for redis [$REDIS_PASS] --redis-db int Redis database to be selected after connecting (default: 0) [$REDIS_DB] --redis-conn-retry int Time in seconds to retry the connection to the cache, if set to 0 the service will stop if the connection fails (default: 10) [$REDIS_CONN_RETRY] --db-type string Type of backend to be used (default: "postgres") [$DB_TYPE] --db-host string Backend host to be connected to (default: "127.0.0.1") [$DB_HOST] --db-port int Backend port to be connected to (default: 5432) [$DB_PORT] --db-name string Database name to be used in the backend (default: "osctrl") [$DB_NAME] --db-user string Username to be used for the backend (default: "postgres") [$DB_USER] --db-pass string Password to be used for the backend (default: "postgres") [$DB_PASS] --db-sslmode string SSL native support to encrypt the connection to the backend (default: "disable") [$DB_SSLMODE] --db-max-idle-conns int Maximum number of connections in the idle connection pool (default: 20) [$DB_MAX_IDLE_CONNS] --db-max-open-conns int Maximum number of open connections to the database (default: 100) [$DB_MAX_OPEN_CONNS] --db-conn-max-lifetime int Maximum amount of time a connection may be reused (default: 30) [$DB_CONN_MAX_LIFETIME] --db-conn-retry int Time in seconds to retry the connection to the database, if set to 0 the service will stop if the connection fails (default: 10) [$DB_CONN_RETRY] --db-filepath string File path to the SQLite database, only used when type is sqlite (default: "./osctrl.db") [$DB_SQLITE_FILEPATH] --db-read-enabled Open a second connection to a read replica for read-heavy, staleness-tolerant queries (osctrl-api: dashboard, node lists, audit, posture, vulnerabilities; osctrl-tls: alert node scans, osctrld metrics). Not supported with sqlite [$DB_READ_ENABLED] --db-read-host string Read replica host (defaults to the primary host) [$DB_READ_HOST] --db-read-port int Read replica port (defaults to the primary port) (default: 0) [$DB_READ_PORT] --db-read-user string Read replica username (defaults to the primary username) [$DB_READ_USER] --db-read-pass string Read replica password (defaults to the primary password) [$DB_READ_PASS] --db-read-sslmode string Read replica SSL mode (defaults to the primary SSL mode) [$DB_READ_SSLMODE] --db-read-max-idle-conns int Maximum idle connections in the read replica pool (defaults to the primary value) (default: 0) [$DB_READ_MAX_IDLE_CONNS] --db-read-max-open-conns int Maximum open connections to the read replica (defaults to the primary value) (default: 0) [$DB_READ_MAX_OPEN_CONNS] --tls, -t Enable TLS termination. It requires certificate and key [$TLS_SERVER] --cert FILE, -T FILE TLS termination certificate from FILE (default: "./config/tls.crt") [$TLS_CERTIFICATE] --key FILE, -K FILE TLS termination private key from FILE (default: "./config/tls.key") [$TLS_KEY] --jwt-secret string Password to be used for the backend [$JWT_SECRET] --jwt-expire int Maximum amount of hours for the tokens to expire (default: 3) [$JWT_EXPIRE] --oidc-enabled Enable the federated-login surface on osctrl-api [$OIDC_ENABLED] --oidc-issuer-url string OIDC issuer URL (the realm root, /.well-known/openid-configuration is appended automatically) [$OIDC_ISSUER_URL] --oidc-client-id string OIDC client ID registered with the IdP [$OIDC_CLIENT_ID] --oidc-client-secret string OIDC client secret [$OIDC_CLIENT_SECRET] --oidc-redirect-url string OIDC redirect URL — must match the IdP client config and end with /oidc/callback [$OIDC_REDIRECT_URL] --oidc-scopes string OIDC scopes as a comma-separated list (defaults to "openid,profile,email") [$OIDC_SCOPES] --oidc-username-claim string ID-token claim used as the osctrl username (preferred_username, email, sub) [$OIDC_USERNAME_CLAIM] --oidc-groups-claim string ID-token claim that contains group memberships (default: groups) [$OIDC_GROUPS_CLAIM] --oidc-required-groups string Comma-separated list of groups — user must belong to at least one to log in [$OIDC_REQUIRED_GROUPS] --oidc-jit-provision Auto-create osctrl users on first OIDC login (as non-admin) [$OIDC_JIT_PROVISION] --oidc-use-pkce Enable PKCE (S256) for the OIDC Authorization Code flow [$OIDC_USE_PKCE] --oidc-link-local-accounts Let an OIDC login claim an existing local password account with the same username, instead of refusing it. Disabled by default: with this on, whoever controls the IdP's username namespace can take over any same-named local account, admins included. [$OIDC_LINK_LOCAL_ACCOUNTS] --saml-enabled Enable the SAML 2.0 federated-login surface on osctrl-api [$SAML_ENABLED] --saml-idp-metadata-url string URL to the IdP's SAML metadata document — fetched once at startup, signing certs + SSO endpoint discovered from it [$SAML_IDP_METADATA_URL] --saml-entity-id string SP entity ID — what the IdP knows us by (conventionally the metadata URL) [$SAML_ENTITY_ID] --saml-acs-url string Assertion Consumer Service URL — where the IdP POSTs SAMLResponse (must end with /api/v1/auth/saml/acs) [$SAML_ACS_URL] --saml-jit-provision Auto-create osctrl users on first SAML login (as non-admin) [$SAML_JIT_PROVISION] --saml-link-local-accounts Let a SAML login claim an existing local password account with the same username, instead of refusing it. Disabled by default: with this on, whoever controls the IdP's username namespace can take over any same-named local account, admins included. [$SAML_LINK_LOCAL_ACCOUNTS] --saml-username-attribute string SAML attribute (Name or FriendlyName) whose value becomes the osctrl username; empty = use NameID verbatim [$SAML_USERNAME_ATTRIBUTE] --saml-signing-cert string Path to PEM cert used to sign outbound AuthnRequests (paired with --saml-signing-key); empty disables AuthnRequest signing [$SAML_SIGNING_CERT] --saml-signing-key string Path to PEM RSA private key used to sign outbound AuthnRequests (paired with --saml-signing-cert) [$SAML_SIGNING_KEY] --saml-force-authn Force re-authentication at the IdP on every SAML login (defaults true; SLO substitute since v1 has no SAML SLO) [$SAML_FORCE_AUTHN] --saml-logout-url string IdP session-termination URL for SAML users (e.g. https://tenant.auth0.com/v2/logout) — the logout handler returns it so the SPA can end the IdP session [$SAML_LOGOUT_URL] --mcp-enabled Serve the Model Context Protocol endpoint at /api/v1/mcp, exposing osctrl's read surface to MCP clients under the caller's own permissions [$MCP_ENABLED] --mcp-allow-writes Also expose the mutating MCP tools (run_query, expire_query, complete_query, tag_node). Requires --mcp-enabled; the caller's own permissions still apply [$MCP_ALLOW_WRITES] --osquery-version string Version of osquery to be used (default: "5.24.0") [$OSQUERY_VERSION] --osquery-tables-file string File with the osquery tables to be used (default: "./data/5.24.0.json") [$OSQUERY_TABLES] --osquery-logger Enable remote tls logger for osquery [$OSQUERY_LOGGER] --osquery-config Enable remote tls config for osquery [$OSQUERY_CONFIG] --osquery-query Enable remote tls queries for osquery [$OSQUERY_QUERY] --osquery-carve Enable remote tls carver for osquery [$OSQUERY_CARVE] --osquery-accelerated Enable accelerated mode when returning distributed queries to osquery [$OSQUERY_ACCELERATED] --osquery-file-explorer Enable on-demand node file explorer queries [$OSQUERY_FILE_EXPLORER] --osquery-console Enable on-demand per-node console queries [$OSQUERY_CONSOLE] --read-only-configuration Disable configuration changes via admin or api services [$OSQUERY_READ_ONLY] --carver-type string Carver to be used to receive files extracted from nodes (db or s3) (default: "db") [$CARVER_TYPE] --carver-s3-bucket string S3 bucket to be used as configuration for carves [$CARVER_S3_BUCKET] --carver-s3-region string S3 region to be used as configuration for carves [$CARVER_S3_REGION] --carve-s3-key-id string S3 access key id to be used as configuration for carves [$CARVER_S3_KEY_ID] --carve-s3-secret string S3 access key secret to be used as configuration for carves [$CARVER_S3_SECRET] --carver-local-dir string Unused: the local carver is not supported (default: "./carved_files/") [$CARVER_LOCAL_DIR] --rate-limit-login-burst int Maximum burst for the login rate limiter (default: 10) [$RATE_LIMIT_LOGIN_BURST] --rate-limit-login-period duration Refill period for the login rate limiter (default: 1m0s) [$RATE_LIMIT_LOGIN_PERIOD] --rate-limit-login-evict-after duration Idle bucket eviction window for the login rate limiter (default: 10m0s) [$RATE_LIMIT_LOGIN_EVICT_AFTER] --rate-limit-login-retry-after int Retry-After seconds returned by the login rate limiter (default: 60) [$RATE_LIMIT_LOGIN_RETRY_AFTER] --rate-limit-login-max-buckets int Maximum per-key buckets for the login rate limiter; 0 uses the default (default: 0) [$RATE_LIMIT_LOGIN_MAX_BUCKETS] --rate-limit-pre-auth-burst int Maximum burst for the pre-auth rate limiter (default: 60) [$RATE_LIMIT_PRE_AUTH_BURST] --rate-limit-pre-auth-period duration Refill period for the pre-auth rate limiter (default: 1m0s) [$RATE_LIMIT_PRE_AUTH_PERIOD] --rate-limit-pre-auth-evict-after duration Idle bucket eviction window for the pre-auth rate limiter (default: 10m0s) [$RATE_LIMIT_PRE_AUTH_EVICT_AFTER] --rate-limit-pre-auth-retry-after int Retry-After seconds returned by the pre-auth rate limiter (default: 60) [$RATE_LIMIT_PRE_AUTH_RETRY_AFTER] --rate-limit-pre-auth-max-buckets int Maximum per-key buckets for the pre-auth rate limiter; 0 uses the default (default: 0) [$RATE_LIMIT_PRE_AUTH_MAX_BUCKETS] --rate-limit-service-config-apply-burst int Maximum burst for the service-config-apply rate limiter (default: 3) [$RATE_LIMIT_SERVICE_CONFIG_APPLY_BURST] --rate-limit-service-config-apply-period duration Refill period for the service-config-apply rate limiter (default: 10m0s) [$RATE_LIMIT_SERVICE_CONFIG_APPLY_PERIOD] --rate-limit-service-config-apply-evict-after duration Idle bucket eviction window for the service-config-apply rate limiter (default: 30m0s) [$RATE_LIMIT_SERVICE_CONFIG_APPLY_EVICT_AFTER] --rate-limit-service-config-apply-retry-after int Retry-After seconds returned by the service-config-apply rate limiter (default: 60) [$RATE_LIMIT_SERVICE_CONFIG_APPLY_RETRY_AFTER] --rate-limit-service-config-apply-max-buckets int Maximum per-key buckets for the service-config-apply rate limiter; 0 uses the default (default: 0) [$RATE_LIMIT_SERVICE_CONFIG_APPLY_MAX_BUCKETS] --enable-http-debug Enable HTTP Debug mode to dump full HTTP incoming request [$HTTP_DEBUG] --http-debug-file string File to dump the HTTP requests when HTTP Debug mode is enabled (default: "./debug-http-api.log") [$HTTP_DEBUG_FILE] --http-debug-show-body Show body of the HTTP requests when HTTP Debug mode is enabled [$HTTP_DEBUG_SHOW_BODY] --http-debug-host string Only dump HTTP requests from the osquery node with this UUID / host_identifier (case-insensitive). Empty dumps everything when --enable-http-debug is set. [$HTTP_DEBUG_HOST] --db-health-check Enable a background DB liveness monitor. After --db-health-threshold consecutive ping failures, EnvCache switches to stale-serve mode (serve cached entries on DB miss, extend TTLs) so the API keeps responding to read-only env lookups during a DB outage. Disabled by default. [$DB_HEALTH_CHECK] --db-health-interval int Seconds between DB health pings when --db-health-check is enabled. (default: 5) [$DB_HEALTH_INTERVAL] --db-health-threshold int Consecutive DB ping failures required before EnvCache enters stale-serve mode. (default: 3) [$DB_HEALTH_THRESHOLD] --version, -v Print version information --help, -h show help