Triggers
A trigger is a standing rule that watches for one kind of match and notifies you when it happens. What each match type means, and how to pick the right one.
A trigger is a standing rule that watches your environments for one specific kind of match and sends a notification when one happens. It has three parts: which environments' files it watches, which condition it watches for, and where the notification goes. A trigger notifies. It does not block, quarantine, or interrupt anything, because Stairwell is not inline and is not a network enforcement point. Everything a trigger produces is information arriving at a person or a system that can act on it.
Triggers are the reason anything Stairwell finds reaches you without somebody opening the UI. Nothing else in the platform pushes.
What does a trigger watch?
Three settings, chosen in that order when you create one.
- Object environments. The environments whose files are eligible to alert. A file has to be present in one of these for the trigger to have anything to say about it.
- Conditions. What kind of match you care about: a YARA rule matching, a threat report indicator linking, the automated verdict turning malicious, or an opinion of Malicious being recorded. Each condition also asks where its criteria come from, which is a separate question from where the files are. A rule condition asks which environments' rules count. A report condition asks which environments' reports count.
- Destination. Email, a webhook, or the API you poll. See Event Notifications for the procedure and the payload.
The split between whose files and whose criteria is the part worth slowing down for, because it is what lets one trigger watch your own fleet using Stairwell's research rules, and it is also the most common misconfiguration. Selecting your own environment as the rule source when your team has written no rules produces a trigger that is correct, saved, and permanently silent.
Two of the conditions apply only to your own environments and cannot watch the global malware corpus. If you include a global malware corpus environment in the object environments while the automated-verdict or opinion condition is selected, saving fails and tells you to remove that environment or deselect the condition. That is deliberate: the corpus produces malicious verdicts at a volume nobody wants delivered to an inbox.
What are the match types, and which one should I choose?
Every notification carries a match type saying why it fired. There are six, and choosing wrong is the reason a trigger is either silent or deafening.
| Match type | It fires when |
|---|---|
OBJECT_SEEN | A file arrives somewhere in a watched environment and something already established about that file satisfies one of your conditions |
YARA_RULE_MATCH | A YARA rule newly matches a file that was already in a watched environment |
THREAT_REPORT_MATCH | A threat report indicator newly links to a file that was already in a watched environment |
MAL_EVAL_MATCH | The automated verdict for a file in a watched environment newly reaches high confidence malicious |
OBJECT_OPINION_MATCH | Someone records an opinion of Malicious in one of the opinion environments you chose |
| The default alert | The automated verdict turns malicious and no trigger of yours is watching for that. Stairwell alerts anyway |
Read that as two groups rather than six rows, because that is how it behaves.
The five configured types split by which side moved. If the file moved, meaning it showed up somewhere new, you get OBJECT_SEEN. If the knowledge moved, meaning a rule, a report, a verdict, or an opinion changed under a file that was already sitting there, you get the type named after the thing that changed. Same underlying facts, different label, decided entirely by which of the two arrived second. This is why silencing by match type is delicate, and it has its own section in Trigger Silences.
The default alert is configured by nobody. When the automated verdict for a file in your environment reaches high confidence malicious and no trigger of yours is watching for that, Stairwell records the alert regardless, so a customer who has configured nothing still hears about malware. It appears on the Alerts page with a source of MalEval Detection and a trigger name of MalEval Verdict. Because it belongs to no trigger it has no destination: it is not emailed and not sent to a webhook. If you want automated verdicts delivered somewhere, configure the condition for it.
Why did a trigger fire on a file that has been here for months?
Because a match can happen in either direction in time, and the file arriving is only one of the two ways.
Stairwell keeps the executables and scripts your fleet has run, so a rule written today can match a file that arrived last spring, and a report published this morning can link to a file that has been on three of your servers since before the campaign had a name. When that happens the trigger fires now, about a file that is old. The notification carries the sightings, so the dates are in front of you. Read them before treating the alert as news.
This is the most useful property of the arrangement and the most confusing one on first contact. A conventional alert means something happened a moment ago. A Stairwell notification means something is now known, and the event it describes may be historical.
Does a trigger firing mean the file is malicious?
No, and the distinction decides how you spend the next twenty minutes.
A YARA rule matching means a file has a shape somebody wrote a rule about. That is evidence, not a verdict. Your own remote monitoring agent genuinely has the shape of a remote monitoring agent, and intrusions use remote monitoring agents, so the rule is doing its job when it matches your copy. The same holds for a threat report link: an indicator connecting your file to a report through shared infrastructure is a far weaker statement than one connecting it by hash.
The automated verdict is a stronger statement, because it is the resolved output of multiple detection engines, machine learning, and analyst opinion rather than a single criterion. It is still not a confirmed incident.
So triage the notification rather than acting on it. Read which criterion matched, check prevalence, read the sightings, and decide after that. The Alert Is a Legitimate IT Tool walks the case where the answer turns out to be your own tooling, which is the most common answer.
How often will the same file notify me?
Once per new place, not once per execution.
A file appearing at a location where that same file has already been seen does not notify again. A file appearing on a new asset, or at a new path on an asset you already have it on, does. That is what makes a notification count meaningful: forty notifications for one hash means forty places, which is a spreading story rather than a busy machine.
Verdict-driven notifications have their own suppression. Once a file has notified a given trigger on the strength of its automated verdict, that trigger does not re-notify for the same file within twenty-four hours, whichever engine produced the newer result.
Where do I see triggers and what they produced?
- Settings, then Integrations, then Event notifications. Your triggers with their destinations and condition counts, and where you create, edit, and delete them.
- The Alerts page in the left navigation, which is every notification your environments produced, filterable by source and by match type. Notifications are kept there for 180 days.
- Your destination, whichever you chose, receiving each match as it happens.
- The object panel of any file in a notification, which is where triage actually happens. See The Object Panel.
What should I read next?
- Event Notifications, for the procedure to create one and what a webhook payload contains.
- Trigger Silences, for cutting noise without cutting the detection along with it.
- The Alert Is a Legitimate IT Tool, the playbook for the notification you will see most often.
Updated 4 days ago