> ## 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.

# Cotool Detection Authoring

> Iteratively craft production-ready detections with Cotool assistance

Cotool's detection authoring workflow helps you move from an initial idea to a tested, reviewable detection that you can deploy either directly to a platform or through Git-based review.

## Why Detection Authoring in Cotool Is Different

If you use a general AI assistant to write detections, you usually run into one of three problems:

<CardGroup cols={3}>
  <Card title="1. Syntax issues" icon="circle-xmark">
    The query looks plausible but does not compile or does not match the destination platform
  </Card>

  <Card title="2. Environment mismatch" icon="database">
    The rule assumes fields, indexes, or data sources you do not actually have
  </Card>

  <Card title="3. Too much noise" icon="bell">
    The logic technically works but produces alert volume that is too high to be useful
  </Card>
</CardGroup>

**Cotool's approach** is to combine AI-generated suggestions, an editable draft in Detection Studio, test execution, and controlled publishing.

## Two Ways to Start

You can start detection authoring in either of these ways:

### 1. Start from Suggestions

Cotool can generate suggested detections and place them in the **Suggestions** queue. From there you can:

* Review the detection name, description, reasoning, and query
* Dismiss low-value ideas to keep the queue clean
* Restore previously dismissed suggestions
* Open a suggestion in **Detection Studio** for editing
* Deploy a strong suggestion directly if it is already ready

### 2. Start from Scratch

If you already know what you want to build, start a new detection authoring session and guide the agent directly in chat.

This is useful when:

* You have a precise detection concept
* You want to bring your own threat report or sample logs
* You already know the target platform and rough logic

## The Current Workflow

<Steps>
  <Step title="Review or create an initial idea">
    Start from a generated suggestion or describe the detection you want to build.
  </Step>

  <Step title="Open the detection in Detection Studio">
    Clicking **Edit** on a suggestion creates a draft and opens it in Detection Studio.

    If the draft came from a suggestion, Cotool keeps a link back to the source suggestion so you can trace where it came from.
  </Step>

  <Step title="Refine the draft">
    Update the detection name, description, query, MITRE mapping, and any platform-specific configuration.

    Draft changes autosave while you work.
  </Step>

  <Step title="Test Detection">
    Use **Test Detection** to validate the current draft against recent data.

    Depending on platform support, the test view can show:

    * Query errors
    * Sample rows
    * Execution time
    * Data scanned
    * Estimated volume or noisiness
  </Step>

  <Step title="Iterate until the draft is reviewable">
    Ask Cotool to tighten conditions, add exclusions, change output fields, or adapt the logic to your environment. Re-test after each meaningful change.
  </Step>

  <Step title="Publish using the right path">
    When the rule is ready, publish it using the method your platform supports:

    * **Deploy direct to platform**
    * **Deploy via Git**

    If you publish through Git, Cotool opens a PR-based path for review. If you deploy directly, the suggestion is marked as published.
  </Step>
</Steps>

## What You Can Do in Detection Studio

Detection Studio is the working area for turning a rough proposal into a production-ready rule.

### Edit the rule itself

You can directly update:

* **Name**
* **Description**
* **Query**
* **MITRE technique mapping**
* **Platform-specific config** where supported

### Keep provenance

If a draft came from a suggestion, the editor keeps a visible link to the source suggestion. This is helpful when a teammate wants to understand where a rule originated or compare the edited draft to the original idea.

### Copy and share the draft query

You can copy the current query directly from the editor while iterating with teammates or pasting it into other review workflows.

## Testing Before You Publish

The **Test Detection** panel is one of the most valuable parts of the workflow.

It helps you answer practical questions before a rule goes live:

* Does the query execute successfully?
* Are the expected fields present?
* Is the result set empty because the logic is wrong, or because the data is not there?
* Is the rule too noisy for production?
* Does the platform-specific rule configuration validate cleanly?

<Note>
  Test after every major change. A detection that looks correct in chat can still fail because of field names, ingestion gaps, platform constraints, or unexpectedly high volume.
</Note>

## Publish Options

Cotool supports different publishing paths depending on the platform:

| Option                        | Best for                                                                                |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| **Deploy direct to platform** | Fast rollout when the rule is ready and your team is comfortable publishing from Cotool |
| **Deploy via Git**            | Teams that want code review, PR visibility, or a detection-as-code workflow             |

### Direct platform deployment

Use this when you want the detection created in the destination system immediately.

### Git-based deployment

Use this when detections should go through normal review before they are merged or deployed. Cotool creates a PR-backed path so reviewers can inspect the final rule.

## Example Workflow

### Scenario: suspicious PowerShell activity in Splunk

<Steps>
  <Step title="Generate or select a suggestion">
    You review a suggestion for suspicious PowerShell execution from the Suggestions page and click **Edit**.
  </Step>

  <Step title="Open the draft in Detection Studio">
    Cotool creates a draft linked to the source suggestion and opens it in Detection Studio.
  </Step>

  <Step title="Refine the query">
    You update the logic to focus on encoded commands and add exclusions for known admin tooling.
  </Step>

  <Step title="Run Test Detection">
    Cotool executes the query on recent data. The test results show sample rows, execution time, and whether the alert volume looks reasonable.
  </Step>

  <Step title="Adjust for noise">
    You tighten the filters based on the test output and run the test again.
  </Step>

  <Step title="Publish">
    Once the rule looks production-ready, you either deploy it directly to Splunk or send it through a Git-based review flow.
  </Step>
</Steps>

## When to Use Suggestions vs Manual Authoring

| Start with suggestions when...                | Start from scratch when...                                |
| --------------------------------------------- | --------------------------------------------------------- |
| You want AI-generated ideas to review quickly | You already know the exact detection concept              |
| You are looking for coverage gaps             | You have a specific threat report or detection hypothesis |
| You want a first draft to refine              | You want tighter control from the first prompt            |

## Best Practices

<AccordionGroup>
  <Accordion title="Use suggestions as a starting point, not the finish line">
    Even a strong suggestion should be tested and reviewed before deployment. The fastest path is often: suggestion -> draft -> test -> publish.
  </Accordion>

  <Accordion title="Be explicit about false positives">
    Give Cotool concrete exclusions, approved tools, service accounts, or maintenance patterns. Specific exclusions are much safer than broad "reduce noise" requests.
  </Accordion>

  <Accordion title="Attach threat context when possible">
    Threat reports, sample logs, and example indicators help Cotool produce a rule that is closer to your real environment.
  </Accordion>

  <Accordion title="Watch the test results, not just the query text">
    A clean-looking query can still be invalid, too noisy, or mismatched to your data. Use the test panel as your source of truth.
  </Accordion>

  <Accordion title="Choose the publish path that matches your team process">
    If your team relies on code review, use the Git path. If you are iterating quickly in a supported platform, direct deployment may be the better fit.
  </Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I deploy a suggestion without opening the editor?">
    Yes, if a suggestion is already good enough and the platform supports it, you can publish from the Suggestions workflow. Open Detection Studio when you want to refine or validate first.
  </Accordion>

  <Accordion title="What happens if the draft came from a suggestion?">
    Cotool keeps the link between the draft and the original suggestion, so you can trace the source and see whether you are working from an edited copy.
  </Accordion>

  <Accordion title="What if the test query returns no data?">
    Treat that as a signal to investigate. It may mean the query is too narrow, the fields are wrong, or the underlying data is not available in your environment.
  </Accordion>

  <Accordion title="Does Cotool publish detections automatically?">
    Cotool does not deploy rules on its own. You choose when to publish and whether to deploy directly or go through Git-based review.
  </Accordion>

  <Accordion title="How do I keep the suggestion queue manageable?">
    Dismiss low-value suggestions and restore them later if priorities change. This keeps the queue focused on rules your team actually wants to work on.
  </Accordion>
</AccordionGroup>