Credentials Guardian Documentation

Complete guide to installing, configuring, and using Credentials Guardian for credential health monitoring and secret leak detection in Jenkins.

Installation

Credentials Guardian can be installed in two ways:

Option 1: Upload HPI File

  1. Download the latest creds-guardian.hpi file from your dashboard
  2. Navigate to Manage Jenkins → Plugins → Advanced Settings
  3. Under "Deploy Plugin", click "Choose File" and select the HPI file
  4. Click "Deploy" to install the plugin

Option 2: Manual Installation

  1. Copy the creds-guardian.hpi file to your Jenkins plugins directory: 
    cp creds-guardian.hpi $JENKINS_HOME/plugins/
  2. Restart Jenkins to load the plugin

Quick Start

Get credential monitoring running in minutes:

1. Activate Your License

Navigate to Manage Jenkins → System → Credentials Guardian. Enter your license key and click "Activate".

2. Enable the Plugin

Check "Enable Credentials Guardian" to start monitoring.

3. Configure Alert Thresholds

Set when you want to be notified about expiring credentials (default: 30, 7, and 1 day before expiration).

4. Configure Notifications

Add notification channels (Slack, Email) to receive alerts about expiring credentials and detected leaks.

5. Save Configuration

Click "Save". Credentials Guardian immediately begins scanning credentials and monitoring build logs.

Requirements

  • Jenkins Version: 2.426.x LTS or later
  • Java Version: Java 17 or later
  • Network: HTTPS connectivity for license validation and external notifications

Global Settings

Configure Credentials Guardian in Manage Jenkins → System → Credentials Guardian.

Enable Credentials Guardian

Master toggle to enable or disable all monitoring features.

Scan Interval

How often to scan credentials for expiration status. Default: every 6 hours.

Expiration Tracking

Monitor credential expiration dates and get notified before they expire.

Alert Thresholds

Configure multiple alert thresholds to get early warnings:

  • 30 days: First warning, time to plan credential rotation
  • 7 days: Urgent warning, schedule rotation soon
  • 1 day: Critical warning, credential expires tomorrow

Supported Credential Types

  • Username/Password credentials
  • SSH private keys
  • Secret text / tokens
  • Certificate credentials
  • Any credential type with an expiration date

Leak Detection

Scan build logs for accidentally exposed secrets.

Built-in Patterns

20+ pre-configured patterns detect common secret formats:

  • AWS Access Keys and Secret Keys
  • GitHub / GitLab tokens
  • Slack webhooks and tokens
  • Private keys (RSA, DSA, EC)
  • Database connection strings
  • Generic API keys and passwords
  • JWT tokens
  • And more...

Custom Patterns

Add your own regex patterns to detect organization-specific secrets:

Pattern Name: Internal API Key
Regex: MYORG-[A-Za-z0-9]{32}
Severity: HIGH

Important

Leak detection scans build logs as they are written. It does not scan historical build logs. Enable leak detection early to catch secrets before they accumulate in logs.

Notifications

Get alerted about credential issues through multiple channels.

Supported Channels

  • Slack: Webhook-based notifications with customizable messages
  • Email: SMTP-based alerts using Jenkins mailer or custom SMTP

Notification Types

  • Credential expiration warnings (at each threshold)
  • Credential expired alerts
  • Secret leak detected in build log
  • Unused credential detected

Usage Auditing

Track which credentials are used by which jobs.

Usage Tracking

  • Which jobs reference each credential
  • Last time each credential was used
  • Unused credentials that may be candidates for removal

Unused Credential Detection

Credentials that haven't been used in a configurable period (default: 90 days) are flagged as potentially unused. This helps clean up stale credentials and reduce your attack surface.

Health Dashboard

Access the dashboard from the Jenkins sidebar at Credentials Guardian.

Dashboard Sections

  • Overview: Total credentials, healthy/warning/expired counts
  • Expiring Soon: Credentials expiring within each threshold
  • Recent Leaks: Recently detected secret leaks in build logs
  • Unused Credentials: Credentials with no recent usage
  • Audit Trail: Complete history of credential events

Calendar View

Alongside the list-style dashboard, a Monday-first monthly calendar lays out every tracked credential with an expiration date, including already-expired ones. Each day shows the credentials expiring that day with the same ok/warning/error/info status badges used elsewhere on the dashboard, and Prev/Next links step between months. The calendar is part of the same dashboard and shares its Jenkins.ADMINISTER permission gate; it is not a separate feature with its own license or permission requirement.

Export Audit Reports

"Export CSV" and "Export PDF" links next to Recent Activity download the audit trail in either format. Both cover the same in-memory activity window the dashboard already displays, not the rotated on-disk daily log files -- a full historical export of those is a separate, not-yet-built feature.

Licensing

Activating Your License

  1. Purchase a subscription from the product page
  2. Copy your license key from the dashboard
  3. In Jenkins, navigate to Manage Jenkins → System → Credentials Guardian
  4. Enter your license key and click "Activate"

License Validation

Credentials Guardian validates your license periodically (every 24 hours). If the license server is unreachable, a 72-hour grace period allows continued operation.

Unlicensed Behavior

Without a valid license:

  • All monitoring is disabled
  • No notifications are sent
  • A warning banner is shown to admins

Configuration as Code (JCasC)

The license key can also be set through Configuration as Code, under unclassified.credentialsGuardianConfiguration.licenseKey, instead of only the UI. Any JCasC secret source works, including an environment variable, a Docker or Kubernetes secret file, or a secrets plugin.

A key applied while Jenkins is still starting up is validated in the background right away, on the existing revalidation scheduler, so it never blocks Jenkins' startup on the license server's response. It is not skipped: a later Save on the configuration page, or a later Configuration as Code reload after startup, still validates synchronously as before.

FAQ

Does Credentials Guardian access credential values?

No. Credentials Guardian only reads credential metadata (name, type, expiration date, usage references). It never accesses or stores actual credential values like passwords or private keys.

How does leak detection work without accessing secrets?

Leak detection uses regex pattern matching on build log output. It looks for known secret formats (AWS keys, tokens, etc.) in the log text, not by comparing against stored credential values.

Can I exclude certain credentials from monitoring?

Yes. You can exclude credentials by ID or by pattern in the global configuration. This is useful for test credentials or credentials managed by external systems.

What data does Credentials Guardian collect?

Only license validation data (license key, pseudonymous controller identifier, or the controller URL when a request does not include one as with older plugin versions, plugin version) is sent externally. All credential monitoring data stays on your Jenkins instance.

Can I export the audit trail?

Yes. The dashboard has Export CSV and Export PDF links that download the same in-memory audit window shown on screen. Export does not cover the rotated on-disk daily log files, only the current in-memory history.

Does Credentials Guardian support JCasC?

Yes. The license key can be set through Jenkins Configuration as Code instead of only the UI. A key applied while Jenkins is starting is validated in the background rather than blocking startup; a later Save or Configuration as Code reload validates it immediately as before.

Changelog

Recent Updates (2026-10-23)

  • The audit trail on the dashboard can now be exported as CSV or PDF. Both formats cover the same in-memory activity window already shown on screen, not the rotated on-disk daily log files.
  • Added a calendar view of upcoming and already-expired credential expirations, alongside the existing list-style dashboard. It shares the dashboard's existing permission gate, not a separate one.
  • The license key can now be set through Jenkins Configuration as Code instead of only the UI. A key applied during Jenkins startup is validated in the background rather than blocking the boot process; a later Save or Configuration as Code reload still validates it immediately.

Version 1.0.0

Initial Release

  • Credential expiration tracking with configurable thresholds
  • 20+ built-in secret leak detection patterns
  • Custom regex pattern support
  • Credential usage auditing across jobs
  • Unused credential detection
  • Multi-channel notifications (Slack, Email)
  • Health dashboard with overview and drill-down
  • Complete audit trail