Safeguard Docs
Credentials Vault

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.
PermissionsOn 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 readAt every scan start and every access test, so an edit applies to the next scan without a restart.
StrictnessAn 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 itsafeguard 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.jsonl

Top-level settings

SettingDefaultMeaning
providersnoneThe list of providers, below.
allow_envtrueWhether env://NAME references may be read on this machine.
allow_filetrueWhether file:///path references may be read on this machine.
native.approval_wait10mHow 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_filevault-audit.jsonl next to this fileWhere the local audit file is written. off turns it off. See Audit.

Settings every provider takes

SettingDefaultMeaning
namethe typeHow references and the app's registered provider point at this entry. Must be unique in the file.
typerequiredarcon, 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.
urlrequired except Azure and AWSThe 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.
timeout15sTime limit for one request, as 15s, 1m.
ca_certsystem CAsPEM file of the CA that issued the provider's certificate, added to the system CAs.
client_cert, client_keynonePEM client certificate and its unencrypted private key, for mutual TLS. Paths only; read at use. Required for CyberArk CCP.
tls_insecure_skip_verifyfalseTurns certificate checking off. Logs a warning on every request. For a short test only.
allow_httpfalseAccept a plain http:// url to another machine. Logs a warning on every request: the API key and the password cross the network unencrypted.
retries2Extra 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_refsanyGlob 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/*.
reasonSafeguard 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

TypeSettings
arconvariant (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-ccpapp_id (when set, references must use this AppID), client_cert, client_key, reason.
cyberark-conjuraccount (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-vaultauth (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).
beyondtrustapi_key, run_as (both required), reason, duration_minutes. url is the API base, for example https://pws.example.internal/BeyondTrust/api/public/v3.
delineaauth (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-vaultauth (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-managerregion, profile, endpoint (VPC endpoint). Credentials come from the default AWS chain.
restapi_user, api_key and the same request settings as arcon, with no defaults. See REST connector.

Environment variables

VariableMeaning
SAFEGUARD_SECRET_PROVIDERSPath of the provider file.
SAFEGUARD_VAULT_AUDIT_FILEPath of the local audit file, or off. Overrides audit_file.
SAFEGUARD_RUNNER_NAMEThe 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_CHECKINoff stops the runner's vault check-in (no Test access and no provider status in the app; scans still read credentials).
HTTPS_PROXY, NO_PROXYCalls 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/safeguard owned by it, mode 600 (directories 700).
  • Start the runner with safeguard runner start under that account (see Local Runner) and set SAFEGUARD_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.

On this page