Security Reference

This document describes Torc's security features, threat model, and best practices for secure deployments.

Authentication & Authorization

HTTP Basic Authentication

Torc uses HTTP Basic authentication with bcrypt password hashing.

Security Properties:

• ✅ Industry-standard authentication method
• ✅ Bcrypt hashing with configurable work factor (cost 4-31)
• ✅ No plaintext password storage
• ✅ Salt automatically generated per password
• ⚠️ Credentials sent base64-encoded (requires HTTPS)

Architecture:

Client Request
    ↓
[Authorization: Basic base64(username:password)]
    ↓
Server Middleware
    ↓
Extract credentials → Verify against htpasswd file (bcrypt)
    ↓
Success: Add username to request context
Failure: Return None authorization (logged)
    ↓
API Handler (receives authorization context)

Authentication Modes

Recommendation: Use Required mode in production.

Transport Security

HTTPS/TLS

When to use HTTPS:

• ✅ Always when authentication is enabled
• ✅ When transmitting sensitive workflow data
• ✅ Over untrusted networks (internet, shared networks)
• ✅ Compliance requirements (PCI-DSS, HIPAA, etc.)

Configuration:

# Server
torc-server run --https --auth-file /etc/torc/htpasswd

# Client
torc --url https://torc.example.com/torc-service/v1 workflows list

TLS Version: Torc uses the system's OpenSSL/native-tls library. Ensure:

• TLS 1.2 minimum (TLS 1.3 preferred)
• Strong cipher suites enabled
• Valid certificates from trusted CA

Network Security

Deployment Patterns:

Pattern 1: Internal Network Only

[Torc Clients] ←→ [Torc Server]
    (Trusted internal network)

• May use HTTP if network is truly isolated
• Still recommend HTTPS for defense in depth

Pattern 2: Load Balancer with TLS Termination

[Torc Clients] ←HTTPS→ [Load Balancer] ←HTTP→ [Torc Server]
    (Internet)              (Internal trusted network)

• TLS terminates at load balancer
• Internal traffic may use HTTP
• Ensure load balancer validates certificates

Pattern 3: End-to-End TLS

[Torc Clients] ←HTTPS→ [Torc Server]
    (Internet or untrusted network)

• Most secure pattern
• TLS all the way to Torc server
• Required for compliance scenarios

Internal Network Quick Setup

For internal, trusted networks where the primary goal is preventing accidental access rather than defending against malicious attacks, use this optimized configuration:

# 1. Create htpasswd with lower cost factor (faster auth)
torc-htpasswd add --cost 8 /etc/torc/htpasswd alice
torc-htpasswd add --cost 8 /etc/torc/htpasswd bob

# 2. Run server with auth and access control
torc-server run \
  --auth-file /etc/torc/htpasswd \
  --require-auth \
  --enforce-access-control \
  --credential-cache-ttl-secs 60

This provides:

• User isolation (users only see their own workflows)
• Fast CLI response (~10ms first auth, <1ms cached)
• Protection against accidental modifications
• Simple username/password authentication

For higher security requirements (internet-facing, compliance, sensitive data), use the default cost factor (12) and HTTPS.

Credential Management

Password Requirements

Recommendations:

• Minimum 12 characters
• Mix of uppercase, lowercase, numbers, symbols
• No dictionary words or common patterns
• Unique per user and environment

Bcrypt Cost Factor:

Cost Selection Criteria:

• Higher cost = more CPU, slower login
• Balance security vs. user experience
• Consider attack surface (internet-facing vs. internal)
• For internal networks with trusted users, cost 8 provides reasonable security with fast response

Creating passwords with a specific cost:

# Default cost (12) - good for most deployments
torc-htpasswd add /etc/torc/htpasswd alice

# Lower cost (8) - faster, suitable for internal networks
torc-htpasswd add --cost 8 /etc/torc/htpasswd alice

# Higher cost (14) - slower, for high-security environments
torc-htpasswd add --cost 14 /etc/torc/htpasswd alice

Credential Caching

To improve CLI responsiveness, the server caches successful authentications for a configurable duration (default: 60 seconds). This avoids repeated bcrypt verification for the same credentials.

Configuration:

# CLI option
torc-server run --credential-cache-ttl-secs 60

# Environment variable
export TORC_CREDENTIAL_CACHE_TTL_SECS=60

# Config file (torc.toml)
[server]
credential_cache_ttl_secs = 60

Performance impact:

Security notes:

• Passwords are never stored in plaintext in the cache
• Cache keys are SHA-256 hashes of credentials
• Cache entries auto-expire after TTL
• Failed authentications are never cached
• Set --credential-cache-ttl-secs 0 to disable caching

Htpasswd File Security

File Permissions:

# Restrict to server process owner only
chmod 600 /etc/torc/htpasswd
chown torc-server:torc-server /etc/torc/htpasswd

Storage Best Practices:

• ❌ Never commit to version control
• ❌ Never share between environments
• ✅ Store in secure configuration management (Ansible Vault, HashiCorp Vault)
• ✅ Backup with encryption
• ✅ Rotate regularly (quarterly recommended)

File Format Security:

# Comments allowed
username:$2b$12$hash...

• Only bcrypt hashes accepted ($2a$, $2b$, or $2y$)
• No plaintext passwords
• No MD5, SHA-1, or weak hashes

Client Credential Storage

Best Practices:

Examples:

# Good: Environment variables
read -s TORC_PASSWORD && export TORC_PASSWORD
torc workflows list

# Good: Password prompt
torc alice workflows list
Password: ****

# Acceptable: CI/CD with secrets
TORC_PASSWORD=${{ secrets.TORC_PASSWORD }} torc workflows create

# Bad: Command-line argument (visible in `ps`)
torc --password mypassword workflows list

Threat Model

Threats Mitigated

Threats Not Mitigated

Attack Scenarios

Scenario 1: Compromised htpasswd file

Impact: Attacker has password hashes

Risk: Medium - Bcrypt makes cracking difficult

Mitigation:

1. Immediately revoke all user accounts
2. Generate new htpasswd file with fresh passwords
3. Investigate how file was compromised
4. Increase bcrypt cost if needed

Scenario 2: Leaked credentials in logs

Impact: Credentials in plaintext in logs

Risk: High

Prevention:

• Never log passwords
• Sanitize logs before sharing
• Restrict log access

Response:

1. Rotate affected credentials immediately
2. Audit all log access
3. Review code for password logging

Scenario 3: Network eavesdropping (HTTP)

Impact: Credentials intercepted in transit

Risk: Critical over untrusted networks

Prevention:

• Always use HTTPS when authentication is enabled
• Especially critical for internet-facing deployments

Response:

1. Enable HTTPS immediately
2. Rotate all credentials (assume compromised)
3. Review access logs for suspicious activity

Audit & Monitoring

Authentication Events

Server logs authentication events:

# Successful authentication
DEBUG torc::server::auth: User 'alice' authenticated successfully

# Failed authentication (wrong password)
WARN torc::server::auth: Authentication failed for user 'alice'

# Missing credentials when required
WARN torc::server::auth: Authentication required but no credentials provided

# No authentication configured
DEBUG torc::server::auth: No authentication configured, allowing request

Recommended Monitoring

Metrics to track:

1. Failed authentication attempts (per user, total)
2. Successful authentications (per user)
3. Requests without credentials (when auth enabled)
4. Unusual access patterns (time, volume, endpoints)

Alerting thresholds:

• 5+ failed attempts from same user in 5 minutes
• 100+ failed attempts total in 1 hour
• Authentication from unexpected IP ranges
• Access during unusual hours (if applicable)

Log aggregation:

# Collect auth events
grep "torc::server::auth" /var/log/torc-server.log

# Count failed attempts per user
grep "Authentication failed" /var/log/torc-server.log | \
  awk '{print $(NF)}' | sort | uniq -c

# Monitor in real-time
tail -f /var/log/torc-server.log | grep "WARN.*auth"

Compliance Considerations

GDPR / Privacy

User data in htpasswd:

• Usernames may be personal data (email addresses)
• Password hashes are not personal data (irreversible)

Recommendations:

• Allow users to request account deletion
• Don't use email addresses as usernames (use aliases)
• Document data retention policies

PCI-DSS / SOC2

Requirements that apply:

1. Transport encryption: Use HTTPS
2. Access control: Enable required authentication
3. Password complexity: Enforce strong passwords
4. Audit logging: Enable and monitor auth logs
5. Regular reviews: Audit user accounts quarterly

Configuration:

# PCI-DSS compliant setup
torc-server run \
  --https \
  --auth-file /etc/torc/htpasswd \
  --require-auth \
  --log-level info

Security Checklist

Server Deployment

• HTTPS enabled in production
• Strong TLS configuration (TLS 1.2+, strong ciphers)
• Valid certificate from trusted CA
• Required authentication enabled (--require-auth)
• Htpasswd file permissions: chmod 600
• Htpasswd file owned by server process user
• Bcrypt cost ≥ 12 (≥14 for high-security)
• Strong passwords enforced
• Audit logging enabled
• Log rotation configured
• Firewall rules limit access
• Server runs as non-root user
• Regular security updates applied

Client Usage

• HTTPS URLs used when auth enabled
• Credentials stored in environment variables (not command-line)
• Passwords not logged
• Passwords not committed to version control
• Password prompting used for interactive sessions
• CI/CD secrets used for automation
• Regular password rotation

Operational

• User accounts reviewed quarterly
• Inactive accounts disabled/removed
• Failed login attempts monitored
• Access logs reviewed regularly
• Incident response plan documented
• Backup htpasswd files encrypted
• Disaster recovery tested

Access Control

Admin Group

Torc uses a special admin group to control who can manage access groups. Key properties:

• Config-driven: Admin users are configured via --admin-user flag or admin_users config
• Auto-created: The admin group is created/synced automatically on server startup
• System group: Cannot be deleted or have membership modified via the API
• Required for management: Only admin members can create, delete, or modify access groups

Configuration:

# Via CLI
torc-server run --admin-user alice --admin-user bob --enforce-access-control

# Via config file
[server]
admin_users = ["alice", "bob"]
enforce_access_control = true

Access Group Permissions

Future Enhancements

Planned security features:

1. Token-based authentication: JWT/OAuth2 support
2. API keys: Long-lived tokens for automation
3. LDAP/Active Directory integration: Enterprise SSO
4. Rate limiting: Prevent brute force attacks
5. 2FA/MFA support: Multi-factor authentication
6. Session management: Token expiration, refresh
7. Audit trail: Detailed access logging

Resources

• OWASP Authentication Cheat Sheet
• bcrypt Wikipedia
• HTTP Basic Authentication RFC 7617
• NIST Password Guidelines