Skip to content

Authentication

Jump to bottom
tjnull edited this page Aug 11, 2026 · 1 revision

Authentication & API Security

Leetha includes token-based authentication for securing the web dashboard and REST API when exposed beyond localhost.

When Auth Is Enabled

Authentication is automatically enabled when the web server binds to a non-localhost address (e.g., 0.0.0.0). It is disabled when bound to 127.0.0.1 or ::1.

You can override this with:

  • --auth -- force authentication on
  • --no-auth -- force authentication off

Admin Token

On first startup, Leetha generates an admin token and saves it to ~/.leetha/admin-token. View it with:

leetha auth show-token

Token Management

# List all tokens
leetha auth list-tokens

# Create a new token with a specific role
leetha auth create-token --role analyst --label "readonly-user"

# Revoke a token
leetha auth revoke-token <token-id>

Roles

Role Permissions
admin Full access: settings, capture control, token management, delete alerts, device authorization, bulk auth, baseline/learning window, inventory imports
analyst Read access: devices, alerts, stats. Can acknowledge alerts. Can PATCH device custom properties (owner, location, criticality, tags, notes, presence threshold). Cannot change authorization state, cannot control the learning window, cannot upload inventory files.

Admin-only endpoints

The role gate (leetha/auth/roles.py) enforces admin-only access on:

  • PUT /api/settings, POST /api/settings/apply, POST /api/settings/reset
  • POST /api/capture/restart
  • Token management: /api/auth/tokens, /api/auth/revoke
  • DELETE /api/alerts/*, /api/trust/*, /api/suppressions/*, /api/patterns/*
  • Authorization transitions: POST /api/devices/{mac}/approve, .../reject, .../revoke
  • Bulk authorization: POST /api/devices/bulk/authorization
  • Baseline: POST /api/baseline/finish, POST /api/baseline/restart-learning, POST /api/baseline/clear-attestations, POST /api/baseline/reset
  • Inventory imports: POST /api/inventory/* (e.g. DHCP lease upload)

Analyst tokens that hit an admin-only path receive HTTP 403 with {"error": "Admin access required."}.

Reading authorization state (GET /api/baseline/status, GET /api/devices/{mac}/authorization/history) is available to both roles.

API Authentication

Include the token in the Authorization header:

curl -k -H "Authorization: Bearer ltk_..." https://host/api/devices

WebSocket Authentication

WebSocket connections use the leetha-v1 subprotocol. The auth token is passed as a query parameter or cookie -- the subprotocol name is fixed and no longer echoes the token value:

new WebSocket("wss://host/ws", ["leetha-v1"]);

Cookie Security

When TLS is enabled (the default), the authentication cookie is set with secure=True, ensuring it is only transmitted over HTTPS connections.

Exempt Paths

These paths do not require authentication:

  • /login -- login page
  • /api/health -- health check
  • Static assets (/assets/*)

The /metrics endpoint requires authentication (it is not exempt).

Disabled Endpoints

OpenAPI documentation endpoints are disabled for security hardening:

  • /api/docs -- not available
  • /api/redoc -- not available

Clone this wiki locally