Status: ✅ Production Ready | Security Score: 95/100 | Last Updated: 2025-09-08

Orkee implements comprehensive security measures designed for both local development and production deployments. All critical security features are implemented and active, providing defense-in-depth protection suitable for production use.

Orkee follows a defense-in-depth strategy with zero-trust principles, implementing multiple layers of security:

• Secure by default - Safe configurations out of the box
• Principle of least privilege - Minimal access rights
• Defense in depth - Multiple security layers
• Transparent security - Clear security boundaries and controls
• Production ready - No authentication required for local CLI use

Current Security Model:

• Local Development: Single-user development machine (primary use case)
• Trusted Network: Team environment with network access
• Production: Behind reverse proxy with additional security

Assumed Threats:

• Malicious directory traversal attempts
• Automated vulnerability scanning
• Rate limiting bypass attempts
• Input injection attacks
• Network-based attacks (when exposed)

┌─────────────────────────────────────────────────────────────┐
│                   Implemented Security Layers              │
├─────────────────────────────────────────────────────────────┤
│ 1. TLS/HTTPS Encryption (Transport Layer) ✅               │
│    • TLS 1.2/1.3 with secure ciphers                     │
│    • Certificate validation and auto-generation           │
│    • HTTPS redirect middleware                            │
├─────────────────────────────────────────────────────────────┤
│ 2. Network Security (Application Layer) ✅                 │
│    • CORS origin validation                               │
│    • Per-IP rate limiting with burst protection           │
│    • Comprehensive security headers                       │
├─────────────────────────────────────────────────────────────┤
│ 3. Input Validation (Request Layer) ✅                     │
│    • PathValidator with sandbox enforcement               │
│    • Command injection prevention                         │
│    • Input sanitization and length limits                 │
├─────────────────────────────────────────────────────────────┤
│ 4. Access Control (Resource Layer) ✅                      │
│    • Directory sandboxing (strict/relaxed/disabled)       │
│    • File system boundary enforcement                     │
│    • Sensitive directory blocking                         │
├─────────────────────────────────────────────────────────────┤
│ 5. Error Handling (Response Layer) ✅                      │
│    • Information disclosure prevention                    │
│    • Request ID tracking for audit trails                 │
│    • Sanitized error responses                           │
├─────────────────────────────────────────────────────────────┤
│ 6. Container Security (Infrastructure Layer) ✅            │
│    • Non-root user execution                              │
│    • Security options and resource limits                 │
│    • Multi-stage builds with minimal attack surface       │
└─────────────────────────────────────────────────────────────┘

Implementation: packages/cli/src/tls.rs

• Native Rust TLS using rustls library
• TLS 1.2/1.3 only with secure cipher suites
• Automatic certificate generation for development
• Certificate validation and expiry checking
• Dual server mode with HTTP-to-HTTPS redirect

Configuration:

TLS_ENABLED=true                 # Enable HTTPS
AUTO_GENERATE_CERT=true          # Auto-generate dev certificates
ENABLE_HSTS=true                 # HTTP Strict Transport Security
TLS_CERT_PATH=/path/to/cert.pem  # Custom certificate path
TLS_KEY_PATH=/path/to/key.pem    # Custom key path

Implementation: packages/cli/src/middleware/rate_limit.rs

• Per-IP address tracking using Governor crate
• Endpoint-specific rate limits with burst protection
• Configurable thresholds per endpoint category
• Retry-After headers for rate-limited responses

Default Limits:

RATE_LIMIT_HEALTH_RPM=60        # Health endpoints: 60 requests/minute
RATE_LIMIT_BROWSE_RPM=20        # Directory browsing: 20 requests/minute  
RATE_LIMIT_PROJECTS_RPM=30      # Project operations: 30 requests/minute
RATE_LIMIT_PREVIEW_RPM=10       # Preview operations: 10 requests/minute
RATE_LIMIT_GLOBAL_RPM=30        # Default for other endpoints
RATE_LIMIT_BURST_SIZE=5         # Burst multiplier

Implementation: packages/cli/src/api/path_validator.rs

• Comprehensive PathValidator with three security modes
• Path traversal detection and prevention
• Command injection protection
• Canonical path resolution

Three Security Modes:

• Allowlist only: Access restricted to configured paths only
• Zero path traversal: All ../ navigation blocked
• Maximum security: Suitable for production environments

• Blocklist approach: Block dangerous system paths
• Controlled traversal: Limited ../ navigation
• Development friendly: Balance of security and usability

• No restrictions: Use only in completely trusted environments

Always Blocked Paths:

# System directories
/etc, /sys, /proc, /dev, /boot, /root
/usr/bin, /usr/sbin, /bin, /sbin
/var/log, /var/run, /tmp

# Sensitive user directories  
~/.ssh, ~/.aws, ~/.gnupg, ~/.docker, ~/.kube
~/.env, ~/.credentials, ~/.gitconfig

# Windows system paths
C:\Windows, C:\System32, C:\Program Files

Implementation: packages/cli/src/middleware/security_headers.rs

Complete Header Suite:

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'
X-Content-Type-Options: nosniff
X-Frame-Options: DENY  
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), camera=(), microphone=()
Strict-Transport-Security: max-age=31536000; includeSubDomains

Implementation: packages/cli/src/lib.rs

• Strict allowlist of permitted origins
• Configurable origin validation
• Credentials explicitly disabled
• Development flexibility with localhost support

Configuration:

CORS_ORIGIN="http://localhost:5173"     # Specific allowed origin
CORS_ALLOW_ANY_LOCALHOST=true           # Dev mode flexibility

Implementation: packages/cli/src/error.rs + tracing throughout

• Sanitized error responses (no internal details)
• Request ID correlation for audit trails
• Comprehensive structured logging
• Security event markers for monitoring

Audit Events Logged:

// Security events automatically logged:
- Rate limit violations (with IP addresses)
- Path traversal attempts  
- Invalid path access attempts
- Configuration errors
- Certificate validation failures
- TLS handshake issues

Implementation: deployment/docker/

• Multi-stage builds for minimal attack surface
• Non-root user execution (USER orkee)
• Security options (no-new-privileges:true)
• Resource limits and health checks
• Read-only root filesystem capability

Implementation: deployment/

• Systemd service with security hardening
• Nginx reverse proxy with SSL termination
• Firewall configuration guidance
• Certificate management (Let's Encrypt support)
• Backup and recovery procedures

Design Decision: Orkee implements API token authentication designed for local-first desktop applications with automatic token management.

Security Model:

• Local-first: App runs on localhost, user owns the machine
• Simple API tokens: No complex OAuth flows or user login required
• Automatic token generation: Token created on first startup
• Defense in depth: Protects against localhost malware and cross-origin attacks
• Transparent to users: Desktop app handles authentication automatically

Components:

• Token Generation: packages/projects/src/api_tokens/storage.rs
• Token Middleware: packages/cli/src/middleware/api_token.rs
• Token Storage: ~/.orkee/api-token (file) + api_tokens table (database)
• Desktop Integration: packages/dashboard/src-tauri/src/lib.rs

Token Format:

• 32 random bytes encoded as base64 (URL-safe, no padding)
• Example: mK3tN9xQ8vR2jP7wL4yF6hS1dC5bA0zX8uI2oE9gT7r
• Length: 43 characters

Token Storage:

1. File Storage: ~/.orkee/api-token

   • Permissions: 0600 (owner read/write only on Unix)
   • Allows desktop app to read token automatically
   • Enables manual API testing

2. Database Storage: api_tokens table

   • Stores SHA-256 hash (not plaintext token)
   • Tracks creation time, last used time, active status
   • Supports future multi-token scenarios

Token Lifecycle:

1. First startup: Generate token, display once, save to file and database
2. Subsequent startups: Token already exists, read from file
3. Authentication: Hash incoming token, compare with database using constant-time comparison
4. Update: Record last_used_at timestamp on successful authentication

✅ SHA-256 Hashing: Tokens stored as hashes in database

• Protects against database export attacks
• Attacker cannot recover plaintext tokens from database

✅ Constant-Time Comparison: Prevents timing attacks

• Uses subtle crate for constant-time comparison
• Verification time same regardless of match accuracy

✅ File Permissions: Token file readable only by owner

• Unix: 0600 permissions (owner read/write only)
• Windows: NTFS permissions for current user only

✅ Whitelisted Endpoints: Health/status endpoints bypass auth

• /api/health - Basic health check
• /api/status - Detailed service status
• /api/csrf-token - CSRF token retrieval

✅ Development Mode Bypass: Authentication disabled in dev mode

• Enabled with ORKEE_DEV_MODE=true (automatic with orkee dashboard --dev)
• All API endpoints accessible without tokens
• Web dashboard works without token file access
• Security: Only on localhost (127.0.0.1), single-user trusted environment

✅ Automatic Rotation Support: Infrastructure ready for token rotation

• Token revocation support (is_active flag)
• Multiple token support (name field)
• Last used tracking for unused token cleanup

1. Client Request
   ├─ Desktop app: Automatically includes token from ~/.orkee/api-token
   └─ Manual: Include X-API-Token header

2. Middleware Check
   ├─ Whitelisted paths: Skip authentication
   ├─ Development mode (ORKEE_DEV_MODE=true): Skip authentication
   └─ Protected paths: Continue to validation

3. Token Extraction
   ├─ Extract X-API-Token header
   └─ Return 401 if missing

4. Token Verification
   ├─ Hash provided token (SHA-256)
   ├─ Query database for matching hash where is_active = 1
   ├─ Constant-time comparison
   └─ Return 401 if no match

5. Update Timestamp
   ├─ Update last_used_at in database
   └─ Non-fatal error if update fails

6. Request Proceeds
   └─ Pass to handler

Automatic Authentication:

// packages/dashboard/src-tauri/src/lib.rs
#[tauri::command]
async fn get_api_token() -> Result<String, String> {
    let home = dirs::home_dir()
        .ok_or_else(|| "Unable to determine home directory".to_string())?;

    let token_path = home.join(".orkee").join("api-token");

    fs::read_to_string(&token_path)
        .map(|t| t.trim().to_string())
        .map_err(|e| format!("Failed to read API token: {}", e))
}

API Client:

// packages/dashboard/src/services/api.ts
async get<T>(endpoint: string, options?: RequestOptions): Promise<ApiResponse<T>> {
  const token = await getApiToken();
  const headers: HeadersInit = {
    ...options?.headers,
  };

  if (token) {
    headers['X-API-Token'] = token;
  }

  // ... rest of request
}

All API endpoints except whitelisted paths require authentication:

• Projects API: /api/projects/*
• Settings API: /api/settings/*
• Preview Servers: /api/preview/*
• Directory Browsing: /api/browse-directories
• Tasks & Specs: /api/tasks/*, /api/specs/*

Unit Tests: 6 tests in packages/projects/src/api_tokens/storage.rs

• Token generation uniqueness
• Hash determinism
• Hash uniqueness for different inputs
• Valid token verification
• Invalid token rejection
• Constant-time comparison

Middleware Tests: 6 tests in packages/cli/src/middleware/api_token.rs

• Whitelisted paths bypass authentication
• Missing token returns 401
• Invalid token returns 401
• Valid token allows access
• Token updates last_used timestamp
• Authentication logic correctness

Token Management (Planned):

orkee tokens list              # List all tokens
orkee tokens generate <name>   # Generate named token
orkee tokens revoke <id>       # Revoke specific token
orkee tokens regenerate        # Rotate default token

Additional Features:

• Token expiration dates
• Named tokens for different purposes (CI, testing, admin)
• Token permissions (future RBAC)
• Auto-renewal before expiration

For complete authentication documentation, see:

• API_SECURITY.md - Complete API authentication guide
• MANUAL_TESTING.md - Manual testing procedures
• DOCS.md - Configuration reference

Orkee implements OAuth 2.0 authentication for AI providers (Claude, OpenAI, Google, xAI), allowing users to authenticate with their subscription accounts instead of API keys.

OAuth Flow Security:

• PKCE (RFC 7636): Protection against authorization code interception

  • SHA256 code challenge generation
  • 43-character code verifier (256 bits of entropy)
  • Code challenge sent with authorization request
  • Code verifier validated during token exchange

• State Parameter: CSRF protection

  • Cryptographically secure random state generation
  • State validation on callback
  • 10-minute timeout (configurable via OAUTH_STATE_TIMEOUT_SECS)

• Callback Server: Localhost-only OAuth callback

  • Binds to 127.0.0.1:3737 (not 0.0.0.0)
  • Temporary server (starts for auth, stops after)
  • No external network exposure

Storage:

• Location: ~/.orkee/orkee.db (oauth_tokens table)
• Encryption: ChaCha20-Poly1305 AEAD
  • Unique nonce per token encryption
  • Per-token encryption (not batch)
  • Same encryption as API keys
• Access Control: Database file permissions (Unix: 0600)

Token Management:

• Automatic Refresh: Tokens refreshed 5 minutes before expiry
• Refresh Buffer: Configurable via OAUTH_TOKEN_REFRESH_BUFFER_SECS
• Expiry Tracking: Stored in database, checked on each use
• Graceful Degradation: Falls back to API keys if OAuth token expired

Supported Providers:

Provider Configurations:

• Default client IDs provided (configurable)
• Redirect URI: http://localhost:3737/callback
• Scopes: Provider-specific (minimal required permissions)

Components:

• Auth Package: packages/auth/ - Separate package for OAuth logic
• Database Schema: oauth_tokens and oauth_providers tables
• API Endpoints: /api/auth/* for token management
• CLI Commands: orkee login, orkee logout, orkee auth status

Security Features: ✅ PKCE implementation with SHA256 ✅ State parameter CSRF protection ✅ Localhost-only callback server ✅ Encrypted token storage ✅ Automatic token refresh ✅ Browser opening with user confirmation ✅ Token validation on each use ✅ Graceful error handling

Unit Tests: 30+ OAuth-specific tests

• PKCE generation and verification
• State parameter handling
• Token encryption/decryption
• Token expiry and refresh logic
• Provider configuration parsing
• Callback server operation

Security Tests:

• PKCE code challenge determinism
• State parameter uniqueness
• Token encryption uniqueness
• Constant-time operations where applicable

OAuth Environment Variables:

# Callback server (localhost-only, no external exposure)
OAUTH_CALLBACK_PORT=3737

# Security timeouts
OAUTH_STATE_TIMEOUT_SECS=600        # State parameter timeout
OAUTH_TOKEN_REFRESH_BUFFER_SECS=300 # Refresh buffer time

Provider Override (optional, for custom OAuth clients):

OAUTH_CLAUDE_CLIENT_ID=custom-client-id
OAUTH_CLAUDE_REDIRECT_URI=http://localhost:3737/callback
OAUTH_CLAUDE_SCOPES="model:claude account:read"

For Users:

• Use OAuth for Claude Pro/Max subscriptions (no API costs)
• Set auth_preference=hybrid for fallback to API keys
• Monitor token expiry via orkee auth status
• Revoke tokens when not in use: orkee logout <provider>

For Developers:

• Never log OAuth tokens (implementation sanitizes logs)
• Always use PKCE for authorization code flows
• Validate state parameter on callback
• Refresh tokens before expiry (not after)
• Encrypt tokens at rest

Planned Features:

• OAuth token rotation (manual and automatic)
• Multi-device token sync (via Orkee Cloud)
• Provider-specific scope customization
• OAuth audit log (successful/failed attempts)
• Token usage analytics

For detailed OAuth setup and troubleshooting, see:

• OAUTH_SETUP.md - Complete OAuth setup guide
• SECURITY_AUDIT.md - OAuth security audit
• oauth.md - Implementation plan and status

# Recommended development configuration
TLS_ENABLED=false                    # HTTPS not required for localhost
BROWSE_SANDBOX_MODE=relaxed          # Balanced security/usability  
RATE_LIMIT_ENABLED=true              # Protect against accidental DoS
SECURITY_HEADERS_ENABLED=true        # Practice secure defaults
CORS_ALLOW_ANY_LOCALHOST=true        # Development flexibility

# Required production configuration
TLS_ENABLED=true                     # Always use HTTPS
ENABLE_HSTS=true                     # Enforce HTTPS in browsers
BROWSE_SANDBOX_MODE=strict           # Maximum directory protection
RATE_LIMIT_ENABLED=true              # Essential for network access
SECURITY_HEADERS_ENABLED=true        # Full header protection
CORS_ALLOW_ANY_LOCALHOST=false       # Explicit origin control
AUTO_GENERATE_CERT=false             # Use proper CA certificates

Implementation: Throughout test suites (144+ tests)

// Security-focused tests included:
- Path traversal detection tests
- Rate limiting enforcement tests  
- TLS configuration validation tests
- Input validation boundary tests
- CORS policy enforcement tests
- Error message sanitization tests

# Test rate limiting
for i in {1..100}; do curl https://your-domain.com/api/health; done

# Test path traversal protection
curl "https://your-domain.com/api/directories/list" \
  -d '{"path": "../../../etc/passwd"}'

# Test HTTPS redirect
curl -I http://your-domain.com/

# Test security headers
curl -I https://your-domain.com/

# Test CORS restrictions
curl -H "Origin: https://malicious-site.com" \
  -X OPTIONS https://your-domain.com/api/health

# 1. Use production environment template
cp deployment/examples/.env.production .env
# Edit .env with your domain and settings

# 2. Deploy with Docker (includes all security features)
docker-compose -f deployment/docker/docker-compose.yml up -d

# 3. Configure SSL certificates
sudo certbot certonly --standalone -d your-domain.com

# 4. Set up Nginx reverse proxy (optional but recommended)
sudo cp deployment/nginx/orkee-ssl.conf /etc/nginx/sites-available/
sudo nginx -t && sudo systemctl reload nginx

Reverse Proxy (Recommended):

• Use provided Nginx configurations with SSL termination
• Additional rate limiting and DDoS protection
• WAF (Web Application Firewall) integration
• SSL/TLS optimization

Container Security:

• Configurations use non-privileged user
• Resource limits enforced
• Security options enabled
• Health checks configured

Network Security:

• Firewall rules documented
• VPN access for administration
• Network segmentation recommendations
• Load balancer configuration

For security vulnerabilities, please DO NOT open public issues.

Report security issues privately:

• GitHub: Use private vulnerability reporting
• Email: Create issue with [SECURITY] prefix
• Response Time: We aim to respond within 48 hours

1. Acknowledgment (48 hours): Confirm receipt and begin investigation
2. Assessment (5 days): Severity assessment and impact analysis
3. Development (varies): Fix development and testing
4. Disclosure (coordinated): Public disclosure after fix is available

• Dependency vulnerability scanning (cargo audit, pnpm audit)
• Security configuration validation
• Certificate renewal procedures
• Log monitoring and alerting setup
• Backup and recovery testing

Configuration Security:

• TLS enabled for production deployments
• Rate limiting enabled and properly configured
• Directory sandbox set to appropriate mode
• CORS origins properly restricted
• Security headers enabled
• Error logging configured

Infrastructure Security:

• Application running as non-privileged user
• Container security options enabled
• Firewall configuration documented
• SSL certificate management automated
• Health monitoring configured

Operational Security:

• Incident response procedures documented
• Security update procedures established
• Backup and recovery tested
• Monitoring and alerting configured

Implementation: packages/dashboard/src-tauri/

The Orkee Desktop application includes native installers with automatic CLI installation. Security considerations:

• PATH Modification: Uses WriteRegExpandStr for direct registry manipulation
• Permission Model: Supports both per-user (%LOCALAPPDATA%) and per-machine (Program Files) installations
• Duplication Prevention: Checks for existing PATH entries before adding
• Clean Uninstall: Removes PATH entries on uninstall to prevent orphaned entries
• Known Limitation: No atomic read-modify-write (NSIS framework limitation) - see INSTALLER_README.md
• Risk: Requires admin privileges for per-machine install (standard practice)

• Location Detection: Checks multiple install locations (not hardcoded)
• Permission Model: Requires admin privileges to write to /usr/local/bin (standard practice)
• Binary Verification: Checks binary exists before copying
• Graceful Failure: Non-fatal errors with helpful messages
• Risk: Modifies /usr/local/bin (standard system location)

• Symlink Approach: Prefers symlinks over copies (easier updates)
• Fallback Safety: Falls back to copy if symlink fails
• Permission Handling: Graceful degradation for insufficient permissions
• Risk: Requires root for package installation (standard practice)

• No Auto-Install: AppImages don't support post-install hooks (by design)
• Manual Setup: Clear documentation provided for manual CLI extraction
• User Control: Users choose installation location (no sudo required)
• Risk: Users must manually extract and install CLI binary

Binary Verification:

• ✅ Installer scripts verify binary exists before operations
• ✅ Target paths validated before file operations

Path Security:

• ✅ No arbitrary path modification (only designated binary directories)
• ✅ PATH duplication checks prevent accumulation
• ✅ Clean uninstall removes PATH entries

Permission Handling:

• ✅ Graceful failure for insufficient permissions
• ✅ Clear error messages guide users
• ✅ Per-user options available (Windows, AppImage)

Script Quality:

• ✅ Shellcheck validation in CI pipeline
• ✅ Portable shebang (#!/usr/bin/env bash)
• ✅ Error handling with set -e

Binary Integrity: Users can verify downloaded binaries:

# Verify checksum from GitHub releases
sha256sum Orkee_*.dmg
# Compare against checksums.txt in release assets

Code Signing Status:

• ⚠️ Currently unsigned (requires Apple Developer certificate)
• ⚠️ macOS Gatekeeper may show warnings
• Future: Will add code signing for production releases

Script Auditing: All installer scripts are:

• Open source and auditable at packages/dashboard/src-tauri/
• Validated by shellcheck in CI
• Simple, readable bash scripts (no obfuscation)

• packages/dashboard/src-tauri/INSTALLER_README.md - Installer implementation details
• PRODUCTION_STATUS_FINAL.md - Complete production readiness status
• deployment/README.md - Deployment guide with security hardening
• DOCS.md - Complete configuration reference including security settings

Deductions:

• -3 points: Minor unmaintained dependencies (no security impact)
• -2 points: No authentication system (by design for local CLI use)

Orkee is PRODUCTION READY with comprehensive security controls implemented.

The application provides enterprise-grade security suitable for:

• ✅ Local development environments
• ✅ Trusted network deployments
• ✅ Production deployments behind reverse proxy
• ✅ Container orchestration platforms

All critical security features are implemented and active, providing defense-in-depth protection against common attack vectors.

Last Updated: 2025-09-08
Security Status: ✅ PRODUCTION READY
Next Review: Quarterly security assessment