• Reporting Vulnerabilities
• Security Model
• Authentication and Access Control
• Input Validation
• Threat Model
• Dependency Security

If you discover a security vulnerability in Mallard Metrics, please report it responsibly by opening a private security advisory on GitHub.

Do NOT open a public issue for security vulnerabilities.

We will acknowledge receipt within 48 hours and provide a timeline for a fix.

• Storage format -- Event data is stored in Parquet files with ZSTD compression, organized by site_id and date for partition pruning
• Atomic writes -- Parquet files, api_keys.json and the visitor-ID secret are written to a temporary file and renamed into place, so an interrupted write leaves either the old content or the new, never a truncated file
• File permissions -- api_keys.json and .secret are created mode 0600. Anyone able to read the secret can re-derive every visitor ID from an IP and User-Agent, which is the whole pseudonymisation guarantee
• Encryption at rest -- Not provided by Mallard Metrics itself. Use filesystem-level encryption (e.g., LUKS, dm-crypt) if required
• Data retention -- Configurable automatic deletion of old partitions via MALLARD_RETENTION_DAYS
• Container hardening -- The image runs as uid 65532 and writes only to /data; the bundled compose file adds read_only, cap_drop: ALL and no-new-privileges

• Password hashing -- Argon2id with default parameters (memory-hard, GPU-resistant)
• Session tokens -- 256-bit cryptographic random tokens, stored as HttpOnly cookies
• Cookie attributes -- HttpOnly, Secure (when MALLARD_SECURE_COOKIES=true or dashboard_origin starts with https://), SameSite=Strict
• Session expiration -- Configurable TTL (default: 24 hours) via MALLARD_SESSION_TTL

• Key format -- mm_ prefix followed by a cryptographic random string
• Storage -- Keys are SHA-256 hashed at rest. Plaintext keys are shown only once at creation time. Keys are persisted to data/api_keys.json and survive server restarts.
• Operations -- Create, list, and revoke via /api/keys endpoints
• Scopes -- Two scopes available:
  • ReadOnly — access to all GET /api/stats/* and export endpoints
  • Admin — full access including creating, listing, and revoking API keys
• Comparison -- Constant-time SHA-256 comparison prevents timing side-channel attacks

State-mutating endpoints authenticated via session cookie validate the Origin or Referer header against dashboard_origin. Requests with a mismatched or absent origin receive 403 Forbidden. Set MALLARD_DASHBOARD_ORIGIN in production to enable CSRF protection.

• Ingestion (POST /api/event) -- Permissive CORS. The tracking script must be able to POST from any customer domain.
• Dashboard and API (/api/stats/*, /api/keys/*) -- Restrictive CORS. When MALLARD_DASHBOARD_ORIGIN is set, only that origin is allowed.

All DuckDB queries use parameterized statements ($1, ?). User input is never interpolated into SQL strings. Funnel steps and sequence conditions use a safe page:/path and event:name format that is parsed and validated before being incorporated into queries.

All user-provided data (page names, referrers, UTM parameters, custom properties) is sanitized before storage. Control characters are stripped and strings are truncated to maximum lengths.

Beyond length, two fields are validated by shape:

• Custom properties must parse as a JSON object. Anything else is dropped rather than stored, because a non-object value would break every JSON query on that site's props column.
• revenue_currency must be three ASCII letters. It was previously truncated to three characters, which turned DOLLARS into DOL.

Two independent token-bucket limiters guard the ingestion endpoint:

Both default to 0 (unlimited). The per-site limit alone is not sufficient: a single client can consume the whole site budget and deny service to everyone else on that site.

Both bucket maps are capped by MALLARD_MAX_TRACKED_KEYS, because their keys come from attacker-influenced values and the cleanup sweep only runs every 15 minutes. Idle buckets are reclaimed before a new key is refused.

The per-IP limiter depends on the client address being accurate — see MALLARD_TRUST_PROXY_HEADERS under Threat Model.

Known bot User-Agents are automatically filtered from analytics when MALLARD_FILTER_BOTS=true (default). This prevents automated crawlers and scrapers from inflating visitor counts.

• cargo deny runs in CI to check for known vulnerabilities, license issues, and duplicate dependencies
• GitHub Actions are pinned to commit SHAs for reproducible, tamper-resistant builds
• Minimal dependency surface -- the project avoids unnecessary dependencies to reduce attack surface
• Static binary -- the FROM scratch Docker image contains only the compiled binary, with no shell, package manager, or other tools that could be exploited