# Security Policy

## Supported Versions

We actively support the following versions of Codomyrmex with security updates (current release: **v1.2.7** — see [pyproject.toml](pyproject.toml) and [CHANGELOG.md](CHANGELOG.md)):

| Version | Supported          |
| ------- | ------------------ |
| 1.2.x   | :white_check_mark: |
| 1.1.x   | :white_check_mark: (best-effort) |
| < 1.1   | :x:                |

## Reporting a Vulnerability

We take the security of Codomyrmex seriously. If you discover a security vulnerability, please report it responsibly by following these steps:

### 🔒 Private Disclosure Process

1. **Do NOT create a public GitHub issue** for security vulnerabilities
2. Email security details to: `danielarifriedman@gmail.com` (or create a private GitHub security advisory)
3. Include the following information:
   - Description of the vulnerability
   - Steps to reproduce the issue
   - Potential impact assessment
   - Any suggested fixes (optional)

### 📝 What to Include

- **Vulnerability Description**: Clear explanation of the security issue
- **Reproduction Steps**: Detailed steps to reproduce the vulnerability
- **Impact Assessment**: What systems or data could be affected
- **Environment Details**: Operating system, Python version, Codomyrmex version
- **Proof of Concept**: Safe demonstration code (if applicable)

### ⏱️ Response Timeline

- **Initial Response**: Within 48 hours of report
- **Confirmation**: Within 5 business days
- **Fix Timeline**: Critical vulnerabilities within 30 days, others within 90 days
- **Public Disclosure**: After fix is available and deployed

## Security Considerations by Module

### 🔐 High-Security Modules

#### **coding** (code execution sandbox)

- Executes untrusted code in isolated environments
- **Risk**: Code injection, container escape, resource exhaustion
- **Mitigation**: Docker isolation, resource limits, network restrictions
- [Module Security Details](src/codomyrmex/coding/SECURITY.md)

#### **ai_code_editing**  

- Processes external AI API responses
- **Risk**: Prompt injection, malicious code generation
- **Mitigation**: Input sanitization, output validation, API key protection
- [Module Security Details](src/codomyrmex/agents/ai_code_editing/SECURITY.md)

#### **git_operations**

- Interacts with version control systems
- **Risk**: Command injection, unauthorized repository access
- **Mitigation**: Input validation, safe command construction
- [Module Security Details](src/codomyrmex/git_operations/SECURITY.md)

### 🛡️ Security Best Practices

#### **API Key Management**

- Store API keys in environment variables or `.env` files
- Never commit API keys to version control
- Use least-privilege access for service accounts
- Regularly rotate API keys

#### **Input Validation**

- All user inputs are validated and sanitized
- File paths are validated to prevent directory traversal
- Code execution is sandboxed and resource-limited

#### **Network Security**

- External API calls use HTTPS
- Code execution sandbox has restricted network access
- No unnecessary network services exposed

#### **Dependency Security**

- Regular dependency updates and vulnerability scanning
- Pin specific versions to avoid supply chain attacks
- Use `pip-audit` and `safety` for vulnerability detection

## Threat Model

### 🎯 Attack Vectors

1. **Code Injection**
   - **Target**: Code execution sandbox, AI code generation
   - **Mitigation**: Sandboxing, input validation, output sanitization

2. **API Abuse**
   - **Target**: AI services, external integrations  
   - **Mitigation**: Rate limiting, authentication, input validation

3. **File System Access**
   - **Target**: File operations, path traversal
   - **Mitigation**: Path validation, restricted file access

4. **Resource Exhaustion**
   - **Target**: Long-running operations, large data processing
   - **Mitigation**: Timeouts, memory limits, process restrictions

### 🔍 Security Controls

- **Authentication**: API key validation for external services
- **Authorization**: Least-privilege access patterns
- **Input Validation**: Comprehensive input sanitization  
- **Output Encoding**: Safe handling of generated content
- **Error Handling**: Secure error messages without information disclosure
- **Logging**: Security event logging without sensitive data exposure

## Security Testing

### 🧪 Automated Security Testing

```bash
# Run security linters
bandit -r src/codomyrmex/

# Check for known vulnerabilities
pip-audit

# Dependency vulnerability scanning
safety check

# Static analysis security rules
pylint --load-plugins=pylint_security src/codomyrmex/
```

### 🔍 Manual Security Testing

- Regular code reviews focusing on security
- Penetration testing of code execution sandbox
- API security testing for external integrations
- Input validation testing with malicious payloads

## Incident Response

In case of a confirmed security incident:

1. **Immediate Response**: Contain the threat and assess scope
2. **Investigation**: Determine root cause and affected systems  
3. **Remediation**: Implement fixes and deploy patches
4. **Communication**: Notify affected users and stakeholders
5. **Post-Incident**: Conduct post-mortem and improve security measures

## Security Updates

Security updates are distributed through:

- **GitHub Releases**: Tagged releases with security fixes
- **Security Advisories**: GitHub security advisories for critical issues
- **Documentation**: Updated security guidance and best practices
- **Dependency Updates**: Regular dependency updates with security fixes

## Compliance and Standards

Codomyrmex follows these security standards and practices:

- **OWASP Top 10**: Addressing common web application security risks
- **CWE/SANS Top 25**: Mitigating most dangerous software weaknesses  
- **NIST Cybersecurity Framework**: Identify, Protect, Detect, Respond, Recover
- **Secure Development Lifecycle**: Security integrated throughout development

## Contact

For security-related questions or concerns:

- **Security Email**: `danielarifriedman@gmail.com` (private disclosure)
- **Security Advisories**: [GitHub Security Advisories](https://github.com/docxology/codomyrmex/security/advisories)
- **General Issues**: [GitHub Issues](https://github.com/docxology/codomyrmex/issues) (for non-security issues only)

## Related Documentation

- **[Production Deployment Guide](docs/deployment/production.md)** - Production security and deployment practices
- **[Contributing Guide](docs/project/contributing.md)** - Security considerations for contributions
- **[Module Security Details](src/codomyrmex/coding/SECURITY.md)** - Code execution sandbox security
- **[AI Security Details](src/codomyrmex/agents/ai_code_editing/SECURITY.md)** - AI integration security considerations
- **[Git Operations Security](src/codomyrmex/git_operations/SECURITY.md)** - Version control security
- **[PAI Trust Gateway](src/codomyrmex/agents/pai/trust_gateway.py)** - Three-tier (UNTRUSTED / VERIFIED / TRUSTED) gate for destructive MCP tools; see [PAI.md](PAI.md#trust-model)

---

**Last Updated**: Auto-generated from security review
**Version**: 1.0
**Scope**: All Codomyrmex modules and components

## Navigation Links

- **Documentation**: [Reference Guides](docs/README.md)
- **All Agents**: [AGENTS.md](AGENTS.md)
- **Functional Spec**: [SPEC.md](SPEC.md)
- **Home**: [README.md](README.md)
