Security Guidelines

This document outlines security best practices for handling credentials and sensitive information in this project.

---

Table of Contents

• Secret Management
• Environment Configuration
• Incident Response: Exposed Secrets
• Prevention Measures
• Security Checklist
• Reporting Security Issues

---

Secret Management

Principles

1. Never commit secrets to version control

   • Tokens, passwords, API keys, and private keys must never be committed
   • Even "temporary" commits can persist in git history indefinitely

2. Use environment variables

   • Store sensitive configuration in environment variables
   • Load from .env files that are excluded from git
   • See .auto-claude/.env.example for the required variables

3. Treat tokens like passwords

   • Do not share tokens via email, chat, or other insecure channels
   • Use secure secret sharing tools if transfer is necessary
   • Rotate credentials regularly

4. Minimize token scope

   • Request only the permissions your application needs
   • Use fine-grained tokens when available
   • Review and revoke unused tokens periodically

Supported Secret Types

Type	Pattern	Description
GitHub PAT (new)	ghp_xxxx	Personal Access Token
GitHub OAuth	gho_xxxx	OAuth Access Token
GitHub App User	ghu_xxxx	GitHub App User Token
GitHub App Server	ghs_xxxx	GitHub App Server Token
GitHub Fine-grained	github_pat_xxxx	Fine-grained PAT
AWS Access Key	AKIA*	AWS IAM Access Key
Private Keys	-----BEGIN * PRIVATE KEY-----	RSA/EC/SSH Keys

---

Environment Configuration

Setup Instructions

1. Copy the example file

   cp .auto-claude/.env.example .auto-claude/.env

2. Edit with your values

   # Use your preferred editor
   nano .auto-claude/.env

3. Verify file is ignored

   git check-ignore .auto-claude/.env
   # Should output: .auto-claude/.env

Required Variables

See .auto-claude/.env.example for the complete list with documentation.

Variable	Required	Description
GITHUB_TOKEN	Yes	GitHub OAuth or Personal Access Token
GITHUB_API_URL	No	Custom API URL (for GitHub Enterprise)
GITHUB_REPOSITORY	No	Repository context (owner/repo format)

Security Best Practices for .env Files

• Never commit .env files - they are ignored by .gitignore
• Set restrictive permissions: chmod 600 .auto-claude/.env
• Don't copy .env between environments - create fresh for each
• Use different tokens per environment (dev, staging, prod)

---

Incident Response: Exposed Secrets

If you discover an exposed secret, follow these steps immediately:

Step 1: Revoke the Secret (CRITICAL - Do First!)

For GitHub Tokens:

1. Go to https://github.com/settings/tokens
2. Find and delete the exposed token
3. Verify revocation (see below)

For detailed instructions, see: docs/TOKEN_REVOCATION_GUIDE.md

Step 2: Verify Revocation

Use the verification script:

GITHUB_TOKEN="exposed_token_here" ./tools/verify-token-revoked.sh

Or manually test:

curl -H "Authorization: token <TOKEN>" https://api.github.com/user
# Should return 401 Unauthorized if revoked

Step 3: Assess Exposure Scope

Determine how the secret was exposed:

Exposure Type	Severity	Action Required
Local file only	Low	Revoke, cleanup
Committed to branch (not pushed)	Medium	Revoke, rewrite history
Pushed to remote	High	Revoke, force push, notify team
Public repository	Critical	Revoke immediately, audit access

Step 4: Clean Up

1. Remove from files: Replace with placeholder or redact
2. Update .gitignore: Ensure file pattern is excluded
3. Clean git history (if committed):

   # Option 1: BFG Repo Cleaner
   java -jar bfg.jar --replace-text passwords.txt
   
   # Option 2: git filter-repo
   git filter-repo --replace-text replacements.txt

Step 5: Document and Learn

1. Document the incident in build-progress.txt
2. Identify how the exposure occurred
3. Implement additional prevention measures
4. Review and update security practices

---

Prevention Measures

1. Pre-commit Hooks

This project includes pre-commit hooks for secret detection. Set them up:

# Option A: Using pre-commit framework (recommended)
pip install pre-commit
pre-commit install

# Option B: Standalone bash script
cp tools/pre-commit-secrets.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

For detailed setup instructions, see: docs/PRECOMMIT_SETUP.md

2. .gitignore Rules

The .gitignore file is configured to exclude:

• Environment files (.env, .env.*)
• Credential files (*.credentials, secrets.json)
• Private keys (*.pem, *.key, id_rsa)
• Cloud provider credentials

3. Code Review

When reviewing pull requests, check for:

• Hardcoded credentials or tokens
• New configuration files that might contain secrets
• Test files with real API keys
• Comments containing sensitive information

4. Regular Audits

Periodically scan the codebase for secrets:

# Using gitleaks
gitleaks detect --source .

# Using detect-secrets
detect-secrets scan

---

Security Checklist

Before Committing

• No hardcoded tokens, passwords, or API keys
• .env files are NOT being committed
• Test data uses fake/mock credentials
• Pre-commit hooks are installed and passing

For New Contributors

• Read this SECURITY.md document
• Copy .env.example to .env and configure
• Install pre-commit hooks
• Never share tokens via chat or email

For Code Reviews

• Check for hardcoded secrets
• Verify sensitive files are in .gitignore
• Ensure new dependencies don't introduce vulnerabilities
• Review any changes to authentication/authorization code

Periodic Tasks

• Rotate tokens quarterly (or more frequently)
• Review and revoke unused tokens
• Audit git history for accidentally committed secrets
• Update dependencies for security patches

---

Reporting Security Issues

For This Project

If you discover a security vulnerability:

1. Do NOT create a public issue
2. Document the vulnerability privately
3. Contact the maintainers directly
4. Allow time for remediation before disclosure

GitHub Secret Scanning

GitHub automatically scans for exposed secrets in public repositories. If you receive a notification:

1. Revoke the exposed secret immediately
2. Follow the incident response steps above
3. Review the commit that triggered the alert

---

Related Documentation

Document	Description
docs/TOKEN_REVOCATION_GUIDE.md	Step-by-step token revocation instructions
docs/PRECOMMIT_SETUP.md	Pre-commit hook installation guide
.auto-claude/.env.example	Environment configuration template
.gitignore	Excluded file patterns

---

Document created as part of security remediation task 007 Last updated: 2026-01-01