Policy guide

A PermitUSB policy is an ordered list of rules. Each rule has one match condition and one action. The engine walks rules in tier order, most-specific first, then within a tier in your saved order.

The five match types

vid_pid

Match a specific make+model. Use when you want to allow (or block) every YubiKey 5, every Logitech MX Keys, every iPhone — anything where the manufacturer + model is the right granularity.

{ "match_type": "vid_pid", "match_vid": "1050", "match_pid": "0407", "action": "allow" }

serial

Match a single physical device by VID + PID + serial. Use for "this exact thumb drive issued to Joe."

{ "match_type": "serial", "match_vid": "0781", "match_pid": "5567", "match_serial": "AA010401190902103045", "action": "allow" }

Some cheap devices report a dummy serial like "0000000000". The engine treats those as "no serial available," not "matches all empty serials."

device_group

Match against a named set of (vid, pid, serial) triplets. Build a group like "Approved engineering thumb drives" once, reference it from any rule. Adding members changes every referencing policy's effective behaviour.

vendor_name

Case-insensitive substring match against the device's manufacturer string or friendly name. Useful for "allow anything from Logitech." Inconsistent vendor strings (Logi vs Logitech vs Logitech, Inc.) are why this is substring-based, not exact-match.

class

Match by Windows PNP class — USBSTOR, HIDClass, Printer, Image, Media, etc. The engine matches against the device's full class set (PNPClass + Service + child enumerations) rather than just the parent's class, so a rule like "block USBSTOR" actually blocks thumb drives even though their parent USB device shows class "USB."

Tier ordering

  1. Serial + device_group — per-instance, most specific.
  2. Vid_pid — entire make+model.
  3. Vendor_name — narrower than class, broader than vid_pid.
  4. Class — broadest.

Within a tier, rules evaluate in saved position order. The first enabled rule that matches wins. If nothing matches, the device is blocked.

Actions

  • allow — device is enabled; logged at info severity.
  • block — device is disabled via Configuration Manager APIs; logged at warn; tray notifies.
  • audit — decision logged but enforcement is skipped. Useful for testing rules before flipping them to block.

Discovery mode

Per-endpoint-group, time-bound. While it's active, the API rewrites every rule's action to audit server-side. The agent doesn't know it's in discovery mode — it just sees a policy where nothing blocks.

Hardcoded guardrails

Certain devices are always allowed regardless of policy: HID-class (mouse, keyboard), smart card readers, internal-bus peripherals. These guardrails are in the agent itself and can't be disabled — a misconfigured class-block rule won't accidentally lock you out of Device Manager.

Authoring patterns

Common SMB starting policy:

  1. Allow specific security keys by vid_pid (YubiKey, Titan)
  2. Allow vendor_name substrings for trusted peripherals (Logitech, Microsoft)
  3. Allow class for printers, audio, video
  4. Block class USBSTOR (mass storage) — caught by the default deny but explicit makes audit logs cleaner
  5. Optional: allow specific approved thumb drive serials at the top tier for individual users

The Standard Office template is exactly this pattern; apply and tune.

Policy guide — PermitUSB docs