/create-detection) in a workspace with Code Mode enabled, or use Open editor on an existing detection in Detections. Describe the behavior to detect, the available data, the time window, and the exceptions that should not alert.
For example: “Detect repeated failed sign-ins followed by a successful sign-in for the same user. Use our collected identity logs, include evidence for both stages, and exclude our documented test accounts.”
Develop the draft
The editor maintains a draft Python notebook. Work with Cotool to inspect the available schemas and tools, implement the conditions, and review the resulting logic. Draft changes autosave but do not replace the published version. Detection output usesemit_results(). Each finding needs a meaningful entity, and new published logic must set entity_type, such as user, host, or ip. Severity and supporting fields describe the result. Use stable entity identifiers so repeated activity can be correlated consistently.
Notebooks reach connected integrations through the cotool_tools SDK: tool actions as tools.<action>(...) and connected CLI integrations (AWS, Azure, Google Cloud) as clis.aws(...), clis.az(...), and clis.gcloud(...). CLI commands run outside the notebook with the organization’s connected credentials, and only read-only commands are allowed; commands that change state or expose credentials are refused. Publishing records the tools and CLIs a notebook uses, and each must be connected for the detection to run.
Query signals
A detection can read thesignals table in Cotool Logs as well as your log tables. Each row is one security-relevant event that a signal detection recorded, with the same fields for every source: signal_type, event_time, actor, target, IP address with country and network, and attrs for type-specific details.
Use signals when the detection is about a pattern across events, not one event:
- a count, such as five failed MFA signals for one user in ten minutes;
- a sequence, such as a script run on a host followed by a new persistence item on it;
- first-seen behavior, such as an account changing an application’s credentials for the first time;
- activity across tools, such as a sign-in from a new country followed by a role grant in another product.
signal_type with the exact types you need. Cotool then knows which signals the detection depends on and waits for them to be complete before each scheduled run.
Always read the table with FINAL and is_deleted = 0:
FINAL and the is_deleted filter, a query can count one signal twice or count a signal that was removed, and the detection can alert on it. In a detection, use the run’s time window in place of the fixed interval shown here.
Run the current revision
Select Run in the editor and inspect the output and any errors. Check that the logic reachesemit_results(), including when there are no matching findings.
Before publishing, verify:
- The source data exists and covers the intended time window.
- The detection identifies the intended entity and includes useful evidence.
- Expected benign activity is handled by explicit conditions or exclusions.
- The current revision completes successfully.
emit_results(). A successful earlier revision does not validate subsequent edits. An empty emitted result set is different from never calling emit_results().