We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.

Email: [email protected]

sequenceDiagram
    participant User
    participant PAM as PAM Module
    participant LLNG as LLNG Portal

    User->>PAM: One-time token
    PAM->>LLNG: POST /pam/verify
    LLNG-->>PAM: User attributes + authorization
    Note over LLNG: Token consumed (single-use)
    PAM-->>User: Session established

1. User provides a one-time token generated by the LLNG portal
2. PAM module verifies token via /pam/verify endpoint
3. Token is consumed (single-use) and cannot be replayed
4. Server returns user attributes and authorization status

Certificate Pinning: When configured, the module validates the server's public key against the pinned value, preventing MITM attacks even with compromised CAs.

# Example configuration
min_tls_version = 13
cert_pin = sha256//AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

When request_signing_secret is configured, requests include:

• X-Timestamp: Unix timestamp (server should reject if too old)
• X-Nonce: Unique timestamp_ms-uuid format (server should reject duplicates)
• X-Signature-256: HMAC-SHA256 signature of the request

This provides defense-in-depth against request tampering, even if TLS is somehow compromised.

The PAM module authenticates to the LLNG server using:

The server token should be stored in a file with restricted permissions (0600) owned by root.

For OAuth2 token introspection and refresh operations, the module uses JWT Client Assertion (RFC 7523) instead of HTTP Basic Authentication. This provides enhanced security:

• The client_secret is never transmitted over the network
• Each request includes a unique JWT signed with HMAC-SHA256
• JWT contains: iss, sub, aud, exp, iat, and unique jti (UUID v4)
• JWT validity is 5 minutes to prevent replay attacks

When token_rotate_refresh = true (default), the module automatically rotates the refresh token after each successful token refresh. This limits the window of opportunity if a token is compromised, as stolen tokens become invalid after the next legitimate use.

In bastion/backend architectures, the PAM module supports cryptographic verification that SSH connections to backends originate from authorized bastion servers.

flowchart LR
    subgraph Bastion["Bastion Server"]
        proxy["llng-ssh-proxy"]
    end

    subgraph LLNG["LLNG Portal"]
        bastion_token["/pam/bastion-token"]
        jwks["/.well-known/jwks.json"]
    end

    subgraph Backend["Backend Server"]
        pam["pam_llng.so"]
        cache["JWKS Cache"]
    end

    proxy -->|1. Request JWT| bastion_token
    bastion_token -->|2. Signed JWT| proxy
    proxy -->|3. SSH + JWT| pam
    pam -->|4. Get public keys| jwks
    jwks -->|5. Cache keys| cache
    pam -->|6. Verify signature| cache

# /etc/security/pam_llng.conf
bastion_jwt_required = true
bastion_jwt_issuer = https://auth.example.com
bastion_jwt_jwks_url = https://auth.example.com/.well-known/jwks.json
bastion_jwt_jwks_cache = /var/cache/pam_llng/jwks.json
bastion_jwt_cache_ttl = 3600
bastion_jwt_clock_skew = 60
# Optional: restrict to specific bastions
bastion_jwt_allowed_bastions = bastion-01,bastion-02

# /etc/ssh/sshd_config
AcceptEnv LLNG_BASTION_JWT

The JWKS cache enables JWT verification without network access to LLNG:

1. First connection fetches JWKS from LLNG portal
2. Public keys cached locally with configurable TTL
3. Subsequent verifications use cached keys
4. Cache refreshed when TTL expires or unknown key ID encountered

This provides resilience against LLNG outages while maintaining security.

When cache_encrypted = true (default), cached tokens are encrypted using:

• Algorithm: AES-256-GCM (authenticated encryption)
• Key Derivation: PBKDF2-SHA256 with 100,000 iterations
• Key Source: Machine ID (/etc/machine-id) + cache username as salt
• Authentication: GCM tag prevents tampering

File format:
[Plaintext: "expires_at\n"][Magic: LLNGCACHE02][IV: 12 bytes][Tag: 16 bytes][Ciphertext]

The plaintext timestamp header allows quick expiration checks without decryption (performance optimization). However, the timestamp is duplicated inside the encrypted payload for integrity verification. If an attacker modifies the plaintext header to extend cache validity, the mismatch with the encrypted timestamp causes immediate rejection and cache file deletion.

• Each user's cache is stored in a separate file
• File permissions: 0600 (owner read/write only)
• Directory permissions: 0700

When cache_invalidate_on_logout = true (default):

• User's cache is cleared when their PAM session closes
• Prevents stale tokens from being reused

Configure high-risk services via high_risk_services (comma-separated).

Protection against brute-force attacks:

Lockout state is stored per-user in rate_limit_state_dir.

When create_user_enabled = true, users can be automatically created on first login.

All paths are validated before use:

Shell Validation (approved_shells):

• Must be in approved list (default: common shells like /bin/bash, /bin/zsh)
• Must be absolute path
• No path traversal sequences (.., //)
• No shell metacharacters

Home Directory Validation (approved_home_prefixes):

• Must start with approved prefix (default: /home, /var/home)
• Same safety checks as shell

Skeleton Directory Validation:

• Must be absolute path
• Must be owned by root
• No symlinks in path components
• No dangerous patterns

• UIDs are generated deterministically from username hash
• Range: 10000-60000 (configurable)
• Collision handling: If UID exists, operation fails safely (returns 0)
• No fallback to random UIDs that could cause unpredictable behavior

The NSS module (libnss_llng.so) provides user resolution:

• Buffer overflow protection: All string copies use bounds-checked safe_strcpy()
• Server input validation: Shell and home paths from server are validated against approved lists
• UID range enforcement: Server-provided UIDs must be within configured min_uid/max_uid range
• Fail-safe: Returns appropriate error codes on any failure; invalid paths fall back to defaults

User accounts are created by directly writing to /etc/passwd and /etc/shadow rather than using external tools like useradd. This design choice was made for:

Advantages:

• Portability: No dependency on useradd which may not exist or have different options across distributions
• Atomicity: Single-process control over file locking ensures consistent state
• Predictability: No external tool behavior variations or unexpected prompts

Trade-offs:

• PAM account creation hooks are not triggered (this module IS the PAM hook)
• SELinux contexts must be handled separately if required
• System audit logs only see file modifications, not semantic "user created" events

Mitigations:

• The module emits its own structured audit events when audit_enabled = true
• File operations use exclusive locks (flock) to prevent race conditions
• If /etc/shadow write fails after /etc/passwd succeeds, rollback is attempted via userdel
• TOCTOU protection: user existence is re-checked after acquiring locks

When audit_enabled = true:

Audit events include:

• Authentication attempts (success/failure)
• Authorization decisions
• Rate limit triggers
• User creation events

For real-time security monitoring:

Recommended permissions:

CRITICAL: Never enable debug logging in production environments.

When log_level = debug, the module may log sensitive information to syslog:

• SSH certificate metadata (key_id, serial, principals)
• Token validation details
• Authorization request parameters

Risk: If debug logs are captured by a log aggregator or accessed by unauthorized users, this information could be used to:

• Identify infrastructure topology
• Track user movements across systems
• Correlate sessions for targeting

Recommendation:

• Use log_level = warn or log_level = error in production
• If debug logging is temporarily needed, ensure syslog access is restricted
• Rotate and purge logs containing debug output promptly

The encryption key for cached tokens and secrets is derived from /etc/machine-id.

Impact of machine-id change:

• All cached tokens become unreadable (automatic re-authentication required)
• Encrypted secrets in the secret store become permanently unrecoverable
• Server enrollment tokens must be re-issued

Scenarios causing machine-id change:

• VM cloning without regenerating machine-id
• System reinstallation
• Container image reuse across hosts
• Some cloud provider instance recreation

Recommendations:

1. Document machine-id stability as a deployment requirement
2. Before system migration: Backup enrollment tokens or plan for re-enrollment
3. VM cloning: Always regenerate machine-id (systemd-machine-id-setup) and re-enroll
4. Monitoring: Alert on machine-id changes via configuration management

Re-enrollment procedure after machine-id change:

# 1. The old token file is now unusable - remove it
rm /etc/security/pam_llng.token

# 2. Re-run enrollment
llng-pam-enroll --portal https://auth.example.com --client-id pam-access

Service accounts (ansible, backup, deploy, etc.) are local accounts that authenticate via SSH key only, bypassing OIDC authentication. They are defined in a local configuration file.

Service accounts are validated against the same security rules as regular users:

Important: The SSH server must have ExposeAuthInfo yes in /etc/ssh/sshd_config:

# /etc/ssh/sshd_config
ExposeAuthInfo yes

This setting allows the PAM module to access the SSH key fingerprint via the SSH_USER_AUTH environment variable, which is required for fingerprint validation.

sequenceDiagram
    participant SA as Service Account
    participant SSH as SSH Server
    participant PAM as PAM Module

    SA->>SSH: SSH key authentication
    SSH->>PAM: pam_sm_authenticate
    Note over SSH: ExposeAuthInfo provides<br/>SSH_USER_AUTH with fingerprint
    PAM->>PAM: Extract fingerprint from SSH_USER_AUTH
    PAM->>PAM: Check service_accounts.conf
    PAM->>PAM: Validate fingerprint matches config
    Note over PAM: Fingerprint OK = authorized
    PAM-->>SSH: PAM_SUCCESS
    SSH-->>SA: Session established

1. Service account connects via SSH with its configured key
2. SSH server exposes key fingerprint via SSH_USER_AUTH (requires ExposeAuthInfo yes)
3. PAM module extracts fingerprint and checks if user is in service_accounts.conf
4. PAM module validates that the SSH key fingerprint matches the configured value
5. If fingerprint matches, account is authorized locally (no LLNG call needed)
6. sudo permissions are checked from the same configuration file

[ansible]
key_fingerprint = SHA256:abc123def456
sudo_allowed = true
sudo_nopasswd = true
gecos = Ansible Automation
shell = /bin/bash
home = /var/lib/ansible

The offline cache enables Desktop SSO authentication when the LLNG server is unreachable. This section describes the security architecture and considerations.

Password Hashing (Argon2id):

These parameters follow OWASP guidelines for high-security password storage.

Data Encryption (AES-256-GCM):

File format:
[Magic: OBCRED01 (8 bytes)][AES-256-GCM encrypted JSON]

GCM authentication ensures any tampering (bit flips, truncation) is detected and the entry is rejected.

The encryption key is derived from a root-only key file or /etc/machine-id, ensuring:

• Portability prevention: Cache files are useless on other machines
• Cloning detection: VM clones with same machine-id must re-enroll
• Hardware binding: Physical theft of disk provides no access without key file

Impact of machine-id/key change:

• All cached credentials become permanently unreadable
• Users must authenticate online to re-cache credentials
• No security risk (encrypted data remains encrypted)

stateDiagram-v2
    [*] --> Stored: Successful online auth
    Stored --> Verified: Correct password (offline)
    Stored --> Failed: Wrong password
    Failed --> Failed: Increment failures
    Failed --> Locked: Max attempts reached
    Locked --> Stored: Lockout expires
    Stored --> Expired: TTL exceeded
    Expired --> [*]: Entry removed
    Verified --> [*]: User authenticated

Note: The lockout thresholds (5 attempts, 5 minutes) are compile-time constants defined in offline_cache.h (OFFLINE_CACHE_MAX_FAILED_ATTEMPTS and OFFLINE_CACHE_LOCKOUT_DURATION). For environments requiring stricter lockout, recompile with lower thresholds (minimum recommended: 3 attempts, 15 minutes).

Lockout state is stored within the encrypted cache entry, ensuring it cannot be reset by file manipulation.

The greeter and PAM module communicate via structured error codes (must match include/offline_cache.h):

The PAM module sends structured messages (OFFLINE_ERROR:code[:locktime]) via PAM conversation so the greeter can display appropriate feedback.

When to enable offline mode:

• Corporate workstations with network reliability concerns
• Laptops used in areas with poor connectivity
• Business continuity during LLNG maintenance

When NOT to enable offline mode:

• High-security environments requiring real-time authorization
• Shared/public workstations
• Systems requiring immediate access revocation

Emergency procedures:

# Immediate user revocation
ob-cache-admin invalidate username

# Force online-only authentication
touch /etc/open-bastion/force_online

# Complete cache flush
ob-cache-admin invalidate-all

The ob-cache-admin tool provides secure cache management:

# List cached credentials (metadata only, no secrets)
ob-cache-admin list

# Show details for a specific user
ob-cache-admin show username

# Invalidate specific user's cache (secure deletion)
ob-cache-admin invalidate username

# Invalidate all cached credentials
ob-cache-admin invalidate-all

# Unlock a locked account
ob-cache-admin unlock username

# Remove invalid/orphaned files
ob-cache-admin cleanup

Security notes:

• Requires root privileges (cache files owned by root)
• Never displays passwords or hashes
• Uses shred for secure file deletion
• Unlock cannot modify encrypted lockout state directly; offers invalidation instead

Offline authentication events are logged to:

• Syslog (via PAM)
• Structured audit log (/var/log/open-bastion/audit.json)

Look for:

• offline_auth_success: User authenticated via cache
• offline_auth_failure: Failed offline authentication attempt
• offline_cache_locked: User locked out due to failed attempts

1. Generate a key file: Use ob-desktop-setup --offline or create manually (dd if=/dev/urandom of=/etc/open-bastion/cache.key bs=32 count=1)

2. Set appropriate TTL: Default 7 days; reduce for high-security environments

3. Enable disk encryption: Use LUKS or similar for the system drive

4. Monitor lockouts: Check ob-cache-admin stats for unusual patterns

5. Regular cleanup: Run ob-cache-admin cleanup periodically via cron

6. Disable when not needed: Set auth_cache_enabled = false to eliminate the attack surface entirely

When a user authenticates offline and the network returns, the system revalidates the session via three mechanisms:

Anti-firewall-bypass protection: If the SSO portal is unreachable despite network being available (possible local firewall manipulation), all offline sessions are terminated after offline_max_sso_unreachable seconds (default: 1h).

To report security vulnerabilities, please email [email protected] with:

1. Description of the vulnerability
2. Steps to reproduce
3. Potential impact
4. Any suggested fixes (optional)

• We will acknowledge your report within 48 hours
• We will keep you informed of our progress
• We will credit you in the security advisory (unless you prefer anonymity)
• We will not take legal action against researchers who follow responsible disclosure

Only the latest minor version receives security updates. We recommend always running the latest release.

• Security issues are fixed in private and released as part of a new version
• Security advisories are published after the fix is available
• Critical vulnerabilities may receive expedited patches

For detailed information about the security architecture and implementation:

• Security Architecture - Transport security, authentication, encryption
• Enrollment Security - Server enrollment security analysis
• SSH Connection Security - SSH authentication and authorization
• Offboarding Procedures - Revocation and deprovisioning
• Future Improvements - Planned security enhancements

When deploying Open Bastion:

1. Use TLS 1.3 - Set min_tls_version = 13 in configuration
2. Enable audit logging - Set audit_enabled = true for security monitoring
3. Enable rate limiting - Enabled by default, protects against brute-force
4. Restrict file permissions - Configuration files should be 0600 owned by root
5. Use certificate pinning - For high-security environments, pin the LLNG server certificate
6. Never enable debug logging in production - Debug logs may contain sensitive information