Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

Every option is an environment variable and a command-line flag of the same name (NANOBOM_PUBLIC_URL is --public-url); a flag wins over the variable. nanobom <command> --help lists them with their defaults. This page lists the options of the server, nanobom serve, and those every command reads; the options of the other commands are in the command-line reference.

Boolean options take true or false, as variables and as flags (--run-after-upload false). Leave an option unset rather than empty: an empty variable is a value, and an empty URL is an invalid one, which stops nanobom at startup.

Every command

VariableFlagDefault
NANOBOM_DATABASE_URL--database-urlsqlite:///data/nanobom.dbThe database. SQLite: sqlite:///absolute/path.db (three slashes before an absolute path) or sqlite://relative/path.db, created if missing. PostgreSQL: postgres://user:password@host:port/database, an existing database (see below).
NANOBOM_LOG_FORMAT--log-formatjsonjson (one object per line, for collectors) or text.
NANOBOM_LOG_LEVEL--log-levelinfoA tracing filter, such as info,nanobom=debug. On PostgreSQL, the notices the server sends at startup (“relation already exists, skipping”) are logged from WARN up, not at INFO, unless the filter mentions sqlx; a filter such as error or off is never made more verbose.

PostgreSQL URLs

postgres://user:password@host:port/database?parameter=value&… (postgresql:// works too). The port defaults to 5432. Characters of the user or password outside letters, digits and -._~ are percent-encoded (@ is %40). The database must exist; nanobom creates its tables at startup, so the role needs to own the database or to be allowed to create tables in its public schema. nanobom opens at most 8 connections.

Parameter
sslmodedisable, prefer (the default: TLS when the server offers it, without checking the certificate), require (TLS, certificate not checked), verify-ca (certificate checked against the trusted authorities) or verify-full (also checks that it names the host). The trusted authorities are the public ones of webpki-roots, plus sslrootcert if given. Use verify-full: with verify-ca, any server holding a certificate from a public authority passes, whatever its name.
sslrootcertA PEM file of authorities to trust in addition to the public ones, such as a managed database’s CA bundle.
sslcert, sslkeyA client certificate and its key, for servers that require one.
application_nameThe name shown in pg_stat_activity.

See Run on PostgreSQL.

Addresses and files

VariableFlagDefault
NANOBOM_PUBLIC_URL--public-urlhttp://localhost:8080The address users reach nanobom at. Used for links in webhooks, emails and API responses, the OpenID Connect redirect URI, the Secure flag of cookies (set when it is https) and the cross-site request check (the Origin of form submissions must match it). Set it to the address in the browser’s address bar, scheme and port included.
NANOBOM_LISTEN_ADDRESS--listen-address0.0.0.0:8080Address and port to listen on. 127.0.0.1:8080 keeps nanobom reachable only through a local reverse proxy.
NANOBOM_SITE_ROOT--site-rootsiteThe directory of the web interface’s assets (the site directory of a release archive; /app/site in the image). Relative paths are relative to the working directory.

Runs

VariableFlagDefault
NANOBOM_SCHEDULE--schedule0 3 * * *When every project is re-evaluated: a cron expression in UTC with five fields (minute, hour, day of month, month, day of week), or off. 0 */6 * * * runs every six hours, 30 2 * * 1-5 at 02:30 on weekdays. off turns scheduled runs off; uploads and manual checks still run. An invalid expression stops the server at startup.
NANOBOM_RUN_AFTER_UPLOAD--run-after-uploadtrueEvaluate a project right after each upload. With false, projects are evaluated by the schedule, manual checks and uploads that wait.
NANOBOM_UPLOAD_WAIT_SECONDS--upload-wait-seconds300Longest time an upload with wait or fail_on waits for its evaluation. Keep it below your reverse proxy’s read timeout.
NANOBOM_MAX_WAITING_UPLOADS--max-waiting-uploads32Most uploads with wait or fail_on waiting for their evaluation at once; at least 1. Another one is refused with a 503 and Retry-After before anything is stored (status codes). Uploads that do not wait are not counted. Each waiting upload holds a connection open, through every proxy in between.
NANOBOM_OSV_URL--osv-urlhttps://api.osv.dev/The OSV API, or a compatible mirror offering /v1/querybatch and /v1/vulns/{id}.
NANOBOM_MAXIMUM_SBOM_SIZE--maximum-sbom-size16Largest accepted SBOM, in MiB. Parsing takes a few times this much memory.
NANOBOM_STALE_AFTER_DAYS--stale-after-days30Days without an SBOM after which a project is stale; 0 turns the feature off.
NANOBOM_FAILURE_WEBHOOK_URL--failure-webhook-urlReceives a run.failed document when a run fails.

Email

VariableFlagDefault
NANOBOM_SMTP_URL--smtp-urlThe SMTP server that sends email notifications. Unset, email is off and organizations’ email settings are hidden. smtps://user:password@smtp.example.org connects with TLS (port 465 by default); smtp://user:password@smtp.example.org:587?tls=required upgrades the connection with STARTTLS and fails without it; smtp://relay.internal:25 sends in clear text, for a relay on a trusted network only, so a smtp:// URL with a user or password must set tls=required or tls=opportunistic (STARTTLS when the server offers it); nanobom refuses to start otherwise. Percent-encode special characters of the user and password (@ as %40). Certificates are checked against the public authorities of webpki-roots. Treat it as a secret: it is not shown by --help nor logged.
NANOBOM_SMTP_FROM--smtp-fromThe sender of the emails, nanobom@example.org or nanobom <nanobom@example.org>. Required with NANOBOM_SMTP_URL.

nanobom refuses to start when NANOBOM_SMTP_URL is set without NANOBOM_SMTP_FROM, when either is invalid, or when a smtp:// URL has credentials but no tls=required or tls=opportunistic (the error says so without repeating the URL). The SMTP server itself is contacted at the first email: send a test email from an organization’s settings to check it. Removing NANOBOM_SMTP_URL abandons, at the next start, the emails still waiting for a retry.

Exploitation data

VariableFlagDefault
NANOBOM_EXPLOITATION_DATA--exploitation-datatrueDownload exploitation data (CISA KEV, FIRST EPSS) after each run. false for instances that cannot reach them; fail_on=exploited is then refused.
NANOBOM_KEV_URL--kev-urlhttps://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.jsonCISA’s Known Exploited Vulnerabilities catalog (JSON). A mirror must serve the catalog’s JSON as is.
NANOBOM_EPSS_URL--epss-urlhttps://api.first.org/data/v1/epssFIRST’s EPSS API. A mirror must answer GET <url>?cve=CVE-…,CVE-… like FIRST’s API.

Accounts and sessions

VariableFlagDefault
NANOBOM_LOCAL_ACCOUNTS--local-accountstrueSign-in with a username or email address and a password.
NANOBOM_PASSWORD_MINIMUM_LENGTH--password-minimum-length12Minimum length of local passwords.
NANOBOM_PERSONAL_ORGANIZATIONS--personal-organizationstrueGive each new user an organization of their own; applies to users created afterwards.
NANOBOM_SESSION_INACTIVITY_DAYS--session-inactivity-days7Sign users out after this many days without a request (at least 1).
NANOBOM_TRUST_FORWARDED_HEADERS--trust-forwarded-headersfalseRead client addresses from X-Forwarded-For, X-Real-IP and Forwarded, for sign-in rate limiting. Only behind a reverse proxy that sets them.

nanobom refuses to start when local accounts are off and OpenID Connect is not configured.

OpenID Connect

Enabled by setting both NANOBOM_OIDC_ISSUER and NANOBOM_OIDC_CLIENT_ID; setting only one stops nanobom at startup. See Set up single sign-on.

VariableFlagDefault
NANOBOM_OIDC_ISSUER--oidc-issuerIssuer URL of the provider; its discovery document is read from it.
NANOBOM_OIDC_CLIENT_ID--oidc-client-idClient identifier.
NANOBOM_OIDC_CLIENT_SECRET--oidc-client-secretClient secret, for confidential clients; public clients rely on PKCE alone.
NANOBOM_OIDC_SCOPES--oidc-scopesopenid profile emailScopes to request, separated by spaces.
NANOBOM_OIDC_CREATE_USERS--oidc-create-userstrueCreate users at their first sign-in.
NANOBOM_OIDC_ADMINISTRATOR_CLAIM--oidc-administrator-claimClaim granting instance administration, applied at each sign-in (administrator claim). Dotted paths reach nested claims.
NANOBOM_OIDC_ADMINISTRATOR_VALUE--oidc-administrator-valueValue the administrator claim must contain; without it, the claim must be true.
NANOBOM_OIDC_GROUPS_CLAIM--oidc-groups-claimClaim listing the user’s groups or roles, for the group mapping.
NANOBOM_OIDC_GROUP_MAPPING--oidc-group-mappinggroup=organization:role entries separated by ; or line breaks (syntax).
NANOBOM_OIDC_BUTTON_LABEL--oidc-button-labelSign in with single sign-onLabel of the sign-in button.