# 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.