How to audit Jenkins credentials and secrets: inventory, scope review and safe rotation

Jenkins controllers quietly accumulate cloud keys, deploy tokens, SSH keys and passwords that nobody has reviewed since the job that needed them was created. This guide is a step-by-step audit: how to inventory every credential store on a controller, find out which jobs and people can use each credential, spot secrets that live outside the Credentials plugin, and rotate safely without breaking builds. It assumes you administer or have delegated read access to a Jenkins controller and want evidence you can hand to an auditor. For the wider hardening picture (controller isolation, plugins, CSRF) read the Jenkins Security Guide first; this page goes deeper on the credentials themselves.

Key takeaways

• There are at least three stores to check: the System store at the root, a Folder store in every folder (Folders plugin), and a per-user store for every user, and each needs its own review.
• Scope decides blast radius: a GLOBAL credential in the root store is available to every job that runs with Credentials/UseItem, which by default is implied by Job/Configure.
• Administer means every secret: Jenkins documents that Script Console access is essentially administrator access and that credentials accessed through scripts are decrypted, so the admin list is part of the credential audit.
• Secrets hide outside the plugin: plain environment variables, job parameters, Groovy-interpolated strings and console logs are where audits find the worst exposures.
• Rotate after you map usage: the plugin's usage tracking depends on consumer plugins and is not definitive, so confirm consumers before you revoke anything.

When you need this

Run this audit on a schedule (quarterly for controllers that deploy to production) and on specific triggers:

• After a Jenkins or plugin security advisory: for example, the Credentials plugin advisory in which encrypted credential values were revealed to users with Extended Read permission (versions 1380.va_435002fa_924 and earlier).
• After a person with Administer leaves or is found to be untrusted: the Jenkins permissions documentation advises rotating or revoking all stored secrets if an untrusted user gains Overall/Administer.
• Before migrating to an external secrets store or to OIDC federation: you need the inventory to plan the move.
• When a public or internet-reachable controller is discovered: in the Homebrew GitHub token exposure, a broadly scoped GitHub token used by build automation was visible on the environment variables page of a public Jenkins server.
• During an NHI programme inventory: Jenkins is often the largest single holder of machine credentials in an engineering estate. See the CI/CD Pipeline Identity Security Guide.

Before you start

• Access: an account with Overall/Administer, or Overall/SystemRead plus Extended Read if your controller has that optional permission enabled (it is off by default and is enabled with the jenkins.security.SystemReadPermission system property or the Extended Read Permission plugin). Do the audit with a named account, not a shared one.
• A backup and a change window: the audit itself is read-only, but the remediation is not. Back up $JENKINS_HOME configuration, and note that Jenkins advises keeping the secrets/ directory out of routine backups because it holds the decryption keys. Treat any backup that does include it as a credential.
• An API token for the audit account: create a new token for the REST queries (Jenkins records each new token's use count and last use date) and revoke it when you finish.
• A place to record findings: a spreadsheet or ticket with one row per credential: store, domain, ID, type, scope, description, owner, consumers, last rotation, decision.
• Agreement on who decides: the job owner must approve any rotation or deletion. Do not delete credentials on your own judgement during the audit.

Step-by-step

1. Enumerate credential providers and stores

1. Open Manage Jenkins > Configure Credentials and record which credentials providers are permitted. Providers that you do not use (for example the per-user store) can be restricted here.
2. Open Manage Jenkins > Credentials and record every store listed under Stores scoped to Jenkins, including the System store and its default domain Global credentials (unrestricted) plus any additional domains.
3. Walk every folder. Each folder with the Folders plugin exposes its own store at folder name > Credentials > Folder, and that store supports only global scope, which exposes credentials to every child of the folder.
4. Check per-user stores. These are only visible at People > username > Credentials > User, and a user cannot see another user's store, so ask users (or use an administrator script approved for the audit) to list theirs.

2. Pull the inventory through the REST API

The Credentials plugin's REST API mirrors the web UI URLs. Query each store and domain and save the JSON as evidence. The documented URL pattern is:

• Domains in a store: <jenkins>/<path to context>/credentials/store/<store id>/api/json?tree=domains[urlName]
• Credential IDs in a domain: <jenkins>/<path to context>/credentials/store/<store id>/domain/<domain name>/api/json?tree=credentials[id]
• Folder example: https://jenkins.example.com/job/example-folder/credentials/store/folder/domain/testing/api/json?tree=credentials[id]

Authenticate with the audit account's API token and include the CSRF crumb header if your configuration requires it for the request type. The API returns IDs, descriptions and types; it does not need to return secret values for an audit, and you should never export them.

3. Classify each credential

For every credential, go to the target system and check what the secret can actually do. A GitHub token, cloud access key or registry password is only as dangerous as its permissions there, and the Homebrew case shows how a token's scopes can be widened over time without anyone noticing on the Jenkins side.

4. Map who and what can use each credential

• Job authentication: by default jobs run as SYSTEM. The Credentials plugin documentation explains that once jobs run as a specific authentication (for example with the Authorize Project plugin), a credential in the root or a folder store resolves only for authentications with Credentials/UseItem, which is hidden and implied by Job/Configure unless you enable the com.cloudbees.plugins.credentials.UseItemPermission system property.
• Hidden UseOwn: Credentials/UseOwn is implied by Item/Build unless the com.cloudbees.plugins.credentials.UseOwnPermission property is set.
• Configure and Replay: anyone who can configure a job, or use Run/Replay on a Pipeline, can change the script that binds a credential. Treat Job/Configure on a folder as the right to use every credential in it.
• Agent permissions: Jenkins documents that users with Agent/Configure or Agent/Create can make jobs run on a machine they control and so gain access to build data, including credentials.
• Administrators: list every account and group with Overall/Administer. Script Console access is equivalent, and its changes may not appear in normal logs.

5. Hunt for secrets outside the Credentials plugin

• Environment variables: check global properties (Manage Jenkins > System > Global properties), node properties and job environment blocks for literal keys. This is exactly where the Homebrew token sat.
• Job parameters: string parameters with default values that are passwords or tokens; these are stored in job config.xml as plain text.
• Jenkinsfiles: search repositories for sh "...${ patterns that use credentials inside double quotes. Jenkins states that Groovy string interpolation should never be used with credentials, because the secret is expanded before it reaches the agent and becomes visible in process arguments.
• Console logs and archived artefacts: masking in Credentials Binding catches the bound value as printed, not encoded or transformed forms. Scan logs and artefacts with a secret scanner. See How to find secrets in CI logs and build artefacts.
• Configuration as code and job XML: scan $JENKINS_HOME/jobs/*/config.xml and any JCasC YAML in source control with a secret scanner; encrypted {...} values are fine, plaintext keys are findings.

6. Check the controller file system

Jenkins encrypts stored secrets with AES (CBC mode, PKCS#5 padding, random IV) using keys in $JENKINS_HOME/secrets/, and secrets/master.key protecting those keys is stored unencrypted. Confirm the directory is readable only by the Jenkins service account (Jenkins suggests mode 0700), that Jenkins does not run as root, and that no backup job, file share or container image copies secrets/ alongside the credential XML files. Anyone with both can decrypt every credential.

Verify it worked

An audit is complete when every credential has an owner and a decision, and the evidence can be regenerated. Check these measures:

Re-run the REST queries after remediation and diff against the first export. For API tokens, check each user's token list: Jenkins shows creation dates in orange after six months and red after twelve, which makes stale tokens easy to spot.

Rollback and common errors

• Rotating before mapping consumers: usage tracking needs cooperation from the consuming plugin and is not definitive. Rotate in the target system first by creating a second key, update the Jenkins credential in place (keep the same ID so jobs keep working), run the affected jobs, then revoke the old key. Rollback is restoring the previous value while the old key is still valid.
• Changing credential IDs: IDs cannot be changed once set, and jobs reference credentials by ID. Create a new credential and update jobs, rather than deleting and recreating with a different ID.
• Moving credentials between stores: the plugin can move a credential between domains in the same store, but not from one store to another (JENKINS-20075). Moving a key into a folder store means recreating it there, updating jobs, then deleting the root copy.
• Turning on UseItem and breaking builds: enabling the UseItemPermission property or switching jobs away from SYSTEM authentication will stop jobs resolving credentials until the right permission is granted. Test on one folder first; rollback is removing the property and restarting.
• Trusting log masking: masked logs are not proof a secret never leaked. The Credentials Binding plugin has had advisories on improper masking. Rotate any secret found unmasked in a log, artefact or screenshot.
• Exporting secrets as evidence: do not dump decrypted values through the Script Console to "prove" an inventory. IDs, types and scopes are the evidence; decrypted values in a spreadsheet are a new leak.

Hardening afterwards

• Replace static cloud keys with federation: use OIDC token exchange from Jenkins to the cloud provider where your plugins support it, so there is no long-lived key to audit. See the Dynamic Secrets and Ephemeral Credentials Guide.
• Move high-value secrets to an external store: the Credentials plugin documentation notes that with an external store, access to the controller file system does not by itself compromise credentials, and the store's last-accessed tracking helps identify credentials to rotate after a breach. See the HashiCorp Vault Guide.
• Use folders as security boundaries: the plugin's own advice is to put deployment keys in a "Deployment" folder and restrict that folder to people allowed to deploy.
• Disable legacy API tokens: in Configure Global Security, disable legacy token creation on user creation and re-creation of legacy tokens by users.
• Enforce single-quoted credential use: add a review or lint rule against double-quoted sh, bat and powershell steps that reference bound credentials.

Practitioner checklist

• List every credentials provider, store and domain, including every folder store and per-user store.
• Export credential IDs, types and scopes through the REST API and keep the JSON as evidence.
• Record an owner, target system, real permissions and consumers for every credential.
• List every holder of Overall/Administer, Job/Configure, Agent/Configure and Agent/Create, and justify each one.
• Scan job XML, JCasC files, Jenkinsfiles, console logs and artefacts for plaintext secrets.
• Confirm $JENKINS_HOME/secrets/ permissions, that Jenkins does not run as root, and where backups go.
• Revoke legacy and stale user API tokens and disable legacy token creation.
• Rotate using the create, update, test, revoke order, keeping credential IDs stable.
• Move production deploy credentials into restricted folders or an external store, or replace them with OIDC federation.
• Revoke the audit account's API token and schedule the next audit.

Standards and references

• Jenkins: Using credentials
• Jenkins Credentials plugin: User guide
• Jenkins: Permissions
• Jenkins: Storing secrets
• Jenkins: Script Console
• Jenkins: Using a Jenkinsfile (string interpolation and credentials)
• Jenkins: Credentials Binding plugin
• Jenkins: New API token system

Related NHI Mgmt Group resources: Jenkins Security Guide · CI/CD Pipeline Identity Security Guide · Secrets Rotation Runbook Template · How to find secrets in CI logs and build artefacts