diff --git a/.github/SECURITY_REPORTING.md b/.github/SECURITY_REPORTING.md new file mode 100644 index 0000000..da70667 --- /dev/null +++ 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! 🔒 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f037d0f..55ae2c8 100644 --- 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. diff --git a/README.md b/README.md index e112aec..221ad9d 100644 --- 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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9a3b794 --- /dev/null +++ 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! 🔒