> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Author and Publish Detections

> Develop a detection, validate its current revision, and publish it to run in Cotool.

Use [Create a Detection](https://app.cotool.ai/?command=create-detection) (`/create-detection`) in a workspace with Code Mode enabled, or use **Open editor** on an existing detection in [Detections](https://app.cotool.ai/detections/overview). 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](https://docs.cotool.ai/detections-platform/signals) 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](https://docs.cotool.ai/detections-platform/signals#promotions-from-signal-to-alert).

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`:

```sql theme={null}
SELECT actor_display, count() AS grants
FROM cotool_logs.signals FINAL
WHERE signal_type = 'okta.admin_role.granted'
  AND is_deleted = 0
  AND event_time >= now() - INTERVAL 1 DAY
GROUP BY actor_display
```

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](https://docs.cotool.ai/detections-platform/operations) to configure alert severity and triage routing.

[Back to Detections Platform](https://docs.cotool.ai/detections-platform/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.