Skip to content

Security: rodacato/SheLLM

SECURITY.md

Security Policy

Architecture

The isolation floor for a served request — what each protection is, what enforces it, the risks accepted and what is deferred until the CLIs get tools back — is recorded in ADR-0011.

SheLLM is designed as an internal service. It is not intended to be exposed to the public internet.

Network Isolation

  • The service binds to 127.0.0.1 (loopback) in production — only accessible from the same host
  • No TLS termination is performed by SheLLM — this is the responsibility of the reverse proxy (if any)
  • Multi-client bearer token authentication managed via the Admin API. Set SHELLM_REQUIRE_AUTH=true (default) to reject all requests when no API keys are configured. Network isolation remains the primary trust boundary in production; bearer tokens add defense-in-depth.
  • Rate limiting: Global + per-client sliding window (requests per minute). Prevents abuse even from trusted internal clients.
  • Auth failure alerting: A spike in auth failures above SHELLM_AUTH_ALERT_THRESHOLD per minute fires a webhook to SHELLM_ALERT_WEBHOOK_URL for incident response.

Admin Authentication Hardening

The admin dashboard (/admin/*) authenticates in two ways against the same SHELLM_ADMIN_PASSWORD:

  • Browsers sign in at /admin/login and get a session cookie: HMAC-signed with a key derived from the database's key-hashing secret, HttpOnly, SameSite=Lax, Secure behind TLS, scoped to /admin, renewed while in use (lifetime and renewal interval in src/middleware/admin-session.js), cleared by POST /admin/logout. Lax rather than Strict because some browsers treat launching the installed app from the home screen as arriving from another site and drop a Strict cookie; a cross-site POST still carries no Lax cookie, and the Sec-Fetch-Site check below refuses it regardless. Sessions are stateless — there is nothing to steal from the server, and rotating the secret invalidates every one of them.
  • Scripts keep using HTTP Basic, so curl -u admin:… /admin/keys still works.

A cookie-authenticated request that is not a GET is refused when the browser reports Sec-Fetch-Site as anything but same-origin, which is what stops a cross-site form from using the session.

Dashboard assets and the service worker

The SPA's own files (JS, CSS, images, the manifest and the worker) are served without a session — they carry no account data — while /admin/dashboard/ itself and every /admin/* API route need one. The service worker caches that shell and the CDN scripts, stylesheets and fonts it loads, and nothing else: it ignores non-GET requests, any other origin, and any path outside its hardcoded shell list, so no key, log or provider response is ever written to a device's cache.

Brute-force protection: Failed login attempts are tracked per IP address using an in-memory sliding window. After SHELLM_ADMIN_MAX_ATTEMPTS failures within the window, further attempts from that IP are rejected with 429 Too Many Requests and a Retry-After header.

Audit logging: All admin authentication attempts (success and failure) are logged via the structured JSON logger. Failed attempts include: IP address, attempted username, and failure reason (missing_header, invalid_encoding, invalid_format, wrong_password, wrong_username). Successful attempts log the IP and username at info level.

Password strength enforcement: At startup, if SHELLM_ADMIN_PASSWORD is set, the service warns if the password is shorter than 12 characters or matches a list of commonly used weak passwords. In production (NODE_ENV=production), the server refuses to start with a weak password.

Password env cleanup: After reading SHELLM_ADMIN_PASSWORD into a closure, the value is deleted from process.env to prevent accidental leakage to subprocesses.

Username validation: Optionally, set SHELLM_ADMIN_USER to restrict admin access to a specific username. When not set (default), any username is accepted with the correct password. When set, username comparison uses crypto.timingSafeEqual.

Security headers: The admin dashboard (/admin/dashboard/*) is served with restrictive headers:

  • X-Frame-Options: DENY — prevents clickjacking
  • X-Content-Type-Options: nosniff — prevents MIME sniffing
  • Content-Security-Policy — restricts script/style sources to self + CDNs (Tailwind, Alpine.js)
  • Referrer-Policy: no-referrer — prevents URL leakage
  • Cache-Control: no-store — prevents caching of admin pages

Client Key Management

Client API keys are managed via the Admin API (/admin/keys). Keys are stored hashed using HMAC-SHA256 with a server-side secret (auto-generated or via SHELLM_HMAC_SECRET). Legacy SHA-256 hashes are auto-upgraded to HMAC on first successful auth.

  • Production: Database file stored on VPS (owned by shellmer user, mode 600, directory mode 700)
  • Development: In-memory or file DB — when no keys exist and SHELLM_REQUIRE_AUTH=false, auth is disabled
  • Key expiration: Expired keys are automatically marked inactive by a daily cleanup job
  • Pre-commit hook: scripts/pre-commit scans staged changes for client keys (shellm-<32 hex>), provider API keys (sk-…) and a literal CLAUDE_CODE_OAUTH_TOKEN. npm install installs it by pointing core.hooksPath at scripts/

Auth Token Handling

SheLLM manages auth tokens for two CLI tools. These tokens are equivalent to API keys and must be treated accordingly.

Provider Where the credential lives
Claude Code CLAUDE_CODE_OAUTH_TOKEN in the config file, ~shellmer/.config/shellm/env (mode 600); the CLI's own state is in ~shellmer/.claude/
Codex CLI ~shellmer/.codex/

Rules:

  • Auth token directories live in the shellmer user's home directory on the VPS, outside the checkout entirely — there is nothing for .gitignore to exclude
  • Rotate them as the service user (sudo -iu shellmer): claude setup-token, then replace CLAUDE_CODE_OAUTH_TOKEN in the config file and restart; codex login for codex

Input Handling

Prompt text passes through sanitization before reaching a CLI subprocess. The request body size is capped by SHELLM_MAX_CHAT_BODY_BYTES.

Sanitization (src/middleware/sanitize.js)

  • NFKC normalization — canonicalizes Unicode to prevent homoglyph and fullwidth character bypasses
  • Zero-width character stripping — removes U+200B-200F, U+2028-202F, U+FEFF, U+00AD
  • Null bytes (\0) are stripped — prevents injection in C-based CLI parsers
  • Carriage returns (\r) are normalized — prevents log injection

Subprocess Safety

What a spawned CLI is prevented from doing — nothing the caller wrote in argv, no shell, an allowlisted environment, a per-request working directory, a timeout that kills the whole process group — is the floor table in ADR-0011, with the file that enforces each row. Two more:

  • NO_COLOR=1 is injected, and ANSI escape codes and control characters are stripped from CLI output
  • With no input, stdin is ignore, so a CLI never hangs on an interactive prompt

Health Endpoint

  • GET /health — returns only { status: "ok" } (unauthenticated liveness probe)
  • GET /health/detailed — returns full provider status, queue depth, circuit breakers (requires admin auth)

Accepted Risks

  • Provider account suspension: SheLLM drives subscription CLIs on your behalf. Volume that looks automated can get an account suspended, and with it every product tied to it. See Fair use and provider terms.

Claude CLI --dangerously-skip-permissions

The Claude CLI provider uses --dangerously-skip-permissions so a one-shot request never stops to ask. The flag removes the prompt, not the sandbox. Compensating controls:

  • The CLI's own tools are off — --tools '', plus --disable-slash-commands, --strict-mcp-config and disableAllHooks (ADR-0002). There is nothing for skipped permissions to authorize.
  • Each request runs in its own temp directory outside the checkout, so a tool that did run would find no code.
  • The systemd unit sandboxes the process and every CLI it spawns: ProtectSystem=strict, ReadOnlyPaths=/home/shellmer/shellm (the service cannot write the code it runs), PrivateTmp=yes, NoNewPrivileges=yes.
  • The service runs as the unprivileged shellmer user, never root.
  • SHELLM_CLAUDE_SKIP_PERMISSIONS=false disables the flag.

Claude CLI Installer

scripts/setup/vps.sh installs Claude Code with curl https://claude.ai/install.sh | bash -s <version>, pinned in config/cli-versions/package.json and run as the unprivileged service user. The installer publishes no checksum, so the pin is what makes an install reproducible.

CSP unsafe-inline / unsafe-eval

The admin dashboard CSP allows unsafe-inline and unsafe-eval for Tailwind CSS CDN and Alpine.js. Mitigated by: the dashboard requires admin authentication — an HMAC-signed session cookie in the browser, HTTP Basic for scripts — and is not public-facing.

What This Service Does NOT Protect Against

  • Prompt injection: SheLLM does not inspect prompt content. A pattern-based guard was removed in 2026-09 because it blocked ordinary coding prompts while missing real injections; isolating what the CLI can reach is the defense that works.
  • PII exposure: SheLLM does not inspect prompt content. Callers must anonymize data before sending it.
  • Rate limiting bypass: A compromised client key still allows requests up to its RPM limit.
  • CLI vulnerabilities: If a CLI tool has a vulnerability, SheLLM inherits it. A host runs the versions its release pins, so a fix reaches it when the pin moves (VERSIONS.md).

Supported Versions

Only the latest released version receives security patches. See CHANGELOG.md for the current version.

Reporting Vulnerabilities

Do not open a public issue. Report privately through GitHub private vulnerability reporting (Security → Report a vulnerability) with:

  • A description of the vulnerability
  • Steps to reproduce it
  • The potential impact
  • A suggested fix, if you have one

Disclosure timeline

  • 0 days — reported
  • 48 hours — acknowledgment
  • 7 days — assessment and fix development
  • 30 days — fix released and advisory published

The advisory is the point. SheLLM is self-hosted: an operator running an older copy learns they must upgrade from the published advisory and from nothing else, so a silent patch leaves them exposed. It is drafted privately and published only once the fix has shipped.

Severity

SheLLM holds credentials for the operator's own LLM subscriptions. Anything touching admin authentication, the key store, or subprocess construction is treated as high severity by default.

Scope

In scope: authentication and authorization bypass, command and prompt injection reaching a subprocess, key or token disclosure, SSRF through a provider gateway, and anything that exposes one client's traffic to another.

Out of scope: vulnerabilities in third-party dependencies (report those upstream), denial of service, social engineering, and anything requiring access to the host the operator already controls. The accepted risks named above are accepted, not vulnerabilities.

Dependency Policy

  • Minimize dependencies. The runtime set is dependencies in package.json, kept small on purpose. Every additional package increases supply chain risk.
  • Audit before adding. Before adding any dependency, verify: maintenance status, download count, known vulnerabilities (npm audit), and whether a built-in alternative exists.
  • Lock versions. package-lock.json is committed and used for reproducible installs (npm ci).
  • No postinstall scripts. If a dependency runs scripts on install, evaluate whether it's worth the risk.
  • CI audit: CI runs npm run audit:security, which fails on high/critical vulnerabilities.

Runtime Security

  • In production, the service runs as a dedicated non-root user (shellmer) on the VPS via systemd
  • Bound to loopback and reached through a tunnel, reverse proxy or private network that terminates TLS (deployment guide)
  • The unit sets no memory or CPU limit; MAX_CONCURRENT and the rate limits are what bound load
  • LOG_LEVEL=debug in production emits a startup warning (may expose sensitive data)

There aren't any published security advisories