headplane/headplane-security-assessment.md

Headplane Security Assessment Report

Executive Summary

This comprehensive security assessment of the Headplane project has identified multiple critical and high-priority security vulnerabilities that require immediate attention. The analysis focused on authentication, authorization, session management, OIDC implementation, and infrastructure security.

Critical Security Findings

1. CRITICAL: Shared API Key Authentication (Issue #290 Context)

Severity: Critical | CVSS Score: 9.1 (Critical)

Vulnerability: All OIDC-authenticated users share a single Headscale API key.

Location: /app/routes/auth/oidc-callback.ts:54

userSession.set('api_key', context.config.oidc?.headscale_api_key!);

Impact:

• Complete privilege escalation potential
• No user isolation between OIDC sessions
• Single point of failure for entire authentication system
• Violation of principle of least privilege

Root Cause: System uses a single administrative API key for all OIDC users instead of generating individual user-scoped keys.

Recommendation: Implement individual API key generation per user or implement proper user scoping in the Headscale API client.

---

2. HIGH: Insecure Session Configuration

Severity: High | CVSS Score: 7.5 (High)

Vulnerabilities:

• Weak cookie security options
• Missing security headers configuration
• Inadequate session validation

Locations:

• /app/server/index.ts:43-51 - Basic cookie configuration with TODO comment
• /app/server/web/sessions.ts:60-67 - sameSite set to 'lax' instead of 'strict'

Evidence:

// TODO: Better cookie options in config
sessions: await createSessionStorage({
    name: '_hp_session',
    maxAge: 60 * 60 * 24, // 24 hours
    secure: config.server.cookie_secure,
    secrets: [config.server.cookie_secret],
})

// In sessions.ts:
sameSite: 'lax', // TODO: Strictify with Domain

Impact:

• CSRF vulnerability potential
• Session hijacking risks
• Cross-site request forgery attacks

Recommendations:

1. Set sameSite: 'strict' for authentication cookies
2. Implement proper domain restriction
3. Add security headers (HSTS, CSP, etc.)
4. Consider implementing CSRF tokens

---

3. HIGH: OIDC Implementation Vulnerabilities

Severity: High | CVSS Score: 7.3 (High)

Vulnerabilities:

• Missing custom endpoint support makes system vulnerable to discovery failures
• Inadequate OIDC state validation
• Weak error handling exposes internal details

Locations:

• /app/server/web/oidc.ts:61 - TODO comment about missing custom endpoints
• /app/routes/auth/oidc-callback.ts:28-30 - Basic state validation
• /app/utils/oidc.ts:22-30 - Host header manipulation vulnerability

Evidence:

// TODO: Support custom endpoints instead of relying on OIDC discovery.
// This will enable us to support servers like GitHub that do not support
// nor advertise a .well-known endpoint.

// Vulnerable host detection:
let host = req.headers.get('Host');
if (!host) {
    host = req.headers.get('X-Forwarded-Host');
}

Impact:

• Host header injection attacks
• OIDC downgrade attacks
• Authentication bypass potential

Recommendations:

1. Implement custom endpoint configuration
2. Validate and whitelist allowed hosts
3. Implement proper redirect URI validation
4. Add rate limiting to OIDC endpoints

---

4. MEDIUM: Insufficient Permission System (Issue #266, #299)

Severity: Medium | CVSS Score: 6.5 (Medium)

Vulnerabilities:

• Automated ownership assignment needs rework
• Default member role has insufficient restrictions
• Permission escalation through first-user registration

Location: /app/server/web/sessions.ts:164-180

Evidence:

private async registerSubject(subject: string) {
    if (Object.keys(this.caps).length === 0) {
        log.debug('auth', 'First user registered as owner: %s', subject);
        this.caps[subject] = { c: Roles.owner };
        // First user automatically becomes owner
    }
    // ...
    this.caps[subject] = { c: Roles.member };
    // New users get member role with 0 capabilities
}

Impact:

• Race condition for first-user owner assignment
• No access control on initial system setup
• Potential privilege escalation through timing attacks

Recommendations:

1. Implement explicit owner assignment during system initialization
2. Add confirmation step for first-user registration
3. Implement proper role assignment workflows
4. Add audit logging for role changes

---

5. MEDIUM: Infrastructure Security Hardening Required

Severity: Medium | CVSS Score: 5.8 (Medium)

Vulnerabilities:

• SystemD services lack security hardening
• Container and process isolation insufficient
• No principle of least privilege implementation

Location: /nix/module.nix:87, 107

Evidence:

# TODO: Harden `systemd` security according to the "The Principle of Least Power".
# See: `$ systemd-analyze security headplane-agent`.
# TODO: Harden `systemd` security according to the "The Principle of Least Power".
# See: `$ systemd-analyze security headplane`.

Impact:

• Container escape potential
• Excessive system access
• Privilege escalation opportunities

Recommendations:

1. Implement SystemD security directives
2. Use unprivileged containers
3. Implement proper file system restrictions
4. Add network isolation

---

Security Architecture Issues

Authentication Flow Analysis

Current Issues:

1. Single API Key Model: All OIDC users share one API key, eliminating user isolation
2. Mixed Authentication: Both API key and OIDC authentication with different privilege models
3. Session State Management: Inconsistent validation between auth methods

Recommended Architecture:

// Proposed: User-scoped authentication
interface UserSession {
    auth_type: 'api_key' | 'oidc';
    user_id: string;
    capabilities: Capabilities;
    api_tokens: string[]; // User-specific tokens
    expires_at: Date;
}

Authorization System Review

Current Role System (generally well-designed):

• Bitwise capability system provides granular permissions
• Clear role hierarchy from member to owner
• Proper capability checking implementation

Identified Issues:

1. Owner role cannot be reassigned (line 204-206 in sessions.ts)
2. Default member role has zero capabilities but can access UI
3. No audit trail for permission changes

OIDC Security Analysis

Arctic Migration Benefits (Issue #306): The proposed migration to Arctic OAuth2/OIDC library would address several current vulnerabilities:

1. Better Security Defaults: Arctic provides more secure default configurations
2. PKCE Support: Enhanced protection against authorization code interception
3. State Management: Improved CSRF protection in OAuth flows
4. Error Handling: Better security error handling without information disclosure

Migration Priority: High - This should be prioritized as it addresses multiple security issues simultaneously.

---

Priority Recommendations

Immediate Actions (Critical - Fix within 1 week)

1. Issue #290 Mitigation: Implement temporary user isolation by adding user context to API calls
2. Session Security: Implement strict sameSite cookies and proper domain restrictions
3. Host Header Validation: Add whitelist validation for host headers in OIDC flows

Short Term (High Priority - Fix within 1 month)

1. Arctic Migration (Issue #306): Complete migration to Arctic OAuth2/OIDC library
2. Permission System Rework (Issue #266): Implement proper ownership assignment workflow
3. OIDC Validation (Issue #310): Ensure OIDC configuration is not populated in YAML when disabled
4. SystemD Hardening: Implement security directives for service isolation

Medium Term (Fix within 3 months)

1. API Key Management: Implement per-user API key generation
2. Audit Logging: Add comprehensive security event logging
3. Rate Limiting: Implement authentication and API rate limiting
4. Security Headers: Add comprehensive security header configuration

---

Recommended Security Enhancements

1. Session Security Configuration

// Proposed secure session configuration
const secureSessionConfig = {
    name: '_hp_session',
    maxAge: 60 * 60 * 8, // Reduced to 8 hours
    secure: true, // Always require HTTPS
    httpOnly: true,
    sameSite: 'strict' as const,
    domain: config.server.trusted_domain,
    secrets: [config.server.cookie_secret],
    // Add session rotation
    rotateSecrets: true,
};

2. Security Headers Implementation

// Add to server configuration
const securityHeaders = {
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
    'X-Content-Type-Options': 'nosniff',
    'X-Frame-Options': 'DENY',
    'X-XSS-Protection': '1; mode=block',
    'Referrer-Policy': 'strict-origin-when-cross-origin',
    'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'",
};

3. SystemD Security Hardening

serviceConfig = {
    # Security hardening
    NoNewPrivileges = true;
    PrivateTmp = true;
    PrivateDevices = true;
    ProtectSystem = "strict";
    ProtectHome = true;
    ProtectKernelTunables = true;
    ProtectKernelModules = true;
    ProtectControlGroups = true;
    RestrictSUIDSGID = true;
    RestrictRealtime = true;
    RestrictNamespaces = true;
    LockPersonality = true;
    MemoryDenyWriteExecute = true;
    
    # Capability restrictions
    CapabilityBoundingSet = ["CAP_NET_BIND_SERVICE"];
    AmbientCapabilities = ["CAP_NET_BIND_SERVICE"];
    
    # Network restrictions
    RestrictAddressFamilies = ["AF_INET" "AF_INET6"];
    
    # File system restrictions
    ReadWritePaths = ["/var/lib/headplane"];
    ReadOnlyPaths = ["/etc/headscale"];
};

---

Compliance and Standards

OWASP Top 10 2021 Mapping

1. A01 - Broken Access Control: Addressed by permission system rework
2. A02 - Cryptographic Failures: Addressed by session security improvements
3. A03 - Injection: Low risk due to TypeScript and API abstraction
4. A04 - Insecure Design: Addressed by architecture recommendations
5. A05 - Security Misconfiguration: Addressed by SystemD hardening
6. A06 - Vulnerable Components: Monitor dependencies with automated scanning
7. A07 - Identification/Authentication Failures: Primary focus of this assessment
8. A08 - Software/Data Integrity Failures: Add dependency integrity checks
9. A09 - Security Logging Failures: Implement comprehensive audit logging
10. A10 - Server-Side Request Forgery: Add URL validation in integrations

Security Testing Recommendations

1. Automated Security Testing:

   • Implement SAST scanning with Semgrep
   • Add dependency vulnerability scanning
   • Container image security scanning

2. Manual Security Testing:

   • Penetration testing of authentication flows
   • Session management testing
   • Authorization bypass testing

3. Security Monitoring:

   • Failed authentication attempt monitoring
   • Unusual permission escalation detection
   • API key usage anomaly detection

---

Conclusion

The Headplane project has several critical security vulnerabilities that require immediate attention, particularly around the shared API key authentication model and session security. The planned migration to Arctic OAuth2/OIDC library should be prioritized as it addresses multiple security concerns simultaneously.

The role-based permission system is well-designed but needs improvements in the ownership assignment workflow. Infrastructure security hardening through SystemD directives will provide defense-in-depth protection.

With proper implementation of the recommended security measures, Headplane can achieve a robust security posture suitable for production deployment.

---

Assessment Date: 2025-09-13
Assessor: Security Analysis - Comprehensive Review
Classification: Internal Security Assessment
Next Review: 2025-12-13 (Quarterly)