Security Policy

Security Philosophy

Capacitarr is developed using AI-assisted coding ("vibe coding"). We believe this makes rigorous, transparent security practices more important, not less. Every line of code — whether human-written or AI-generated — passes through the same gauntlet of static analysis, dependency scanning, container scanning, and dynamic application security testing before it reaches a release.

This document is our commitment to transparency. Every security exception, suppression, and allowlist entry is individually documented with rationale — not hidden in config files. We want you to be able to audit our security posture yourself.

We actively welcome independent security assessments. If you run a scan, penetration test, or code review and find something, we want to hear about it. We will prioritize investigating and remediating any findings brought to our attention. See Reporting a Vulnerability below for how to reach us.

Supported Versions

Only the latest stable release receives security fixes. Pre-release versions (alpha, beta, RC) are not covered.

Reporting a Vulnerability

If you discover a security vulnerability, please report it privately:

1. GitHub: Open a security advisory (private by default)
2. Email: Send details to the project maintainer listed in CONTRIBUTORS.md

Do not open a public issue for security vulnerabilities.

What to Include

• Description of the vulnerability
• Steps to reproduce
• Affected version(s)
• Potential impact assessment
• Suggested fix (if you have one)

Response Timeline

• Acknowledgment: Within 72 hours
• Initial assessment: Within 1 week
• Fix release: Dependent on severity; critical issues target a patch release within 2 weeks

Security Model

Capacitarr is designed as a self-hosted, single-instance application for home lab environments. The security model reflects this:

Authentication

• Password authentication: bcrypt-hashed passwords (cost factor 12)
• JWT sessions: HMAC-SHA256 signed tokens with 24-hour expiry. Set JWT_SECRET for persistent sessions across restarts
• API keys: SHA-256 hashed before storage; plaintext shown once on generation and never stored
• Reverse proxy auth: Optional trusted header authentication (AUTH_HEADER) for SSO integration (Authelia, Authentik, Organizr)

Data Protection

• Integration API keys: Stored in plaintext in the SQLite database. This is an accepted trade-off: full encryption-at-rest would require a master key, adding complexity with minimal practical benefit when the database file is on a user-owned machine. Ensure the /config volume has restrictive file permissions (chmod 600)
• API key masking: Integration API keys are masked in all API responses (only last 4 characters visible)
• Cookie security: Set SECURE_COOKIES=true when serving over HTTPS

Network Security

• SSRF protection: All user-provided URLs are validated to use HTTP or HTTPS schemes only
• CORS: Same-origin by default; explicit CORS_ORIGINS configuration required for cross-origin access
• Rate limiting: Three endpoints are rate-limited per IP address to prevent abuse:
  • Login: 10 attempts per 15-minute window
  • Integration connection test: 30 attempts per 5-minute window
  • Engine manual run: 5 attempts per 5-minute window
• Response body limits: Upstream API responses are capped at 64 MiB via io.LimitReader to prevent denial-of-service from oversized responses
• Security headers: All responses include:
  • Content-Security-Policy — restricts resource loading to same-origin with per-request cryptographic nonces for inline scripts (script-src uses nonce-based allowlisting; connect-src, font-src, frame-ancestors, base-uri, form-action are same-origin)
  • Strict-Transport-Security — HSTS with 2-year max-age (only when SECURE_COOKIES=true)
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • Referrer-Policy: strict-origin-when-cross-origin
  • Permissions-Policy: camera=(), microphone=(), geolocation=()
  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Resource-Policy: same-origin
  • X-Permitted-Cross-Domain-Policies: none

CI Security Scanning (SAST + SCA)

Every push and pull request is scanned by 7 static security tools. All are blocking — failures prevent merge. Run all scans locally with: make security:ci

Tool Inventory

Gitleaks Configuration (.gitleaks.toml)

Gitleaks scans the entire git history for accidentally committed secrets. The following paths are allowlisted because they contain intentional example/test credentials, not real secrets:

All allowlisted patterns are documented in .gitleaks.toml with rationale. Gitleaks remains active for all production source code, configuration files, and scripts.

Semgrep Configuration (.semgrepignore and nosemgrep)

Semgrep scans all Go and Vue/TypeScript source files (every file tracked by git except the marketing site). Test files, utility files, and all production code are scanned.

.semgrepignore exclusion — 1 directory:

Files skipped by Semgrep's built-in 1 MB size limit — 7 files:

Inline nosemgrep annotations — every suppressed finding with rationale:

Inline nolint annotations — every suppressed golangci-lint finding with rationale:

Semgrep partial-parse warnings (files that are scanned but where Semgrep's parser can't fully parse certain syntax):

Dynamic Application Security Testing (DAST)

In addition to static analysis, Capacitarr is tested with OWASP ZAP — the industry-standard open-source DAST tool. ZAP makes real HTTP requests with attack payloads against a running instance, testing for the OWASP Top 10 and 50+ additional vulnerability categories.

Run locally: make build && make security:zap

Latest baseline (2026-04-06, pre-release scan for v3.1.0): 119 rules tested (53 active + 66 passive), 118 PASS, 0 FAIL, 1 WARN

The full test-by-test breakdown with rule IDs is in docs/security/zap-baseline-20260406.md. Previous baselines: 2026-03-24, 2026-03-23, 2026-03-16, 2026-03-10.

Testing cadence: Run DAST scanning (make security:zap) before each release, after significant code changes affecting HTTP handlers or authentication, and periodically as part of routine security hygiene. The baseline should be updated in this document after each scan.

Temporary Workarounds — pnpm audit Registry 410

As of 2026-04-15, the npm registry retired both legacy audit endpoints (/-/npm/v1/security/audits and /-/npm/v1/security/audits/quick), returning HTTP 410 Gone. This breaks pnpm audit on all pnpm 10.x versions and 11.0.0-rc.0. The upstream fix is tracked in pnpm/pnpm#11265.

Workaround applied: The --ignore-registry-errors flag has been added to pnpm audit in both the Makefile (security:ci target) and .github/workflows/ci.yml (security-pnpm-audit job). This prevents the 410 response from failing the CI pipeline.

Impact on security posture: Minimal. The --ignore-registry-errors flag means pnpm audit will pass even if the registry is unreachable, but Trivy filesystem scanning (security:trivy) independently scans all Node.js dependencies for HIGH/CRITICAL CVEs using the same vulnerability databases. The pnpm.overrides policy (see below) continues to enforce patched dependency versions at install time.

When to remove: Once pnpm ships a release that uses the new bulk advisory endpoint (/-/npm/v1/security/advisories/bulk), remove the --ignore-registry-errors flag from the Makefile and CI workflow, and delete this section.

Dependency Override Policy (pnpm.overrides)

When transitive npm dependencies have known vulnerabilities but the upstream parent package (e.g., Nuxt, ESLint) has not yet released an update with a patched version, we use pnpm.overrides in frontend/package.json to force the patched version. This ensures:

• The security:pnpm-audit CI job continues to enforce zero known vulnerabilities as a blocking gate
• Shipped Docker images contain patched dependency versions, not just silenced findings
• The security posture is not weakened by allow_failure or audit --ignore flags

Current overrides (as of 2026-04-05):

When to remove overrides: After upstream packages release versions that natively depend on the patched versions, pnpm audit will pass without overrides. At that point, remove the override entries and verify. Overrides that remain after upstream updates are harmless (they match or are lower than the naturally resolved version) but should be cleaned up for hygiene.

When adding new overrides: Add the override to frontend/package.json, update this table, and include the advisory URL in the commit message. Run pnpm install to regenerate the lockfile and pnpm audit to verify.

Gosec G117 — JSON Secret Field Policy

Gosec rule G117 flags exported struct fields whose JSON key names match secret patterns (password, apiKey, token, secret). The rule aims to prevent accidental serialization of sensitive data — for example, a secret leaking into logs when a struct is formatted with %+v or marshaled to JSON in an error response.

How Capacitarr handles this:

1. All internal structs use json:"-" tags on secret fields. This includes:
   • config.Config.JWTSecret — application configuration
   • db.AuthConfig.Password and db.AuthConfig.APIKey — user credentials
   • All integration client structs (EmbyClient.APIKey, PlexClient.Token, etc.)
   
   These fields are never serialized to JSON. The json:"-" tag is the correct structural fix for G117 and prevents accidental exposure regardless of how the struct is used.
2. Three files are excluded from G117 via per-file linter exclusion. These files define structs where secret-pattern JSON keys are part of the REST API contract:
   • internal/db/models.go — IntegrationConfig.APIKey (json:"apiKey") is the user-configured integration credential. It is masked before inclusion in any API response; only the last 4 characters are visible.
   • routes/auth.go — LoginRequest.Password (json:"password") accepts the user's password for authentication. This struct is decode-only and is never JSON-encoded.
   • routes/integrations.go — Connection test request accepts an API key. Decode-only, never JSON-encoded.
   
   These exclusions are defined in backend/.golangci.yml using path+text matching. G117 remains active for all other files — any new struct with a secret-pattern JSON key will be flagged and must be addressed with either a json:"-" tag or an explicit addition to the exclusion list after security review.

Why not a global G117 exclusion? A global exclusion would silently pass any future struct that accidentally exposes a secret field in JSON. The per-file approach ensures that each exemption is explicitly documented and the rest of the codebase remains protected.

Container Hardening

The official Docker image uses a hardened Alpine runtime:

• Alpine digest pinned: The runtime base image is pinned to a specific SHA-256 digest for reproducible, auditable builds. The digest is updated periodically (or via Renovate Bot) to pick up security patches
• Package manager removed: apk is deleted after installing runtime dependencies (ca-certificates, tzdata, su-exec). An attacker with code execution cannot install additional tools
• No curl/wget packages: Healthchecks use busybox wget (built into Alpine's busybox), eliminating the curl package from the attack surface
• Capabilities dropped: cap_drop: ALL removes all Linux capabilities, then cap_add restores only the 4 needed by the PUID/PGID entrypoint: CHOWN (chown /config), DAC_OVERRIDE (create user in /etc/passwd), SETUID/SETGID (su-exec drops to PUID:PGID). The Go binary itself needs zero capabilities
• No privilege escalation: no-new-privileges: true prevents any child process from gaining privileges via setuid/setgid binaries
• Non-root execution: The entrypoint.sh creates a user with the configured PUID/PGID and uses su-exec to drop from root to that user before starting the application

Optional additional hardening for advanced users:

# Add to your docker-compose.yml for maximum lockdown:
services:
  capacitarr:
    read_only: true        # Immutable root filesystem
    tmpfs:
      - /tmp:size=10M      # Writable temp directory in RAM
    user: "1001:1001"      # Fixed UID/GID (replaces PUID/PGID env vars)

Note: read_only: true requires using user: instead of PUID/PGID because the PUID/PGID entrypoint writes to /etc/passwd at startup. The /config volume is always writable regardless of read_only.

Supply Chain Security — Docker Image Pinning

All Docker images used in CI pipelines and local Makefile targets are pinned to specific version tags rather than :latest. This prevents silent supply chain attacks where a compromised upstream image could propagate into our build and security scanning pipeline.

Pinning Policy

• No :latest tags: Every Docker image reference in CI workflows and Makefile must use a specific version tag (e.g., :0.69.3, :v2.11.4, :3.21)
• No curl-pipe-to-shell: CI jobs must not download and execute scripts from external URLs at runtime. All tools must be consumed via their official Docker images
• Makefile ↔ CI parity: Every tool version in CI workflows must match the corresponding version in the Makefile. Both files are updated together. Note: CI uses GitHub Actions (which install tool binaries directly), while the Makefile uses Docker images. Tool versions are kept in sync even though the delivery mechanism differs
• Digest pinning for runtime image: The production Dockerfile runtime base image (alpine) is pinned to a specific SHA-256 digest for reproducible, auditable builds

Regular Re-evaluation

Pinned Docker image versions are re-evaluated on a regular basis to pick up security patches and new features:

1. Check each pinned image for newer stable releases
2. Pull and test updated versions locally with make ci
3. Update version tags in both Makefile and CI workflows
4. Update the Dockerfile runtime base image digest if a new Alpine patch is available
5. Commit with chore(deps): bump <tool> to v<version>

Currently Pinned Images

Note on ZAP :stable tag: The OWASP ZAP proxy image (ghcr.io/zaproxy/zaproxy) uses the :stable tag because ZAP does not publish individually versioned image tags. The :stable tag tracks the latest stable release. This is an accepted exception to the pinning policy — ZAP is used only for local DAST scanning (make security:zap), not in CI pipelines, so a compromised image cannot affect builds or releases.

Note on crane: The crane CLI tool (from google/go-containerregistry) is used in the release pipeline to mirror multi-arch Docker images from GHCR to Docker Hub. It is currently installed via curl-pipe-to-shell in the GitHub Actions workflow (release.yml), which is a known deviation from the "no curl-pipe-to-shell" policy. This is being tracked for remediation (e.g., switching to a pre-built Docker image or a pinned GitHub Action).

Next reassessment date: 2026-04-27

Important Caveats

• AUTH_HEADER trust model: When enabled, Capacitarr unconditionally trusts the configured header. The server must be behind a reverse proxy that sets this header. Direct internet exposure with AUTH_HEADER enabled allows authentication bypass
• Single-user design: Capacitarr does not implement role-based access control. All authenticated users have full access
• Local network assumption: The security model assumes the application runs on a trusted local network or behind a reverse proxy