Alert Routing

Alert routing controls where alerts go after Cotool creates them: which response agent triages each new alert, and where escalated alerts are announced. Both use the same kind of ordered routes, so they behave the same way.

​

Open routing

Go to Settings > Routing. The page has two sections, each with an ordered list of routes:

• Alert Triage Routing chooses which response agent triages each new alert from a Cotool detection or an agent.
• Escalated Alert Notification Routing chooses where an escalated alert is announced.

Each section opens as a read-only table. Choose Edit to change it, then Save in the bar at the bottom of the page, or Cancel to leave without changes. You can also see routing where it applies:

• A Cotool detection’s Settings tab shows a small graph of where its next alert goes: the triage route it matches, the agent that triages it, then the escalation route and the destinations notified.
• An agent’s page shows the same graph for the alerts the agent creates, and, for an agent that triages alerts, every detection, agent, and trigger whose alerts it triages.

Every node in these graphs links to its detection, its agent, or its section of Settings > Routing.

​

How routes work

A route has a name, one or more conditions, and what to do with the alerts it matches. Routes are checked from top to bottom, and the first enabled route whose conditions all match wins. Alerts that no route matches fall through to the default at the bottom of the list. A route can match on: When a route has several conditions, an alert has to match all of them. Because table conditions follow what a detection queries, a detection you add later, including one from the detection library, is routed as soon as it is published.

​

Triage routing

Triage routes decide which response agent triages a new alert from a Cotool detection or an agent. Each route either sends matching alerts to an agent, which starts a triage run right away, or leaves them Unassigned so they stay open for a person. Alerts that no route matches go to the default agent. If the default is Leave unassigned, those alerts stay open and unassigned.

​

Edit triage routes

1. Go to Settings > Routing and choose Edit next to Alert Triage Routing.
2. Add, reorder, or remove routes, and choose an agent (or Unassigned) for each.
3. Choose the default agent in Default route.
4. Choose Save.

To check where one detection’s or agent’s alerts go, open its page and look at its routing graph. If a route’s agent is deleted, the route is skipped and its alerts fall through to the next matching route. A route never sends an agent’s own alerts back to that agent. Routes can’t send alerts between agents in a loop, for example Agent A’s alerts to Agent B and Agent B’s alerts back to Agent A, including through the default agent. Saving routes or a default agent that would do that fails and names the agents in the loop. If a loop forms later, for example when an agent gets the create-alert tool, Cotool doesn’t start triage on an alert routed to an agent that already created an alert in the chain that led to it, or on an alert more than five alerts down such a chain. The alert stays unassigned, with a comment saying why. A list holds up to 50 routes. Routes copied from per-detection routing rules can make a longer list, which you can edit and save at its current length but can’t add to. Changing triage routing requires the Manage Alerts permission.

​

Escalation notifications

Escalated alert notifications use the same kind of routes, so the same conditions match, plus one more: Alert triaged by agent matches the response agent the alert is assigned to for triage. Triage routes cannot use it, because they choose that agent. They are configured in Settings > Routing under Escalated Alert Notification Routing: choose Edit to turn notifications on, set a minimum severity, add routes that send matching escalations to their own destinations, and choose default destinations for everything else. Settings > Notifications shows how they are set and links there. Alerts created by triggers only match on the agent that triaged them, which is the trigger’s own agent. Hunt alerts always go to the default destinations. Each destination on a route or in the defaults has its own severity setting next to it, on top of the minimum severity. Any severity sends it every escalation the minimum allows; Critical only, for example, sends it only critical alerts. A route can send every escalation to a Slack channel and only critical ones to incident.io this way. A route still handles every alert its conditions match, so an alert below all of its destinations’ settings notifies nobody instead of moving on to the next route. Alerts of unknown severity go only to destinations set to Any severity. Hunt alerts honor the default destinations’ settings.

​

Status changes in Slack

A Slack escalation notification keeps up with the alert. When anyone changes the alert’s status, from Cotool, Slack, or a triage agent, the notification is edited to show the new status and the person who set it. A reply in its thread says what the status changed to, who changed it, and why. In a channel where the alert already has a thread, the reply goes in that thread instead.

​

Declare incidents in incident.io

An incident.io destination declares an incident in incident.io for each escalated alert it is sent, and the alert’s notification card links to it. Connect incident.io in Tools first, then create the destination from an escalation route or the default destinations. Choose the incident.io severity to declare incidents with (a new destination starts on your least severe one), whether they are private or public, and optionally an incident type; otherwise incident.io applies its default type. Private is the default. Only the incident’s responders and people with access to private incidents can open a private incident, so the link on the alert asks anyone else to request access. Send test declares a test incident, which does not page anyone. incident.io destinations only receive escalated alerts and Hunt alerts. A Hunt alert declares one incident per destination: when it is refreshed, its notification links to the incident it already declared. incident.io allows 10 new incidents an hour. Past that, Cotool keeps trying each incident for up to two hours, then reports the delivery as failed.

​

Trigger-created alerts

Response-agent triggers can create alerts when Create alert on trigger is enabled. Default behavior by trigger type: You can change the toggle when creating or editing the trigger on its agent’s page. Trigger-created alerts are assigned to the response agent that owns the trigger, and Cotool starts that agent’s triage run from the alert. To move a trigger to another agent, edit it and choose the new Agent; its URL, secret, and email address keep working. Cotool stores the original trigger payload with the alert. The alert detail page shows the payload in Alert Payload when it is available.

​

Routing outcomes

​

Keep routing healthy

Review Settings > Routing when:

• New detection alerts are piling up as open and unassigned
• A response agent is deleted or disabled
• A detection or a group of detections should be handled by a different response agent than the organization default
• A trigger is producing too many or too few alerts