This document outlines security best practices for using and contributing to the Agentic Proposal Generator.

Anthropic API keys are sensitive credentials that must never be committed to version control.

1. Use Environment Variables (Recommended)

   export ANTHROPIC_API_KEY='sk-ant-your-key-here'

2. Use .env Files (Local Development)

   # Create .env file in project root
   echo "ANTHROPIC_API_KEY=sk-ant-your-key-here" > .env

3. Production Deployment

   • Use secure environment variable management
   • Consider using secrets management services (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
   • Never hardcode keys in source code
   • Rotate keys regularly (quarterly at minimum)
   • Use separate keys for dev/staging/production

The project includes multiple layers of protection:

1. .gitignore Protection

   # API Keys and secrets
   .env
   .env.*
   *.key
   *sk-ant-*
   *anthropic*key*
   secrets.json
   config.json
   credentials.json
   

2. Runtime Validation

   • API keys are validated before use
   • Clear error messages when keys are missing
   • No key logging or exposure in error messages

3. Pre-commit Hooks

   • detect-private-key hook scans for common key patterns
   • Automatically blocks commits containing potential secrets
   • Install with: pre-commit install

4. CI/CD Security

   • GitHub Actions never require API keys (mock tests only)
   • Secrets stored in GitHub Secrets (encrypted)
   • No keys in logs or artifacts

ACT IMMEDIATELY - Exposed keys can be found and abused within minutes.

1. Immediately revoke the key

   • Go to Anthropic Console
   • Delete the exposed key immediately
   • Do this FIRST, before anything else

2. Generate a new key

   • Create a replacement key
   • Update your local environment
   • Update production/staging environments

3. Clean Git history

   # Remove from recent commit (if not pushed)
   git reset --soft HEAD~1
   git reset HEAD .env
   git commit -m "Your commit message"
   
   # If already pushed, use filter-branch (use with caution)
   git filter-branch --index-filter \
     'git rm --cached --ignore-unmatch .env' HEAD
   
   # Force push (notify team first!)
   git push --force-with-lease

4. Monitor your Anthropic account

   • Check usage logs for unauthorized access
   • Enable spending limits
   • Set up usage alerts
   • Review recent API calls

5. Notify maintainers

   • If pushed to public repository, notify maintainers
   • Consider rotating shared keys
   • Review security practices

1. Never share .env files

   • Each developer should have their own API key
   • Use .env.example as template (no real keys)
   • Add .env to global .gitignore

2. Use separate keys for different environments

   • Development keys with strict usage limits
   • Staging keys with moderate limits
   • Production keys with appropriate permissions
   • Label keys clearly in Anthropic Console

3. Regular key rotation

   • Rotate development keys monthly
   • Rotate production keys quarterly
   • Document rotation in security calendar
   • Test new keys before decommissioning old ones

1. Mock API calls in tests

   • NEVER use real API keys in automated tests
   • Use mock responses for predictable testing
   • Mock tests are the default (tests/unit, tests/integration)
   • Live tests only for pre-release validation

2. Sanitize logs

   • Never log API keys or full API responses
   • Redact sensitive information from debug output
   • Use structured logging with key filtering

3. CI/CD Best Practices

   • Mock tests run in CI (no API keys needed)
   • Secrets stored in GitHub Secrets
   • Never print environment variables in logs
   • Use continue-on-error: true for safety checks only

Discovery call transcripts may contain sensitive business information:

1. No persistent storage

   • Transcripts are processed in memory only
   • No automatic caching of input content
   • Claude API processes data according to their privacy policy

2. Output sanitization

   • Generated proposals don't expose raw API responses
   • Review proposals before sharing externally
   • Consider data classification requirements

3. Data handling recommendations

   • Review generated proposals before sharing
   • Consider data classification requirements
   • Implement appropriate access controls
   • Follow your organization's data handling policies
   • Be aware of information sent to third-party APIs

The project includes MCP tools that may access external data:

1. Tool Permissions

   • MCP tools defined in src/agentic_proposal_generator/mcp/tools.py
   • Review tool capabilities before deployment
   • Limit tool permissions appropriately

2. External Data Access

   • Company lookup tools may access public APIs
   • No credentials stored in MCP configuration
   • Review tool outputs before use

If you discover a security vulnerability:

1. Do NOT open a public issue

   • Security issues should not be publicly disclosed
   • Use private disclosure channels

2. Report through GitHub Security Advisories

   • Go to Security tab → Report a vulnerability
   • Provide detailed reproduction steps
   • Include affected versions

3. Contact maintainers privately

   • For urgent matters, contact repository owner directly
   • Allow reasonable time for fix (90 days standard)

4. Responsible Disclosure

   • Work with maintainers to verify fix
   • Coordinate public disclosure timing
   • Credit provided in security advisories

Report any of the following:

• API key exposure in code/commits
• Injection vulnerabilities
• Authentication/authorization bypasses
• Sensitive data exposure
• Dependency vulnerabilities
• Insecure configurations

• Input data: Discovery call transcripts contain confidential business information
• AI processing: Content is sent to Anthropic's API - review Anthropic's privacy policy
• Output data: Generated proposals may contain derived business insights

1. Review Anthropic's Terms of Service

   • Understand data processing policies
   • Ensure compliance with your organization's requirements
   • Review commercial data usage terms

2. Implement appropriate controls

   • Data classification policies
   • Access logging and monitoring
   • Retention and deletion policies
   • Encryption in transit and at rest

3. Consider regulatory requirements

   • GDPR (EU data protection)
   • CCPA (California privacy law)
   • Industry-specific compliance (HIPAA, SOX, PCI-DSS, etc.)
   • International data transfer restrictions

4. Business Considerations

   • Confidentiality agreements with customers
   • Intellectual property protection
   • Competitive information handling
   • Client data protection obligations

• API keys stored securely (not in code)
• .gitignore configured properly
• No sensitive data in commit history
• Environment variables configured
• Access controls implemented
• Monitoring and alerting configured
• Spending limits set on API keys
• Pre-commit hooks installed

• Rotate API keys quarterly
• Review access logs monthly
• Update dependencies weekly (uv sync)
• Monitor for security advisories
• Audit .gitignore effectiveness
• Review user permissions
• Test incident response procedures
• Security training for team members

• No hardcoded secrets or API keys
• Input validation on user-provided data
• Error messages don't leak sensitive info
• Dependencies are up to date
• Security tests pass
• Bandit scan passes (no high-severity issues)

1. Keep dependencies updated

   # Update dependencies
   uv sync --upgrade
   
   # Check for security vulnerabilities
   uv run safety check

2. Review dependency changes

   • Check uv.lock for unexpected changes
   • Review security advisories for dependencies
   • Test thoroughly after updates

3. Minimize dependencies

   • Only add necessary dependencies
   • Prefer well-maintained packages
   • Review package maintainer reputation

• Anthropic Security Best Practices
• Claude API Documentation
• OWASP Top 10
• Git Security Documentation
• 12 Factor App - Config
• GitHub Security Best Practices

Remember: Security is a shared responsibility. Every contributor and user plays a role in keeping the project and its users secure.

• 1.0 (2025-01-05): Initial security guidelines for Agentic Proposal Generator