Skip to main content

Tags

Tags are a flexible mechanism for assigning rules and settings to hosts.

Concepts​

  • Tag - a named collection of settings and rules applied to a set of hosts. By default there's always a global tag which applies to all hosts connected to Workshop and each host gets a tag defined as host:<machine_uuid>.
  • Tag Order - the order in which tags inherited by groups are applied to hosts. This defines the precedence used when resolving settings and rules.
  • Overridden Tags - when an admin explicitly sets the tags on a host via the "Override tags" toggle. This locks the tag set on the host so it is no longer derived from group membership. Hosts with overridden tags cannot participate in approval workflows.
  • Sync Settings - options that change how Santa operates on a given host. When applied to tags they are resolved from least specific to most specific tag. Each individual setting is replaced atomically by a higher-precedence tag — values are never merged within a single setting. For example, a device cannot combine Allowed Path Regex values from multiple tags; only the highest-precedence tag's value applies. This means different settings can come from different tags (e.g. one tag sets Client Mode, another sets Blocked Path Regex), but any single setting is wholly owned by the most specific tag that defines it. Settings that follow this atomic override behavior include:
    • Client Mode
    • Removable Media Blocking
    • Network Share Blocking
    • Transitive Rules
    • Allowed Path Regex
    • Blocked Path Regex
    • Telemetry Collection
    • Network Extension
  • Approval Workflow Settings - these define if the hosts running Santa that are part of the tag can use approval workflows to allow applications that don't have explicit rules. The Approval Workflow settings are an atomic unit (not merged from less specific tags). Simply, the most specific tag's value applies. They do not apply to hosts with overridden tags.
  • Risk Engine Exceptions - settings that allow a Santa instance that's a member of a tag to override a risk engine plugin.
  • Rules - policies that describe what software Santa should allow or block. Rules from multiple tags can apply to the same host. When tags define conflicting rules for the same identifier, the most specific / highest precedence tag wins.

Admins can apply rules, approval workflow settings and sync settings to tags via the APIs. These won't apply until the tag becomes part of a host's effective tag set, either directly or through group membership.

Relationships​

How Settings and Rules Are Applied​

Settings and rules are resolved from global (least specific) to the host tag (most specific). When multiple tags define the same setting or a conflicting rule, the setting or rule from the most specific tag wins.

Note: Approval workflow settings have additional host-assignment restrictions described above.

Consider a host with the effective tag order: global → team-a → host:<uuid> that was applied via group membership.

Setting Typeglobalteam-ahost:<uuid>Effective Value
Client ModeMonitorLockdown(not set)Lockdown
Blocked Path Regex/tmp/.*/opt/.*(not set)/opt/.*
Approval Workflow(not set)Self-approval(not set)Self-approval
Rule for app XBlockAllow(not set)Allow
Rule for app Y(not set)BlockAllowAllow

Tag Creation​

Important: Tags must be created before they can be assigned. You cannot reference a tag that doesn't already exist.

To create tags:

  1. Navigate to the All Tags section in /settings.
  2. Click "Create Tag"
  3. Provide a unique name - max 42 chars - then click "Next"
  4. You will be prompted to add the tag to the tag order. Drag the tag to the desired position and click "Create".

Once created the tag will appear in the Tagged Settings pane above and can now be assigned to rules, settings, and hosts. The tag order can also be edited in the Tagged Settings pane.

An unlimited number of tags can be created, but only 25 can be in the tag order at a time. If this limit is restrictive, reach out to support with your use case.

Tags can also be created using the CreateTag RPC.

Tag Assignment Methods​

Tags can be applied to hosts via two methods:

1. Manual Assignment (Per-Host)​

Tags can be manually assigned directly to individual hosts through the Workshop interface or UpdateHost RPC. This provides granular control over which tags are applied to specific machines.

warning

If a host has tags manually assigned, that host cannot participate in approval workflows.

2. Automatic Assignment (Via Groups)​

Tags can be automatically applied to hosts through group membership. This provides scalable tag management across multiple hosts.

In order to use tags applied by groups, they must be added to the Tagged Settings section. This defines the order in which the tags will apply.

  1. Navigate to the Tagged Settings section in /settings.
  2. Click "Add Settings"
  3. Choose a tag
  4. Click Add

There is currently a 25 tag limit. If you find you need more tags, contact support with your use case.

Tags can also be ordered with the UpdateTagOrder RPC.

Group Attachment Methods​

There are two methods to attach a host to a group (which contains tags):

Method 1: Directory Sync​

When directory sync is enabled:

  • Any group the host's primary user is a member of will gain access to that group's assigned tags
  • This provides seamless integration with existing directory structures.
  • Tag assignment happens automatically based on user group membership

Method 2: Primary User Groups (Client-Defined)​

Starting with version 2025.6 of Santa:

  • You can define primary user groups for a host directly on the client
  • This method provides more flexibility for environments that aren't using directory sync
  • Allows manual specification of which groups a host should inherit tags from
warning

If a host has tags manually assigned via primary user groups, that host cannot participate in approval workflows. This is a temporary restriction, future versions of Workshop will enable approval workflows for client defined groups.

Tag Application Order​

For both group assignment methods, the total set of tags are applied to the host using the defined tag order. This ensures consistent and predictable tag application across your environment.

Examples​

Roll Out Lockdown Mode to Sales First​

An admin wants to move from Monitor mode to Lockdown mode across the fleet but wants to start with Sales (who run a smaller, more predictable set of software) before rolling it out company-wide.

  1. Create a sales-lockdown tag
  2. Map it to the existing Sales IdP group
  3. Place sales-lockdown above global in the tag order
  4. Set Client Mode to Lockdown on the sales-lockdown tag (global stays in Monitor)
  5. Monitor for a week, resolve any issues
  6. When confident, change the global tag to Lockdown mode and remove the sales-lockdown tag

Different Approval Workflows per Department​

A company wants Engineering to self-approve low-risk software via the risk engine, while Sales and Finance require manager approval for any new software.

  1. Create engineering, sales, and finance tags mapped to their respective IdP groups
  2. On the engineering tag, configure approval workflows to allow self-approval when the risk engine score is below the threshold
  3. On the sales and finance tags, configure approval workflows to require manager approval for all new software
  4. Place all three tags above global in the tag order

Result: each department gets a tailored approval experience without manual per-host configuration. If a user is a member of multiple groups, the associated tag with the higher precedence wins.

Incremental Ban of Compromised Software​

A vulnerability is announced for a widely-used application. The admin wants to block it but roll out the ban gradually to minimize business disruption.

  1. Create a ban-rollout tag
  2. Create an IdP group mapped to that tag
  3. Place it above global in the tag order
  4. Add a block rule for the application to the ban-rollout tag
  5. Add a small initial set of users to the IdP group
  6. (Optional) Trigger a sync
  7. Keep adding members incrementally, waiting for issues to surface
  8. Once at 100%, move the block rule to global and delete the ban-rollout tag