This document provides security guidelines for the agentic-collections repository, focusing on credential management and preventing sensitive data from being committed.

• Credential Management
• Gitleaks Protection
• Environment Setup
• Incident Response

Rule: Never commit API keys, passwords, tokens, or any sensitive credentials directly in code or configuration files.

Why: Hardcoded secrets in version control:

• Can be accessed by anyone with repository access
• Remain in git history even after deletion
• Can be exposed in public forks or clones
• Violate compliance requirements (PCI-DSS, SOC 2, etc.)

Best Practice: Store credentials in environment variables and reference them in code.

❌ INCORRECT (hardcoded):

API_KEY = "sk-proj-abc123def456ghi789"

✅ CORRECT (environment variable):

import os
API_KEY = os.environ.get("OPENAI_API_KEY")

❌ INCORRECT (hardcoded):

const apiKey = "ghp_1234567890abcdefghij";

✅ CORRECT (environment variable):

const apiKey = process.env.GITHUB_TOKEN;

MCP Configuration Rule (per CLAUDE.md line 125):

Never hardcode credentials. Always use ${ENV_VAR} references.

❌ INCORRECT (hardcoded credentials):

{
  "mcpServers": {
    "lightspeed-mcp": {
      "env": {
        "LIGHTSPEED_CLIENT_ID": "12345-abcde",
        "LIGHTSPEED_CLIENT_SECRET": "sk-proj-abc123..."
      }
    }
  }
}

✅ CORRECT (environment variable references):

{
  "mcpServers": {
    "lightspeed-mcp": {
      "env": {
        "LIGHTSPEED_CLIENT_ID": "${LIGHTSPEED_CLIENT_ID}",
        "LIGHTSPEED_CLIENT_SECRET": "${LIGHTSPEED_CLIENT_SECRET}"
      }
    }
  }
}

This repository uses gitleaks to automatically scan for secrets before commits.

# Install gitleaks and pre-commit hook (one-time setup)
scripts/install-hooks.sh

This script:

1. Installs gitleaks (via Homebrew on macOS, binary download on Linux)
2. Sets up a pre-commit hook to scan staged changes
3. Uses .gitleaks.toml for project-specific rules

Gitleaks scans for:

• API Keys: OpenAI (sk-, sk-proj-), GitHub (ghp_, ghu_, ghs_), AWS (AKIA), Google (AIza*)
• Private Keys: SSH, SSL/TLS (PEM format)
• Database URLs: Connection strings with embedded passwords
• JWT Tokens: eyJ... format tokens
• Generic Secrets: password, api_key, secret, token assignments
• MCP Hardcoded Values: .mcp.json files without ${VAR} pattern

# Scan entire repository history
gitleaks detect --source . --verbose

# Generate JSON report
gitleaks detect --source . --report-path gitleaks-report.json

# Scan specific branch
gitleaks detect --source . --log-opts="origin/main"

# Scan only staged changes (pre-commit does this automatically)
gitleaks protect --staged

The .gitleaks.toml file contains:

• Default rules: Gitleaks' built-in secret detection patterns
• Custom rules: MCP-specific validation, database URLs
• Allowlist: Patterns to exclude (environment variables, examples, test fixtures)
• Stopwords: Keywords that indicate false positives ("example", "sample", "test")

=========================================
🚨 COMMIT BLOCKED - Secrets Detected
=========================================

Gitleaks found potential secrets in your staged changes.

To fix:
  1. Remove hardcoded secrets
  2. Use environment variables: ${ENV_VAR}
  3. Review .gitleaks.toml for allowed patterns

To bypass (DANGEROUS - only for test fixtures):
  git commit --no-verify

To Fix:

1. Remove the hardcoded secret from your code
2. Replace with environment variable reference
3. Add the actual secret to your local environment (see Environment Setup)
4. Verify fix: git diff --cached
5. Commit again

Warning: Only use for test fixtures or documentation examples.

git commit --no-verify -m "Add test fixture"

If gitleaks incorrectly flags a pattern, you can:

1. Add to allowlist in .gitleaks.toml:

[allowlist]
regexes = [
    '''your-false-positive-pattern''',
]

2. Use stopwords in .gitleaks.toml:

stopwords = [
    "example",
    "your-specific-keyword",
]

3. Inline comment (not recommended):

API_KEY = "sk-example-123"  # gitleaks:allow

Use .env files for local development (already in .gitignore):

# .env (NOT committed)
OPENAI_API_KEY=sk-proj-...
GITHUB_TOKEN=ghp_...
AWS_ACCESS_KEY_ID=AKIA...
LIGHTSPEED_CLIENT_ID=...
LIGHTSPEED_CLIENT_SECRET=...

Loading .env files:

Python (with python-dotenv):

from dotenv import load_dotenv
load_dotenv()

import os
api_key = os.environ["OPENAI_API_KEY"]

Node.js (with dotenv):

require('dotenv').config();

const apiKey = process.env.OPENAI_API_KEY;

Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile:

# API Keys
export OPENAI_API_KEY="your-key"
export GITHUB_TOKEN="your-token"

# Red Hat Lightspeed
export LIGHTSPEED_CLIENT_ID="your-client-id"
export LIGHTSPEED_CLIENT_SECRET="your-client-secret"

# AWS
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

Security Note: Ensure your shell profile has restrictive permissions:

chmod 600 ~/.bashrc ~/.zshrc

For production, consider using:

• AWS Secrets Manager: For AWS-hosted applications
• HashiCorp Vault: For multi-cloud secret management
• 1Password CLI: For team secret sharing
• GitHub Secrets: For CI/CD pipelines

Act Immediately - Assume the secret is compromised.

Priority: Revoke the exposed credential first.

• OpenAI: Go to platform.openai.com/api-keys → Revoke
• GitHub: Go to github.com/settings/tokens → Delete
• AWS: Go to IAM Console → Access Keys → Deactivate/Delete
• Red Hat Lightspeed: Contact administrator or regenerate via console

Warning: Rewriting history requires force push.

# Install git-filter-repo (if not installed)
# macOS: brew install git-filter-repo
# Linux: pip install git-filter-repo

# Remove file from all history
git filter-repo --path path/to/secret/file --invert-paths

# Or remove specific pattern from all files
git filter-repo --replace-text <(echo "sk-proj-actual-key==>REDACTED")

# Force push (WARNING: coordinate with team)
git push --force --all
git push --force --tags

• Inform team members: They need to re-clone or reset their local repos
• Update CI/CD: Rotate secrets in CI/CD pipelines
• Audit access: Check if the secret was used maliciously

# Search git history for secret
git log -S "sk-proj-abc123" --all

# Should return no results after cleanup

After an incident:

• Secret revoked and rotated
• Git history cleaned
• Force push completed
• Team notified
• CI/CD secrets updated
• Access logs audited
• Gitleaks hook installed/verified
• Root cause analysis completed
• Process updated to prevent recurrence

• Repository Guidelines: CLAUDE.md - Line 125 documents MCP credential requirements
• .gitignore: Pre-configured to exclude common secret files (.env, *.key, *.pem)
• MCP Example: rh-sre/.mcp.json - Reference implementation with ${VAR} pattern
• Gitleaks Configuration: .gitleaks.toml - Project-specific rules

• Gitleaks: https://github.com/gitleaks/gitleaks
• OWASP Secrets Management: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
• GitHub Secret Scanning: https://docs.github.com/en/code-security/secret-scanning
• AWS Secrets Manager: https://aws.amazon.com/secrets-manager/
• git-filter-repo: https://github.com/newren/git-filter-repo

For questions about this security policy:

1. Review this SECURITY.md document
2. Check CLAUDE.md for repository-specific guidelines
3. Test with: gitleaks protect --staged
4. Open a GitHub issue for policy clarifications

Important: Never include actual secrets in issue reports or pull request descriptions.