This document outlines the security policies, threat model, and best practices for SingBox-Rust.

We provide security updates for the following versions:

• Cryptographic Keys: JWT signing keys, API keys, TLS certificates
• User Data: Routing information, DNS queries, connection metadata
• System Resources: Memory, file descriptors, network connections
• Configuration: Authentication settings, routing rules, upstream endpoints

• External Attackers: Attempting to intercept or manipulate traffic
• Insider Threats: Users with access to configuration or logs
• Supply Chain Attacks: Compromised dependencies or build tools
• Local System Compromise: Unauthorized access to the host system

• Network-based attacks (MITM, traffic analysis)
• Configuration injection and privilege escalation
• Memory corruption and resource exhaustion
• Credential theft from logs or memory dumps
• Dependency vulnerabilities and supply chain compromise

SingBox-Rust supports secure key loading through multiple sources, in order of security preference:

1. Environment Variables (Recommended for production)

   [auth.jwt]
   source = "env"
   name = "JWT_SIGNING_KEY"

2. File-based Keys (Secure for containerized deployments)

   [auth.jwt]
   source = "file"
   path = "/run/secrets/jwt_key"

3. Inline Configuration (⚠️ NOT recommended for production)

   [auth.jwt]
   source = "inline"
   value = "your-secret-here"  # Only for development/testing

• Key files MUST have restrictive permissions (0600 or similar)
• Key files MUST NOT be world-readable or group-readable
• The application will reject keys with insecure file permissions

• Use dedicated secret management systems (Kubernetes Secrets, HashiCorp Vault, etc.)
• Avoid setting secrets in shell history or process environment
• Rotate keys regularly (recommended: every 90 days)

• JWT keys support RS256, ES256, and HS256 algorithms
• RSA keys must be at least 2048 bits
• ECDSA keys must use P-256 curve or stronger
• All keys are validated during loading

1. Generate New Key

   # For RSA keys
   openssl genpkey -algorithm RSA -out new_key.pem -pkcs8 -aes256
   
   # For ECDSA keys
   openssl genpkey -algorithm EC -out new_key.pem -pkcs8 -aes256 \
     -pkeyopt ec_paramgen_curve:P-256

2. Update Configuration

   • Add new key to JWKS endpoint or configuration
   • Update key ID references in configuration
   • Deploy configuration changes

3. Rotate Keys

   • Keep old key active for grace period (24-48 hours)
   • Monitor for authentication errors
   • Remove old key after grace period

SingBox-Rust includes built-in credential redaction to prevent sensitive information from appearing in logs:

use sb_security::{redact_token, redact_key, redact_credential};

// Tokens show first 4 and last 4 characters
let token = "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.payload.signature";
info!("Auth token: {}", redact_token(token));
// Logs: "Auth token: Bear********ture"

// Keys show only type and length
let key = "-----BEGIN RSA PRIVATE KEY-----\nMIIE...";
info!("Loaded key: {}", redact_key(key));
// Logs: "Loaded key: RSA-[KEY:1234]"

// Credentials are heavily redacted
let password = "super_secret_password";
info!("Credential: {}", redact_credential(password));
// Logs: "Credential: su**********"

• Never log: Raw secrets, private keys, passwords, JWT tokens
• Always redact: Authorization headers, API keys, user credentials
• Log safely: Redacted versions, metadata (length, type), error context

• Store logs in secure, access-controlled locations
• Implement log retention policies (recommend: 30-90 days)
• Use encrypted storage for log archives
• Monitor log access and implement audit trails

We use cargo-deny to enforce security policies:

# Check for known vulnerabilities
cargo deny check advisories

# Verify license compliance
cargo deny check licenses

# Detect supply chain issues
cargo deny check bans

• Vulnerabilities: All HIGH and CRITICAL severity vulnerabilities are blocked
• Unmaintained Crates: Unmaintained dependencies are blocked in production
• License Compliance: Only approved licenses (MIT, Apache-2.0, BSD variants)
• Multiple Versions: Flagged for review to reduce attack surface

• MIT
• Apache-2.0
• BSD-3-Clause
• BSD-2-Clause
• ISC
• Unicode-DFS-2016

• Secure Allocation: Sensitive data uses zeroize for automatic cleanup
• Constant-Time Operations: Cryptographic comparisons use subtle crate
• Bounds Checking: All array/slice access is bounds-checked
• No unsafe Code: Forbidden except in vetted dependencies

# Example configuration limits
[security]
max_connections = 10000
max_memory_mb = 512
max_file_descriptors = 1024
request_timeout_seconds = 30

• TLS 1.2+ required for all encrypted connections
• Certificate validation enforced by default
• Support for custom CA bundles and certificate pinning
• Rate limiting on admin endpoints

For security vulnerabilities, please email: security@singbox.example.com

DO NOT file public GitHub issues for security vulnerabilities.

• Acknowledgment: Within 24 hours
• Initial Assessment: Within 72 hours
• Fix Development: Based on severity (Critical: 7 days, High: 14 days)
• Public Disclosure: 90 days after fix release (coordinated disclosure)

• Critical: Remote code execution, authentication bypass
• High: Privilege escalation, data exposure
• Medium: Information disclosure, denial of service
• Low: Configuration issues, non-security bugs

1. Immediate Actions

   • Rotate all cryptographic keys
   • Check logs for suspicious activity
   • Isolate affected systems

2. Assessment

   • Determine scope of potential compromise
   • Identify affected secrets and keys
   • Review access logs and network traffic

3. Recovery

   • Generate new secrets and keys
   • Update all dependent systems
   • Monitor for continued suspicious activity

4. Reporting

   • Document incident timeline
   • Report to security team
   • Update security procedures if needed

# 1. Generate new keys immediately
openssl genpkey -algorithm RSA -out emergency_key.pem -pkcs8 -aes256

# 2. Update JWKS endpoint
curl -X POST https://your-jwks-endpoint/rotate \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emergency_rotation": true}'

# 3. Revoke compromised keys
curl -X DELETE https://your-jwks-endpoint/keys/$COMPROMISED_KEY_ID \
  -H "Authorization: Bearer $ADMIN_TOKEN"

• All security-sensitive code requires peer review
• Cryptographic implementations require expert review
• External security audits recommended annually

# Run security-focused tests
cargo test --features security-tests

# Check for vulnerabilities
cargo audit

# Verify secure compilation
cargo deny check

# Test with sanitizers
RUSTFLAGS="-Z sanitizer=address" cargo test

• Monitor authentication failures and rate limiting
• Alert on suspicious configuration changes
• Track key rotation and expiration events
• Log all administrative actions

• Follows OWASP Application Security Guidelines
• Implements NIST Cybersecurity Framework principles
• Compliant with modern TLS best practices

• Authentication: Multi-factor support, key-based auth
• Authorization: Role-based access control, principle of least privilege
• Encryption: TLS 1.2+, strong cipher suites
• Integrity: Configuration validation, secure defaults
• Availability: Rate limiting, resource controls

• Use environment variables or secure files for secrets
• Verify file permissions on key files (0600)
• Enable TLS for all network connections
• Configure appropriate rate limits
• Set up log monitoring and alerting
• Run cargo deny check before deployment
• Implement key rotation procedures
• Test incident response procedures

• Disable inline secrets in production
• Use strong, randomly generated keys
• Configure appropriate session timeouts
• Enable request ID tracking
• Set conservative resource limits
• Validate all external dependencies

• Regular security updates
• Monitor for security advisories
• Backup and test key recovery procedures
• Conduct regular security reviews
• Train team on security procedures
• Maintain incident response documentation

Last updated: 2025-09-28 Next review: 2025-12-28