286 lines
6.8 KiB
Markdown
286 lines
6.8 KiB
Markdown
# 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.
|