6.8 KiB
6.8 KiB
Security Policy
Supported Versions
| Version | Supported |
|---|---|
| 0.1.x | ✅ |
Security Principles
AegisGitea MCP is designed with security as the primary concern:
- Read-Only by Design: No write operations to Gitea
- Least Privilege: Bot user has minimal necessary permissions
- Explicit Access: No implicit or hidden data access
- Full Auditability: Every action is logged
- 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:
- Email: security@youromain.com (replace with your actual contact)
- Subject:
[SECURITY] AegisGitea MCP - Brief Description - 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
-
Token Management
- Use dedicated bot user (never personal accounts)
- Rotate tokens quarterly
- Store tokens in secrets manager
- Never commit tokens to version control
-
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
-
Access Control
- Review bot user permissions monthly
- Remove access from archived repositories
- Document which repositories are AI-visible
- Implement approval workflow for new access
-
Monitoring
- Review audit logs weekly
- Set up alerts for unusual access patterns
- Monitor for failed authentication attempts
- Track file access frequency
-
Updates
- Keep Docker images updated
- Monitor security advisories
- Test updates in staging first
- Maintain rollback capability
For Developers
-
Code Review
- All changes require peer review
- Security-critical changes require 2+ reviewers
- Automated tests must pass
-
Dependencies
- Pin dependency versions
- Review dependency licenses
- Monitor for security advisories
- Use tools like
pip-auditorsafety
-
Testing
- Write tests for authorization logic
- Test boundary conditions
- Include negative test cases
- Fuzz test inputs
Known Limitations
- Trust in Gitea: Authorization depends on Gitea's access control
- Token Security: Compromised token = compromised access until rotated
- Rate Limiting: Current implementation is per-server, not per-client
- 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)
-
Isolate: Stop the MCP container
docker-compose down -
Revoke: Delete bot user token in Gitea
- Go to Gitea > Settings > Applications
- Delete the token immediately
-
Preserve: Save audit logs for analysis
docker cp aegis-gitea-mcp:/var/log/aegis-mcp/audit.log ./incident-$(date +%Y%m%d-%H%M%S).log
Investigation (within 1 hour)
- Review audit logs for unauthorized access
- Check which repositories were accessed
- Identify timeframe of suspicious activity
- Document findings
Remediation (within 24 hours)
- Generate new bot user token
- Review and update bot user permissions
- Deploy updated configuration
- Monitor for continued suspicious activity
- Notify affected repository owners if necessary
Post-Incident (within 1 week)
- Conduct post-mortem analysis
- Update security procedures
- Implement additional safeguards
- Document lessons learned
- 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.