secrets-management.yaml

# Secrets Management Security Code Review Guidelines
# Comprehensive rules for secure handling of secrets and sensitive configuration
# Version: 1.0
# Last Updated: 2026-01-02

name: Secrets Management Security Guidelines
description: Code review guidelines for secrets management covering storage, git security, rotation, logging, and configuration

globs:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/*.php"
  - "**/*.cs"
  - "**/*.yaml"
  - "**/*.yml"
  - "**/*.json"
  - "**/*.env*"
  - "**/*.config*"
  - "**/*.properties"
  - "**/secrets*"
  - "**/credentials*"
  - "**/*docker*"
  - "**/terraform*"
  - "**/ansible*"

rules:
  # ============================================================================
  # SECRET STORAGE RULES
  # ============================================================================
  
  - name: no-hardcoded-secrets
    description: >
      Never hardcode secrets, API keys, passwords, or tokens in source code. This includes
      connection strings, encryption keys, and private keys. Use environment variables or
      secret management systems. Scan code and commits for accidental secret commits.
    severity: critical

  - name: use-environment-variables
    description: >
      Store secrets in environment variables for local development and simple deployments.
      Never commit .env files with real secrets. Use .env.example with placeholder values.
      Document required environment variables. Validate presence at startup.
    severity: high

  - name: use-secret-managers
    description: >
      In production, use dedicated secret managers (HashiCorp Vault, AWS Secrets Manager,
      Azure Key Vault, GCP Secret Manager). These provide encryption, access control,
      audit logging, and rotation. Integrate with your deployment pipeline.
    severity: high

  - name: secure-secret-transmission
    description: >
      Secrets should only be transmitted over encrypted channels (TLS). Never send secrets
      in URL query parameters (logged in access logs). Use secure secret injection at
      runtime, not build time. Avoid secrets in CI/CD logs.
    severity: high

  - name: encrypt-secrets-at-rest
    description: >
      Encrypt secrets at rest when stored in databases, files, or configuration systems.
      Use envelope encryption with key management service. Separate encryption keys from
      encrypted data. Consider using sealed secrets for Kubernetes.
    severity: high

  # ============================================================================
  # GIT SECURITY RULES
  # ============================================================================

  - name: configure-gitignore
    description: >
      Ensure .gitignore excludes all files that may contain secrets: .env, *.pem, *.key,
      credentials.json, secrets.yaml, etc. Add patterns for IDE-specific files and local
      configuration. Audit .gitignore regularly. Use global gitignore for personal files.
    severity: high

  - name: implement-pre-commit-hooks
    description: >
      Use pre-commit hooks to detect secrets before they're committed. Tools like
      detect-secrets, git-secrets, or truffleHog can scan for patterns and entropy.
      Configure hooks project-wide and document setup. Run hooks in CI as backup.
    severity: high

  - name: enable-secret-scanning
    description: >
      Enable secret scanning in your repository (GitHub, GitLab, etc.). Configure alerts
      for detected secrets. Set up automated revocation for compromised credentials.
      Monitor scanning results regularly. Train developers on response procedures.
    severity: medium

  - name: clean-git-history
    description: >
      If secrets are committed, rotating them is essential - the secret is compromised even
      if removed in a later commit. Use git filter-branch or BFG Repo-Cleaner to remove
      secrets from history. Force push and notify collaborators to re-clone.
    severity: critical

  - name: protect-sensitive-branches
    description: >
      Protect main/production branches with required reviews. Prevent force pushes that
      could hide secret removal. Require signed commits for sensitive repositories.
      Audit branch protection settings regularly.
    severity: medium

  # ============================================================================
  # SECRET ROTATION RULES
  # ============================================================================

  - name: implement-key-rotation
    description: >
      Implement automated key and secret rotation. Define rotation schedules based on
      risk (30-90 days typical). Design systems to support rotation without downtime.
      Support multiple active keys during rotation periods. Log rotation events.
    severity: high

  - name: handle-expiration-properly
    description: >
      Set expiration on all secrets and tokens. Monitor for approaching expiration.
      Implement graceful handling of expired credentials with clear error messages.
      Automate renewal where possible. Alert on renewal failures.
    severity: medium

  - name: implement-revocation-procedures
    description: >
      Have clear procedures for immediate secret revocation on breach or employee departure.
      Maintain inventory of all secrets and their locations. Practice revocation procedures.
      Automate revocation where possible. Audit access after revocation.
    severity: high

  # ============================================================================
  # LOGGING RULES
  # ============================================================================

  - name: redact-secrets-in-logs
    description: >
      Implement automatic secret redaction in logging. Mask passwords, tokens, API keys
      in log output. Use structured logging with marked sensitive fields. Review log
      output regularly for leaked secrets. Configure log aggregators for redaction.
    severity: high

  - name: avoid-sensitive-data-in-errors
    description: >
      Error messages should not expose sensitive configuration, connection strings, or
      internal paths. Use generic error messages for users. Log detailed errors server-
      side only. Implement different error verbosity for development vs production.
    severity: high

  - name: secure-debug-output
    description: >
      Disable debug output in production. Debug endpoints can expose secrets, stack traces,
      and configuration. Use feature flags to control debug features. Audit code for
      print/console.log statements that might expose sensitive data.
    severity: high

  - name: protect-audit-logs
    description: >
      Protect audit logs containing sensitive information. Encrypt at rest, restrict access,
      and implement tamper detection. Separate audit logs from application logs. Ensure
      secrets in audit context are redacted or hashed.
    severity: medium

  # ============================================================================
  # CONFIGURATION RULES
  # ============================================================================

  - name: use-secure-defaults
    description: >
      Default configurations should be secure. Don't ship with default passwords, disabled
      authentication, or overly permissive settings. Require explicit opt-in for less
      secure options. Document security implications of configuration options.
    severity: high

  - name: separate-environment-secrets
    description: >
      Use different secrets for different environments (dev, staging, production). Never
      share production secrets with development. Implement secret isolation between
      environments. Rotate secrets when environment access changes.
    severity: high

  - name: secure-secret-injection
    description: >
      Inject secrets at runtime, not build time. Don't bake secrets into container images
      or compiled artifacts. Use init containers, sidecar injectors, or runtime secret
      managers. Verify secrets are not in build artifacts.
    severity: high

  - name: implement-secret-versioning
    description: >
      Version secrets to track changes and enable rollback. Link deployments to specific
      secret versions. Maintain history for audit purposes. Implement automated rollback
      if new secrets cause failures.
    severity: medium

  - name: secure-third-party-integrations
    description: >
      Store third-party API keys and credentials securely. Use OAuth where possible over
      API keys. Implement key rotation for integrations. Monitor third-party key usage
      for anomalies. Have revocation procedures for compromised integration credentials.
    severity: high

  - name: implement-secret-access-logging
    description: >
      Log all secret access from secret managers. Monitor for unusual access patterns.
      Alert on access from unexpected sources or at unusual times. Use this for both
      security monitoring and compliance audit trails.
    severity: medium

  - name: secure-config-files
    description: >
      Configuration files containing secrets must have restrictive permissions. Use 600
      or 400 for files with secrets. Verify permissions in deployment scripts. Use
      configuration management that enforces permissions. Audit file permissions regularly.
    severity: high

  - name: avoid-secrets-in-urls
    description: >
      Never pass secrets in URL query parameters. URLs are logged in browser history,
      server access logs, and referrer headers. Use POST body or headers for sensitive
      data. Audit code for token/key parameters in URLs.
    severity: high