Skip to main content
Use Create a Detection (/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 uses emit_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 the signals 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.
If one event alone should alert, edit the promotion on its signal type instead of writing a detection. See Promotions. Filter on 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:
Cotool replays signal detections when one is updated or after a gap. A replay rewrites signals and marks the ones it retracts as deleted, and Cotool runs your SQL as written. Without 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 reaches emit_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.
Publishing requires a successful run of the exact draft revision and evidence that it reached emit_results(). A successful earlier revision does not validate subsequent edits. An empty emitted result set is different from never calling emit_results().

Publish and check the schedule

Select Publish to create a new published version. The first publish enables scheduling, defaulting to hourly if a cadence has not been set. Review Settings immediately if a different cadence or a paused schedule is needed. Subsequent publishes replace the live logic while preserving schedule settings. Review version history and the Logic tab to confirm which version is live. For a detection using a fixed sliding lookback, keep the lookback at least as long as the run cadence to avoid gaps between windows. For detections using an advancing window, only successful scheduled runs advance the cursor; manual runs do not.

Manual runs and alerts

The detection detail page’s run action executes the published version. In production, manual published runs record execution output without creating detection hits or alerts. Use Executions to inspect these results. Scheduled runs process findings into hits and qualifying alerts. Continue with Operate and Tune Detections to configure alert severity and triage routing. Back to Detections Platform