Epochly Security: Threat Model

This is the public companion to the Security Policy. It enumerates the adversaries Epochly defends against, the network surface the package exposes, the trust boundary between licensing and telemetry, and the supply-chain posture for published wheels.

Attacker Model

Epochly is a Python performance overlay that runs in-process with your application. The threat model assumes the host operating system, Python interpreter, and your Python source code are trusted. We explicitly defend against:

• Curious user. A consumer inspecting outbound network traffic. We prevent inadvertent disclosure of raw hardware-fingerprint attributes, function inputs/outputs, source trees, datasets, or environment secrets.
• Network adversary (passive or on-path). An observer between your host and our API. We guarantee TLS-only transport, no plaintext PII, and no replayable secrets in URL query strings.
• Package-supply-chain attacker. A third party attempting to publish a malicious wheel under the epochly name. We rely on signed, reproducible release artifacts and an auditable release pipeline.
• Licensing-bypass attacker. A user attempting to bypass trial or device-license enforcement. Server-side validation of proof tokens means client-side tampering fails closed at the backend.

Out of scope:

• Nation-state adversaries with endpoint compromise.
• Physical access to the host or kernel-level rootkits.
• Malicious modifications of the Python interpreter itself.
• Adversarial downstream packages that re-export Epochly's APIs without preserving the documented telemetry and licensing gates.

Network Surface

Epochly's outbound traffic targets a single base URL (https://api.epochly.com by default, overrideable via EPOCHLY_API_URL). Endpoints fall into two privacy classes:

• License-class endpoints (trial, license validation, compatibility, device management). Governed by EPOCHLY_OFFLINE_MODE=1; they remain reachable under EPOCHLY_DISABLE_TELEMETRY=1 because they are required for licensing correctness.
• Telemetry-class endpoints (metrics, critical events, compatibility reports). Suppressed by either EPOCHLY_OFFLINE_MODE=1 or EPOCHLY_DISABLE_TELEMETRY=1.

All requests use HTTPS and a versioned User-Agent header. No long-lived API keys are emitted from default-mode runs; the Lens heartbeat requires an explicit opt-in plus stored credentials.

License / Fingerprint Trust Boundary

Device licensing requires a stable per-host identifier so that one paid seat cannot be silently shared across unlimited machines. In default mode, the device-registration request contains only a SHA-256 digest of the canonicalized hardware attributes — the raw fingerprint data is not sent. Setting EPOCHLY_SEND_RAW_FINGERPRINT=1 is a deliberate, documented opt-in that restores the raw attributes for support and debugging; it is never silently enabled. Server-side validation of proof tokens means that even if a client tampers with the fingerprint or proof material, registration fails closed at the backend. Telemetry payloads pass through scrubbers that redact host, username, home-directory, email, IP, and MAC tokens before transmission.

Telemetry Data Flow

Epochly emits two telemetry surfaces, both opt-out by default:

• Anonymous community telemetry. Scrubbed events such as session start, routing decisions, and JIT/worker/GPU/allocator/workload resource events. No function inputs, outputs, datasets, source trees, or secrets.
• Lens heartbeat. Opt-in only — requires an explicit opt-in plus an API key or stored Lens credentials.

See Telemetry Data Flow for the per-field accounting and env-var controls.

Supply Chain

• Build provenance. Wheels are built in CI from a clean checkout on every release; manual tag pushes are blocked by policy.
• SBOM. Dependency metadata is declared in the package manifest, and a machine-readable SBOM is attached to each GitHub release. You can also generate one locally with cyclonedx-py.
• Wheel publishing. Wheels publish to PyPI via a trusted-publisher OIDC flow rather than long-lived API tokens, removing the static-secret attack surface. Consumers who require artifact pinning today can pin to a specific hash with pip install epochly== --hash=sha256:....
• Reproducibility. The release pipeline rebuilds wheels from a clean checkout on every run; no developer machines push artifacts directly to PyPI.