api.yml

# YAML configuration for osctrl-api.
# This service is the authenticated REST API used by the React frontend,
# osctrl-cli, and automation.

# Version of the configuration schema this file targets. osctrl warns at
# startup when this differs from the version the binary supports: a lower
# number means fields were added since this file was written, a higher
# number means the binary is older than this file. See pkg/config/version.go.
version: 4

# Main HTTP service behavior and shared service-level features.
service:
  # Optional live query/carve notifications. Enable on both API and TLS.
  eventsEnabled: false
  # Set a shared deployment-unique Redis channel namespace before enabling.
  eventsNamespace: ""
  # Address to bind. Use 0.0.0.0 inside containers or behind a proxy.
  listener: 127.0.0.1
  # TCP port for osctrl-api.
  port: 9000
  # Valid values: "debug", "info", "warn", "error"
  logLevel: info
  # Valid values: "json", "console"
  logFormat: json
  # Public hostname used when building URLs and operator-facing metadata.
  host: osctrl.net
  # Valid values: "jwt", "none". `none` requires OSCTRL_INSECURE_NO_AUTH=1
  # in the environment and is intended for local-dev only — it impersonates
  # super-admin on every request. Production deployments MUST use `jwt`.
  auth: jwt
  # Serve /api/v1/service-config and show the Service Config section in
  # the SPA, where sections can be read, edited, written back to this file
  # and applied with a restart. This switch does not change how config is
  # loaded: every boot seeds the sections of this file into the
  # service_config table and then resolves those rows back over them, so
  # the service always runs on the stored values. When false (default)
  # none of the routes are registered and the SPA hides the section —
  # change the rows directly in the database, or this file, and restart.
  serviceConfigEnabled: false
  # Multi-factor authentication for password logins. When true, users
  # without a second factor enroll an authenticator app at their next
  # login instead of being locked out; service accounts (token-based) and
  # federated logins are unaffected. Users can always enroll voluntarily
  # from their profile page, whether or not this is set.
  mfaRequired: false
  # Label authenticator apps show next to the account. Empty uses
  # "osctrl (<host>)".
  mfaIssuer: ""
  # WebAuthn Relying Party ID for passkeys and hardware security keys:
  # the registrable domain, no scheme or port. Empty uses `host`.
  # Changing it invalidates every credential already registered.
  mfaRPID: ""
  # Comma-separated list of origins the SPA is served from, with scheme
  # and any non-default port ("https://osctrl.example.com:8443"). Empty
  # uses https://<mfaRPID>. A browser refuses the ceremony when its
  # origin is not listed, so this must match what users actually visit.
  mfaOrigins: ""
  # Write security-relevant API actions to audit_logs.
  auditLog: true
  # Comma-separated CIDR list whose X-Real-IP / X-Forwarded-For headers
  # utils.GetIP will trust. Leave empty (default) when osctrl-api is
  # directly internet-facing — forwarding headers are then ignored and
  # RemoteAddr is used verbatim, preventing header-spoofed rate-limit
  # bypass and audit-log poisoning. Set to your edge proxy's CIDR(s)
  # when osctrl-api sits behind a trusted reverse proxy (e.g.
  # `10.0.0.0/8` or `192.0.2.1/32,2001:db8::/64`).
  trustedProxies: ""
  # Path to a MaxMind GeoLite2-Country .mmdb file. When set, node IP
  # addresses are resolved to ISO 3166-1 alpha-2 country codes and
  # included in the node API response (shown as flag emojis in the
  # SPA nodes table and node detail page). Empty (default) disables
  # GeoIP entirely — no lookups, no country codes, no overhead.
  # Download the free database from:
  #   https://dev.maxmind.com/geoip/geolite2-free-geolocation-data
  # Update weekly for best accuracy. Example:
  #   geoipDBPath: /data/GeoLite2-Country.mmdb
  geoipDBPath: ""
  # Enable the security & compliance posture system. When false
  # (default), posture API endpoints are not registered and the SPA
  # hides posture controls. When true, the API serves posture data
  # from the shared database (collected by osctrl-tls).
  postureEnabled: false
  # Only used by osctrl-tls for ingestion; kept here so the service
  # configuration shape is complete and can round-trip through the API.
  postureQueryPrefix: "osctrl:posture:"
  # Enable the alerting subsystem. When false (default), the alert API
  # routes are not registered and the alert tables are not created.
  # When true, the API serves alert rule/channel management and
  # history from the shared database (evaluated by osctrl-tls).
  # Requires a service restart to change.
  alertsEnabled: false
  # Enable the health/system-status subsystem. When false (default), the
  # /api/v1/health routes are not registered and the SPA hides the Health
  # section. When true, the API serves GET /api/v1/health/status: a live
  # DB ping, a Redis PING, its own runtime stats, the osctrl-tls
  # heartbeat, and cached upgrade status. Requires a service restart to
  # change.
  healthEnabled: false
  # DB health monitor. When enabled, osctrl-api pings the database
  # every dbHealthInterval seconds. After dbHealthThreshold
  # consecutive failures, EnvCache switches to stale-serve mode:
  # cached entries are served on DB miss instead of returning 500,
  # and TTLs are extended to ~60m so cached envs stay warm for the
  # duration of the outage. This keeps the API responding to
  # read-only env lookups (used by handlers that consult EnvCache)
  # during a DB outage. Write paths still require the DB and will
  # fail. The stale-serve window is bounded at 60m so rotated
  # enroll secrets are not accepted indefinitely.
  # Disabled by default; enable in production where DB blips are
  # expected and API availability for read paths is prioritized.
  dbHealthCheck: false
  # Seconds between DB health pings.
  dbHealthInterval: 5
  # Consecutive failures before EnvCache enters stale-serve mode.
  dbHealthThreshold: 3

# Database configuration. This is the primary source of truth for API state.
db:
  # Valid values: "postgres", "mysql", "sqlite".
  type: postgres
  # Database host. Ignored by sqlite.
  host: 127.0.0.1
  # Database port. Defaults match PostgreSQL.
  port: 5432
  # Database/schema name.
  name: osctrl
  # Database username.
  username: postgres
  # Database password. Prefer env vars/secrets in production.
  password: postgres
  # PostgreSQL SSL mode, for example disable, require, verify-full.
  sslmode: disable
  # Maximum idle DB connections retained by the pool.
  maxIdleConns: 20
  # Maximum open DB connections.
  maxOpenConns: 100
  # Maximum connection lifetime in minutes.
  connMaxLifetime: 30
  # Seconds to keep retrying DB connection at startup; 0 fails fast.
  connRetry: 10
  # SQLite database file path when type is sqlite.
  filePath: ./osctrl.db

# Redis cache configuration. Used for env cache, activity tiles, and query cache.
redis:
  # Redis host when connectionString is empty.
  host: 127.0.0.1
  # Redis port when connectionString is empty.
  port: 6379
  # Redis password when connectionString is empty.
  password: ""
  # Full Redis URL. Overrides host/port/password/db when set.
  connectionString: ""
  # Redis logical DB number.
  db: 0
  # Seconds to keep retrying Redis connection at startup; 0 fails fast.
  connRetry: 10

# HTTP request rate limits. Values match the built-in defaults.
rateLimits:
  # Password and SSO login initiation attempts per client IP.
  login:
    # Tokens available immediately.
    burst: 10
    # Refill window.
    period: 1m
    # Idle client buckets are evicted after this duration.
    evictAfter: 10m
    # Retry-After response header in seconds.
    retryAfter: 60
    # Maximum tracked client buckets; 0 uses the internal default.
    maxBuckets: 0
  # Read-only pre-auth routes, such as login environment/method discovery.
  preAuth:
    burst: 60
    period: 1m
    evictAfter: 10m
    retryAfter: 60
    maxBuckets: 0
  # POST /api/v1/service-config/apply restart requests.
  serviceConfigApply:
    burst: 3
    period: 10m
    evictAfter: 30m
    retryAfter: 60
    maxBuckets: 0
  # Unused by osctrl-api; present so rateLimits has the full shared shape.
  enroll:
    burst: 20
    period: 1m
    evictAfter: 10m
    retryAfter: 60
    maxBuckets: 0

# osquery feature switches used by API handlers and the frontend feature API.
osquery:
  # osquery schema version shown to query-building UI.
  version: 5.23.1
  # JSON schema file with osquery table metadata.
  tablesFile: ./data/5.23.1.json
  # Whether osquery log endpoints/features are enabled.
  logger: true
  # Whether remote config management is enabled.
  config: true
  # Whether distributed query APIs are enabled.
  query: true
  # Whether file carve APIs are enabled.
  carve: true
  # Whether accelerated query polling features are enabled.
  accelerated: false
  # Whether per-node console routes are enabled when query is also true.
  console: false
  # Whether per-node file explorer routes are enabled when query is also true.
  fileExplorer: false
  # Prevents API-driven osquery configuration changes when true.
  readOnly: false

# SAML 2.0 federated login. Disabled by default; when `enabled` is true
# the API fetches the IdP metadata at startup and REFUSES TO START if
# that fails, rather than serving a login page with a broken SSO button.
# The SPA discovers this via GET /api/v1/auth/methods and renders a
# "Continue with SAML" button automatically — no frontend rebuild needed.
#
# Register osctrl with the IdP by pointing it at the SP metadata URL:
#   https://<host>/api/v1/auth/saml/metadata
#
# Note: certPath, keyPath, rootUrl, loginUrl and spInitiated are legacy
# fields consumed only by osctrl-admin; osctrl-api ignores them.
# See docs/auth-providers.md for per-IdP walkthroughs.
saml:
  # Enables SAML routes when true.
  enabled: false
  # SP entity ID — what the IdP knows us by, conventionally the metadata URL
  entityId: ""
  # Where the IdP POSTs the SAMLResponse; must end with /api/v1/auth/saml/acs
  acsUrl: ""
  # Legacy SAML certificate path; ignored by osctrl-api.
  certPath: ""
  # Legacy SAML private key path; ignored by osctrl-api.
  keyPath: ""
  # IdP metadata XML — fetched once at startup for signing certs + SSO endpoint
  metadataUrl: ""
  # Legacy service root URL; ignored by osctrl-api.
  rootUrl: ""
  # Legacy IdP login URL; ignored by osctrl-api.
  loginUrl: ""
  # IdP session-termination URL (e.g. https://<tenant>.auth0.com/v2/logout).
  # Returned to the SPA on logout so the IdP session dies too; without it
  # the next SSO click silently re-authenticates.
  logoutUrl: ""
  # Auto-create osctrl users on first login, as non-admin
  jitProvision: false
  # Let a SAML login claim an existing LOCAL password account with the same
  # username, instead of refusing it. Off by default: with this on, whoever
  # controls the IdP's username namespace can take over any same-named local
  # account, admins included. Turn it on when you pre-create accounts locally
  # and want the IdP to adopt them; the first such login stamps the row as
  # federated and is recorded in the audit log.
  linkLocalAccounts: false
  # Attribute (Name or FriendlyName) whose value becomes the osctrl username.
  # Empty = use the NameID verbatim, which is usually a mailbox and is fine:
  # a username may be either a plain handle (^[a-zA-Z0-9_-]{1,64}$) or an
  # email address. Email usernames are stored lowercased so identity does not
  # depend on the casing the IdP happens to emit.
  usernameAttribute: ""
  # PEM cert + RSA key for signing outbound AuthnRequests. Both must be set
  # to enable signing; some IdPs require it and all should support it.
  signingCertPath: ""
  signingKeyPath: ""
  # Force re-authentication at the IdP on every login. Defaults true — it is
  # the substitute for SAML SLO, which is not implemented yet.
  forceAuthn: true
  # Legacy flag from the old admin service; ignored by osctrl-api.
  spInitiated: false

# OIDC federated login. Same posture as SAML above: disabled by default,
# fail-fast on discovery errors at startup, advertised to the SPA through
# /api/v1/auth/methods. Both protocols can be enabled at the same time.
oidc:
  # Enables OIDC routes when true.
  enabled: false
  # Realm root — /.well-known/openid-configuration is appended automatically
  issuerUrl: ""
  # OIDC client ID registered with the IdP.
  clientId: ""
  # OIDC client secret. Prefer env vars/secrets in production.
  clientSecret: ""
  # Must match the IdP client config and end with /api/v1/auth/oidc/callback
  redirectUrl: ""
  # Empty defaults to [openid, profile, email]
  scopes: []
  # Empty defaults to preferred_username. `email` is supported and is stored
  # lowercased; it is only accepted when the IdP also sets email_verified, so
  # an unverified address cannot claim someone else's account. Auth0's `sub`
  # (e.g. `auth0|abc123`) is still rejected — use `nickname` or `email` there.
  usernameClaim: ""
  # Empty defaults to `groups`
  groupsClaim: ""
  # Login is denied unless the user belongs to at least one of these.
  # Empty disables the group gate.
  requiredGroups: []
  # Auto-create osctrl users on first login, as non-admin
  jitProvision: false
  # Let an OIDC login claim an existing LOCAL password account with the same
  # username, instead of refusing it. Off by default: with this on, whoever
  # controls the IdP's username namespace can take over any same-named local
  # account, admins included. Turn it on when you pre-create accounts locally
  # and want the IdP to adopt them; the first such login stamps the row as
  # federated and is recorded in the audit log.
  linkLocalAccounts: false
  # PKCE (S256) for the authorization code flow
  usePKCE: false

# Model Context Protocol endpoint, served at /api/v1/mcp. Lets MCP clients
# (Claude Code, Claude Desktop, and others) read the fleet — environments,
# nodes, the osquery schema, and query results.
#
# Disabled by default: it is a read surface designed for LLM agents, and that
# should be an explicit choice rather than something a deployment inherits on
# upgrade.
#
# Enabling it grants no new access. Requests authenticate with the same bearer
# token or session cookie as any other API call, and each tool call is
# dispatched back through osctrl-api's own handlers — so the per-endpoint
# permission checks apply exactly as they do for the SPA or osctrl-cli. A
# caller sees only what their own token already allows.
#
# See docs/mcp.md.
mcp:
  enabled: false
  # Also expose the mutating tools: run_query, expire_query, complete_query
  # and tag_node. Separate from `enabled`, and off by default, because the
  # risks are not comparable — a read tool spends context, while run_query
  # spends work on every targeted endpoint, and an agent acting on text it
  # read from a monitored host only becomes a real path once writes are on.
  #
  # The caller's own permissions still apply either way (run_query needs
  # query-level, tag_node admin-level); this switch decides whether the tools
  # exist at all. Queries scheduled through MCP are never hidden and always
  # carry an expiry, so an operator can see and outlast anything an agent
  # started.
  allowWrites: false

# JWT authentication configuration. Used for API bearer tokens and SPA cookies.
jwt:
  # Signing secret. Required when auth is jwt.
  jwtSecret: ""
  # JWT lifetime in hours.
  hoursToExpire: 3

# TLS termination configuration for serving HTTPS directly from osctrl-api.
tls:
  # When false, terminate TLS at nginx/load balancer instead.
  termination: false
  # PEM certificate file when termination is true.
  certificateFile: ./config/tls.crt
  # PEM private key file when termination is true.
  keyFile: ./config/tls.key

# Logger configuration to handle received logs from osquery nodes
logger:
  # Valid values: "none", "stdout", "file", "db", "graylog", "splunk", "logstash", "kinesis", "s3", "kafka", "elastic"
  type: db
  # Optional multi-destination logging/export. Empty uses `type`.
  types: []
  # Reuse the main db section for DB logging when true.
  loggerDBSame: false
  # Also persist status/on-demand query logs in DB even with external exporters.
  alwaysLog: false
  # Separate DB destination for log records when loggerDBSame is false.
  # Fields match the top-level db section.
  db:
    type: ""
    host: ""
    port: 0
    name: ""
    username: ""
    password: ""
    sslmode: ""
    maxIdleConns: 0
    maxOpenConns: 0
    connMaxLifetime: 0
    connRetry: 0
    filePath: ""
  # S3 logger destination.
  s3:
    # Bucket name for log objects.
    bucket: ""
    # AWS region for the bucket.
    region: ""
    # Optional static access key. Prefer instance/task roles in production.
    accessKey: ""
    # Optional static secret key. Prefer instance/task roles in production.
    secretAccessKey: ""
  # Graylog logger destination.
  graylog:
    # Graylog endpoint URL.
    url: ""
    # Source host value attached to Graylog messages.
    host: ""
    # Stream/name for distributed query logs.
    queries: ""
    # Stream/name for status logs.
    status: ""
    # Stream/name for result logs.
    results: ""
  # Elasticsearch logger destination.
  elastic:
    # Elasticsearch host.
    host: ""
    # Elasticsearch port.
    port: ""
    # Prefix for generated index names.
    indexPrefix: ""
    # Separator used inside date suffixes.
    dateSeparator: ""
    # Separator between prefix and date suffix.
    indexSeparator: ""
  # Splunk HEC logger destination.
  splunk:
    # Splunk HEC URL.
    url: ""
    # Splunk HEC token. Prefer env vars/secrets in production.
    token: ""
    # Source host value attached to events.
    host: ""
    # Splunk index name.
    index: ""
  # Logstash logger destination.
  logstash:
    # Logstash host.
    host: ""
    # Logstash port.
    port: ""
    # Transport protocol, for example tcp or udp.
    protocol: ""
    # Optional HTTP/TCP path depending on protocol.
    path: ""
  # AWS Kinesis logger destination.
  kinesis:
    # Kinesis stream name.
    stream: ""
    # AWS region for the stream.
    region: ""
    # Optional custom endpoint.
    endpoint: ""
    # Optional static access key. Prefer instance/task roles in production.
    accessKey: ""
    # Optional static secret key. Prefer instance/task roles in production.
    secretKey: ""
    # Optional AWS session token.
    sessionToken: ""
  # Kafka logger destination.
  kafka:
    # Comma-separated Kafka bootstrap servers.
    bootstrapServers: ""
    # CA certificate path for TLS verification.
    sslCALocation: ""
    # Connection timeout.
    connectionTimeout: 5s
    # SASL authentication settings.
    sasl:
      # SASL mechanism, such as plain or scram-sha-512.
      mechanism: ""
      # SASL username.
      username: ""
      # SASL password. Prefer env vars/secrets in production.
      password: ""
    # Kafka topic for log events.
    topic: ""
  # Local rotating file logger destination.
  local:
    # Log file path for local/file logging.
    filePath: ""
    # Rotate after this size in MB.
    maxSize: 0
    # Number of rotated files to keep.
    maxBackups: 0
    # Days to keep rotated files.
    maxAge: 0
    # Compress rotated files with gzip.
    compress: false

# Carver configuration to handle file carves from osquery nodes
carver:
  # Valid values: "none", "local", "db", "s3"
  type: db
  # S3 destination for carved files when type is s3.
  s3:
    # Bucket name for carved files.
    bucket: ""
    # AWS region for the bucket.
    region: ""
    # Optional static access key. Prefer instance/task roles in production.
    accessKey: ""
    # Optional static secret key. Prefer instance/task roles in production.
    secretAccessKey: ""
  # Local filesystem destination when type is local.
  local:
    # Directory where carved files are written.
    carvesDir: ./carved_files/

# Debug configuration for dumping incoming HTTP requests. Use only temporarily.
debug:
  # Enables request dumping.
  enableHttp: false
  # Destination file for dumped requests.
  httpFile: ./debug-http-api.log
  # Include request bodies. May contain secrets or node data.
  showBody: false
  # When non-empty, only dump requests from the osquery node whose UUID
  # (or enroll host_identifier) matches this value (case-insensitive).
  # Empty dumps every request when enableHttp is true.
  hostIdentifier: ""