The Safeguard vault
Keep scan credentials in Safeguard with per-credential policy, roles and grants, target binding, check-out leases, approvals, versions, rotation, per-organization encryption keys and an exportable audit log.
The Safeguard vault
The Safeguard vault stores a credential's value for you and controls how it is used. This page covers how to turn the controls on, create a credential, set its policy, and what each control does. To keep a credential in your own PAM instead, see Provider setup. To compare the two, see Choose where each credential lives.
A credential behaves the new way only after its policy is turned on. Entries without a policy work exactly as they always have, so nothing changes for existing scans until you decide.
Turn it on
The vault controls are part of the Credentials Vault page, under Settings, next to Sandboxes. They appear when Safeguard has enabled them for your organization, and the page is shown to the people who can see Sandboxes settings. When they are on, the page has four tabs:
| Tab | What it holds |
|---|---|
| Credentials | Your credentials, with badges for the policy, the version, the rotation state, scans using it and requests waiting. The detail view has the tabs Overview, Access, Bindings, Approvals, Rotation, Versions, Leases and History |
| Providers | The Safeguard vault and the PAM products you registered. See Provider setup |
| Access and approvals | Grants for each credential and the queue of requests waiting for a decision |
| Audit log | Every vault event across the organization, with filters and export |
If you do not see these tabs, or Protect with a vault policy when adding a credential, contact Safeguard support to turn them on for your organization. Your existing credentials stay under Sandboxes, Cloud credentials as before.
Older CLI versions and runners keep working with credentials that have no policy. A runner that is too old to check a credential out gets the error CHECKOUT_REQUIRED for a credential with a policy, and never the value. Update with safeguard self-update.
Create a credential
- Open Credentials Vault, then the Credentials tab, and choose Add a credential.
- Keep Where the value lives on Stored in Safeguard. Enter the name, type, username and secret, and a handle such as
staging-login. Scans refer to the credential assgvault://staging-login. - Tick Protect with a vault policy. Safeguard saves the credential and turns its policy on with safe defaults: write-only, a 15 minute lease, no approval.
- Open the credential and use the Access, Bindings, Approvals and Rotation tabs to set the rest.
From a terminal: safeguard vault add --name staging-login --kind stored, then safeguard vault policy set staging-login --enable --write-only. See the CLI reference.
The policy applies to shared credentials, the ones your organization's scans can use. Personal credentials keep today's rules.
The value is write-only after you save it. Neither the app nor the CLI shows it again. To change it, add a new version (see Versions). Scans use the value through a check-out, and nothing else returns it, unless a person holds the REVEAL grant (see Write-only values and reveal).
A credential can also be a pointer to your PAM. Policy, grants, bindings, approval and audit then apply to it in the same way, and your runner reads the value from your PAM. Versions, reveal and rotation do not apply, because there is no stored value and your PAM rotates it.
The policy
Each credential has one policy. All of it is optional.
| Setting | What it does | Default when the policy is on |
|---|---|---|
| Write-only | The value is never shown to people or returned by the API. Only a check-out returns it | On |
| Require approval before use | A scan asks first and an approver decides | Off |
| Approval valid for | How long an approved request can be used for check-outs | 1 hour |
| Lease length | How long a check-out lasts before it must be renewed | 15 minutes |
| Longest lease with renewals | The cap on a lease, counted from when it was issued | 4 hours |
| One user at a time (exclusive) | Only one lease may be active. A second check-out fails with LEASE_HELD | Off |
| Recent sign-in needed within | Approving, denying, revealing, and changing the policy or grants need a sign-in this recent | Not required until you set it. 900 seconds is a good value |
| Bindings | Which targets, scan types and runners may use the credential | No limit |
| Rotation | A schedule, and how a runner changes the value | None |
| Grants | Who may do what | The creator and the vault roles |
Lease and approval times run from 30 seconds (60 for the approval window) up to 7 days.
Roles and grants
Two layers decide who can do what with a credential that has a policy.
Vault roles
Roles come from your identity provider through your sign-in: the roles and groups in the token your users sign in with. Assign them in your identity provider the way you assign any other role.
| Role | What it allows |
|---|---|
vault-admin | View, manage and approve every credential in the organization. Never reveal a value, and not use a credential unless granted or the creator. Tenant administrators count as vault-admin |
vault-approver | View and approve requests for credentials that require approval |
vault-auditor | View credential details and read and export the audit log |
Grants on one credential
A grant gives a person, a group, a role or an AI agent a set of permissions on one credential. In the Access tab, choose Add a grant, pick the principal type (User, Group or Role) and the principal, and tick the permissions.
| Permission | What it allows |
|---|---|
VIEW | See the credential's details. Not the value. Every other permission includes it |
USE | Check the credential out in a scan, including a runner signed in as that person |
MANAGE | Edit it, change its policy, add versions, rotate it, revoke leases, delete it |
APPROVE | Approve or deny requests to use it |
REVEAL | Show the value. Only given by an explicit grant, never implied by any role |
The creator has VIEW, USE and MANAGE. Everyone else needs a grant or a role. A member without VIEW does not see the credential in lists at all.
Every credential the API returns carries the list of permissions you hold on it, so the app and the CLI show only the actions you may take. The server checks every action regardless.
Changing grants needs a recent sign-in when the policy sets one. A person can never approve their own request.
Target binding
Bindings limit where a credential can be used. They have three lists, and an empty list means no limit on that point:
| List | Examples |
|---|---|
| Targets | https://app.example.com/*, *.corp.example, 10.0.1.0/24, db1.corp.example |
| Scan types | dast, api, infra_host, source, scm |
| Runners | runner-a |
A target pattern is a URL pattern matched on scheme, host and path, a host pattern, an IPv4 or IPv6 range, or an exact host. Hosts are compared in lower case, in their internationalized form, without a trailing dot. A list may hold up to 50 patterns.
The check happens in three places:
- When a target is saved. Saving a DAST, API or host target whose credential field holds
sgvault://refuses a credential bound elsewhere, withCREDENTIAL_NOT_BOUND. If the vault cannot be reached at that moment, the save goes through and the check at check-out still stands. - At check-out, on the platform. This one is authoritative.
- On the runner, again before the value is used.
A scan outside the bindings is refused with NOT_BOUND. A credential used for a source-code integration (scan type scm) must list the git host under Targets, or it is refused. A runner that is not on the runner list is refused with RUNNER_NOT_ALLOWED.
Check-out, check-in and leases
A scan does not read a credential with a policy. It checks it out.
- The scan (a runner, the CLI, or Safeguard's cloud scanner) asks the vault for the credential and says what it is for: the scan, the target, the scan type and the runner.
- The vault checks the grant (USE), the bindings, the approval and the lease rules. If all pass, it answers with the value and a lease that has an end time. A credential that needs an approval answers that the request is waiting instead.
- While the scan runs, the runner renews the lease at two thirds of its length. It never goes beyond Longest lease with renewals.
- When the scan ends, it checks the credential in. If it never does, the lease expires on its own, and the expiry is recorded.
Each of these events is an audit row: CHECKOUT, LEASE_RENEW, CHECKIN, LEASE_EXPIRE.
The Leases tab lists the scans holding the credential now. Someone with MANAGE can Revoke a lease. With One user at a time on, a credential held by one scan is refused to the next with LEASE_HELD, and is free again at check-in, revoke or expiry.
If the scan is waiting on a runner with an old version, or the platform route is missing, see Troubleshooting.
Approvals and recent sign-in
Turn on Require approval before use in the Approvals tab to make a person decide before a scan can use a credential.
- A scan that needs the credential opens a request. The request names the scan, runner, target and scan type, and has a reason.
- Approvers hold APPROVE through the
vault-approverorvault-adminrole or a grant. They see the request in Access and approvals, and in the Approvals tab of the credential, and choose Approve or Deny with an optional comment. - An approved request is valid for Approval valid for, and for a request that named a runner, scan or target, only for those. It authorizes the person who asked, and nobody else. A request must name at least the runner or the scan.
- The waiting scan reads the decision. A runner waits for
native.approval_waitinsecret-providers.yaml(10 minutes by default;0fails at once with the request id). If the wait ends, the scan stops withAPPROVAL_PENDING, and you run it again once it is approved. A denial stops it withAPPROVAL_DENIED.
A request nobody decides expires after 24 hours. The requester can cancel their own request. The requester cannot approve it.
When the policy sets Recent sign-in needed within, approving, denying, revealing, and changing the policy or grants require that you signed in within that many seconds. If not, the app asks you to sign in again, and API calls answer FRESH_AUTH_REQUIRED.
From the command line, safeguard vault requests lists, approves and denies. See the CLI reference.
Write-only values and reveal
With Write-only on, which is the default, nobody reads the value through the app or API. A request to reveal it answers WRITE_ONLY unless the person holds the REVEAL grant and, where the policy asks for it, has signed in recently. A reveal is audited. A refused reveal is audited as REVEAL_DENIED.
With Write-only off, a person with MANAGE can reveal the value, again with the sign-in rule and an audit row.
Versions
Each change of the value is a version. Turning the policy on stores the current value as the first version. The Versions tab lists them with the time, who made them and how: create, update, rotation or import. It never lists values.
| State | Meaning |
|---|---|
| Current | The version scans use |
| Previous | The one before, kept for roll-back by hand |
| Pending | A new value staged by a rotation that has not been confirmed |
| Retired and discarded | Older versions and failed attempts |
To change a value, choose Add a new version, enter the value and an optional user name, and save. The new version is current at once. The response never echoes the value. Safeguard keeps the details of the last 20 older versions. The values of retired versions are removed after 30 days.
Rotation
Rotation changes a credential's password or key on a schedule, or on demand. Safeguard plans it and a runner in your network does it, because only the runner can reach the system that owns the account.
Set it in the Rotation tab: the kind, how often in days, the runner that does the work, and the settings of the kind. Rotate now starts one immediately.
- The platform queues a rotation when it is due, or when you choose Rotate now. The named runner claims it at its next vault check-in and receives the current value.
- The runner generates a new secret locally and sends it to the vault, which stores it as a pending version.
- The runner applies it on the target and signs in with it to prove it works.
- If that works, the pending version becomes current and the old one becomes previous. If it fails, the runner puts the target back to the current value, the pending version is discarded, and the rotation reports why. If even the roll-back fails, the result is
ROLLBACK_FAILEDand the credential needs attention.
If a runner claims a rotation and does not report back within 15 minutes, the rotation ends as RUNNER_TIMEOUT. A staged value that may already be on the target is kept visible as needing attention, and never silently dropped.
What can be rotated
| Kind | What the runner does | Settings |
|---|---|---|
| SSH password | Signs in over SSH with the current password, changes it with passwd, then verifies with a new session | Host, port, host key fingerprint (SHA256:..., required) |
| SSH key | Creates a new ed25519 key, adds its public part to ~/.ssh/authorized_keys, verifies a login with it, then removes the old public key line | Host, port, host key fingerprint (required) |
| HTTP API token | Calls a configured URL with the current token and reads the new token from a JSON path in the answer. The new token is stored before the old one is revoked, so a failure never leaves you without a working token. Optionally calls a revoke URL for the old one | Token URL, method, JSON path, optional revoke URL |
| Manual | A reminder only. When due, a manager adds a new version | None |
| Not rotated by Safeguard | Why |
|---|---|
| Windows and Active Directory passwords | Not supported |
| Database accounts | Not supported |
| Cloud access keys | Not supported |
| Credentials held in an external PAM | Your PAM rotates them itself |
| SSH accounts behind a forced command or MFA | The runner cannot complete the sign-in or change |
Every host and URL in the rotation settings (the SSH host, the token URL, and any verify or revoke URL) must be covered by the credential's Targets bindings, or the rotation is refused with ROTATION_HOST_NOT_BOUND. A rotation that names a host therefore needs a non-empty target list. A rotation that fails after it may already have changed the target keeps the pending version, marked as needing attention. Rotation settings are descriptive only. A setting that names a secret is refused, and the runner verifies the SSH host key against the fingerprint you give. The runner never logs a value. A rotation that fails reports one of these codes in the audit log: AUTH_FAILED (the current credential was refused), UNREACHABLE, HOST_KEY_REQUIRED, HOST_KEY_MISMATCH, ISSUE_FAILED, STAGE_FAILED, APPLY_FAILED, VERIFY_FAILED, ROLLBACK_FAILED, BAD_CONFIG or RUNNER_TIMEOUT.
Per-organization encryption keys
Every organization has its own data key. Safeguard wraps it with the platform's master key and uses it to encrypt the values of credentials with a policy, and every version, with AES-256-GCM. A ciphertext carries the organization, credential and version it belongs to, so copying it to another organization or another row produces something that cannot be decrypted. Values of credentials without a policy keep their existing format, untouched.
A vault administrator can rotate the organization key with POST /api/v1/me/vault/keys/rotate. New writes use the new key, and older rows are re-wrapped the next time they are written. Rotating the platform's master key keeps working as before. No key material is ever logged or returned, and a key rotation is audited as KEY_ROTATE.
AI agents
An AI agent signed in to your organization is treated as a member with a ceiling. It can use a credential, and see its details, only when that credential is granted to it, with a grant whose principal type is AGENT and whose principal is agent:<principal id>. It can never manage a credential, approve or deny a request, or reveal a value. An attempt to manage answers AGENT_CANNOT_MANAGE. The audit log shows the actor of such a read as an agent.
Use it in a scan
When a scan or a save needs a credential with a policy, the vault checks it out as the signed-in person it runs for, so that person needs USE on it (and an approval, if one is required). A scheduled scan with no signed-in person behind it cannot check out a credential that has a policy, and runs without it. Use a credential without a policy for those scans, or start the scan yourself.
Give a scan field sgvault://<handle> with the From the vault button, or type it. For a credential that holds a user name and a secret, sgvault://<handle>#username reads the user name and #password the secret. The picker hides credentials whose bindings exclude the current target or scan type. See Using vault credentials in scans.
Audit
Every event is recorded and can be filtered and exported by the person who holds the auditor, admin or VIEW rights. See Audit.
Credentials Vault
Choose where each scan credential lives, in the Safeguard vault with access controls, approvals, leases and rotation, or in your own PAM where the value is read inside your network at scan time.
Import from a browser or password manager
Bring saved logins from Chrome, Edge, Brave, Arc, Opera, Firefox, Safari, 1Password, Bitwarden, LastPass or any CSV file into your personal vault, in the web app or with the CLI, with a review step before anything is saved.