tractatus/SECURITY.md

# Security Policy

## Reporting Security Vulnerabilities

The Tractatus Framework takes security seriously. We appreciate your efforts to responsibly disclose your findings.

### Where to Report

**Please DO NOT report security vulnerabilities through public GitHub issues.**

Instead, please report security vulnerabilities by emailing:

**security@agenticgovernance.digital**

### What to Include

To help us better understand and resolve the issue, please include as much of the following information as possible:

- **Type of vulnerability** (e.g., SQL injection, cross-site scripting, authentication bypass)
- **Full paths of affected source files**
- **Location of the affected code** (tag/branch/commit or direct URL)
- **Step-by-step instructions to reproduce the issue**
- **Proof-of-concept or exploit code** (if applicable)
- **Impact of the vulnerability** (what an attacker could achieve)
- **Suggested mitigation** (if you have one)

### What to Expect

When you report a vulnerability, you can expect:

1. **Acknowledgment**: We will acknowledge receipt of your report within **48 hours**
2. **Assessment**: We will assess the vulnerability and determine its severity
3. **Updates**: We will keep you informed of our progress
4. **Resolution**: We will work to release a fix as quickly as possible
5. **Credit**: With your permission, we will credit you in the security advisory

### Disclosure Policy

- We request that you give us a reasonable amount of time to address the vulnerability before public disclosure
- We will keep you informed of our remediation timeline
- Once a fix is released, we will publish a security advisory crediting you (unless you prefer to remain anonymous)

### Supported Versions

We currently support the following versions with security updates:

| Version | Supported          |
| ------- | ------------------ |
| 3.5.x   | ✅ Yes             |
| < 3.5   | ❌ Not supported   |

Only the latest minor version receives security updates. We strongly recommend keeping your installation up to date.

## Security Best Practices for Implementers

If you're implementing the Tractatus Framework in your own project, we recommend:

### 1. Environment Security

- **Never commit `.env` files** to version control
- **Rotate secrets regularly** (JWT secrets, API keys, database credentials)
- **Use strong passwords** for MongoDB and admin accounts
- **Enable MongoDB authentication** in production
- **Use TLS/SSL** for all connections in production

### 2. Network Security

- **Use firewalls** to restrict access to MongoDB and application ports
- **Enable rate limiting** (already configured in the framework)
- **Use reverse proxy** (nginx/Apache) with HTTPS
- **Configure CORS** appropriately for your use case
- **Monitor failed authentication attempts**

### 3. Deployment Security

- **Run as non-root user** (framework defaults to this)
- **Use Docker secrets** for sensitive configuration
- **Keep dependencies updated** (`npm audit` regularly)
- **Enable security headers** (already configured)
- **Disable debug logs** in production

### 4. Database Security

- **Create read-only database users** for reporting
- **Enable MongoDB access control**
- **Backup encryption keys** securely
- **Regular security audits** of database access logs
- **Implement data retention policies**

### 5. API Security

- **Validate all input** (framework provides validation middleware)
- **Sanitize error responses** (already configured)
- **Use authentication** for all admin endpoints
- **Implement request signing** for critical operations
- **Monitor for unusual API patterns**

## Known Security Considerations

### MongoDB Connection

The framework uses MongoDB for persistence. Ensure your MongoDB instance:

- Has authentication enabled
- Is not exposed to the public internet
- Uses encrypted connections (TLS)
- Has appropriate network firewall rules
- Is regularly backed up

### Rate Limiting

The framework includes rate limiting middleware configured for:

- **Public endpoints**: 100 requests per 15 minutes per IP
- **Adjustable limits**: See `src/config/app.config.js`

Adjust these limits based on your expected traffic and security requirements.

### Session Management

The framework uses MongoDB to store session state. Ensure:

- Sessions have appropriate timeouts
- Session data is regularly cleaned up
- Sensitive data is not stored in sessions

### Input Validation

All API endpoints include input validation middleware. However:

- Additional validation may be needed for your specific use case
- Always validate data at multiple layers
- Never trust client-side validation alone

## Security Updates

We will publish security advisories for any vulnerabilities discovered in the framework:

- **GitHub Security Advisories**: https://github.com/AgenticGovernance/tractatus-framework/security/advisories
- **Mailing List**: Subscribe at https://agenticgovernance.digital for security notifications

## Compliance

The Tractatus Framework is designed with security best practices in mind:

- **OWASP Top 10**: Protections against common vulnerabilities
- **Input Validation**: All endpoints validate input
- **Output Encoding**: Responses are sanitized
- **Security Headers**: Helmet middleware with custom CSP
- **Error Handling**: No stack traces in production

## Security Audit History

| Date       | Type           | Findings | Status   |
|------------|----------------|----------|----------|
| 2025-10-21 | Internal Review| 0 Critical| Resolved |

We welcome third-party security audits. Please contact us if you're interested in conducting an audit.

## Contact

For security-related questions or concerns:

- **Email**: security@agenticgovernance.digital
- **Documentation**: https://agenticgovernance.digital
- **GitHub Issues**: For non-security bugs only

## Acknowledgments

We would like to thank the following individuals for responsibly disclosing security vulnerabilities:

*(None reported yet - this is the initial release)*

---

**Thank you for helping keep Tractatus Framework and our community safe!**