security: Add comprehensive security policy and vulnerability reporting process

2026-01-09 09:25:00 +01:00
parent 0101d7da84
commit 241baf30bd
4 changed files with 666 additions and 0 deletions
--- a/.github/SECURITY_REPORTING.md
+++ b/.github/SECURITY_REPORTING.md
@@ -0,0 +1,309 @@
 # Security Vulnerability Reporting
 This file explains how to report security vulnerabilities to the Claude How To project.
 ## Quick Links
 - **Private Reporting**: https://github.com/luongnv89/claude-howto/security/advisories
 - **Security Policy**: [SECURITY.md](../SECURITY.md)
 - **Report Template**: See below
 ## Report a Vulnerability
 ### Option 1: GitHub Private Vulnerability Report (RECOMMENDED)
 This is the preferred method for reporting security vulnerabilities.
 **Steps:**
 1. Go to: https://github.com/luongnv89/claude-howto/security/advisories
 2. Click "Report a vulnerability"
 3. Fill in the details (use template below)
 4. Submit
 **Advantages:**
 - Keeps vulnerability private until fix is released
 - Automatic notifications to maintainers
 - Built-in collaboration features
 - Integrated with GitHub security tools
 ### Option 2: GitHub Security Alert (For Dependencies)
 If you discover a vulnerability in a dependency:
 1. Go to: https://github.com/luongnv89/claude-howto/security/dependabot/alerts
 2. Review the alert
 3. Create a pull request with the fix
 4. Tag with `security` label
 ### Option 3: Private Email (If GitHub unavailable)
 If you cannot use GitHub's reporting system:
 **Coming soon**: Security contact email will be added here
 For now, use GitHub's private vulnerability reporting as described above.
 ## Vulnerability Report Template
 Use this template when reporting a vulnerability:
 ```
 **Title**: [Brief description of vulnerability]
 **Severity**: [Critical/High/Medium/Low]
 Estimated CVSS Score: [0-10]
 **Type**: [Code/Documentation/Dependency/Configuration]
 **Affected Component**:
 - File: [path/to/file.py]
 - Section: [Section name if documentation]
 - Version: [latest/specific version]
 **Description**:
 [Clear explanation of what the vulnerability is]
 **Potential Impact**:
 [What could an attacker do with this vulnerability?]
 [Who could be affected?]
 **Steps to Reproduce**:
 1. [First step]
 2. [Second step]
 3. [Third step]
 [Expected result vs actual result]
 **Proof of Concept** (if available):
 [Code or steps to demonstrate the vulnerability]
 **Suggested Fix**:
 [Your recommended solution, if you have one]
 **Additional Context**:
 [Any other relevant information]
 **Your Information**:
 - Name: [Your name or anonymous]
 - Email: [Your email]
 - Credit: [How you'd like to be credited, if at all]
 ```
 ## What Happens After You Report
 ### Timeline
 1. **Immediate (< 1 hour)**
   - Automatic notification sent to project maintainers
 2. **Within 24 hours**
   - Initial assessment of the report
   - Confirmation that we received it
   - Preliminary severity assessment
 3. **Within 48 hours**
   - Detailed response from security team
   - Questions for clarification (if needed)
   - Timeline for fix (if vulnerability confirmed)
 4. **Within 1-7 days** (depends on severity)
   - Fix developed and tested
   - Security advisory prepared
   - Fix released and public advisory published
 ### Communication
 We will keep you informed through:
 - GitHub private vulnerability discussion
 - Email (if provided)
 - Updates in the discussion thread
 You can:
 - Ask clarifying questions
 - Provide additional information
 - Suggest improvements to the fix
 - Request timeline adjustments
 ### Disclosure Timeline
 **Critical Issues (CVSS 9.0-10.0)**
 - Fix: Released immediately (within 24 hours)
 - Disclosure: Public advisory issued same day
 - Notice: 24 hours advance notice to reporter
 **High Issues (CVSS 7.0-8.9)**
 - Fix: Released within 48-72 hours
 - Disclosure: Public advisory on release
 - Notice: 5 days advance notice to reporter
 **Medium Issues (CVSS 4.0-6.9)**
 - Fix: Included in next regular update
 - Disclosure: Public advisory on release
 - Notice: Coordinated timing
 **Low Issues (CVSS 0.1-3.9)**
 - Fix: Included in next regular update
 - Disclosure: Advisory on release
 - Notice: Same day as release
 ## Security Vulnerability Criteria
 ### In Scope
 We accept reports on:
 - **Code Vulnerabilities**
  - Injection attacks (command, SQL, etc.)
  - Cross-site scripting (XSS) in examples
  - Authentication/authorization flaws
  - Path traversal vulnerabilities
  - Cryptography issues
 - **Documentation Security**
  - Exposed secrets or credentials
  - Insecure code patterns
  - Security anti-patterns
  - Misleading security claims
 - **Dependency Vulnerabilities**
  - Known CVEs in dependencies
  - Supply chain attacks
  - Malicious dependencies
 - **Configuration Issues**
  - Insecure defaults
  - Missing security headers
  - Credential exposure in examples
 ### Out of Scope
 We do NOT accept reports on:
 - Vulnerabilities in Claude Code itself (contact Anthropic)
 - Vulnerabilities in external services
 - Theoretical vulnerabilities without proof
 - Issues already reported to upstream projects
 - Social engineering or phishing
 - User education/training issues
 ## Responsible Disclosure Guidelines
 ### Do's ✅
 - **Report privately** before public disclosure
 - **Be specific** with file paths and line numbers
 - **Provide proof** of the vulnerability
 - **Give us time** to fix (coordinated disclosure)
 - **Update** if you discover more details
 - **Be professional** in all communications
 - **Respect confidentiality** until we publish
 ### Don'ts ❌
 - **Don't publicly disclose** before we fix
 - **Don't exploit** the vulnerability beyond testing
 - **Don't modify** other users' data
 - **Don't demand** payment or favors
 - **Don't share** the vulnerability with others
 - **Don't use** it in any harmful way
 - **Don't spam** with non-security related issues
 ## Coordinated Disclosure
 We practice responsible disclosure:
 1. **Private Report**: You report to us privately
 2. **Our Assessment**: We evaluate and assess severity
 3. **Fix Development**: We develop and test a fix
 4. **Advance Notice**: We give you advance notice before public disclosure
 5. **Public Release**: We release fix and advisory together
 6. **Your Credit**: We acknowledge your contribution (if desired)
 **Timeline varies based on severity** (see section above)
 ## After the Fix is Released
 ### Public Advisory
 A public security advisory will include:
 - Description of the vulnerability
 - Affected versions
 - Severity (CVSS score)
 - Steps to remediate
 - Link to the fix
 - Credit to reporter (with permission)
 ### Your Recognition
 If you wish to be credited:
 - Your name/handle in the advisory
 - Link to your profile/website
 - Mention in release notes
 - Addition to hall of fame (if created)
 ### No Compensation
 Please note:
 - This is a volunteer-run open-source project
 - We cannot offer financial rewards
 - We do offer recognition and credit
 - Your contribution helps the community
 ## Security Research
 If you're conducting security research:
 1. **Get Permission**: Contact maintainers first
 2. **Define Scope**: Agree on what you'll test
 3. **Report Findings**: Use this process
 4. **Respect Timeline**: Allow time for fixes
 5. **Publish Responsibly**: Coordinate with us
 ## Questions?
 For questions about this process:
 1. Check [SECURITY.md](../SECURITY.md) for detailed policy
 2. Look at [FAQ](#faq) section below
 3. Open a discussion with `[SECURITY]` label
 4. Use private vulnerability reporting for sensitive questions
 ## FAQ
 **Q: Will my report be kept confidential?**
 A: Yes, until the fix is released. We only share details with those working on the fix.
 **Q: How long do I need to wait before public disclosure?**
 A: We follow responsible disclosure timelines based on severity (24 hours to 7 days). You can agree to extend this if needed.
 **Q: Will I get credit?**
 A: Yes, in the security advisory and release notes (unless you prefer anonymity).
 **Q: What if the vulnerability is minor?**
 A: All legitimate security issues are taken seriously. Even minor fixes will be acknowledged.
 **Q: Can I report vulnerabilities in documentation only?**
 A: Yes! Documentation security is important too. Examples with insecure patterns are in scope.
 **Q: What if I'm not sure if something is a security issue?**
 A: Report it anyway! If it's not a security issue, we'll let you know. False positives are fine.
 **Q: Can I publicly discuss the vulnerability after reporting?**
 A: No, please keep it private until we publish the advisory. Premature disclosure could put users at risk.
 **Q: How do I know you received my report?**
 A: GitHub will send an automatic notification, and we'll follow up within 24 hours.
 **Q: What if I don't hear back?**
 A: Check GitHub security advisories page. If you still don't see a response, you can follow up with a comment on the private report.
 ## Resources
 - [SECURITY.md](../SECURITY.md) - Full security policy
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - Contributing guidelines
 - [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) - Community standards
 - [OWASP Guide](https://owasp.org/www-project-responsible-disclosure/) - Responsible disclosure best practices
 - [Coordinated Vulnerability Disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerable_Dependency_Management_Cheat_Sheet.html)
 ---
 Thank you for helping keep this project secure! 🔒
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -314,6 +314,18 @@ Contributors are recognized in:
 - GitHub contributors page
 - Commit history
 ## Security
 When contributing examples and documentation, please follow secure coding practices:
 - **Never hardcode secrets or API keys** - Use environment variables
 - **Warn about security implications** - Highlight potential risks
 - **Use secure defaults** - Enable security features by default
 - **Validate inputs** - Show proper input validation and sanitization
 - **Include security notes** - Document security considerations
 For security issues, see [SECURITY.md](../SECURITY.md) for our vulnerability reporting process.
 ## Code of Conduct
 We are committed to providing a welcoming and inclusive community. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for our full community standards.
--- a/README.md
+++ b/README.md
@@ -827,6 +827,17 @@ Found an issue or want to contribute an example? We'd love your help!
 **Our Community Standards:**
 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - How we treat each other
 - [SECURITY.md](SECURITY.md) - Security policy and vulnerability reporting
 ### Reporting Security Issues
 If you discover a security vulnerability, please report it responsibly:
 1. **Use GitHub Private Vulnerability Reporting**: https://github.com/luongnv89/claude-howto/security/advisories
 2. **Or read** [.github/SECURITY_REPORTING.md](.github/SECURITY_REPORTING.md) for detailed instructions
 3. **Do NOT** open a public issue for security vulnerabilities
 Security issues are taken seriously and will be addressed promptly. See [SECURITY.md](SECURITY.md) for our full security policy.
 Quick start:
 1. Fork and clone the repository
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -0,0 +1,334 @@
 # Security Policy
 ## Overview
 The security of the Claude How To project is important to us. This document outlines our security practices and describes how to report security vulnerabilities responsibly.
 ## Supported Versions
 We provide security updates for the following versions:
 | Version | Status | Support Until |
 |---------|--------|---------------|
 | Latest (main) | ✅ Active | Current + 6 months |
 | 1.x releases | ✅ Active | Until next major version |
 **Note**: As an educational guide project, we focus on maintaining current best practices and documentation security rather than traditional version support. Updates are applied directly to the main branch.
 ## Security Practices
 ### Code Security
 1. **Dependency Management**
   - All Python dependencies are pinned in `requirements.txt`
   - Regular updates via dependabot and manual review
   - Security scanning with Bandit on every commit
   - Pre-commit hooks for security checks
 2. **Code Quality**
   - Linting with Ruff catches common issues
   - Type checking with mypy prevents type-related vulnerabilities
   - Pre-commit hooks enforce standards
   - All changes reviewed before merging
 3. **Access Control**
   - Branch protection on `main` branch
   - Required reviews before merge
   - Status checks must pass before merge
   - Limited write access to repository
 ### Documentation Security
 1. **No Secrets in Examples**
   - All API keys in examples are placeholders
   - Credentials are never hardcoded
   - `.env.example` files show required variables
   - Clear warnings about secret management
 2. **Security Best Practices**
   - Examples demonstrate secure patterns
   - Security warnings highlighted in documentation
   - Links to official security guides
   - Credential handling discussed in relevant sections
 3. **Content Review**
   - All documentation reviewed for security issues
   - Security considerations in contributing guidelines
   - Validation of external links and references
 ### Dependency Security
 1. **Scanning**
   - Bandit scans all Python code for vulnerabilities
   - Dependency vulnerability checks via GitHub security alerts
   - Regular manual security audits
 2. **Updates**
   - Security patches applied promptly
   - Major versions evaluated carefully
   - Changelog includes security-related updates
 3. **Transparency**
   - Security updates documented in commits
   - Vulnerability disclosures handled responsibly
   - Public security advisories when appropriate
 ## Reporting a Vulnerability
 ### Security Issues We Care About
 We appreciate reports on:
 - **Code vulnerabilities** in scripts or examples
 - **Dependency vulnerabilities** in Python packages
 - **Cryptography issues** in any code examples
 - **Authentication/Authorization flaws** in documentation
 - **Data exposure risks** in configuration examples
 - **Injection vulnerabilities** (SQL, command, etc.)
 - **SSRF/XXE/Path traversal** issues
 ### Security Issues Out of Scope
 These are outside the scope of this project:
 - Vulnerabilities in Claude Code itself (report to Anthropic)
 - Issues with external services or libraries (report to upstream)
 - Social engineering or user education (not applicable to this guide)
 - Theoretical vulnerabilities without proof of concept
 - Vulnerabilities in dependencies reported through official channels
 ## How to Report
 ### Private Reporting (Preferred)
 **For sensitive security issues, please use GitHub's private vulnerability reporting:**
 1. Visit: https://github.com/luongnv89/claude-howto/security/advisories
 2. Click "Report a vulnerability"
 3. Fill in the vulnerability details
 4. Include:
   - Clear description of the vulnerability
   - Affected component (file, section, example)
   - Potential impact
   - Steps to reproduce (if applicable)
   - Suggested fix (if you have one)
 **What happens next:**
 - We'll acknowledge receipt within 48 hours
 - We'll investigate and assess severity
 - We'll work with you to develop a fix
 - We'll coordinate disclosure timeline
 - We'll credit you in the security advisory (unless you prefer anonymity)
 ### Public Reporting
 For non-sensitive issues or those already public:
 1. **Open a GitHub Issue** with label `security`
 2. Include:
   - Title: `[SECURITY]` followed by brief description
   - Detailed description
   - Affected file or section
   - Potential impact
   - Suggested fix
 ## Vulnerability Response Process
 ### Assessment (24 hours)
 1. We acknowledge receipt of the report
 2. We assess severity using [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document)
 3. We determine if it's in scope
 4. We contact you with initial assessment
 ### Development (1-7 days)
 1. We develop a fix
 2. We review and test the fix
 3. We create a security advisory
 4. We prepare release notes
 ### Disclosure (varies by severity)
 **Critical (CVSS 9.0-10.0)**
 - Fix released immediately
 - Public advisory issued
 - 24-hour advance notice to reporters
 **High (CVSS 7.0-8.9)**
 - Fix released within 48-72 hours
 - 5-day advance notice to reporters
 - Public advisory on release
 **Medium (CVSS 4.0-6.9)**
 - Fix released in next regular update
 - Public advisory on release
 **Low (CVSS 0.1-3.9)**
 - Fix included in next regular update
 - Advisory on release
 ### Publication
 We publish security advisories that include:
 - Description of the vulnerability
 - Affected components
 - Severity assessment (CVSS score)
 - Fix version
 - Workarounds (if applicable)
 - Credit to reporter (with permission)
 ## Best Practices for Reporters
 ### Before Reporting
 - **Verify the issue**: Can you reproduce it consistently?
 - **Search existing issues**: Is it already reported?
 - **Check documentation**: Is there guidance on secure usage?
 - **Test the fix**: Does your suggested fix work?
 ### When Reporting
 - **Be specific**: Provide exact file paths and line numbers
 - **Include context**: Why is this a security issue?
 - **Show impact**: What could an attacker do?
 - **Provide steps**: How can we reproduce it?
 - **Suggest fixes**: How would you fix it?
 ### After Reporting
 - **Be patient**: We have limited resources
 - **Be responsive**: Answer follow-up questions quickly
 - **Keep it confidential**: Don't publicly disclose before fix
 - **Respect coordination**: Follow our timeline for disclosure
 ## Security Headers and Configuration
 ### Repository Security
 - **Branch protection**: Main branch requires 2 approvals for changes
 - **Status checks**: All CI/CD checks must pass
 - **CODEOWNERS**: Designated reviewers for key files
 - **Signed commits**: Recommended for contributors
 ### Development Security
 ```bash
 # Install pre-commit hooks
 pre-commit install
 # Run security scans locally
 bandit -c pyproject.toml -r scripts/
 mypy scripts/ --ignore-missing-imports
 ruff check scripts/
 ```
 ### Dependency Security
 ```bash
 # Check for known vulnerabilities
 pip install safety
 safety check
 # Or use pip-audit
 pip install pip-audit
 pip-audit
 ```
 ## Security Guidelines for Contributors
 ### When Writing Examples
 1. **Never hardcode secrets**
   ```python
   # ❌ Bad
   api_key = "sk-1234567890"
   # ✅ Good
   api_key = os.getenv("API_KEY")
   ```
 2. **Warn about security implications**
   ```markdown
   ⚠️ **Security Note**: Never commit `.env` files to git.
   Add to `.gitignore` immediately.
   ```
 3. **Use secure defaults**
   - Enable authentication by default
   - Use HTTPS where applicable
   - Validate and sanitize inputs
   - Use parameterized queries
 4. **Document security considerations**
   - Explain why security matters
   - Show secure vs. insecure patterns
   - Link to authoritative sources
   - Include warnings prominently
 ### When Reviewing Contributions
 1. **Check for exposed secrets**
   - Scan for common patterns (api_key=, password=)
   - Review configuration files
   - Check environment variables
 2. **Verify secure coding practices**
   - No hardcoded credentials
   - Proper input validation
   - Secure authentication/authorization
   - Safe file handling
 3. **Test security implications**
   - Can this be misused?
   - What's the worst case?
   - Are there edge cases?
 ## Security Resources
 ### Official Standards
 - [OWASP Top 10](https://owasp.org/www-project-top-ten/)
 - [CWE Top 25](https://cwe.mitre.org/top25/)
 - [CVSS Calculator](https://www.first.org/cvss/calculator/3.1)
 ### Python Security
 - [Python Security Advisories](https://www.python.org/dev/security/)
 - [PyPI Security](https://pypi.org/help/#security)
 - [Bandit Documentation](https://bandit.readthedocs.io/)
 ### Dependency Management
 - [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/)
 - [GitHub Security Alerts](https://docs.github.com/en/code-security/supply-chain-security/managing-vulnerabilities-in-your-dependencies)
 ### General Security
 - [Anthropic's Security Policy](https://www.anthropic.com/security)
 - [GitHub Security Best Practices](https://docs.github.com/en/code-security)
 ## Security Advisories Archive
 Past security advisories are available in the [GitHub Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) tab.
 ## Contact
 For security-related questions or to discuss security practices:
 1. **Private Security Report**: Use GitHub's private vulnerability reporting
 2. **General Security Questions**: Open a discussion with `[SECURITY]` tag
 3. **Security Policy Feedback**: Create an issue with `security` label
 ## Acknowledgments
 We appreciate the security researchers and community members who help keep this project secure. Contributors who report vulnerabilities responsibly will be acknowledged in our security advisories (unless they prefer anonymity).
 ## Policy Updates
 This security policy is reviewed and updated:
 - When new vulnerabilities are discovered
 - When security best practices evolve
 - When the project scope changes
 - Annually as a minimum
 **Last Updated**: January 2026
 **Next Review**: January 2027
 ---
 Thank you for helping keep Claude How To secure! 🔒