Tag Provenance — Manual vs. Rule Tags

Every tag on an agent comes from one of two places: it was typed by an operator (a manual tag), or it was asserted by an automatic tagging rule. Athena keeps those two pools separate and shows you the origin of each tag, so you can tell at a glance why a device carries a label — and remove it the right way. This page explains the model, the tag source values, and the two most common questions it answers: “why does this tag keep coming back?” and “why can't I remove it?”

Two pools, one effective list#

An agent's effective tags — the labels you filter and target on — are the union of two independent pools:

Because the pools are independent, the same tag can be present in both at once — you typed prod by hand and a rule also asserts prod. When that happens the two collapse into a single entry (never a duplicate), and its source is reported as Both. Matching is case-insensitive, and when a manual and a rule tag differ only by capitalization the manual casing wins for display.

The tag source#

Each effective tag is marked with a source so you always know how it got there:

A tag with source Rule or Both also lists which rules currently assert it (a tag can be asserted by more than one rule), together with the time it was first assigned. That is what lets you jump straight from an unexpected label to the rule responsible for it.

“Why does this tag keep coming back?”#

If a tag returns moments after you remove it, it is a rule-assigned tag (source Rule). Manual edits never touch the rule pool, so removing it from the manual list changes nothing the rule is still asserting. To make a rule tag go away, address the rule, not the agent:

• Fix the device — a rule such as Low Disk Space retracts its tag automatically once the machine no longer matches the condition.
• Adjust the rule — edit the rule's condition so this device is out of scope.
• Disable or delete the rule — see Automatic Tagging Rules.

The provenance view names the exact rule(s) behind the tag, so you know which one to change.

Editing manual tags without clobbering rule tags#

Athena provides a dedicated route that reads and writes only the manual pool and leaves rule-assigned tags completely untouched. Use it whenever you add or remove manual tags by script:

PUT api/agents/{id}/tags is a whole-list replace of the manual pool only. Blank entries are dropped and entries differing only by case are de-duplicated. An empty array clears the manual pool; any rule-assigned tags survive, and the response shows the refreshed tags with their updated provenance.

# Add a manual tag while leaving rule-assigned tags alone.
# 1) Read the current MANUAL tags (source = Manual or Both) from the provenance view.
GET api/agents/550e8400-e29b-41d4-a716-446655440000/tags

# 2) Send back the full manual list you want, with your new tag added.
PUT api/agents/550e8400-e29b-41d4-a716-446655440000/tags
{
  "tags": ["production", "patched"]
}

Reading manual vs. effective tags in PowerShell#

Get-AthenaAgent returns each agent's effective tags in the Tags property — the manual ∪ rule union. That is the correct list for filtering and targeting, but not for building a new manual list. To change manual tags safely, decide the manual set explicitly rather than round-tripping Tags:

# SAFE: set an explicit manual list. Rule-assigned tags are preserved.
Set-AthenaAgent -Id "550e8400-e29b-41d4-a716-446655440000" -Tags @("production", "patched")

# AVOID: reading the effective list and writing it back copies rule tags
# into the manual pool permanently.
# $a = Get-AthenaAgent -Hostname "SERVER01"
# Set-AthenaAgent -Id $a.Id -Tags ($a.Tags + "patched")   # <-- don't do this

To see a device's full tag provenance — each tag marked Manual, Rule, or Both, and the rules behind the rule-assigned ones — use the provenance endpoint (GET api/agents/{id}/tags) shown above.

Script-driven tagging on Linux#

The provenance view also reports whether script-driven tagging is possible on a device. On non-Windows agents this is unavailable: rules that test the output of a PowerShell scan definition cannot match, because those scan definitions do not run on the Linux agent. This is scoped to script-based rules only — agent- and inventory-field rules still tag Linux devices normally (for example a rule on operating system, hostname, or a hardware field). So a Linux agent showing no script-driven tags is expected, not a sign that auto-tagging is broken.

Auditing#

Changes to an agent's manual tags are written to the audit log with the agent, the operator, and the resulting tag list, so tag edits are traceable and safe to forward to a SIEM. See the Audit Event Types Reference for the tag and tagging-rule event families.