wyre-ai/msp-claude-plugins/computer-groups

ThreatLocker Computer Groups

Computer groups are the policy-scoping unit in ThreatLocker. Policies are applied at the group level, never at the individual computer level. A computer must belong to exactly one group, and moving a computer between groups changes which policy set applies to it. Groups can be global (visible across all child organizations) or org-specific.

Anti-triggers

• A directory group. "Group" here is a ThreatLocker policy boundary

with no relationship to Entra ID or Active Directory membership. Security and distribution groups in a managed M365 tenant are cipp-groups.

• The client a computer belongs to. Tenancy is the organization, not

the group; a computer sits in exactly one of each — use threatlocker-organizations.

• Why a specific execution was blocked. The group only says which

policy set applied; the individual block and the resulting request are threatlocker-audit-log and threatlocker-approval-requests.

• A single machine's own record. Hostname, agent version, install

date, and the maintenance-mode toggle sit on the computer rather than the group; use threatlocker-computers.

API Tools

List Computer Groups (Full)

threatlocker_computer_groups_list

Full list with metadata — group name, ID, OS type, parent org, computer count, and policy associations. Use this for audits and reports.

List Computer Groups (Dropdown)

threatlocker_computer_groups_dropdown

Slim list intended for selection UIs — typically just id, name, and osType. Use this when you only need to map an ID to a name or pick a target group for a move.

Why two endpoints?

The full list is heavier and includes counts and metadata that requires more lookups server-side. The dropdown returns immediately and is the right choice when you are about to issue another call (move, assign) and just need the IDs.

Key Concepts

osType Enum

A group's osType constrains which computers can be assigned to it — you cannot put a Mac into a Windows-only group.

Global vs Org-Specific Groups

• Global groups are defined at the partner level and inherited by

all child organizations. Useful for fleet-wide baselines (e.g. "All Windows Servers").

• Org-specific groups live inside a single child org. Most

client-specific policy customization lives here.

The full list endpoint exposes the parent organization on each row, so you can filter or group by it.

Common Workflows

Mapping Computer → Group

The threatlocker_computers_list response includes computerGroupId and computerGroupName directly, so a separate call is usually unnecessary. When you have a stale ID and need the current name, use threatlocker_computer_groups_dropdown to resolve.

Auditing Group Hygiene

1. List all groups with threatlocker_computer_groups_list.
2. Flag groups with zero computers (likely dead or deprecated).
3. Flag groups with extreme computer counts (oversized — policy

changes there will have wide blast radius).

1. Flag groups whose osType does not match the OS distribution of

the computers actually assigned to it (misclassified group).

Choosing a Target Group for a New Endpoint

1. Pull dropdown groups with threatlocker_computer_groups_dropdown.
2. Filter to the matching osType for the new computer.
3. Filter to the appropriate organization scope.
4. Pick the group whose policy posture matches the endpoint's role

(workstation, server, kiosk, etc.).

Identifying Global vs Org-Specific

1. Use the full list endpoint and inspect the parent organization on

each row.

1. Groups with the partner organization as parent are global.
2. Groups whose parent matches a child org ID are org-specific to that

child.

Edge Cases

• Empty groups — Some groups exist for future use. Don't auto-flag

every empty group as a problem; cross-reference recent policy edits before recommending deletion.

• OS-mismatch surprises — A computer's reported operatingSystem

string is normalized into the osType enum at assignment time. Edge OS strings (Windows IoT, macOS preview builds) sometimes land in the wrong bucket.

• Dropdown vs full — Don't try to compute counts from the dropdown

— it does not return computer counts. Use the full list for that.

Best Practices

• Use the dropdown for any "pick a group" workflow; only call the full

list when you genuinely need metadata or counts.

• When scoping a policy change, list the group's computers first and

estimate impact before recommending the change.

• Keep group naming consistent across organizations — analysts triage

faster when "Workstations - Standard" means the same thing everywhere.

Related Skills

• api-patterns — Auth and pagination
• computers — Computers within groups
• organizations — Org scope for groups