Last audited: 2026-03-17

• Security Architecture
  • For Users
    • Authentication
    • Data Classification
    • Encryption at Rest
    • Route Protection
    • Data Protection
    • Input Validation
    • Security Response Headers
    • Threat Model
    • Is There Any Telemetry Baked In?
    • Username Privacy Mode
    • Known Limitations
    • Unmitigated Attack Vectors
      • 1. Disk Seizure / Physical Access
      • 2. Compromised Host / Memory Dump
      • 3. Correlation Attack on Masked Usernames
      • 4. Network Traffic Analysis
      • 5. Tracker-Side Logging
      • 6. DNS Rebinding
    • Backup Security
      • Data Handling
      • Authentication
      • Optional Encryption Layer
      • Restore Safety
      • File Security
    • Deployment Hardening
    • Vulnerability Reporting
  • For Contributors
    • Security Testing
    • CI Integration
    • Static Security Audit
      • Inline Suppression
    • Security Review Checklist
      • Pre-Flight (run every PR)
      • 1. Authentication & Authorization
      • 2. Input Validation
      • 3. XSS Prevention
      • 4. Encryption & Secrets
      • 5. Session Security
      • 6. External Requests
      • 7. Database Operations
      • 8. File Operations
      • 9. Security Headers
      • 10. Docker & Deployment
      • Quick Verification Commands
    • Huntarr Anti-Pattern Checklist

• Password hashing: Argon2 (memory-hard KDF) — src/lib/auth.ts
• Session tokens: Encrypted JWE (A256GCM) via jose — src/lib/auth.ts
• Cookie security: httpOnly, secure (when BASE_URL is HTTPS or SECURE_COOKIES=true), sameSite=strict, 7-day hard expiry
• Password policy: 8-128 characters enforced on setup and login
• Username: Optional login username (6-100 chars), case-insensitive
• TOTP 2FA: Optional TOTP via otpauth (SHA1, 6 digits, 30s period, ±1 window). Secret encrypted at rest with AES-256-GCM. Stateless enrollment via JWE setup tokens (5min TTL).
• Backup codes: 8 codes in XXXX-XXXX hex format, hashed with SHA-256 + random salt, encrypted at rest. Each code is single-use.
• Two-step login: When TOTP is enabled, login returns a pending token (60s JWE). The client sends the pending token + TOTP code to complete authentication.
• Auth model: No whitelist or bypass — every API route independently calls authenticate(), which decrypts the JWE session.

Disk seizure note: If an adversary accesses the raw database files, all unencrypted fields above are readable. Deploy on an encrypted filesystem (LUKS, dm-crypt, or equivalent). See Known Limitations.

All tracker API tokens are encrypted before database storage — src/lib/crypto.ts.

The encryption key is derived from the master password on login and stored in the encrypted JWE session. It is never persisted to disk in plaintext.

The scheduler key (used to decrypt API tokens during background polling) is wrapped with a separate HKDF-derived key from SESSION_SECRET and stored in appSettings.encryptedSchedulerKey. This enables polling to run 24/7, surviving both container restarts and user logouts. The key is only cleared on destructive operations: lockdown, nuke, password change, and restore. If SESSION_SECRET is rotated, the stored key becomes undecryptable and polling will resume after the next login.

Authentication is enforced at three independent levels:

1. Proxy (src/proxy.ts): Checks for tt_session cookie on all non-public routes. Returns 401 for API routes; redirects to /login for pages.
2. Route handlers: Each API route calls authenticate() from src/lib/api-helpers.ts, which decrypts and validates the full JWE token.
3. Layout guard (src/app/(auth)/layout.tsx): Server Component calls getSession() before rendering any authenticated page.

Public routes are explicitly limited to: /login, /setup, /api/auth/*, /api/health.

• encryptedApiToken is never included in API responses — serializeTrackerResponse() in src/lib/tracker-serializer.ts uses an allowlist pattern; the token is structurally unreachable from the response object.
• All database queries use Drizzle ORM (parameterized queries, no SQL injection surface).
• No unsafe HTML injection methods anywhere in the codebase.
• Emergency lockdown (POST /api/settings/lockdown): Stops scheduler, revokes all API tokens, rotates encryption salt, wipes TOTP/username, destroys session. Requires active session and three-checkbox UI acknowledgment.
• Scrub & delete (POST /api/settings/nuke): Overwrites sensitive columns with random bytes, then deletes all rows. Requires active session + master password. Disk reclamation handled by PostgreSQL autovacuum.
• Backup/restore: Pure JSON format (no zip/tar). Restore validates all fields before database writes. File deletion uses path.resolve() + base directory prefix check. Restore requires master password re-confirmation. Encrypted fields travel as ciphertext. See Backup Security.
• External HTTP requests use AbortSignal.timeout(15_000) — src/lib/adapters/unit3d.ts:29.
• Error messages sanitize hostnames and do not leak full URLs containing API tokens.

All API routes validate inputs — src/app/api/trackers/route.ts, src/app/api/trackers/[id]/route.ts.

Configured in next.config.ts for all routes:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 0 (disables legacy XSS auditor; prevents IE/Edge quirks)
• X-DNS-Prefetch-Control: off (prevents DNS prefetching which can leak browsing activity)
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy: camera=(), microphone=(), geolocation=()

Nope 😎

Optional privacy mode (Settings → Store Usernames) controls whether tracker usernames and user classes are persisted to the database.

When disabling, you can optionally scrub historical data to retroactively replace all previously stored usernames with their masked equivalents.

The character-count mask is not strong anonymization. An investigator with database access could cross-reference the character count with ratio, upload volume, and user class to narrow down the account. For stronger protection, combine privacy mode with full-disk encryption (see Deployment Hardening).

The test-connection flow (POST /api/trackers/test) always returns the real username for confirmation. This value is ephemeral — displayed in the browser, never written to the database.

1. Progressive lockout only (no IP-based rate limiting): Failed login and TOTP attempts trigger escalating lockouts (5 attempts → 30s, 10 → 2min, 15 → 15min, 20 → 1hr) via getProgressiveLockoutMs() in src/lib/wipe.ts. The counter is global (not per-IP), so an unauthenticated attacker can lock out the legitimate user. Deploy behind a reverse proxy with per-IP rate limiting on /api/auth/login for additional protection.
2. API token in URL parameter: UNIT3D (?api_token=TOKEN) and GGn (?key=TOKEN) pass tokens in the query string, which may appear in the tracker's server access logs. Gazelle trackers use Authorization headers (not logged by default). Upstream limitation.
3. No CSP header: Content Security Policy is not yet configured due to ECharts canvas rendering complexity. Basic headers (X-Frame-Options, X-Content-Type-Options) are in place.
4. Optional 2FA: TOTP is available but not required. Backup codes use SHA-256 + random salt (not Argon2 — high-entropy generated codes don't need memory-hard KDF).
5. DNS rebinding not mitigated at fetch time: SSRF protection validates hostnames when tracker URLs are saved, not when outbound requests are made. See Unmitigated Attack Vectors for details.
6. Scheduler key persisted in DB: The encryption key is wrapped with an HKDF-derived key from SESSION_SECRET and stored in appSettings to enable 24/7 polling. An attacker with both database access and SESSION_SECRET could unwrap the key and decrypt all API tokens. For Docker Compose deployments, SESSION_SECRET is in the same trust boundary as DB credentials. Deploy on an encrypted filesystem for defense against disk seizure. Rotating SESSION_SECRET invalidates the stored key — polling resumes after the next login.
7. Client IP in auth logs: Failed and successful login attempts include the client IP (from CF-Connecting-IP or the rightmost X-Forwarded-For entry) in server log lines. IPs are never stored in the database. To suppress, configure your reverse proxy to strip these headers before forwarding to the app, or set LOG_LEVEL=error to disable info/warn log events entirely.

These vectors are not fully mitigated at the application layer. Apply the recommended countermeasures at the infrastructure level.

Risk: Physical access to the server exposes all unencrypted database fields — tracker names, base URLs, usernames (unless privacy mode is enabled), and usage statistics. API tokens are AES-256-GCM protected, but all metadata is plaintext.

Countermeasure: Deploy the Docker volume on a LUKS- or dm-crypt-encrypted partition. See Deployment Hardening.

Risk: Root access to a running host allows process memory dumps. The scrypt-derived encryption key is held in scheduler memory for the session duration. With this key, all encrypted API tokens can be decrypted.

Countermeasure: On scheduler stop (triggered by lockdown, nuke, password change, or restore), the encryption key buffer is explicitly zero-filled (Buffer.fill(0)). Logout does not zero the key — the scheduler persists through logout for 24/7 polling. V8 may have created internal copies during GC compaction, but those are not directly inspectable. Standard server hardening also applies: patched OS, SSH key auth, non-root container.

Risk: The character-count mask (▓7 for a 7-character username) combined with ratio, upload volume, and tracker name may allow cross-referencing against a tracker's user database. Private trackers typically have small populations (hundreds to low thousands), making this feasible.

Countermeasure: Combine username privacy mode with full-disk encryption. Use the retention policy to limit historical data available for correlation.

Risk: Even over HTTPS, a network observer can see the IP addresses of tracker API endpoints, revealing which trackers the user monitors.

Countermeasure: Route outbound traffic through a VPN or Tor. This is outside the application's scope.

Risk: UNIT3D uses ?api_token=TOKEN and GGn uses ?key=TOKEN — the full URL including the token appears in the tracker's server access logs. Gazelle uses Authorization headers (not logged by default). Upstream limitation.

Countermeasure: None at the application level. Users should be aware that API tokens may appear in tracker server logs depending on the platform.

Risk: SSRF protection in src/lib/network.ts validates hostnames at configuration time, not at request time. An attacker with DNS control could register a domain that resolves to a public IP during validation, then change it to a private IP before the next poll cycle.

Countermeasure: Low risk — single user, manually entered URLs. Deploy on an isolated network segment where the container cannot reach internal services. A future enhancement could add DNS resolution validation at fetch time.

The backup/restore system (src/lib/backup.ts, src/app/api/settings/backup/) maintains the following invariants:

• Encrypted fields travel as ciphertext — encryptedApiToken, totpSecret, encryptedProxyPassword, encryptedUsername, encryptedPassword are never decrypted during backup generation.
• Password hash excluded — app_settings.password_hash is never included in backup files. The restoring user's current password is preserved.
• Encryption salt included — required to re-derive the encryption key from the master password after restore.
• Failed login counter reset — failedLoginAttempts is always set to 0 on restore, regardless of the backup's value.

• All four backup routes (export, restore, history, delete) require a valid session via authenticate().
• Restore requires master password re-confirmation — failed verification increments the failed login counter and triggers lockout.

When backupEncryptionEnabled is true, the entire backup JSON is wrapped in an additional AES-256-GCM layer using the session's encryption key. An encrypted backup (.ttbak) can only be restored with the same master password that created it.

• Restore executes inside a PostgreSQL transaction — any failure rolls back all changes.
• The scheduler is stopped before restore begins (encryption key zeroed).
• The session remains valid after restore. The current encryptionSalt and passwordHash are never overwritten — they are preserved in place. Encrypted fields are re-encrypted from the backup's salt to the current salt via reencryptField().
• BigInt values are serialized as decimal strings (not JSON numbers) to avoid 53-bit integer truncation.

• Backup files are pure JSON — no zip/tar archives, eliminating zip slip attack surface.
• Scheduled backups write to a configurable directory with mkdir({ recursive: true }).
• File deletion validates the resolved path against backupStoragePath using path.resolve() + startsWith(base + path.sep).
• On-demand exports are returned as a browser download and saved to the configured backupStoragePath. If the disk write fails, the browser download still proceeds.

• Encrypted filesystem: Mount the PostgreSQL data volume on a LUKS-encrypted partition. This is the most effective defense against disk seizure.
• Non-root container: The Dockerfile runs as nextjs (UID 1001). Verify with docker exec <container> whoami.
• Read-only filesystem: Mount the application container root as read-only (read_only: true in docker-compose) with tmpfs for /tmp.
• Network isolation: Place PostgreSQL on an internal Docker network with no published ports.
• Reverse proxy: Deploy behind Nginx, Caddy, or Traefik with TLS termination and rate limiting on /api/auth/login.
• NODE_ENV=production: Required for Next.js production optimizations. Cookie secure flag is controlled separately via BASE_URL scheme or SECURE_COOKIES=true.
• SESSION_SECRET: Minimum 32 characters of cryptographically random data. Generate with: openssl rand -base64 48.

If you discover a security vulnerability:

1. Do NOT open a public issue for critical/high severity findings.
2. Use GitHub's private vulnerability reporting on this repository.
3. Alternatively, contact the maintainer directly via the email in the git commit history.
4. Include: description, reproduction steps, impact assessment, and suggested fix if possible.
5. Allow reasonable time for a fix before public disclosure.

Security invariants are verified by 106 automated tests in src/lib/__tests__/security.test.ts:

Additional security-relevant tests exist across other test files.

Run the full test suite:

pnpm test:run

The GitHub Actions workflow (.github/workflows/ci.yml) runs on every push and PR to main:

1. Type check (pnpm tsc) — catches type errors before runtime
2. Full test suite (pnpm test:run) — all 2050+ tests including security invariants
3. Security test count guard — fails the build if the security test count drops below 78, preventing accidental removal of security tests
4. Static security audit (scripts/security-audit.ts) — runs on every PR, comments results on the PR, and fails on critical findings

The count guard ensures security coverage is monotonically non-decreasing. If a security test is removed or refactored, CI fails until the count is restored or the threshold is explicitly updated.

The security audit (scripts/security-audit.ts) performs 28 automated checks on every push and PR:

Critical failures block the build. Warnings are reported but don't block.

Suppress individual findings with an inline comment on the flagged line or the line above:

// security-audit-ignore: stream closed by client disconnect — nothing to recover
} catch { /* stream already closed */ }

Block comments also work: /* security-audit-ignore: reason */

A reason is mandatory. A bare // security-audit-ignore without a colon and explanation is itself a critical failure.

Run locally: npx tsx scripts/security-audit.ts

Run this checklist when adding new features, modifying API routes, or before releases.

pnpm tsc                              # Type safety
pnpm test:run                         # Full test suite (including 78+ security tests)
npx tsx scripts/security-audit.ts     # Static security audit (28 checks)

• Every new API route calls authenticate() from src/lib/api-helpers.ts as its first operation
• No new public routes added without updating the proxy allowlist in src/proxy.ts (lines 12-14)
• authenticate() failure returns NextResponse.json({ error }, { status: 401 }) — no fallthrough
• Destructive operations (nuke, lockdown, restore) require additional password verification beyond the session
• TOTP-protected flows use the pending token pattern (60s JWE), not direct session issuance
• New settings or admin actions do NOT bypass the three-layer defense: proxy -> layout -> route handler

• All user-supplied strings have a maximum length (str.length > N -> 400)
• URL inputs validated with new URL() + scheme restricted to http:// or https://
• Color inputs validated against hex pattern (/^#[0-9a-fA-F]{3,8}$/)
• Numeric inputs parsed and bounds-checked (poll interval clamped to 15-1440)
• Date inputs regex-validated (/^\d{4}-\d{2}-\d{2}$/) or null
• ID parameters parsed as integers with Number() + Number.isNaN() check
• Platform type validated against allowlist, not open string
• No user input concatenated into SQL — all queries use Drizzle ORM's parameterized API
• File paths from user input validated with path.resolve() + startsWith(basePath + path.sep)

• Zero uses of unsafe HTML injection methods in source files (innerHTML assignment, etc.)
• Zero uses of code-injection-risk functions in source files
• All user data rendered through JSX interpolation ({value}), never as raw HTML
• ECharts tooltip formatter functions only render app-computed data, not raw user strings
• No script tags dynamically constructed from user input
• The static security audit (scripts/security-audit.ts check #2) passes

• API tokens stored via encrypt() from src/lib/crypto.ts — never plaintext in the database
• encryptedApiToken excluded from ALL API response objects (grep for // SECURITY comments)
• passwordHash never included in API responses or backup exports
• Encrypted credentials (encryptedUsername, encryptedPassword, encryptedProxyPassword) excluded from responses
• Password change route re-encrypts all secrets with the new derived key
• SESSION_SECRET is at least 32 characters (checked at startup)
• No secrets in console.log, console.error, or logger calls — hostnames only, never full URLs with tokens
• Error messages from adapter-fetch sanitize to hostname only (no token leakage in stack traces)

• Session cookie set with: httpOnly: true, sameSite: "strict", secure: shouldSecureCookies(), path: "/"
• Session has hard expiry (7 days) encoded in the JWE payload — not just cookie maxAge
• Destructive operations (lockdown, nuke, password change, restore) zero-fill the encryption key buffer and stop the scheduler. Logout preserves the scheduler for 24/7 polling.
• Login returns the encryption key only inside the JWE session — never in the response body
• Failed login attempts increment atomically via recordFailedAttempt() in src/lib/wipe.ts

• All outbound HTTP requests have a timeout (AbortSignal.timeout(15_000) or equivalent)
• Tracker URLs validated at creation time — no open redirects or protocol switching
• Proxy-required trackers (useProxy: true) throw if proxy is unavailable — no fallback to direct connection
• qBT client connections validate host/port — no SSRF via user-configured client addresses
• No user-controlled data in Authorization headers beyond the stored (encrypted) API token

• All queries use Drizzle ORM — no raw SQL strings with interpolated values
• BigInt values serialized as decimal strings in JSON (not Number() which truncates at 2^53)
• Backup restore runs inside a transaction — partial failures roll back cleanly
• scrubAndDeleteAll overwrites sensitive columns with random bytes before deletion
• Failed login counter uses atomic SQL (update + returning) — no TOCTOU race

• File read/delete operations validate resolved path against base directory + path.sep
• Backup format is pure JSON — no zip/tar archives (eliminates zip slip surface)
• No shell commands with user-supplied arguments
• Scheduled backup filenames are server-generated (timestamp-based) — not user-controlled

Verify in next.config.ts:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy: camera=(), microphone=(), geolocation=()
• X-DNS-Prefetch-Control: off

• Container runs as non-root user (UID 1001 nextjs)
• NODE_ENV=production set in Dockerfile (cookie secure flag derived from BASE_URL/SECURE_COOKIES, not NODE_ENV)
• PostgreSQL on internal network — no published ports
• No .env files tracked by git (checked by security audit #7)
• scripts/reset-password-nuclear.mjs not included in production Docker image

# Run static security audit (covers XSS, auth, secrets, headers)
npx tsx scripts/security-audit.ts

# Verify all API routes authenticate (files missing authenticate/getSession)
grep -rL 'authenticate\|getSession' src/app/api/**/route.ts

# Count security tests (must be >= 78)
pnpm test:run -- src/lib/__tests__/security.test.ts 2>&1 | grep 'Tests'

Comparison against the 21 vulnerabilities found in Huntarr v9.4.2 (security review):