Endpoint groups

An endpoint group is a bucket of machines that share a policy. New endpoints land in your tenant's default group unless they request a different one at install time (see below).

Why groups

Different teams need different policies. Engineering might allow approved thumb drives; the kiosk in the lobby should be HID-only; the warehouse scanners only need their HID scanner. Groups let you set those independently without policy duplication.

Per-group policy

Each group has exactly one assigned policy at a time. v1 enforces a 1:1 group → policy assignment; many-to-many is on the v1.1 list if it turns out to be useful.

Per-group discovery mode

Each group has an optional discovery_mode_until field. While it's set in the future, every rule's action served to that group's agents is coerced to audit. See discovery mode.

Default group

Each tenant has exactly one default group, created during tenant bootstrap. Newly-enrolled endpoints land here unless their MSI install command specified a different group. You can change which group is the default any time from the Endpoint groups list.

Pre-assigning a group at install

Pass ENDPOINT_GROUP to msiexec with the name of the group the new endpoint should join:

msiexec /i PermitUSB.msi /qn TENANT_TOKEN="<token>" ENDPOINT_GROUP="Engineering"

Names are matched case-insensitively and trimmed of surrounding whitespace, so "Information Technology" and "information technology" resolve to the same group. Quote values that contain spaces. An unrecognized name soft-falls-back to the tenant default with a warning logged on the cloud side, so a typo in a deployment script never blocks enrollment.

Moving endpoints

Two ways, and they reconcile automatically:

  • From the dashboard. On Endpoints, change a row's group via the per-row picker. Or bulk-move from the group's detail page. The agent picks up the new group's policy on its next poll (within ~5 min by default) and syncs the new group name back into its local agent.json so the two stay in agreement.
  • From the endpoint. Edit %ProgramData%\PermitUSB\agent.json as Administrator, set the EndpointGroup field to the new group's name, and restart the PermitUSB.Agent service. The agent re-asserts on every service start, so this immediately moves the endpoint. Useful for site-side admins re-homing a machine without dashboard access.

Resolution model when both sides change: local agent.json wins on service start, dashboard moves win during a session (the agent self-heals its JSON to match the server). Renaming a group in the dashboard automatically propagates — the agent notices on its next poll and updates its local file.

Endpoint groups — PermitUSB docs