Runner configuration
Every setting of the runner's secret-providers.yaml, the settings each provider type takes, the environment variables the runner reads, and how to run the runner as a service.
Runner configuration
The runner (and the CLI) read PAM connection settings from one local file. Nothing in it is uploaded to Safeguard.
The settings retries, allowed_refs, allow_http, reason (for CyberArk CCP), revoke_leases, success_json_path, error_json_path and audit_file, and the local audit file, need a CLI released on or after 21 November 2026. From that release a plain http:// url to another machine is refused; change it to https://. Update with safeguard self-update.
The file
| Location | ~/.safeguard/secret-providers.yaml in the home folder of the account the runner runs as. SAFEGUARD_SECRET_PROVIDERS=/path/file.yaml uses another path. |
| Permissions | On macOS and Linux the file must not be readable by group or others (chmod 600), or it is refused. On Windows, restrict it with NTFS permissions to the runner's account. |
| When it is read | At every scan start and every access test, so an edit applies to the next scan without a restart. |
| Strictness | An unknown setting, an unknown provider type, a provider named twice, or a secret written inline makes the whole file refused, with the line number and no value in the message. |
| Check it | safeguard vault providers (add --json for scripts). |
A complete example with three providers:
providers:
- name: arcon
type: arcon
url: https://arcon.example.internal
variant: digital-vault
api_user: env://ARCON_API_USER
api_key: file:///etc/safeguard/arcon-api-key
ca_cert: /etc/safeguard/internal-root-ca.pem
allowed_refs:
- "Windows/10.0.5.*/svc_scan"
- "Web/*/svc_dast"
- name: ccp-prod
type: cyberark-ccp
url: https://ccp.example.internal
app_id: SafeguardScanner
client_cert: /etc/safeguard/ccp-client.pem
client_key: /etc/safeguard/ccp-client.key
ca_cert: /etc/safeguard/internal-root-ca.pem
reason: "Safeguard scan {{scan_ref}} on {{runner}}"
- type: hashicorp-vault
url: https://vault.example.internal:8200
auth: approle
role_id: env://VAULT_ROLE_ID
secret_id: file:///etc/safeguard/vault-secret-id
namespace: security
allow_env: true
allow_file: true
audit_file: /var/log/safeguard/vault-audit.jsonlTop-level settings
| Setting | Default | Meaning |
|---|---|---|
providers | none | The list of providers, below. |
allow_env | true | Whether env://NAME references may be read on this machine. |
allow_file | true | Whether file:///path references may be read on this machine. |
native.approval_wait | 10m | How long a scan waits for an approver when a Safeguard vault credential needs approval. 0 fails at once with the request id. At most 24h. See Approvals. |
audit_file | vault-audit.jsonl next to this file | Where the local audit file is written. off turns it off. See Audit. |
Settings every provider takes
| Setting | Default | Meaning |
|---|---|---|
name | the type | How references and the app's registered provider point at this entry. Must be unique in the file. |
type | required | arcon, cyberark-ccp, cyberark-conjur, hashicorp-vault, beyondtrust, delinea, azure-key-vault, aws-secrets-manager or rest. safeguard vault provider-types prints them all with their settings. |
url | required except Azure and AWS | The provider's base address. https://. A plain http:// address is accepted only for this machine (localhost, 127.0.0.1, ::1) unless allow_http is set. |
timeout | 15s | Time limit for one request, as 15s, 1m. |
ca_cert | system CAs | PEM file of the CA that issued the provider's certificate, added to the system CAs. |
client_cert, client_key | none | PEM client certificate and its unencrypted private key, for mutual TLS. Paths only; read at use. Required for CyberArk CCP. |
tls_insecure_skip_verify | false | Turns certificate checking off. Logs a warning on every request. For a short test only. |
allow_http | false | Accept a plain http:// url to another machine. Logs a warning on every request: the API key and the password cross the network unencrypted. |
retries | 2 | Extra tries after a dropped connection, a timeout, a 429 or a 5xx answer, with a growing pause (about 0.5 s, 1 s, ...). 0 to 5. Authentication, permission and not-found answers are never retried. |
allowed_refs | any | Glob patterns. When set, the runner reads only references whose part after the provider matches one of them, and refuses anything else with NOT_ALLOWED before contacting the PAM. * matches within one / part; ? one character; [...] a set. Example: SafeguardScanner/DAST-Safe/*. |
reason | Safeguard scan <scan> on <runner> | The reason text the PAM records with each read, where it records one (CyberArk CCP Reason, the BeyondTrust request reason, {{reason}} in ARCON and REST templates). {{scan_ref}}, {{runner}} and {{target}} are filled in for CCP, ARCON and REST. |
Settings that hold a secret (api_key, token, secret_id, client_secret, jwt) must be env://NAME (an environment variable of the runner's process) or file:///absolute/path (one trailing newline is dropped). An inline value is refused. api_user and role_id may also be written inline.
Settings per provider type
| Type | Settings |
|---|---|
arcon | variant (digital-vault default, or legacy), api_user, api_key, open_for_hours (default 1), and the request details token_path, token_method, token_body (json, form, form-b64), token_body_template, token_json_path, token_ttl (default 4m), fetch_path, fetch_method, fetch_query, fetch_body_template, fetch_content_type, auth_header, password_json_path, username_json_path, success_json_path, error_json_path. See ARCON PAM. |
cyberark-ccp | app_id (when set, references must use this AppID), client_cert, client_key, reason. |
cyberark-conjur | account (required), auth (api-key default, or jwt), login and api_key for API key sign-in, service_id and jwt for JWT sign-in. |
hashicorp-vault | auth (token default, approle, kubernetes), token, role_id, secret_id, role, jwt_path (default the pod's service account token), auth_mount, namespace, revoke_leases (default true). |
beyondtrust | api_key, run_as (both required), reason, duration_minutes. url is the API base, for example https://pws.example.internal/BeyondTrust/api/public/v3. |
delinea | auth (password default, or client-credentials), api_user, api_key (both required), token_path (default /oauth2/token), fetch_path, token_ttl. url includes the application path. See Delinea Secret Server. |
azure-key-vault | auth (client-credentials or managed-identity), tenant_id, client_id, client_secret, authority_host, imds_url. url replaces the vault address (private endpoints, sovereign clouds). |
aws-secrets-manager | region, profile, endpoint (VPC endpoint). Credentials come from the default AWS chain. |
rest | api_user, api_key and the same request settings as arcon, with no defaults. See REST connector. |
Environment variables
| Variable | Meaning |
|---|---|
SAFEGUARD_SECRET_PROVIDERS | Path of the provider file. |
SAFEGUARD_VAULT_AUDIT_FILE | Path of the local audit file, or off. Overrides audit_file. |
SAFEGUARD_RUNNER_NAME | The runner's name in the audit trail, in access tests and in the app's provider status. Default: the host name. Set it when you run several runners. |
SAFEGUARD_VAULT_CHECKIN | off stops the runner's vault check-in (no Test access and no provider status in the app; scans still read credentials). |
HTTPS_PROXY, NO_PROXY | Calls to the PAM follow the process's proxy settings. Put your PAM's host in NO_PROXY so its traffic does not go through a proxy. |
Variables that env:// settings name (for example ARCON_API_USER) must be set in the environment of the runner's process: in the systemd unit's Environment= or EnvironmentFile=, the launchd plist, or the Windows service's environment. Prefer file:// for keys, with the file readable only by the runner's account.
Running the runner as a service
- Create a dedicated operating-system account for the runner. Put the provider file, key files and certificates in that account's home or under
/etc/safeguardowned by it, mode 600 (directories 700). - Start the runner with
safeguard runner startunder that account (see Local Runner) and setSAFEGUARD_RUNNER_NAME. - The runner needs outbound HTTPS to the Safeguard platform, HTTPS to your PAM's API, and network reach to the systems it scans (web applications, APIs, SSH port 22 or WinRM port 5986 on hosts).
- DAST login flows that need a browser need Chrome or Chromium on the runner machine. The runner tells the platform whether it has one; tools that are missing are reported in the scan's coverage, never skipped silently.
Capabilities
A runner declares what it can run each time it polls for work: dast and api always, hostscan for host scans, and browser when Chrome or Chromium is available. A DAST, API or host scan job is addressed to one runner and requires its capability, so it is never handed to another runner or to an older runner that cannot run it. The app lists only runners that declared the right capability when you choose On-prem runner on a target.
Environment variables and files
Read a scan credential from an environment variable or a local file on the machine that runs the scan, for CI jobs and for secrets another agent writes to disk.
Using vault credentials in scans
How DAST, API security, source code and container scans, source-code integrations, and SSH and WinRM host scans use a vault entry or a PAM reference, and which execution setting each needs.