Tags
Labels you attach to objects, assets, hostnames, addresses, and YARA rules, so a campaign or a class of machine can be selected as one thing.
A tag is a label your team attaches to something in Stairwell. Unlike an opinion, a tag makes no claim about whether a file is good or bad. It says this thing belongs to a set, and the set is one you invented.
That is the whole idea, and it is more useful than it sounds. An investigation produces a group of related things: forty files from one campaign, nine machines in one business unit, the rules you wrote during one incident. Without a name for that group, it exists only in the ticket. With one, it is a thing you can query, revisit, and hand to somebody else.
What can be tagged?
Five entity types, which between them cover most of what you work with:
| Entity | Resource pattern |
|---|---|
| Objects | objects/{hash}/tags/{tag} |
| Assets | assets/{asset}/tags/{tag} |
| Hostnames | hostnames/{hostname}/tags/{tag} |
| IP addresses | ipAddresses/{ip_address}/tags/{tag} |
| YARA rules | environments/{environment}/yaraRules/{rule_name}/tags/{tag} |
Those patterns are what the REST APIs and swell address, and the exact request shapes are in the API reference. They are worth knowing if you are tagging in bulk rather than by hand. Tagging forty files from an investigation is a scripting job, not a clicking job.
How do I find things by tag?
With CEL, which is where tags stop being decoration and start being a query surface:
tags.exists(t, t.value == "malware")
tags.exists(t, t.value.startsWith("campaign:"))The second form is the interesting one, and it is the reason for the naming convention below. startsWith lets you select a whole family of tags rather than one, so campaign: returns everything from every campaign you have tracked, while campaign:akira returns one.
How should I name them?
Use category:value, consistently, from the first tag you ever create.
The convention costs nothing and buys the prefix query above. Without it you get a flat namespace where akira and finance-laptops and reviewed sit side by side with no way to ask for one kind, and no way for the next analyst to guess what exists.
Three categories that earn their place in most teams:
campaign:for tracking one intrusion or one published threat across the objects, hostnames, and addresses it touched. This is the one that pays off six months later, when the same operator returns and you want everything you concluded last time.env:orbu:on assets, for the organizational grouping your fleet has but Stairwell does not know about. Finance laptops, build agents, domain controllers.triage:on objects, for the state of your own review. Useful precisely because it is not an opinion: "somebody is looking at this" is a workflow fact, not a judgment about the file.
When should I use a tag rather than something else?
Three tools overlap here and choosing wrongly makes work for the next person.
Use an opinion to record a judgment. Malicious, Trusted, Benign. An opinion changes what the platform reports and overrides the automated verdict inside your environment. A tag does neither.
Use a threat report to record indicators that should keep matching. A report checks your whole history and everything that arrives next. A tag applies only to the things you attached it to and finds nothing new on its own.
Use a tag when the grouping is yours and the platform has no opinion about it. Campaign membership, ownership, review state, anything organizational.
The distinction that matters: a report is a detection, a tag is a bookmark. Tagging forty files from an incident does not mean you will hear about the forty-first. Putting them in a report does.
What should I read next?
- Setting Opinions, for recording a judgment rather than a grouping.
- CEL Query Language, for querying by tag.
- What is a threat report?, for the standing-coverage version of "these things belong together".
- The API reference, for tagging entities programmatically.
Updated 2 days ago