Configuration and environment variables¶

What the CLI reads from its environment, and where its settings come from. This page is generated from the CLI source: every environment variable the public commands read is listed here.

Source

Generated from untrust 1.3.0 (commit 7ef462d9a0c3).

Where settings come from¶

Command-line options. Every scan target and setting is an option. untrust scan has no configuration file.
Environment variables, below. Where a variable stands in for an option, the option you pass takes precedence over the variable, and the variable over the default.
The hosted service's address is always an option, never a default: --org-url (https://<host>/v1/organizations/<org>) for api get and report-upload, --endpoint for release, --origin for collector enroll.
Collector state lives in <state-dir>/collector.json, readable only by its owner. The state directory is --state-dir, then UNTRUST_COLLECTOR_STATE, then ~/.untrust-collector. install-service writes the systemd unit untrust-collector.service with those settings built in.

Cloud credentials and region¶

The scanner uses each cloud SDK's own credential chain and reads none of their variables itself:

Cloud	Credentials
AWS	The boto3 chain: `AWS_PROFILE`, `AWS_ACCESS_KEY_ID` and friends, or an instance or workload role. `untrust scan` and `untrust detect` default `--region` to `us-west-2`, so `AWS_REGION` has no effect on them; pass `--region`.
GCP	Application Default Credentials, including `GOOGLE_APPLICATION_CREDENTIALS`.
Azure	`DefaultAzureCredential` with the `azure` extra, so the standard `AZURE_*` variables work. Without the extra, a token from `az account get-access-token`.

Network¶

Requests to the hosted service use HTTPS, time out after 30 seconds and never follow redirects. report-upload, api get and release don't retry; the CI upload client retries a transient failure up to three times.
collector enroll, collector run and collector install-service take --ca-file to trust a private certificate authority, for example a TLS-inspecting proxy. Other commands use the system trust store.

Credentials for the hosted service¶

Each stands in for a command-line option. An option you pass beats the variable.

Variable	Read by	Default	Purpose
`UNTRUST_API_KEY`	`api get`, `report-upload`, `release verify`, `release se-request`	none	Organization API key. Used when `--api-key` (or `--token` on `release`) is not given. Secret.
`UNTRUST_API_TOKEN`	`release verify`, `release se-request`	none	Second name for the `release` token, read after `UNTRUST_API_KEY`. Secret.
`UNTRUST_CI_ID_TOKEN`	`registry scan --policy-url`	empty	A CI provider ID token sent to fetch your registry trust policy from the console, when `--github-oidc` is not used. Secret.
`UNTRUST_ENROLL`	`collector enroll`	none	One-time enrollment token. Used when `--token` is not given. Secret.

Build and IaC gates, and pull request feedback¶

Variable	Read by	Default	Purpose
`CI_JOB_TOKEN`	`ci-feedback --fetch-base` on GitLab	none	Downloads the target branch's base report. Secret.
`GITHUB_TOKEN`	`ci-feedback` on GitHub; `registry scan` for GHCR	none	Creates the Check Run. Also the fallback login for `ghcr.io`. Secret.
`UNTRUST_CUSTOM_RULES`	`buildscan`, `iacscan`	unset	Path to your organization's custom rules file. `--custom-rules` takes precedence.
`UNTRUST_GITLAB_TOKEN`	`ci-feedback` on GitLab	none	Project access token with `api` scope, used to post the merge request note and commit status. Secret.
`UNTRUST_OCI_IMAGE_CONFIG`	`buildscan` (OCI images)	unset	Path to the image's `image-config.json`, used to work out the user the image runs as.
`UNTRUST_PROGRESS_FILE`	`buildscan`, `iacscan`	unset	Progress checkpoint file. `--progress-file` takes precedence.
`UNTRUST_RULE_SETTINGS`	`ci-feedback`	unset	JSON file of your organization's rule overrides (`--rule-settings`).
`UNTRUST_SOURCE_PATH_PREFIX`	`buildscan`, `ci-feedback`	unset	Install directory inside the artifact to strip from finding paths (`ci-feedback --strip-prefix`).
`UNTRUST_SOURCE_REPO`	`buildscan`	unset	Repository the artifact was built from, to map findings back to source. Set together with `UNTRUST_SOURCE_REVISION`.
`UNTRUST_SOURCE_REPO_PREFIX`	`buildscan`, `ci-feedback`	empty	Source directory in the repository to prepend to finding paths (`ci-feedback --repo-prefix`).
`UNTRUST_SOURCE_REVISION`	`buildscan`	unset	Commit the artifact was built from. Set together with `UNTRUST_SOURCE_REPO`.

Registry scans¶

Registry logins and the tools registry scan runs. The tools run with a temporary Docker configuration, and any COSIGN_* variables are removed from their environment.

Variable	Read by	Default	Purpose
`AZURE_ACCESS_TOKEN`	`registry scan` (Azure Container Registry)	`DefaultAzureCredential`	Azure Resource Manager token, exchanged for a registry token. Secret.
`GHCR_TOKEN`	`registry scan`	unset (anonymous)	Token for `ghcr.io`. Secret.
`GHCR_USERNAME`	`registry scan`	`untrust`	User name for `ghcr.io`.
`UNTRUST_COSIGN`	`registry scan`	`cosign` on `PATH`	Path to the cosign binary.
`UNTRUST_GH`	`registry scan`	`gh` on `PATH`	Path to the GitHub CLI, used to check build provenance.
`UNTRUST_NOTATION`	`registry scan`	`notation` on `PATH`	Path to the notation binary.
`UNTRUST_NOTATION_PLUGINS`	`registry scan`	unset	Notation plugin directory, for example for the AWS Signer plugin.
`UNTRUST_REGISTRY_PASSWORD`	`registry scan`	unset	Password for other registries. Secret.
`UNTRUST_REGISTRY_USERNAME`	`registry scan`	unset	User name for other registries. Used only when the password is also set.

Collector¶

Variable	Read by	Default	Purpose
`UNTRUST_COLLECTOR_STATE`	`collector`	`~/.untrust-collector`	State directory. `--state-dir` takes precedence.
`UNTRUST_COLLECTOR_TOOL_DIRS`	`collector`	`/usr/bin:/usr/local/bin`	Colon-separated directories the collector trusts for evidence tools.
`UNTRUST_COLLECTOR_TPM_QUOTE`	`collector`	off	`1` adds a TPM 2.0 quote to fleet evidence on bare-metal SEV-SNP, TDX and SGX hosts.
`UNTRUST_COLLECT_ROOT_LOGINS`	`collector`	unset	`1` is the same as `--collect-root-logins`.
`UNTRUST_NITRO_AGENT_PORT`	`collector run` on a Nitro parent	`5005`	vsock port of the enclave agent.
`UNTRUST_NITRO_ENCLAVE_CID`	`collector run` on a Nitro parent	unset	CID of the enclave running `untrust collector nitro-agent`.
`UNTRUST_PPCIE`	`collector`	off	`1` forces multi-GPU protected PCIe (PPCIe) mode.

CI run metadata¶

Read from the CI system's own variables; you don't set these. Only GitHub Actions and GitLab CI/CD are recognised.

Variable	Read by	Purpose
`ACTIONS_ID_TOKEN_REQUEST_TOKEN`	`registry scan --github-oidc`	Authorizes the OIDC token request.
`ACTIONS_ID_TOKEN_REQUEST_URL`	`registry scan --github-oidc`	Where to request the GitHub OIDC token. Its host must end in `.actions.githubusercontent.com`.
`CI_API_V4_URL`	`ci-feedback --provider auto`	Present on GitLab; selects GitLab when not on GitHub.
`CI_COMMIT_BRANCH`	run metadata	Set when the pipeline runs for a branch.
`CI_COMMIT_REF_NAME`	run metadata	Branch or tag name.
`CI_COMMIT_SHA`	`ci-feedback`	Commit for the commit status.
`CI_COMMIT_TAG`	run metadata	Set when the pipeline runs for a tag.
`CI_JOB_NAME`	`ci-feedback`	Job name shown in the commit status.
`CI_JOB_URL`	`ci-feedback`	Link from the commit status.
`CI_MERGE_REQUEST_IID`	`ci-feedback`	Merge request for the note.
`CI_MERGE_REQUEST_TARGET_BRANCH_NAME`	run metadata, `ci-feedback`	Target branch of a merge request.
`CI_PIPELINE_SOURCE`	run metadata	Trigger of the pipeline.
`CI_PIPELINE_URL`	run metadata	Pipeline URL.
`CI_PROJECT_ID`	`ci-feedback`	Project for the merge request note.
`GITHUB_ACTIONS`	`ci-feedback --provider auto`	`true` selects GitHub.
`GITHUB_ACTOR`	run metadata	Who started a manually dispatched run (recorded only for `workflow_dispatch`).
`GITHUB_API_URL`	`ci-feedback`	GitHub API base, for GitHub Enterprise Server.
`GITHUB_BASE_REF`	run metadata	Target branch of a pull request.
`GITHUB_EVENT_NAME`	run metadata	Trigger of the run.
`GITHUB_REF`	`ci-feedback`	Full ref of the run.
`GITHUB_REF_NAME`	run metadata	Branch or tag name.
`GITHUB_REF_TYPE`	run metadata	Whether the ref is a branch or a tag.
`GITHUB_REPOSITORY`	run metadata, `ci-feedback`	Builds the run URL; repository for the Check Run.
`GITHUB_RUN_ID`	run metadata	Builds the run URL.
`GITHUB_SERVER_URL`	run metadata	Builds the run URL.
`GITHUB_SHA`	`ci-feedback`	Commit the Check Run is attached to.

Variables marked Secret hold credentials. Set them from your CI system's secret store, never in a file in the repository. The CLI reads tokens only from the environment, sends them only in request headers and never prints them.