Security Overview

Enterprise and government deployments require auditability at every layer. This page documents every security control in HitKeep — from the HTTP server to the browser, and everything in between.

Zero Third-Party Frontend Requests

When a visitor loads your HitKeep dashboard, their browser makes zero requests to third-party domains. Every asset — the Angular application, fonts, icons, and the tracking snippet — is served from your own instance.

Asset	Source
Angular dashboard (JS, CSS)	your-instance.example.com
PrimeIcons, fonts	Bundled into the Angular app — served from your instance
hk.js tracking snippet	your-instance.example.com/hk.js
Favicon images	Server-side proxied (see below) — no browser-to-third-party requests
API calls	your-instance.example.com/api/* exclusively

This is verifiable: open your browser’s Network tab with HitKeep loaded and filter by third-party requests. There are none.

This matters for:

• Content Security Policy (CSP) — you can write a restrictive default-src 'self' policy without allowlisting external domains
• GDPR Article 44+ — no data transfer to third countries via asset loading
• Zero Trust network policies — HitKeep dashboard users do not need outbound internet access
• Restricted-network deployments — the dashboard works without third-party frontend assets or external analytics calls

Favicon Proxy

The dashboard displays site favicons to help identify tracked domains. Favicons are fetched via DuckDuckGo’s public favicon service (icons.duckduckgo.com), but the request is made server-side by HitKeep, not by the browser.

The browser requests:

GET /api/favicon/{domain}    ← your HitKeep instance only

HitKeep’s server then fetches:

GET https://icons.duckduckgo.com/ip3/{domain}.ico

The browser never contacts DuckDuckGo. The favicon is proxied back with a 24-hour cache header.

Security properties of the proxy implementation:

• Domain is validated and normalized before the upstream request is constructed
• URL is built programmatically using url.URL (no string interpolation) to prevent injection
• HTTP redirects from the upstream are NOT followed (prevents SSRF via redirect chaining)
• 5-second upstream timeout enforced
• The //go:build comment on the handler documents the intent explicitly: the URL is constrained to DuckDuckGo’s fixed host only

Source: internal/server/sites/handlers.go — handleGetFavicon()

Zero Telemetry

HitKeep contains no telemetry, no usage reporting, and no phone-home mechanism of any kind.

What doesn’t happen	Notes
Version check to external server	Never performed
Crash/error reporting to external service	Errors log locally via slog only
Feature flag fetch from external endpoint	No feature flag service used
License validation against external server	MIT license — no validation needed
Anonymous usage statistics	Not collected

You can run HitKeep core analytics in a restricted network with no outbound internet access when optional outbound features are disabled.

Verification: The full source is MIT-licensed on GitHub. Audit cmd/ and internal/ for outbound integrations such as favicon lookup, mail delivery, S3 backup/archive paths, or optional AI provider calls before using HitKeep in a tightly restricted network.

Optional AI Provider Calls

AI-powered product features are off by default. When HITKEEP_AI_ENABLED=true and a provider/model are configured, HitKeep can send a structured, feature-specific request to the configured provider or gateway.

For Opportunities, detectors create the recommendation candidate first. HitKeep accepts only approved translation keys, interpolation params, and cited evidence IDs from the provider response. Output that does not match the detector contract is rejected before saving.

HitKeep does not persist raw prompts, raw provider responses, raw external error bodies, or provider secrets. AI run records keep audit metadata, hashes, token/request usage where available, lifecycle events, safe error categories, and the final validated structured output.

Authentication

JWT (Session Tokens)

HitKeep uses JSON Web Tokens stored in HTTP-only cookies for session authentication.

Property	Value
Storage	HTTP-only cookie (not accessible to JavaScript)
Expiry	Short. Defaults to 15 minutes and is configured with -auth-session-minutes
Algorithm	HMAC-SHA256
Secret	Set via HITKEEP_JWT_SECRET environment variable — minimum 32 bytes recommended
Scope	Per-user claims, not shared

HTTP-only cookies eliminate the risk of token theft via XSS — even if a malicious script runs in the page, it cannot read the session cookie.

The dashboard shows the remaining session time and opens an accessibility-friendly warning before expiry. Users can extend the session with one action. Operators can configure the warning lead time with -auth-session-warning-seconds.

When remember-me is enabled by the user, HitKeep stores a separate HTTP-only remembered sign-in token. Its lifetime defaults to 30 days and is configured with -auth-remember-me-days. The dashboard session API exposes both the remembered expiry and configured duration so the frontend reflects the operator policy instead of hardcoding it.

Two-Factor Authentication (TOTP)

RFC 6238 time-based one-time passwords. Compatible with any standard authenticator app (Authy, Google Authenticator, 1Password, Bitwarden).

• Secret stored per-user in DuckDB on your server
• QR code is generated server-side and shown once during enrollment
• TOTP is enforced at every login after enrollment

Passkeys (WebAuthn / FIDO2)

FIDO2-compliant challenge-response authentication. Supports hardware security keys (YubiKey, etc.) and platform authenticators such as Face ID and Touch ID.

• No password required
• Private key never leaves the user’s device or security key
• Phishing-resistant by design (origin-bound)

See Two-Factor Authentication →

Authorization (RBAC)

HitKeep enforces role-based access control at two levels:

Level	Roles
Instance	owner (full instance control), admin (operational administration), user (site-scoped access)
Site	owner (full site control), admin (site administration), editor (goals and funnels), viewer (read-only)

All role checks are enforced server-side in Go. The Angular dashboard reflects the current user’s roles, but access control is not dependent on frontend enforcement.

See Permissions & Roles →

Rate Limiting

All public and authenticated endpoints are protected by per-IP token bucket rate limiters.

Endpoint	Default behavior
POST /ingest	Per-IP rate limited to absorb burst traffic safely
POST /api/ingest/server/*	API-client-only server-side ingest for non-browser clients. Does not require browser Origin/Referer headers, uses the ingest limiter, and forwards from followers to the leader in clustered deployments
POST /api/login	Stricter rate limit to prevent brute-force attacks
GET /api/*	Per-IP rate limited

Rate limits are configurable via flags. See Configuration Reference →

MCP uses the API limiter and API client bearer-token authorization. AI fetch ingest uses the authenticated API surface, so crawler log forwarders should use scoped API client tokens instead of dashboard cookies.

Sec-Fetch Header Validation

State-changing requests are validated against Sec-Fetch-* headers sent by modern browsers. This adds a layer of CSRF protection — requests that don’t originate from a browser navigation (e.g., cross-origin form submissions or programmatic fetch calls without the correct context) are rejected.

This is in addition to, not a replacement for, JWT authentication.

TLS / HTTPS

HitKeep serves HTTP on the configured port. TLS termination is handled by your reverse proxy (Caddy, Traefik, nginx, or a cloud load balancer). This is the standard practice for Go applications.

Recommendation for production: Run behind Caddy with automatic HTTPS — it handles Let’s Encrypt certificate provisioning and renewal with a single reverse_proxy directive.

Security Headers

Configure security headers at your reverse proxy layer. Recommended headers for HitKeep deployments:

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: geolocation=(), camera=(), microphone=()

Because HitKeep serves all assets from the same origin, a default-src 'self' policy is achievable without allowlisting external CDNs.

Restricted-Network Operation

HitKeep core analytics can run with no outbound internet access:

• No license server calls
• No telemetry
• No external CDN dependencies for assets
• Optional features such as favicon lookup, SMTP delivery, S3 backups, Search Console sync, and AI provider enrichment can add outbound calls
• Docker image can be pulled once, pushed to a private registry, and used offline indefinitely

Vulnerability Reporting

HitKeep has a coordinated disclosure policy. To report a security vulnerability, use GitHub Security Advisories.

See SECURITY.md on GitHub →

Related

• Two-Factor Authentication
• API Clients
• Official MCP Server
• AI Fetch Ingest
• AI Fetch on AWS
• Opportunity Recommendations
• Permissions & Roles
• Architecture
• Configuration Reference
• Trusted Proxies

HitKeep Cloud uses the same product security model in managed EU or US infrastructure with region-specific hosting. Start with HitKeep Cloud →