Security Policy

Supported Versions

Version	Supported
Latest	✅ Yes
< Latest	❌ No

We recommend always using the latest version.

Reporting a Vulnerability

Please do not report security vulnerabilities through public GitHub issues.

Reporting Process

Report vulnerabilities via GitHub’s private vulnerability reporting:

Go to the Security tab
Click “Report a vulnerability”
Fill in vulnerability details

What to Include

Type of vulnerability
Full paths of affected source files
Location of affected code (tag/branch/commit)
Step-by-step reproduction instructions
Proof-of-concept or exploit code (if possible)
Impact assessment

What to Expect

Acknowledgment within 48 hours
Regular updates on progress
Credit in security advisory (if desired)
Public disclosure timeline discussion

Security Best Practices

Credentials and Secrets

Never commit credentials
- Don’t commit config.json with real credentials
- Use .gitignore to exclude sensitive files
- Use secret management systems to generate config.json at deployment time
Restrict file permissions
```
chmod 600 config.json
chmod 700 store/
```
Rotate credentials regularly
- Change bot passwords periodically
- Regenerate API tokens regularly
- Update access tokens when needed

Encryption and Storage

Secure the store directory

chmod 700 store/
chown chatrixcd:chatrixcd store/

Backup encryption keys
- Regularly backup store/ directory
- Store backups securely
- Test restore procedures
Enable E2E encryption
- Use encrypted Matrix rooms when possible
- Verify device keys
- Handle key backups properly

Network Security

Use HTTPS only
- Always use HTTPS for Matrix homeserver
- Always use HTTPS for Semaphore API
- Verify SSL certificates
Network isolation
- Run bot in isolated network segment
- Use firewall rules
- Limit outbound connections
API security
- Use least-privilege API tokens
- Implement rate limiting (future)
- Monitor API usage

Access Control

Restrict bot access

bot:
  allowed_rooms:
    - "!secure-room:example.com"

Review permissions
- Audit room memberships
- Review bot capabilities
- Monitor command usage
User verification
- Verify users in sensitive rooms
- Use room encryption
- Implement user-based access control (future)

Security Features

Built-in Security

✅ E2E encryption support
✅ OIDC/OAuth2 authentication
✅ Secure token handling
✅ Access control mechanisms
✅ HTTPS-only endpoints

Audit Logging

The bot logs security-relevant events:

Authentication attempts
Command executions
Task operations
Configuration errors

Review logs regularly:

grep -i "auth" /var/log/chatrixcd.log
grep -i "error" /var/log/chatrixcd.log

Known Security Considerations

Matrix Protocol

Unencrypted rooms expose message content
Device verification required for E2E
Key backup security depends on passphrase

Semaphore Integration

API token has full Semaphore access
Tasks run with Semaphore user permissions
Task logs may contain sensitive data

Bot Deployment

Configuration files contain secrets
Store directory contains encryption keys
Process runs with configured user privileges

Security Updates

Security updates are released ASAP after vulnerability confirmation.

Update Notifications

Subscribe to:

GitHub Security Advisories
Repository notifications
Release notifications

Update Process

# Pull latest changes
git pull origin main

# Update dependencies
pip install -r requirements.txt --upgrade

# Restart bot
systemctl restart chatrixcd

Responsible Disclosure

We follow responsible disclosure practices:

Vulnerability reported privately
Issue confirmed and fixed
Security update released
Public disclosure with credit

We appreciate security researchers who:

Report issues privately
Allow time for fixes
Follow responsible disclosure

Security Checklist

Deployment Security

Development Security

Additional Resources

Contact

For security concerns:

Use GitHub Security Advisories
Contact repository maintainers
Do not use public issues

Thank you for helping keep ChatrixCD secure! 🔒