pyIRCX has been designed with security as a priority. This document outlines security features, known considerations, and recommendations for secure deployment.

Overall Security Rating: PRODUCTION-READY ✅

1. Password Security

• ✅ bcrypt password hashing (industry standard)
• ✅ Configurable work factor (default: 12 rounds)
• ✅ Non-blocking bcrypt operations (prevents DoS)
• ✅ No plaintext password storage
• ✅ Salted hashes (automatic with bcrypt)

2. SQL Injection Protection

• ✅ 100% parameterized queries - All database operations use parameter binding
• ✅ No string concatenation in SQL
• ✅ No f-strings or .format() in queries
• ✅ Async SQLite with proper escaping

Example (Safe):

await db.execute("SELECT * FROM users WHERE username = ?", (username,))

3. Command Injection Protection

• ✅ No shell command execution (except one safe OpenSSL cert check)
• ✅ No eval() or exec() usage
• ✅ No user input passed to subprocess
• ✅ All system operations use safe Python APIs

4. Authentication Security

• ✅ SASL PLAIN authentication support
• ✅ Two-factor authentication (TOTP)
• ✅ Email verification for account recovery
• ✅ Backup codes for MFA recovery
• ✅ Failed authentication tracking with IP lockout
• ✅ Rate limiting on authentication attempts

5. Network Security

• ✅ SSL/TLS support (TLSv1.2+ minimum)
• ✅ IPv4 and IPv6 support
• ✅ DNSBL integration for spam prevention
• ✅ Connection throttling per IP
• ✅ Configurable flood protection
• ✅ Input validation on all protocol commands

6. Access Control

• ✅ Three-tier staff hierarchy (ADMIN/SYSOP/GUIDE)
• ✅ Channel access lists (OWNER/HOST/VOICE/GRANT/DENY)
• ✅ Server-wide ban/gline support
• ✅ Temporary access entries with timeout
• ✅ Permission checks on all privileged operations

7. Input Validation

• ✅ Nickname validation (length, character set)
• ✅ Channel name validation
• ✅ Command parameter validation
• ✅ Message length limits (512 bytes per RFC)
• ✅ Flood detection and throttling

Risk Level: HIGH (if not changed)

Issue:

• Default admin account: admin / changeme
• Default staff accounts with known passwords

Mitigation:

• ✅ Clearly documented in all installation guides
• ✅ WARNING displayed during install
• ✅ Documented in STAFF_ACCOUNT_REFERENCE.md
• ✅ cleanup_users.py script provided

Recommendation:

# IMMEDIATELY after installation:
/STAFF LOGIN admin changeme
/STAFF PASS <strong-new-password>

# Or use cleanup script:
python3 cleanup_users.py

Risk Level: MEDIUM

Considerations:

• Runs on port 9090 (HTTPS)
• Requires system authentication (PAM)
• Uses PolicyKit for privilege escalation
• API exposes read-only database queries

Mitigation:

• ✅ No passwords exposed in API
• ✅ Read-only database access
• ✅ System-level authentication required
• ✅ HTTPS by default
• ✅ Optional installation (not required)

Recommendation:

• Use firewall to restrict port 9090 access
• Keep Cockpit updated
• Use strong system passwords

Risk Level: MEDIUM

Current State:

• Password-based server authentication
• Plaintext password in config (but transmitted over TCP)

Considerations:

• Server passwords stored in pyircx_config.json
• Link passwords transmitted during handshake

Mitigation:

• ✅ Passwords in config file (restricted permissions)
• ⚠️ No TLS for server-to-server links (planned)

Recommendation:

• Use strong link passwords (32+ characters)
• Restrict file permissions: chmod 600 pyircx_config.json
• Use private networks/VPN for server links
• Consider adding TLS support for S2S (future enhancement)

Risk Level: LOW-MEDIUM

Protection Mechanisms:

• ✅ Connection throttling per IP
• ✅ Flood detection (messages/second)
• ✅ Rate limiting on authentication
• ✅ Maximum connections per IP
• ✅ Message length limits
• ✅ DNSBL integration

Potential Vectors:

• ⚠️ CPU exhaustion via bcrypt (mitigated by async execution)
• ⚠️ Memory exhaustion via many connections (OS limits apply)
• ⚠️ Network bandwidth saturation

Recommendation:

• Use reverse proxy (nginx) for DDoS protection
• Configure iptables rate limiting
• Monitor resource usage
• Set ulimit for max connections

Risk Level: LOW

Protected Information:

• ✅ Password hashes never transmitted
• ✅ Email addresses only visible to account owner
• ✅ MFA secrets never exposed
• ✅ Server config not accessible to users

Disclosed Information:

• ℹ️ Server version (VERSION command)
• ℹ️ Server uptime (STATS command)
• ℹ️ User counts and nicknames
• ℹ️ Channel names and topics

Recommendation:

• Normal IRC behavior
• No sensitive data exposed
• Consider hiding version from non-staff

SQL Injection: NONE FOUND

• All queries use parameterized statements
• No string concatenation in SQL
• No .format() or f-strings in queries

Command Injection: NONE FOUND

• No user input to subprocess
• No eval/exec usage
• Safe subprocess use for OpenSSL only

XSS (Web Admin): LOW RISK

• Read-only API
• No user-generated content rendered
• Uses Cockpit framework (maintained by Red Hat)

Path Traversal: NONE FOUND

• No file operations based on user input
• Database path from config only
• Log paths from config only

Authentication Bypass: NONE FOUND

• Proper permission checks on all commands
• SASL implementation follows RFC
• Staff authentication requires valid credentials

Before Production:

• Change all default passwords
• Review and customize pyircx_config.json
• Set restrictive file permissions (600 for config, 644 for code)
• Enable SSL/TLS for client connections
• Configure DNSBL servers
• Set up firewall rules (allow only 6667, 6697, optionally 9090)
• Enable fail2ban or similar for brute force protection
• Review staff accounts (delete test accounts)
• Set up log monitoring/alerting

Network Security:

• Use firewall to restrict administrative access
• Consider VPN for server linking
• Rate limit connections at network level
• Use reverse proxy for DDoS protection
• Enable IPv6 privacy extensions if using IPv6

Ongoing Maintenance:

• Monitor logs for suspicious activity
• Regularly review staff accounts
• Audit channel access lists
• Update server and dependencies
• Backup database regularly
• Test disaster recovery procedures

# Configuration (contains passwords)
chmod 600 pyircx_config.json
chown pyircx:pyircx pyircx_config.json

# Database
chmod 600 pyircx.db
chown pyircx:pyircx pyircx.db

# Code (read-only)
chmod 644 pyircx.py
chown root:root pyircx.py

# Service file
chmod 644 /etc/systemd/system/pyircx.service
chown root:root /etc/systemd/system/pyircx.service

Recommended Settings:

{
  "ssl": {
    "enabled": true,
    "cert_file": "/etc/letsencrypt/live/irc.example.com/fullchain.pem",
    "key_file": "/etc/letsencrypt/live/irc.example.com/privkey.pem",
    "port": 6697,
    "min_version": "TLSv1.2"
  }
}

Certificate Management:

# Let's Encrypt with auto-renewal
certbot certonly --standalone -d irc.example.com
systemctl enable certbot-renew.timer

# Add pyircx user to ssl-cert group
usermod -a -G ssl-cert pyircx

# Auto-reload certs (in cron)
0 3 * * * systemctl reload pyircx

1. Immediate Actions:

   # Stop the server
   systemctl stop pyircx
   
   # Backup current state
   tar czf pyircx-incident-$(date +%Y%m%d).tar.gz \
     /opt/pyircx/ /var/log/pyircx.log
   
   # Review logs
   journalctl -u pyircx -n 1000 > incident-logs.txt

2. Investigation:

   • Review authentication logs
   • Check for unauthorized staff accounts
   • Examine database for anomalies
   • Review network connections
   • Check file integrity

3. Recovery:

   • Reset all staff passwords
   • Audit and clean database
   • Update software if vulnerability found
   • Review and update firewall rules
   • Restore from backup if necessary

If you discover a security vulnerability:

1. DO NOT open a public GitHub issue
2. Email security concerns to: [Insert contact email]
3. Include:
   • Description of vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if available)

User Data Stored:

• Usernames and password hashes
• Email addresses (optional)
• IP addresses (for DNSBL checks)
• Connection metadata (timestamps)
• Chat transcripts (if enabled per channel)

Compliance Notes:

• Password hashes are irreversible
• Email addresses can be deleted
• IP addresses are not permanently stored
• Transcripts are optional per channel
• Users can request account deletion

GDPR Considerations:

• Right to access: Users can view their data via commands
• Right to deletion: CHGPASS DROP command deletes accounts
• Data minimization: Only essential data stored
• Purpose limitation: Data used only for service operation

{
  "logging": {
    "level": "INFO",
    "failed_auth_tracking": true,
    "log_commands": false,
    "log_privmsg": false
  }
}

Watch for suspicious patterns:

# Failed authentication attempts
grep "Auth failed" /var/log/pyircx.log

# STAFF commands (for audit)
grep "STAFF" /var/log/pyircx.log

# Flood events
grep "Flood" /var/log/pyircx.log

# Connection spikes
grep "Connection from" /var/log/pyircx.log | \
  awk '{print $1}' | uniq -c | sort -rn

# fail2ban integration
cat > /etc/fail2ban/filter.d/pyircx.conf <<EOF
[Definition]
failregex = ^.*Auth failed for user .* from <HOST>
            ^.*Flood detected from <HOST>
ignoreregex =
EOF

# Create jail
cat > /etc/fail2ban/jail.d/pyircx.conf <<EOF
[pyircx]
enabled = true
port = 6667,6697
logpath = /var/log/pyircx.log
maxretry = 5
bantime = 3600
EOF

pyIRCX v1.0.3 is production-ready with strong security foundations:

✅ No known vulnerabilities ✅ Industry-standard security practices ✅ Comprehensive protection mechanisms ✅ Channel mode security - Fixed +r mode protection ⚠️ Requires proper deployment configuration ⚠️ Default passwords must be changed

With proper deployment and maintenance, pyIRCX provides a secure platform for IRC/IRCX services.

Document Version: 1.0.4 Last Updated: 2026-01-02 Next Review: 2026-06-01