Safeguard Docs
Credentials Vault

How it works

The path a PAM credential takes from a scan target to your PAM and back, which component does what, and what crosses the network.

How it works

The pieces

PieceWhere it runsWhat it does with credentials
Credentials vaultSafeguard platformKeeps vault entries. A stored entry holds an encrypted value. A PAM entry holds a reference and the PAM product type, never a value. Records the audit trail.
Scan target (DAST, API security, host, source integration)Safeguard platformHolds a reference such as sgvault://dast-login in a credential field, and for DAST, API and host targets the runner that runs the scan.
Safeguard runner (the safeguard CLI)A machine in your networkClaims the scan job, reads secret-providers.yaml, asks your PAM for the value, runs the scan, uploads results.
Provider file secret-providers.yamlThe runner machine onlyThe PAM's address, the identity Safeguard signs in with (as env:// or file:// pointers), certificates and per-provider rules. Never uploaded.
Your PAMYour networkAuthenticates the runner's identity, checks its permission, returns the password, records the retrieval in its own audit.

A DAST scan with an ARCON credential, step by step

  [1] Scan starts            [2] Job to runner          [3] Read from PAM           [4] Scan       [5] End
  -------------------        -------------------        ---------------------       --------       -----------------
  Target: login password     Platform queues a job      Runner: sgvault://dast-     Login with     Value zeroed,
  = sgvault://dast-login     addressed to runner        login -> entry is PAM ->    the value,     audit row on the
  Runs on: runner dc1        "dc1" with capability      pam://arcon/Web/10.0.5.17/  crawl, test    platform + line in
                             "dast". Options carry      svc_dast                                   vault-audit.jsonl;
                             the reference, not a       sign in (api_user, key)                    findings uploaded
                             value                      GetTargetDevicePassKey                     (no value)
  1. The scan starts. The target's credential field holds sgvault://dast-login, and the target is set to run on the on-prem runner dc1.
  2. The platform hands the job to that runner. The job is addressed to dc1 and requires the dast capability, so no other runner, and no older runner, can claim it. The job options carry the reference string, never a value. If dc1 is offline or never picks the job up, the scan fails with the reason (for example runner_offline or runner_did_not_pick_up after 10 minutes). It does not fall back to the cloud.
  3. The runner reads the credential.
    • It looks up dast-login in the vault with its own sign-in. The entry is a PAM entry, so the vault returns only its reference, pam://arcon/Web/10.0.5.17/svc_dast.
    • It finds the arcon provider in its local secret-providers.yaml, checks the reference against that provider's allowed_refs (if set), reads the API key from the file or environment variable the provider names, signs in to ARCON's API over TLS, and requests the password for that target type, server and user.
    • A dropped connection, timeout, 429 or 5xx answer is retried (two more tries by default). A refusal (bad key, no permission, unknown account) is not.
  4. The scan runs with the value, held in memory for this scan only. Every log line, error message, finding, evidence item and upload passes through a redactor that replaces the value with [redacted]. When the DAST engine signs in again during the scan, it reads the password again, so a password your PAM rotated, or a one-time password, still works.
  5. The scan ends. Anything the provider holds is released (a BeyondTrust request is checked in, HashiCorp Vault dynamic-secret leases are revoked, a Vault login token is revoked), the value is zeroed, and the read is recorded twice: on the platform (entry, provider, scan, runner, result) and in the runner's local audit file. Findings and evidence are uploaded without the value.

If the credential cannot be read, the scan does not start. The message names the credential, the provider and the next step, for example: Could not read the credential for the DAST login password from ARCON (arcon): the API user is not allowed to retrieve this account. Check the API user's permission on this account in ARCON, and that no approval is pending for it. Safeguard never sends the reference text as the credential.

Where each scan type reads its credential

ScanWho reads the referenceNotes
CLI scans (safeguard scan --repo, --image, safeguard sbom --image)The CLI process on the machine it runs onFlags --git-token, --git-username, --git-password, --registry-username, --registry-password accept a reference
Runner source and container jobsThe runner that claimed the jobJob options git_token, git_password, registry_password
DAST and API security, target set to On-prem runnerThe chosen runnerStored and PAM entries
DAST and API security, target set to Safeguard cloudSafeguard's cloud scannerStored entries only. The form does not save a PAM entry on a cloud target, and the cloud scanner refuses one
Infrastructure hosts (SSH, WinRM)The chosen runner, alwaysStored and PAM entries

When the credential is in the Safeguard vault

The path is shorter and the checks are more. A scan whose credential is sgvault://<handle> with a policy on does not read the value. It checks the credential out:

  1. The scan asks the vault for the credential and names the scan, target, scan type and runner.
  2. The vault checks that the signed-in user or runner may use it, that the target, scan type and runner are inside its bindings, and whether an approval is needed. An approval makes the scan wait, up to native.approval_wait.
  3. The vault answers with the value and a lease. Safeguard's cloud scanner, a runner or the CLI uses it for the scan, and a runner renews the lease while the scan runs.
  4. At the end the scan checks the credential in. Every step is an audit row.

If the entry points at your PAM, the vault does steps 1 and 2 and then hands the runner the PAM reference, and the runner continues as above. See The Safeguard vault.

Access tests and runner check-in

A running runner checks in with the vault about every 30 seconds. It reports the provider names configured in its secret-providers.yaml and whether each has what it needs (files present, environment variables set), never their values. That is how the app shows Configured on runner X for a registered provider.

When you choose Test access, the vault queues a test for the runner you picked. At its next check-in the runner claims the test, reads the credential exactly as a scan would, and reports OK or the error code and message. The value is not sent. A test nobody claims expires after about two minutes; a claimed test with no result expires after five.

What crosses the network

FromToWhatNever
PlatformRunnerJob options with the reference (sgvault://..., pam://...)A PAM value
RunnerPlatform (vault)Entry lookup by handle; for a stored entry, the audited reveal of its valueProvider settings, certificates, PAM API keys
RunnerYour PAMSign-in with the identity in secret-providers.yaml; the password request; a reason text naming the scan and runner (where the PAM records one)Anything from Safeguard's cloud
RunnerPlatformFindings, SBOMs, evidence, the read outcome (provider, code, scan, runner)The value (redacted if it appears)

All connections from the runner are outbound. Nothing connects to the runner.

Runner offline, PAM offline, platform offline

  • Runner offline. A DAST or API scan addressed to it fails with runner_offline, or with runner_did_not_pick_up if it does not claim the job within 10 minutes. A host scan stays queued until the runner comes back. Access tests expire.
  • PAM unreachable. The read is retried, then the scan stops with UNREACHABLE or TIMEOUT and the reason. Nothing is scanned without the credential.
  • Platform unreachable from the runner mid-scan. References that point straight at the PAM (pam://, vault://) are read without the platform. sgvault:// entries need the vault to look up the entry. Audit records the platform could not receive are retried and are always kept in the runner's local audit file.

On this page