Safeguard Docs
Credentials Vault

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.

Using vault credentials in scans

Wherever a scan accepts a credential, you can give it a reference instead of a value:

  • sgvault://<handle> for an entry in the vault, also written pam://safeguard/<handle>. The app's From the vault button inserts it. This is the recommended form: the platform audit trail then names the entry. Add #username or #password to pick a field.
  • pam://... or vault://... to point straight at your PAM, without a vault entry.

Typing a value works as it always has. A value is a reference only when the whole field is one.

When an entry has a vault policy, the scan checks it out instead of reading it: it says which scan, target, scan type and runner the credential is for, and the vault applies grants, bindings and approval. The picker hides entries whose bindings exclude the target or scan type you are setting up. If a scan is refused, the error code says why; see Troubleshooting.

DAST

Fields that take a reference: login username and password, phone number, bearer token, session cookie and session headers, second-factor secret, request headers and cookie, and the same fields for the second test account. In a header list, each header whose value is wholly a reference is read.

In the app:

  1. Open the DAST target and go to its sign-in settings.
  2. Beside the password (or another credential field) choose From the vault, search the shared entries, and pick one. The field shows Using sgvault://<handle> from the vault. Type a value instead returns to a typed value.
  3. Under Where this scan runs, choose:
    • Safeguard cloud (default): works with Stored in Safeguard entries.
    • On-prem runner, and pick the runner: required for PAM entries. Only runners that declared the dast capability are listed.
  4. Save. Picking a PAM entry while the target runs in the cloud shows "PAM credentials require on-prem runner execution." and the form does not save until an on-prem runner is chosen.

At scan time the runner reads the credential, signs in to the application and crawls it. Each re-login during the scan reads the password again, so a rotated or one-time password works. Findings and evidence are uploaded with the value replaced by [redacted].

Runner requirements: network reach to the application, and Chrome or Chromium on the runner for sign-in flows that need a browser. A tool that is missing on the runner is reported in the scan's coverage, never skipped silently.

API security

Fields that take a reference: bearer token, API key and its header, API secret, access token, request headers, and the second identity's token, key and headers. Inside an API authentication configuration (JSON), any string value that is wholly a reference is read, for example an OAuth client secret written as "client_secret": "sgvault://api-oauth-secret".

In the app: the From the vault button is beside the bearer token, the header API key, the Basic password, the OAuth client secret, and the query and cookie API keys inside an authentication configuration. For any other field, type the reference (sgvault://<handle>). Choose Where this scan runs exactly as for DAST; PAM entries need On-prem runner, and only runners that declared the api capability are listed.

When the API rejects the credential mid-scan (HTTP 401), the scan reads the credential once more and retries. A credential your PAM rotated during the scan, or one a vault rotation just replaced, then still works. If the second attempt is also refused, the scan fails with the reason. For a credential with a policy, the second read is a new check-out. The re-read is marked in the audit trail as a refresh.

Source code and registry scans

On the CLI, these flags take a reference: --git-token, --git-username, --git-password, --registry-username, --registry-password.

safeguard scan --repo https://gitlab.example.internal/payments/api.git \
  --git-token sgvault://gitlab-scan-token

safeguard scan --repo https://gitlab.example.internal/payments/api.git \
  --git-token pam://arcon/GitLab/gitlab.example.internal/svc_scan

safeguard scan --image registry.example.internal/payments/api:1.4 \
  --registry-username svc_pull --registry-password sgvault://registry-pull

The CLI reads the value on the machine it runs on, uses it for the scan, and discards it. Nothing is stored in shell history except the reference.

On a runner, the same values in a job (git_token, git_password, registry_password) are read by the runner.

To scan a private repository with a credential from your PAM, run the scan from the CLI or a runner with --git-token <reference>.

Source-code integrations

The access token of a GitHub, GitLab or Bitbucket integration can be a reference to the Safeguard vault.

  1. In Settings, add or edit the source-code integration. Beside the access token, choose From the vault and pick a credential. The field holds sgvault://<handle>.
  2. Save. Safeguard checks the credential out for a few minutes, for the scan type scm and your git host as the target, and checks the token against your git server as it does for a typed token. It then keeps the reference, not the value. Every later use of the integration reads the credential the same way, so a rotated token takes effect without editing the integration.

Only the sgvault:// form works here. An entry that points at your PAM cannot be used for a source-code integration, because Safeguard's cloud cannot reach your PAM. The picker shows such entries as unavailable, and a save with one fails with PAM_NOT_SUPPORTED_FOR_SCM. Typed tokens work as before.

The credential's policy applies at the save and at each use: a credential bound to other targets is refused with CREDENTIAL_NOT_BOUND, one that needs approval answers APPROVAL_PENDING until it is approved, and a credential you may not use answers NOT_PERMITTED. The integration is saved and used on behalf of the signed-in person, who needs USE on the credential, and the credential's Targets bindings must list your git host. Because the lease is short and the integration does not check it in, a credential set to One user at a time is a poor fit for an integration token.

Infrastructure host scans (SSH and WinRM)

An Infrastructure host scan target signs in to Linux, Unix and Windows hosts with a credential from the vault or your PAM, runs a fixed list of read-only commands, and reports the operating system, installed packages and their vulnerabilities, and configuration checks. It always runs on an on-prem runner.

If the Infrastructure Host Scan card is not shown under scanners, contact Safeguard support to turn it on for your organization.

Create the target

  1. Choose Infrastructure Host Scan, then fill in Hosts and credential:
    • Hosts: host names or IP addresses, one per line or separated by commas, and/or an IP range (CIDR), IPv4, /24 (256 hosts) at most.
    • Protocol: SSH (Linux, Unix) on port 22, or WinRM (Windows) on port 5986 (HTTPS).
    • User: the account the scan signs in as. For WinRM, DOMAIN\user or user@domain for a domain account, or a local account name.
    • Credential: a reference only. Pick an entry from the vault (stored or PAM) or type a pam:// or vault:// reference. A typed password or key is refused.
    • For SSH: SSH host-key fingerprints (SHA256:... for any host, or host=SHA256:... for one host), or Trust the host key on the first scan.
  2. Choose the runner (only runners that declared the hostscan capability are listed), and Enable and scan.

SSH (Linux and Unix)

  • The credential is the account's password, or its private key (PEM or OpenSSH format). A key's passphrase can be a second reference.
  • Host keys are verified. A host whose key does not match a configured fingerprint is skipped. A host with an unknown key is skipped and no credential is sent to it, unless Trust the host key on the first scan is on, which records the fingerprint in the result. A changed key is never trusted.
  • Commands (fixed, read-only, no sudo, nothing built from target data): OS release, kernel version, package list (dpkg, rpm or apk), sshd_config and its include folder, login.defs and password quality settings, listening TCP ports.
  • Results: per host an OS-package SBOM with distribution-qualified package URLs, matched against the same vulnerability data as dependency scanning; configuration checks (SSH root login, SSH password authentication, password policy, listening ports) in the scan report.

WinRM (Windows)

  • HTTPS on port 5986 with the host's certificate verified. The runner machine must trust the CA that issued the hosts' WinRM certificates (install it in the runner's system trust store; the CLI also takes --winrm-ca). Plain HTTP on 5985 is refused unless Allow plain HTTP WinRM is checked, which sends the password in the clear.
  • Basic authentication. The WinRM service must allow Basic for the scan account (winrm set winrm/config/service/auth @{Basic="true"}), which is typical for a local account over HTTPS. NTLM, Kerberos and CredSSP are not used, so a domain account that cannot use Basic is refused with a clear reason.
  • Commands (fixed, read-only): OS caption and build, installed hotfixes, installed programs (registry read), listening TCP ports, net accounts.
  • Results: an inventory of the OS, hotfixes and installed programs, and configuration checks, in the scan report. Windows software is not matched against advisories.

When the host refuses the credential

If an SSH sign-in fails with an authentication error, or WinRM answers 401, the scan reads the credential once more and tries that host again. A password rotated since the scan began then works. If it fails again, the host is reported with the reason.

Every command is audited

The runner records each command it runs on each host: host, command id, exit status and duration. Never the output of a command that could hold secrets, and never the credential.

From the command line

safeguard hostscan runs the same scan from a terminal, with the same references:

safeguard hostscan --host 10.0.5.17 --ssh-user scan \
  --credential pam://arcon/Linux/10.0.5.17/scan \
  --known-hosts /etc/safeguard/known_hosts --match

safeguard hostscan --host win-app-01.example.internal --winrm-user scan \
  --credential sgvault://win-scan --winrm-ca /etc/safeguard/internal-root-ca.pem

Where each scan reads its credential

ScanStored entryPAM entryRead by
DAST, API security on Safeguard cloudYesNoSafeguard's cloud scanner
DAST, API security on On-prem runnerYesYesThe chosen runner
CLI and runner source, image and registry scansYesYesThe CLI or runner
Infrastructure host scansYesYesThe chosen runner
Source-code integration access tokenYes, as sgvault://NoSafeguard, when the integration is saved and used

An on-prem scan never falls back to the cloud. If the runner is offline or cannot run that scan type, the scan fails with the reason.

On this page