Security Policy¶

Supported Versions¶

We release patches for security vulnerabilities. Which versions are eligible for receiving such patches depends on the CVSS v3.0 Rating:

Reporting a Vulnerability¶

Please report security vulnerabilities to the maintainers via GitHub Security Advisories.

Security Features¶

Container Security¶

Our Docker images include the following security features:

1. Non-root User: Containers run as a non-root user (UID 1000) by default
2. Minimal Base Image: Using Python slim-bookworm base image (~40MB)
3. Read-only Filesystem: The provided docker-compose.yml sets read_only: true and mounts /tmp as tmpfs
4. No New Privileges: Containers cannot gain new privileges (compose defaults)
5. Health Checks: Built-in health check endpoints

Supply Chain Security¶

1. Signed Images: All container images are signed using cosign
2. SBOM Generation: Software Bill of Materials (SBOM) generated for every build
3. Attestations: Build provenance attestations are generated and published
4. Vulnerability Scanning: Automated scanning with Trivy for CRITICAL and HIGH vulnerabilities
5. Dependency Updates: Automated dependency updates via Renovate

Merge and publication gates¶

The main ruleset requires four independent GitHub Actions checks: ci-success, actionlint, zizmor, and dependency review. The first aggregates the source, container-smoke, and Helm gates; the other three remain separate so a skipped or cancelled scanner cannot be hidden by the aggregator.

Container publication has a stricter boundary than ordinary merge CI:

1. The committed exception policy is validated, including every expiry date.
2. Publication-scoped CodeQL analysis blocks at HIGH or CRITICAL security severity.
3. Each native architecture is built as a local OCI archive and scanned by Trivy for HIGH and CRITICAL vulnerabilities.
4. Only a successfully scanned archive is copied to GHCR, by its exact digest. The multi-arch manifest, signatures, provenance attestation, SBOMs, and optional Helm chart are created only after both architecture jobs pass.

CodeQL and Trivy still upload SARIF when a finding blocks publication, so the rejected result remains visible in the repository Security tab. Codecov and Codacy coverage uploads are reporting-only; the required coverage decision is pytest's local 80% floor in just check. Codacy's externally managed analysis remains enabled through .codacy.yaml; the unused Mend/WhiteSource and Safety configuration files were removed.

Vulnerability exceptions¶

Accepted Trivy findings live in .trivyignore.yaml, which deliberately uses JSON-compatible YAML so the standard-library validator can enforce a strict schema:

{
  "vulnerabilities": [
    {
      "id": "CVE-YYYY-NNNN",
      "statement": "Specific reviewed reason the published image accepts this risk",
      "expired_at": "YYYY-MM-DD"
    }
  ]
}

Every entry requires exactly those three fields, a non-empty rationale, a unique identifier, and a future ISO date. An exception expiring today is already invalid: just security-exceptions and the publication policy job fail before scanning or registry authentication. Findings do not disappear from the policy merely because a later scan stops reporting them; remove an entry in a reviewed change. The committed policy currently accepts no vulnerabilities.

Verification¶

You can verify the authenticity of our container images. Images are built and signed by the shared rknightion/.github container-publish.yml reusable workflow (invoked from this repo's publish.yml), so the keyless Fulcio certificate identity reflects that reusable workflow's path, not a workflow file in this repository:

# Verify container signature
cosign verify ghcr.io/rknightion/meraki-dashboard-exporter:latest \
  --certificate-identity-regexp "^https://github\.com/rknightion/\.github/\.github/workflows/container-publish\.yml@.+$" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

# Download and inspect SBOM
cosign download sbom ghcr.io/rknightion/meraki-dashboard-exporter:latest

# Verify attestations
cosign verify-attestation ghcr.io/rknightion/meraki-dashboard-exporter:latest \
  --type slsaprovenance \
  --certificate-identity-regexp "^https://github\.com/rknightion/\.github/\.github/workflows/container-publish\.yml@.+$" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Best Practices¶

When deploying this exporter:

1. API Key Security: Never commit API keys to version control. Use environment variables or secrets management. Where possible, generate a Meraki Dashboard API key for an account with read-only access scoped to the organisations being exported.
2. Network Security: Run the exporter in a private network, expose only to authorized Prometheus instances.
3. Resource Limits: Apply appropriate CPU and memory limits to prevent resource exhaustion.
4. Regular Updates: Keep the exporter updated to receive security patches.

Webhook receiver¶

The optional Meraki webhook receiver accepts JSON POSTs at /api/webhooks/meraki once enabled (MERAKI_EXPORTER_WEBHOOKS__ENABLED=true). It is configured with:

Authenticated deliveries are freshness-checked and deduplicated only to make Meraki retries idempotent. A successfully processed alert key is kept in a bounded, in-memory TTL cache; duplicate and stale authenticated deliveries are acknowledged with HTTP 2xx so Meraki does not retry them forever, but they do not reapply device state. Failed processing returns 5xx and does not commit the key, so the same delivery can succeed on a later retry. A timezone-naive sentAt is interpreted as UTC before the freshness check.

This is delivery deduplication, not an anti-replay security boundary. The cache is local to one process, is cleared by restart, and is not coordinated between replicas. A caller that knows the shared secret can also create new valid delivery identities. Keep the receiver singleton and protect the shared secret; the cache only suppresses ordinary duplicate delivery within its configured TTL.

API key handling¶

API keys are loaded as Pydantic SecretStr values and are not logged or serialised in the /status, /metrics, or web UI surfaces. Treat the container environment that holds MERAKI_EXPORTER_MERAKI__API_KEY as sensitive.

Endpoint authentication¶

The exporter serves three categories of HTTP endpoint (see the HTTP Endpoints reference for the full list):

• Always-open endpoints (/metrics, /health, /ready) — /metrics must stay reachable by your Prometheus scraper, and /health / /ready are orchestrator probes. These are never gated.
• Sensitive GET UIs (/, /status, /config, /clients, /cardinality*, /api/metrics/cardinality) — these expose PII and operational detail (see the threat model below). They are open by default but can be token-gated (MERAKI_EXPORTER_SERVER__API_TOKEN) and/or suppressed entirely (MERAKI_EXPORTER_SERVER__UI_ENABLED=false).
• State-changing POST control endpoints — /api/collectors/trigger (force an on-demand collector run) and /api/clients/clear-dns-cache — fail closed unless the bearer token is configured.

Set MERAKI_EXPORTER_SERVER__API_TOKEN to require callers of the sensitive GET UIs and the control POSTs to send Authorization: Bearer <token> (a constant-time compare). When it is unset (the default), the control POSTs return HTTP 401 and their UI controls remain visibly disabled; the sensitive GET UIs remain open. When it is configured, controls become API-only and are absent from the UI: it never places the token, or a token-derived credential, in page HTML or JavaScript. The webhook receiver (POST /api/webhooks/meraki) is gated separately by its own shared secret (MERAKI_EXPORTER_WEBHOOKS__SHARED_SECRET), not by this token.

Control API¶

When a control token is configured, the exporter deliberately provides no browser controls for state-changing actions. Use the authenticated API directly instead:

curl -sS -X POST \
  -H "Authorization: Bearer $MERAKI_EXPORTER_SERVER__API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"collector":"DeviceCollector"}' \
  http://localhost:9099/api/collectors/trigger

curl -sS -X POST \
  -H "Authorization: Bearer $MERAKI_EXPORTER_SERVER__API_TOKEN" \
  http://localhost:9099/api/clients/clear-dns-cache

Endpoint exposure & threat model¶

Default read posture is unauthenticated and plaintext. The exporter binds 0.0.0.0:9099 with no TLS and, by default, no auth on GET endpoints. Anyone who can reach the port can read everything below, but cannot invoke either control POST without configuring and presenting a token. This is acceptable only on a trusted/private interface; for any other deployment apply the mitigations that follow.

What each endpoint exposes:

For the full client-tracking privacy/GDPR picture — exactly which fields are PII, where they land (metrics WAL, the /clients cache, optional OTel data-logs), and every mitigation control — see Data Privacy.

Mitigations (v1).

• Bearer token — set MERAKI_EXPORTER_SERVER__API_TOKEN. Sensitive GET UIs then require Authorization: Bearer <token>; setting it also enables the fail-closed control POSTs. /metrics and the probes stay open so Prometheus/Kubernetes keep working.
• Suppress the UI — set MERAKI_EXPORTER_SERVER__UI_ENABLED=false to drop the human UI surface (/, /status, /config, /clients, /cardinality*) entirely; they return 404. Use this when you only need /metrics scraped and want no PII/detail surface at all.
• Reverse proxy + TLS (recommended for any exposed deployment). Terminate TLS and authenticate at a reverse proxy (nginx / Traefik / Caddy / an ingress controller) in front of the exporter, and forward only /metrics to your scraper. Example nginx sketch:

server {
  listen 443 ssl;
  ssl_certificate     /etc/ssl/exporter.crt;
  ssl_certificate_key /etc/ssl/exporter.key;

  # Only expose /metrics to the scraper; everything else stays internal.
  location = /metrics {
    allow 10.0.0.0/8;   # Prometheus subnet
    deny  all;
    proxy_pass http://127.0.0.1:9099;
  }
  location / { deny all; }
}

Native listener TLS/mTLS on the exporter itself is a separate, later roadmap item; for v1 the supported pattern is reverse-proxy termination.

Recommended posture. Bind the exporter to a trusted interface / private network and expose only /metrics (via a reverse proxy where possible). Set MERAKI_EXPORTER_SERVER__API_TOKEN and/or MERAKI_EXPORTER_SERVER__UI_ENABLED=false whenever the sensitive GET UIs or control POSTs are reachable from any network segment you do not fully trust.

Meraki API credential boundary. The exporter accepts known Meraki HTTPS origins by default; custom HTTPS origins require explicit opt-in, and Authorization is never forwarded across a redirect to a different origin.

Beta / early-access API surface¶

The exporter never calls Meraki's beta / early-access Dashboard API endpoints and never enrolls an org into them — beta endpoints are unversioned and can change shape or be withdrawn without notice, so consuming them would undermine the v1 stability promise. There is deliberately no flag to opt in.

Instead, the exporter treats an org being on the beta spec as a risk signal. The org's Early Access opt-ins are surfaced as always-on metrics (meraki_org_early_access_opt_in_info, meraki_org_early_access_opt_in_scoped_networks), and a dedicated meraki_org_has_beta_api gauge (1/0 per org) plus a startup/runtime WARN log fire when an org has opted into has_beta_api. This matters because has_beta_api flips the whole org to the beta Dashboard spec, which can move endpoints this exporter assumes are stable onto the beta surface and silently break collection — alert on meraki_org_has_beta_api == 1 to catch that. The exporter only reads the opt-in state; enrolling or un-enrolling an org remains a human decision made via the Meraki dashboard.