Concepts

Endpoint

A Windows machine with the PermitUSB agent installed. Each endpoint has a hostname, agent version, and an enrollment record. Endpoints belong to exactly one endpoint group.

Endpoint group

A bucket of endpoints that share a policy. Think "Engineering," "Reception," "Kiosks." A new endpoint joins your tenant's default group unless its enrollment token specified a different one.

Each group has an optional discovery mode window — while it's set in the future, every rule's action is coerced to audit server-side, so the agent sees the policy but doesn't actually disable anything. Useful for risk-free rollouts.

Policy

A named, ordered list of rules. Tenants have many policies; each endpoint group has one assigned policy. Every tenant has a default policy — the one a fresh endpoint sees if its group has no explicit assignment.

Rule

One match-condition + one action (allow, block, or audit). Match conditions:

  • vid_pid — a specific make+model.
  • serial — a single physical device.
  • device_group — a named set of (vid, pid, serial) triplets you maintain.
  • vendor_name — substring match against the device's manufacturer / friendly name.
  • class — broad category (USBSTOR, HIDClass, Printer, etc.).

Rule precedence

The engine evaluates rules in tier order, most-specific first:

  1. Serial + device_group (per-instance specificity)
  2. Vid/pid (entire make+model)
  3. Vendor name (substring match against manufacturer)
  4. Class (broadest)

Within a tier, rules are evaluated in their saved position order — first enabled match wins. If nothing matches, the device is blocked by default. See the policy guide for examples.

Hardcoded guardrails

HID-class devices (mice, keyboards) are always allowed regardless of policy — the agent won't disable them even if you deliberately try. v1 ships with a small set of these guardrails so a misconfigured rule can't lock you out of your own machine.

Tray app

Per-user UI app that runs in every signed-in user's session. Talks to the service over a named pipe. Shows status (healthy / stale / tamper / trial-expired), recent events, and toast notifications for blocks. Not required for enforcement — the service does the enforcing — but every fleet should have it for the user-facing transparency.

Cloud control plane

The dashboard + API + Postgres database. Agents poll the API for policy on a configurable interval (default 60s) using an If-None-Match etag to avoid bandwidth on no-op refreshes. Events flow the other direction: SQLite-buffered locally, batched up to the API.

Tenant

Your workspace. Has a single billing relationship, RLS-isolated data, multiple users (with roles), and many endpoints / groups / policies. Single-tenant-per-user is enforced in v1; MSP / multi-tenant access is v1.1+.

Concepts — PermitUSB docs