.

SECURITY.md

@@ -0,0 +1,285 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+---
+
+## Security Principles
+
+AegisGitea MCP is designed with security as the primary concern:
+
+1. **Read-Only by Design**: No write operations to Gitea
+2. **Least Privilege**: Bot user has minimal necessary permissions
+3. **Explicit Access**: No implicit or hidden data access
+4. **Full Auditability**: Every action is logged
+5. **Fail-Safe**: Errors deny access rather than grant it
+
+---
+
+## Threat Model
+
+### In Scope
+
+- Unauthorized access to repositories
+- Token compromise and misuse
+- Data exfiltration via MCP tools
+- Denial of service attacks
+- API abuse and rate limiting bypass
+
+### Out of Scope
+
+- Physical access to server
+- Social engineering attacks
+- Compromise of Gitea instance itself
+- ChatGPT platform security
+
+---
+
+## Security Features
+
+### 1. Authorization
+
+- **Dynamic**: Permissions managed in Gitea, not MCP server
+- **Explicit**: Bot user must be added to each repository
+- **Reversible**: Removing bot user immediately revokes access
+
+### 2. Authentication
+
+- Token-based authentication with Gitea
+- No password storage
+- Tokens should be rotated regularly
+
+### 3. Audit Logging
+
+Every tool invocation logs:
+- Timestamp (UTC)
+- Tool name
+- Repository accessed
+- Target file/path
+- Request correlation ID
+- Success/failure status
+
+Logs are append-only and tamper-evident.
+
+### 4. Input Validation
+
+- File size limits enforced
+- Path traversal protection
+- Request timeout limits
+- Rate limiting per minute
+
+### 5. Container Security
+
+- Runs as non-root user
+- No unnecessary privileges
+- Resource limits enforced
+- Read-only filesystem where possible
+
+---
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead:
+
+1. **Email**: security@youromain.com (replace with your actual contact)
+2. **Subject**: `[SECURITY] AegisGitea MCP - Brief Description`
+3. **Include**:
+   - Description of vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+### Response Timeline
+
+- **24 hours**: Acknowledgment of report
+- **7 days**: Initial assessment and severity rating
+- **30 days**: Fix developed and tested
+- **45 days**: Public disclosure (if applicable)
+
+---
+
+## Security Best Practices
+
+### For Operators
+
+1. **Token Management**
+   - Use dedicated bot user (never personal accounts)
+   - Rotate tokens quarterly
+   - Store tokens in secrets manager
+   - Never commit tokens to version control
+
+2. **Network Security**
+   - Always use HTTPS with valid TLS certificates
+   - Never expose MCP server directly to internet
+   - Use reverse proxy for TLS termination
+   - Consider VPN or IP allowlisting
+
+3. **Access Control**
+   - Review bot user permissions monthly
+   - Remove access from archived repositories
+   - Document which repositories are AI-visible
+   - Implement approval workflow for new access
+
+4. **Monitoring**
+   - Review audit logs weekly
+   - Set up alerts for unusual access patterns
+   - Monitor for failed authentication attempts
+   - Track file access frequency
+
+5. **Updates**
+   - Keep Docker images updated
+   - Monitor security advisories
+   - Test updates in staging first
+   - Maintain rollback capability
+
+### For Developers
+
+1. **Code Review**
+   - All changes require peer review
+   - Security-critical changes require 2+ reviewers
+   - Automated tests must pass
+
+2. **Dependencies**
+   - Pin dependency versions
+   - Review dependency licenses
+   - Monitor for security advisories
+   - Use tools like `pip-audit` or `safety`
+
+3. **Testing**
+   - Write tests for authorization logic
+   - Test boundary conditions
+   - Include negative test cases
+   - Fuzz test inputs
+
+---
+
+## Known Limitations
+
+1. **Trust in Gitea**: Authorization depends on Gitea's access control
+2. **Token Security**: Compromised token = compromised access until rotated
+3. **Rate Limiting**: Current implementation is per-server, not per-client
+4. **Audit Log Size**: Logs grow unbounded (implement rotation)
+
+---
+
+## Security Checklist
+
+Before deploying to production:
+
+- [ ] Bot user created with minimal permissions
+- [ ] Access token generated with read-only scope
+- [ ] TLS configured with valid certificate
+- [ ] Reverse proxy properly configured
+- [ ] Audit logging enabled and tested
+- [ ] Resource limits set in Docker
+- [ ] Firewall rules configured
+- [ ] Monitoring and alerting set up
+- [ ] Incident response plan documented
+- [ ] Team trained on security procedures
+
+---
+
+## Incident Response
+
+If you suspect a security breach:
+
+### Immediate Actions (within 5 minutes)
+
+1. **Isolate**: Stop the MCP container
+   ```bash
+   docker-compose down
+   ```
+
+2. **Revoke**: Delete bot user token in Gitea
+   - Go to Gitea > Settings > Applications
+   - Delete the token immediately
+
+3. **Preserve**: Save audit logs for analysis
+   ```bash
+   docker cp aegis-gitea-mcp:/var/log/aegis-mcp/audit.log ./incident-$(date +%Y%m%d-%H%M%S).log
+   ```
+
+### Investigation (within 1 hour)
+
+1. Review audit logs for unauthorized access
+2. Check which repositories were accessed
+3. Identify timeframe of suspicious activity
+4. Document findings
+
+### Remediation (within 24 hours)
+
+1. Generate new bot user token
+2. Review and update bot user permissions
+3. Deploy updated configuration
+4. Monitor for continued suspicious activity
+5. Notify affected repository owners if necessary
+
+### Post-Incident (within 1 week)
+
+1. Conduct post-mortem analysis
+2. Update security procedures
+3. Implement additional safeguards
+4. Document lessons learned
+5. Train team on new procedures
+
+---
+
+## Compliance Considerations
+
+### GDPR
+
+- Audit logs may contain personal data (usernames, timestamps)
+- Implement log retention policy (recommend 90 days)
+- Provide mechanism for data deletion requests
+
+### SOC 2
+
+- Audit logging satisfies monitoring requirements
+- Access control model supports least privilege
+- Incident response procedures documented
+
+### Internal Policies
+
+- Adapt security practices to your organization's policies
+- Document any deviations from standard procedures
+- Obtain necessary approvals before deployment
+
+---
+
+## Security Roadmap
+
+Future security enhancements (not yet implemented):
+
+- [ ] Multi-factor authentication for bot token generation
+- [ ] Per-client rate limiting (not just per-server)
+- [ ] Automated audit log analysis and anomaly detection
+- [ ] Integration with SIEM systems
+- [ ] Encrypted audit logs
+- [ ] Support for multiple bot users with different permissions
+- [ ] OAuth2 flow instead of static tokens
+- [ ] Content scanning for sensitive data patterns
+
+---
+
+## Acknowledgments
+
+Security vulnerabilities responsibly disclosed by:
+
+- (None yet - be the first!)
+
+---
+
+## Contact
+
+Security Team: security@yourdomain.com
+General Support: issues in Gitea repository
+
+---
+
+**Remember**: Security is a process, not a product. Stay vigilant.