@stillrivercode/agentic-workflow-template

# Security Guidelines This document provides comprehensive security guidance for using the AI-powered workflow template safely and securely. ## 🔒 Quick Security Checklist Before using this template, ensure you have: - [ ] Set up secure API key management - [ ] Configured repository security settings - [ ] Understood workflow security implications - [ ] Set up monitoring and audit procedures - [ ] Reviewed security troubleshooting procedures - [ ] Established regular security audit schedule ## 🚨 Critical Security Warnings ### ⚠️ API Key Exposure **NEVER commit API keys to your repository.** Always use GitHub Secrets for sensitive credentials. ### ⚠️ GitHub Token Permissions Use the minimum required permissions for GitHub Personal Access Tokens. Start with `repo` scope only. ### ⚠️ AI-Generated Code Review **ALWAYS review AI-generated code** before merging. AI can introduce security vulnerabilities or expose sensitive information. #### AI-Specific Security Risks - **Prompt injection attacks**: Malicious content in issue descriptions - **Information leakage**: AI may expose sensitive data in responses - **Cost-based DoS**: Excessive API usage can drain resources - **Code quality issues**: AI may generate insecure or inefficient code ### ⚠️ Public Repository Considerations If your repository is public, be extra cautious about: - Configuration files that might expose internal architecture - Comments or documentation that reveal sensitive business logic - Test data that might contain real information ## 🔐 API Key Management ### Secure Storage Practices #### GitHub Secrets (Recommended) ```bash # Interactive secure input (preferred) gh secret set OPENROUTER_API_KEY # Enter your API key when prompted # Verify secret is set gh secret list ``` #### Local Development ```bash # Use .env file (never commit) cp .env.example .env # Edit .env with your API key echo ".env" >> .gitignore # Ensure it's ignored ``` ### Key Rotation Schedule #### Regular Rotation - **Monthly**: For production environments - **Quarterly**: For development environments - **Immediately**: If compromise suspected #### Rotation Process 1. Generate new API key at [OpenRouter](https://openrouter.ai) 2. Update GitHub secrets 3. Test workflows with new key 4. Revoke old key 5. Document rotation date ### Monitoring and Usage #### Track Usage - Monitor API costs in OpenRouter dashboard - Set up billing alerts - Review usage patterns regularly #### Security Monitoring - Check for unusual API activity - Monitor failed authentication attempts - Review workflow logs for errors ## 🛡️ Repository Security ### GitHub Security Settings #### Repository Settings ```bash # Enable security features gh repo edit --enable-vulnerability-alerts gh repo edit --enable-automated-security-fixes gh repo edit --enable-dependency-graph ``` #### Branch Protection Rules - Require pull request reviews - Dismiss stale reviews - Require status checks - Restrict pushes to main branch #### Secret Scanning - Enable secret scanning - Configure custom patterns - Review and resolve alerts ### Access Control #### Team Permissions - **Admin**: Repository owners only - **Write**: Core contributors - **Read**: General team members #### Personal Access Tokens - Use minimum required scopes - Prefer fine-grained tokens - Regular rotation schedule ## 🔒 Workflow Security ### GitHub Actions Security #### Workflow Permissions Use minimum required permissions: ```yaml permissions: contents: read issues: write pull-requests: write actions: read # Add only what's needed ``` #### Security Best Practices - Pin action versions to specific commits - Use official actions when possible - Avoid storing secrets in workflow files - Limit workflow triggers appropriately ### AI Workflow Considerations #### Code Review Requirements - **Always review** AI-generated code - **Test thoroughly** before merging - **Check for security vulnerabilities** - **Validate business logic** #### Prompt Security - Avoid including sensitive data in prompts - Sanitize user input in issue descriptions - Review AI responses for information leakage #### Cost-Based Security - Set spending limits to prevent abuse - Monitor unusual cost patterns - Implement circuit breakers ### Secret Management #### Workflow Secrets ```yaml # Access secrets securely - name: Use API Key env: API_KEY: ${{ secrets.OPENROUTER_API_KEY }} run: | # Use $API_KEY in commands ``` #### Environment Variables - Use GitHub environments for sensitive workflows - Implement approval requirements - Restrict environment access ## 🔍 Security Monitoring ### Daily Monitoring - Review GitHub Actions logs for unusual activity - Check API usage patterns for anomalies - Monitor repository access logs ### Weekly Reviews - Audit active GitHub tokens and their permissions - Review recent AI-generated code changes - Check for new security alerts or vulnerabilities ### Monthly Audits - Complete security audit checklist - Review and rotate API keys - Update security documentation - Assess and update security policies ## 🚨 Incident Response ### Immediate Actions (if security breach suspected) 1. **Revoke compromised credentials immediately** 2. **Disable affected workflows** 3. **Review recent repository activity** 4. **Document the incident** 5. **Notify team members** ### Investigation Steps 1. Identify the scope of the potential breach 2. Review logs and audit trails 3. Assess what data or systems may be affected 4. Determine root cause 5. Implement fixes and preventive measures ### Recovery Procedures 1. Generate new API keys and tokens 2. Update all affected secrets 3. Review and update security policies 4. Re-enable workflows with enhanced monitoring 5. Conduct post-incident review ## 🛠️ Security Troubleshooting ### Common Issues #### API Key Problems **Issue**: Workflows failing with authentication errors **Solutions**: - Verify secret is set: `gh secret list` - Check key validity at OpenRouter - Regenerate key if needed - Ensure proper secret name #### Permission Errors **Issue**: GitHub Actions permission denied **Solutions**: - Check workflow permissions - Verify token scopes - Review repository settings - Update team permissions #### Security Scan Failures **Issue**: Security scans reporting false positives **Solutions**: - Review and whitelist known safe patterns - Update security tool configurations - Add pragma comments for exceptions - Update vulnerable dependencies ### Diagnostic Commands #### Check Repository Security ```bash # Check security settings gh repo view --json securityAndAnalysis # List security alerts gh api repos/:owner/:repo/security-advisories # Check workflow permissions gh workflow list ``` #### Validate Secrets ```bash # List repository secrets gh secret list # Test API key (without exposing it) gh workflow run ai-task.yml ``` #### Review Logs ```bash # Check workflow logs gh run list --workflow=ai-task.yml gh run view <run-id> --log ``` ### Emergency Procedures #### Suspected Compromise 1. **Immediate Actions**: - Disable all workflows - Revoke all API keys - Change all passwords - Review recent activity 2. **Investigation**: - Check workflow logs - Review repository access - Analyze API usage patterns - Document findings 3. **Recovery**: - Generate new credentials - Update all secrets - Re-enable workflows gradually - Monitor for issues ## 📋 Security Audit Checklist ### Monthly Security Audit #### Repository Security - [ ] Review and update branch protection rules - [ ] Check security alert status - [ ] Verify secret scanning is enabled - [ ] Audit team access permissions - [ ] Review recent security-related commits #### API Key Management - [ ] Rotate API keys (if due) - [ ] Review API usage patterns - [ ] Check for unused or expired keys - [ ] Verify billing alerts are configured - [ ] Document key rotation dates #### Workflow Security - [ ] Review workflow permissions - [ ] Check for security issues in AI-generated code - [ ] Verify pre-commit hooks are working - [ ] Test security scanning workflows - [ ] Review workflow logs for anomalies #### Documentation Review - [ ] Update security documentation - [ ] Review and update incident response procedures - [ ] Check that security contacts are current - [ ] Verify security training is up to date ### Quarterly Deep Audit #### Comprehensive Security Review - [ ] Complete risk assessment - [ ] Review all security policies - [ ] Test incident response procedures - [ ] Conduct penetration testing (if applicable) - [ ] Review compliance requirements #### Infrastructure Security - [ ] Audit GitHub organization settings - [ ] Review third-party integrations - [ ] Check for security updates - [ ] Verify backup and recovery procedures #### Team Security - [ ] Review team security training - [ ] Conduct security awareness sessions - [ ] Update security contact information - [ ] Review and update security responsibilities ## 📞 Emergency Contacts ### GitHub Security - Report security vulnerabilities: <https://github.com/security> - GitHub Support: <https://support.github.com> ### API Provider Security - OpenRouter Security: Contact through their support channels - Report API key compromise immediately ### Community Resources - GitHub Community: <https://github.com/community> - Security best practices documentation - Stack Overflow for technical issues ## 📚 Additional Resources - [GitHub Security Best Practices](https://docs.github.com/en/code-security) - [OpenRouter Security Documentation](https://openrouter.ai/docs/security) - [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/) - [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) ## 🔄 Security Updates This security documentation is regularly updated. Check for updates: - When updating the template - Monthly during security audits - After any security incidents - When new features are added --- **Remember: Security is everyone's responsibility. When in doubt, err on the side of caution.**