Secret leak checker

What it does

A scan of your project for leaked keys and passwords, plus a clear order for fixing them. It finds likely credentials in the working files and ranks each one critical, high or lower, so you start with what could hurt most. A bundled Python script runs the scan and can output JSON for your build checks. From the results you rotate real credentials, remove exposed values, and tidy your .env and .env.example files so examples hold no real secrets. It also lists common mistakes, like rotating one system but missing something downstream, and compares cloud secret stores such as Vault and AWS Secrets Manager. It finishes with advice on adding secret scanning before merge.

What goes in and out

You give it

• Your project folder
• Your current .env and .env.example setup
• Where secrets live in production (optional)
• Your CI setup (optional)

You get

• A list of likely leaked secrets ranked by severity
• Rotation and cleanup steps
• A tidied env file layout
• A pre-merge secret scan setup

Full instructions

• Open your AI in a tool that can read your project files and run code. Add the skill's instructions and its scripts folder.
• Tell your AI to scan your project folder. It runs python3 scripts/env_auditor.py /path/to/repo.
• Ask for JSON output if you want to use the results in CI. It adds the --json option.
• Read the critical and high findings first. Check each one is a real credential.
• Rotate any real credential, remove the exposed value, then fix your .env.example and .gitignore.
• Ask your AI to set up secret scanning before merge, so new leaks get caught.

Full instruction file

Env & Secrets Manager

Tier: POWERFUL Category: Engineering Domain: Security / DevOps / Configuration Management

Before you start

Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait.

What you need (use your own material or the linked skill):

• A codebase (yours): a project's code, in a folder or repo the AI can open.

How to start:

1. Look first. Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name.
2. Check what's missing. Look for a codebase. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps.
3. Do the job. Follow the skill below with the facts and tools you have. Mark each gap with MISSING: where it belongs and never invent a fact to fill it.

Overview

Manage environment-variable hygiene and secrets safety across local development and production workflows. This skill focuses on practical auditing, drift awareness, and rotation readiness.

Core Capabilities

• .env and .env.example lifecycle guidance
• Secret leak detection for repository working trees
• Severity-based findings for likely credentials
• Operational pointers for rotation and containment
• Integration-ready outputs for CI checks

When to Use

• Before pushing commits that touched env/config files
• During security audits and incident triage
• When onboarding contributors who need safe env conventions
• When validating that no obvious secrets are hardcoded

Quick Start

# Scan a repository for likely secret leaks
python3 scripts/env_auditor.py /path/to/repo

# JSON output for CI pipelines
python3 scripts/env_auditor.py /path/to/repo --json

Recommended Workflow

1. Run scripts/env_auditor.py on the repository root.
2. Prioritize critical and high findings first.
3. Rotate real credentials and remove exposed values.
4. Update .env.example and .gitignore as needed.
5. Add or tighten pre-commit/CI secret scanning gates.

Reference Docs

• references/validation-detection-rotation.md
• references/secret-patterns.md

Common Pitfalls

• Committing real values in .env.example
• Rotating one system but missing downstream consumers
• Logging secrets during debugging or incident response
• Treating suspected leaks as low urgency without validation

Best Practices

1. Use a secret manager as the production source of truth.
2. Keep dev env files local and gitignored.
3. Enforce detection in CI before merge.
4. Re-test application paths immediately after credential rotation.

Cloud Secret Store Integration

Production applications should never read secrets from .env files or environment variables baked into container images. Use a dedicated secret store instead.

Provider Comparison

Selection Guidance

• Single cloud provider — use the cloud-native secret manager. It integrates tightly with IAM, reduces operational overhead, and costs less than self-hosting.
• Multi-cloud or hybrid — use HashiCorp Vault. It provides a uniform API across environments and supports dynamic secret generation (database credentials, cloud IAM keys) that expire automatically.
• Kubernetes-heavy — combine External Secrets Operator with any backend above to sync secrets into K8s Secret objects without hardcoding.

Application Access Patterns

1. SDK/API pull — application fetches secret at startup or on-demand via provider SDK.
2. Sidecar injection — a sidecar container (e.g., Vault Agent) writes secrets to a shared volume or injects them as environment variables.
3. Init container — a Kubernetes init container fetches secrets before the main container starts.
4. CSI driver — secrets mount as a filesystem volume via the Secrets Store CSI Driver.

Cross-reference: engineering/secrets-vault-manager is a separate skill in the source collection (not included here) covering production vault infrastructure, HA deployment and disaster recovery.

Secret Rotation Workflow

Stale secrets are a liability. Rotation ensures that even if a credential leaks, its useful lifetime is bounded.

Phase 1: Detection

• Track secret creation and expiry dates in your secret store metadata.
• Set alerts at 30, 14, and 7 days before expiry.
• Keep each secret's last rotation date in the secret store's metadata and review it on a schedule. (scripts/env_auditor.py finds likely secrets in files; it does not track rotation dates.)

Phase 2: Rotation

1. Generate a new credential (API key, database password, certificate).
2. Deploy the new credential to all consumers (apps, services, pipelines) in parallel.
3. Verify each consumer can authenticate using the new credential.
4. Revoke the old credential only after all consumers are confirmed healthy.
5. Update metadata with the new rotation timestamp and next rotation date.

Phase 3: Automation

• AWS Secrets Manager — use built-in Lambda-based rotation for RDS, Redshift, and DocumentDB.
• HashiCorp Vault — configure dynamic secrets with TTLs; credentials are generated on-demand and auto-expire.
• Azure Key Vault — use Event Grid notifications to trigger rotation functions.
• GCP Secret Manager — use Pub/Sub notifications tied to Cloud Functions for rotation logic.

Emergency Rotation Checklist

When a secret is confirmed leaked:

1. Immediately revoke the compromised credential at the provider level.
2. Generate and deploy a replacement credential to all consumers.
3. Audit access logs for unauthorized usage during the exposure window.
4. Scan git history, CI logs, and artifact registries for the leaked value, without pasting the value into chat, online tools or command lines (see references/validation-detection-rotation.md).
5. File an incident report documenting scope, timeline, and remediation steps.
6. Review and tighten detection controls to prevent recurrence.

CI/CD Secret Injection

Secrets in CI/CD pipelines require careful handling to avoid exposure in logs, artifacts, or pull request contexts.

GitHub Actions

• Use repository secrets or environment secrets via ${{ secrets.SECRET_NAME }}.
• Prefer OIDC federation (aws-actions/configure-aws-credentials with role-to-assume) over long-lived access keys.
• Environment secrets with required reviewers add approval gates for production deployments.
• GitHub automatically masks secrets in logs, but avoid echo or toJSON() on secret values.

GitLab CI

• Store secrets as CI/CD variables with the masked and protected flags enabled.
• Use HashiCorp Vault integration (secrets:vault) for dynamic secret injection without storing values in GitLab.
• Scope variables to specific environments (production, staging) to enforce least privilege.

Universal Patterns

• Never echo or print secret values in pipeline output, even for debugging.
• Use short-lived tokens (OIDC, STS AssumeRole) instead of static credentials wherever possible.
• Restrict PR access — do not expose secrets to pipelines triggered by forks or untrusted branches.
• Rotate CI secrets on the same schedule as application secrets; pipeline credentials are attack vectors too.
• Audit pipeline logs periodically for accidental secret exposure that masking may have missed.

Pre-Commit Secret Detection

Catching secrets before they reach version control is the most cost-effective defense. Two leading tools cover this space.

gitleaks

# .gitleaks.toml — minimal configuration
[extend]
useDefault = true

[[rules]]
id = "custom-internal-token"
description = "Internal service token pattern"
regex = '''INTERNAL_TOKEN_[A-Za-z0-9]{32}'''
secretGroup = 0

• Install: brew install gitleaks or download from GitHub releases.
• Pre-commit hook: gitleaks git --pre-commit --staged --redact (--redact keeps secret values out of the output)
• Baseline scanning: gitleaks detect --source . --redact --report-path gitleaks-report.json (without --redact the report file holds the secret values; keep it out of git and CI artifacts either way)
• For a suspected false positive, inspect the exact finding locally, confirm it is a public example or non-secret value, and record the reason. If suppression is still needed, use the installed scanner's documented, narrow fingerprint-based allowlist with a reviewer and expiry. Never suppress a whole file or bypass the hook to make a scan pass.

detect-secrets

# Generate baseline
detect-secrets scan --all-files > .secrets.baseline

# Pre-commit hook (via pre-commit framework)
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.5.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

• Supports custom plugins for organization-specific patterns.
• Audit workflow: detect-secrets audit .secrets.baseline interactively marks true/false positives.

False Positive Management

• Do not add broad exclusions to make scans pass. Keep any reviewed, narrow exception visible with its reason, owner and review date.
• If a finding may be real, treat it as exposed: avoid copying the value into logs or online scanners, ask the credential owner to verify through the provider, and rotate or revoke it if confirmed.
• If the scan is a false positive, diagnose the exact pattern and context, then tighten the rule or add only a tool-supported fingerprint exception after review.

Audit Logging

Knowing who accessed which secret and when is critical for incident investigation and compliance.

Cloud-Native Audit Trails

Alerting Strategy

• Alert on access from unknown IP ranges or service accounts outside the expected set.
• Alert on bulk secret reads (more than N secrets accessed within a time window).
• Alert on access outside deployment windows when no CI/CD pipeline is running.
• Feed audit logs into your SIEM (Splunk, Datadog, Elastic) for correlation with other security events.
• Review audit logs quarterly as part of access recertification.

Cross-References

This skill covers env hygiene and secret detection. These related skills live in the source collection and are not included here:

After this

When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own:

• The Project secrets and package risk review.
• The Credential setup planner.
• The AI agent attack tester. It takes the security report. If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring.