# Apex application security documentation
Source: https://docs.cantina.security/apex
Set up Apex to scan repositories and pull requests for exploitable vulnerabilities, verify findings, and run scans through the app, CLI, or API.
Apex is Cantina's agentic application security engineer. It reviews repositories and pull requests for exploitable vulnerabilities, produces findings with evidence and remediation guidance, and verifies whether fixes hold.
## How the docs are organized
The Apex docs are organized around the workflow most teams follow: connect code, define the workspace, scope the scan, and then run or automate the scan from the app or CLI.
Use this page as the entry point when you are deciding which guide belongs to the next step in setup or scan planning.
> **Key idea**
> Start with onboarding when access is not configured yet. Start with the scan manual when a workspace already exists and the main decision is scope.
## Guides
* **[Start here - Client onboarding](/apex/onboarding):** Connect GitHub or GitLab, choose repositories, and send the context Apex needs before the first scan.
* **[Run scans - Apex scan manual](/apex/scan-manual):** Scope a scan, choose when to run it, explain the threat model, and split larger repos into useful review units.
* **[Automate scans - Scheduled scans](/apex/scheduled-scans):** Turn on recurring auto-scans of a workspace, choose a daily or weekly cadence, and keep monitoring without manual runs.
* **[Reference - Apex CLI guide](/apex/cli):** Install the CLI, wire Apex into Claude Code, Codex CLI, or GitHub Copilot CLI, and drive scan workflows from the terminal.
* **[Reference - Apex service API](/apex/api):** Create an organization service key, trigger scans from a headless worker, poll their status, and retrieve GitLab SAST findings.
## Scan workflow
Apex works best when the workspace reflects a real security surface, not a loose collection of unrelated directories. The path below keeps access, scope, and context aligned before the scan starts.
* Connect a code host or use the CLI from the repository you want to scan.
* Create a workspace and choose the repositories, branches, pull requests, or commits in scope.
* Add private docs, architecture notes, API specs, and threat model details that are not obvious from the code.
* Run the scan after the scope and context describe one coherent system.
* Use the CLI or workspace UI to track progress, read findings, and export results.
> **Before the first scan**
> Make sure the person approving repository access and the person deciding scan scope agree on the same repos, refs, and supporting materials.
## Reference
The CLI guide is the canonical reference for local and agent-driven workflows. The service API guide covers static-token, headless HTTP integrations for serverless workers and audit hubs.
* Read [client onboarding](/apex/onboarding) if you are setting up a workspace for the first time.
* Read the [scan manual](/apex/scan-manual) before spending a scan entitlement or splitting a large repo.
* Use the [CLI guide](/apex/cli) when you want Apex available directly inside developer and agent workflows.
* Use the [service API](/apex/api) when a serverless function, cron job, or internal audit hub needs static-token HTTP access.
For a product-level explanation of what Apex finds and how it fits into Cantina, see the [Apex application security overview](https://www.cantina.security/apex).
# Apex service API
Source: https://docs.cantina.security/apex/api
Run Apex from serverless functions, CI, and internal audit hubs with an organization service key and a REST/JSON workflow.
* **Read:** 12 min
* **Updated:** August 17, 2026
* **Audience:** Platform engineers
## § 01 Choose the right integration
Use Apex CLI or MCP when a person or coding agent is working interactively in a repository. Use the service API when a headless process needs HTTP, JSON, and a static organization credential.
| Surface | Intended use | Authentication |
| - | - | - |
| CLI + MCP | Developers and coding agents | Device login |
| Service API | CI, serverless workers, cron jobs, and internal audit hubs | Organization service key |
Set the service key as `APEX_SERVICE_KEY` and send it as `Authorization: Bearer ...` or `X-API-Key`. The CLI does not consume this variable and `apex login` does not accept service keys. `APEX_API_KEY` is a legacy integration name; rename it to `APEX_SERVICE_KEY` when adopting these examples.
The machine-readable contract is available at [`/api/apex/v1/openapi.json`](https://ai.cantina.xyz/api/apex/v1/openapi.json).
## § 02 Prerequisites
* Generate a service key with the smallest required scopes: `scans:create`, `scans:read`, and `findings:read`.
* Store the key in a secret manager. Apex displays the raw secret once and stores only its hash.
* For a remote scan, connect the GitHub repository to the organization that owns the key. The first API scan can create and link its workspace automatically.
* For a remote scan, send a full 40- or 64-character commit SHA. Branch names and moving refs are not accepted.
* For a local or non-Git directory, create a `tar.gz` archive and use the source upload flow. No Git remote or website scan is required.
GitLab service-account access is not yet supported by the version-one remote repository flow. Use a local archive for source that Apex cannot materialize through an organization GitHub connection.
## § 03 Generate a service key
Organization managers and Apex administrators can generate a key from **Company Settings → Service API keys**. Copy the one-time secret directly into a secret manager.
You can also create one from your own authenticated terminal:
```bash theme={null}
apex update
apex login
# Read existing scans and findings only
apex service-key create \
--name "Audit hub" \
--scope scans:read,findings:read \
--expires-at ""
# Add scans:create for an integration that starts or cancels scans
apex service-key create \
--name "Audit hub" \
--scope scans:create,scans:read,findings:read \
--expires-at ""
```
The commands above use device login only to let an authorized person create the service key. The resulting service key is for REST requests, not later CLI authentication.
List metadata or revoke a key without exposing its secret:
```bash theme={null}
apex service-key list
apex service-key revoke
```
## § 04 Check credit balances
Use the service key to read the current balances for its organization before
offering scan choices:
```bash theme={null}
curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
https://ai.cantina.xyz/api/apex/v1/credits
```
```json theme={null}
{
"companyId": "2abf03ae-768b-4717-9d14-43e1a8d8d9a1",
"scansEnabled": true,
"balances": {
"standard": { "purchased": 12, "used": 5, "remaining": 7 },
"audit": { "purchased": 2, "used": 1, "remaining": 1 },
"lite": { "purchased": 8, "used": 3, "remaining": 5 }
},
"scanTypes": {
"standard": {
"available": true,
"ledger": "standard",
"creditsRequired": 1
},
"audit": {
"available": true,
"ledger": "audit",
"creditsRequired": 1
},
"lite": {
"available": true,
"ledger": "lite",
"creditsRequired": 1
}
}
}
```
The endpoint requires `scans:create` and never accepts a company identifier;
the authenticated service key determines the organization. `scanTypes` applies
the active credit ledger, configured cost, and `scansEnabled` state. Source
compatibility is separate: local archives support only `standard`, while
`audit` and `lite` require a provider-backed GitHub source.
The response is a point-in-time snapshot. Scan creation can still return `402`
if another request consumes the entitlement first; refresh the balances before
offering another confirmed choice.
## § 05 Trigger a remote scan
Send a stable, unique `Idempotency-Key` for each intended scan. Reuse it only when retrying the identical request after a transport error, timeout, or `5xx`.
```bash theme={null}
curl --request POST https://ai.cantina.xyz/api/apex/v1/scans \
--header "Authorization: Bearer $APEX_SERVICE_KEY" \
--header "Idempotency-Key: 8c8d9e5d-4fa6-4b65-bd42-14ddb5874c83" \
--header "Content-Type: application/json" \
--data '{
"repoUrl": "https://github.com/acme/payments",
"commit": "0123456789abcdef0123456789abcdef01234567",
"paths": ["src", "packages/auth"],
"scanType": "standard",
"generateThreatModel": true
}'
```
If no active workspace is linked to the canonical repository, Apex creates one and links it before starting the scan. If multiple workspaces match, the API returns a conflict with workspace choices; submit a new intended request with the selected `workspaceId` and a new idempotency key.
When `workspaceId` is present, `useExistingThreatModel` defaults to `true`. Apex validates that a completed model exists before reserving credits. Set `generateThreatModel: true` for a fresh model, or `generateThreatModel: false` only when you intentionally want neither generation nor validated reuse.
The optional `paths` array is a focus hint, not a security boundary. Apex may inspect or report code outside those paths.
| Scan type | Notes |
| - | - |
| `standard` | Default; supports remote repositories and local archives |
| `audit` | Requires a provider-backed source and an audit entitlement |
| `lite` | Requires a provider-backed source and Lite access/credits |
## § 06 Scan a local directory
Raw filesystem paths cannot cross an HTTP boundary. Package the source, calculate its SHA-256 plus compressed and uncompressed byte counts, then create, upload, complete, and scan the archive.
```bash theme={null}
# 1. Create the archive outside the source tree or exclude the output archive.
tar --exclude="./apex-source.tar.gz" -czf apex-source.tar.gz .
# 2. Create the workspace and signed upload session.
curl --request POST https://ai.cantina.xyz/api/apex/v1/source-uploads \
--header "Authorization: Bearer $APEX_SERVICE_KEY" \
--header "Content-Type: application/json" \
--data '{
"workspaceName": "Payments local",
"uploads": [{
"displayName": "payments",
"relativePath": ".",
"archiveFormat": "tar.gz",
"sha256": "",
"compressedBytes": ,
"uncompressedBytes":
}]
}'
# 3. PUT the archive to uploads[0].upload.putUrl using every returned header.
curl --request PUT \
--header "Content-Type: application/gzip" \
--upload-file apex-source.tar.gz \
""
# 4. Verify the upload and retain the returned archiveId and sha256.
curl --request POST \
--header "Authorization: Bearer $APEX_SERVICE_KEY" \
--header "Content-Type: application/json" \
--data '{"workspaceId":""}' \
https://ai.cantina.xyz/api/apex/v1/source-uploads//complete
# 5. Start a standard scan from the completed archive.
curl --request POST https://ai.cantina.xyz/api/apex/v1/scans \
--header "Authorization: Bearer $APEX_SERVICE_KEY" \
--header "Idempotency-Key: " \
--header "Content-Type: application/json" \
--data '{
"workspaceId": "",
"scanType": "standard",
"generateThreatModel": true,
"scanSources": [{
"sourceKind": "local_archive",
"displayName": "payments",
"relativePath": ".",
"archiveId": "",
"sha256": ""
}]
}'
```
A newly created local workspace has no completed threat model to reuse. Keep `generateThreatModel: true` on its first scan; omitting it makes a request with `workspaceId` default to existing-model reuse and can return `THREAT_MODEL_NOT_AVAILABLE`.
Each archive must be at most 500 MiB compressed and 2 GiB uncompressed. A scan can include at most 20 archives. Signed upload URLs are credentials: do not log or persist them beyond the upload.
A successful scan request returns HTTP `202`:
```json theme={null}
{
"scanId": "3e559b86-f524-4b27-a175-fb4944c53f1b",
"workspaceId": "2abf03ae-768b-4717-9d14-43e1a8d8d9a1",
"status": "preparing",
"statusUrl": "/api/apex/v1/scans/3e559b86-f524-4b27-a175-fb4944c53f1b",
"findingsUrl": "/api/apex/v1/scans/3e559b86-f524-4b27-a175-fb4944c53f1b/findings"
}
```
## § 07 Poll and cancel scans
```bash theme={null}
curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
https://ai.cantina.xyz/api/apex/v1/scans/
```
Retain `scanId` and `workspaceId`. Poll with bounded backoff while status is `preparing`, `queued`, or `running`; stop on `completed`, `failed`, or `cancelled`. Large scans can take hours, so a 20-minute timeout is not suitable for full-codebase benchmarking. Make polling resumable instead of creating a duplicate scan after a client restart.
To cancel an active scan:
```bash theme={null}
curl --request POST \
--header "Authorization: Bearer $APEX_SERVICE_KEY" \
https://ai.cantina.xyz/api/apex/v1/scans//cancel
```
Cancellation requires `scans:create`. Repeating a successful cancellation is safe. Apex returns `409` when the scan is already completed or failed, or has not started in Apex yet.
## § 08 Fetch findings
```bash theme={null}
curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
https://ai.cantina.xyz/api/apex/v1/scans//findings
```
The scan findings response is a GitLab SAST report. Each vulnerability includes the persisted Apex finding ID, title, description, severity, and available source location. IDs remain stable when the same scan is fetched again.
A key with `findings:read` can retrieve unpublished drafts. Treat the payload and credential as privileged data.
The first findings request after completion may return `503` with `Retry-After` while Apex durably synchronizes the terminal finding set. Retry the same GET.
To retrieve the same cross-scan set as the workspace findings browser, use a workspace prefix or UUID:
```bash theme={null}
curl --header "Authorization: Bearer $APEX_SERVICE_KEY" \
'https://ai.cantina.xyz/api/apex/v1/workspaces/BEDR9/findings?state=open'
```
`state=open` excludes invalid findings, duplicates, and findings marked fixed, false positive, won't fix, or skipped. Repeat `filter` to combine facets such as `severity:high`, `review:accepted`, `repo:example-app`, `source:lib/auth.ts`, or `!validation:invalid`.
## § 09 Errors and retries
| Code | Meaning |
| - | - |
| `400` | Invalid commit, path hint, archive metadata, or request body |
| `401` | Missing, malformed, expired, or revoked service key |
| `402` | Selected scan credit or entitlement is exhausted |
| `403` | The key lacks the required scope |
| `404` | The resource does not exist in the key's organization |
| `409` | Idempotency conflict, workspace mismatch, active scan, or invalid cancellation state |
| `422` | Unsupported repository or scan-source input |
| `429` | Rate limit reached; respect `Retry-After` |
| `500` / `502` / `503` | Server, provider, provisioning, or finalization failure; retry safely with backoff |
GET and cancellation requests are safe to retry. After a transport error, timeout, or `5xx`, retry scan creation only with the original body and original `Idempotency-Key`. After correcting a definitive `4xx`, submit a new intended request with a new key. Never log authorization headers, the service key, or signed upload URLs.
## § 10 Agent-ready environment prompt
Use the [API agent environment](/apex/api-agent-environment) when a coding agent or orchestration system must choose a source and start one Standard scan, then return the workspace ID, scan ID, and handoff links immediately. It is deliberately REST-only: it does not install Apex CLI, call `apex login`, or remain attached while a multi-hour scan completes.
Short prompts for adapter development:
* Using `APEX_SERVICE_KEY` from the environment, fetch the organization's current Apex Standard credit balance, ask whether to use the exact local archive or a compatible provider-backed commit, start one confirmed Standard scan, and immediately return its workspace ID, scan ID, accepted status, status URL, findings URL, and web link without logging credentials.
* Package this local directory as `tar.gz`, create and complete an Apex source upload, then start a standard scan from its `local_archive` scan source. Keep the service key and signed upload URL secret.
* Given an Apex `scanId`, fetch its findings, preserve the raw response, and import each vulnerability once by stable ID. Do not trigger a new scan.
# Apex API agent environment
Source: https://docs.cantina.security/apex/api-agent-environment
A copyable REST-only prompt that selects a source and starts a Standard Apex scan, then returns handoff links immediately.
* **Read:** 7 min
* **Updated:** August 17, 2026
* **Audience:** Platform engineers and agent developers
## When to use this prompt
Use this environment prompt when an agent, CI worker, or orchestration service
must choose a source and start one Standard Apex scan without remaining attached
for hours. The agent returns the workspace and scan identifiers plus links as
soon as Apex accepts the scan. A person or separate worker can monitor it
afterward.
Do not combine it with CLI instructions. Apex CLI and MCP use device login;
`APEX_SERVICE_KEY` authenticates only the REST API.
Starting a scan requires `scans:create`. A later worker that polls status or
downloads findings also needs `scans:read` or `findings:read`, respectively.
`GET /api/apex/v1/credits` returns the service key organization's current
standard, audit, and Lite balances plus effective scan-type availability. This
is a point-in-time snapshot; scan creation remains authoritative if balances
change before submission.
This prompt intentionally starts only `standard` scans. It offers an exact
local archive or, when compatible, a provider-backed GitHub commit. It never
offers `audit` or `lite`.
## Copyable environment prompt
```text theme={null}
## Task
Help the caller choose a source, confirm, and start exactly one Standard Apex
security scan for this repository through the hosted REST API. As soon as Apex
accepts the scan, return the workspace ID, scan ID, accepted status, and direct
links. Do not wait for the scan to finish, poll it, or fetch findings in this
task. Never offer or start an Audit or Lite scan.
## Integration boundary
- Use the Apex service API documented at https://ai.cantina.xyz/docs/apex-api.
- Do not install or invoke Apex CLI or MCP.
- Do not run `apex login`; CLI device authentication does not accept service
keys.
## Preconditions — check before doing anything else
1. Check only whether `APEX_SERVICE_KEY` is set and non-empty.
- If missing or empty, stop immediately and report that
`APEX_SERVICE_KEY` is not defined.
- Never print, echo, log, serialize, or include its value in an error.
- Do not inspect or print `CANTINA_API_KEY`; this workflow does not use it.
2. Confirm the key is intended to have `scans:create`. If the API returns 403,
stop and report that the key lacks the required scope.
3. Read the current API documentation before making requests. If it conflicts
with this prompt, follow the documentation and report the difference.
4. Call `GET /api/apex/v1/credits` with the service key.
- If `scansEnabled` is false, stop and report that scans are disabled for
the organization.
- Retain `balances.standard` and `scanTypes.standard` in memory. Do not use
CLI/MCP or ask the caller to supply balances.
- Treat `scanTypes.standard.available` as a point-in-time credit check. The
accompanying `ledger` and `creditsRequired` explain the Standard balance
that will be charged.
- Ignore Audit and Lite availability. This workflow never offers those scan
types even when they have available credits.
## Choose before creating anything
1. Inspect the checkout without modifying it. Determine the repository
directory name, full HEAD commit SHA, Git remote, and whether the checkout
is clean and its HEAD commit is available from the GitHub remote.
2. Build the compatible choices below. Never show a source-incompatible choice.
Apply the credit response before presenting the list.
- `standard` + `local_archive`: available when
`scanTypes.standard.available` is true, for the exact local checkout,
including dirty, unpushed, non-Git, or non-GitHub source.
- `standard` + `remote_repo`: available only for a clean, provider-backed
GitHub commit that Apex can materialize and when
`scanTypes.standard.available` is true.
- If no compatible funded choice remains, report the Standard remaining
balance and stop without creating anything.
3. Present one concise selection question. State that the scan type is fixed to
Standard. For each choice show the source mode, effective ledger, credits
required, and that ledger's remaining balance. Explain that a local archive
scans the exact checkout, while a remote scan uses the named commit. Ask:
`Which Standard scan source should I use?`
- Do not create an archive, upload, workspace, or scan before the caller
chooses.
- If only one compatible choice remains, ask the caller to confirm it.
- If the caller already selected a compatible source mode in the same
request, summarize the Standard scan choice and treat it as confirmed.
## Start the confirmed scan
### Local archive choice
1. This source supports only `scanType: standard`. Create a temporary `tar.gz`
archive outside the source tree without modifying tracked files.
2. Calculate the archive SHA-256, compressed byte count, and uncompressed byte
count required by `POST /api/apex/v1/source-uploads`.
3. Create a source-upload session using the repository directory name as the
workspace name. Retain the workspace ID, upload ID, signed PUT URL, and
required upload headers in memory. Treat the signed URL as a credential.
4. PUT the archive to the signed URL using every returned header. Then call
`POST /api/apex/v1/source-uploads/{uploadId}/complete` and retain its archive
ID and verified SHA-256.
5. Build the scan request with the workspace ID, `scanType: standard`,
`generateThreatModel: true`, and one `local_archive` scan source containing
the archive ID and verified SHA-256. A new local workspace has no model to
reuse, so do not omit `generateThreatModel: true`.
### Provider-backed choice
1. Use the canonical GitHub repository URL and full HEAD commit SHA. Do not use
a moving branch or tag.
2. Build the scan request with `scanType: standard`, `repoUrl`, `commit`, and
`generateThreatModel: true`.
3. If workspace resolution returns 409 with multiple matching workspaces, show
those choices and ask which workspace to use. After selection, include its
`workspaceId` and use a new idempotency key because the first request had a
definitive 4xx response.
### Submit and hand off
1. Generate one stable idempotency key for this intended scan. Call
`POST /api/apex/v1/scans` with the confirmed request.
2. After a successful HTTP 202 response, retain the workspace ID from source
setup, workspace resolution, or the accepted response, plus the returned
scan ID, status, `statusUrl`, and `findingsUrl`.
3. Resolve relative API URLs against `https://ai.cantina.xyz` and construct:
- Workspace link:
`https://ai.cantina.xyz/workspace/`
- Scan link:
`https://ai.cantina.xyz/workspace/?scanId=`
4. Delete only the temporary local archive, if one was created. Do not modify
repository files.
5. Return the handoff output immediately. Do not call the status or findings
endpoints, wait for a terminal state, or create `apex-findings.json`.
## Credit and error UX
- On 402, report that the Standard scan credit is unavailable. Do not submit
another scan. Refresh `GET /api/apex/v1/credits`; if Standard is available,
re-present the compatible source choices and require confirmation. Otherwise
report the remaining Standard balance and stop.
- On 403, report the missing `scans:create` scope.
- On a workspace-resolution 409, ask the caller to choose from the returned
workspaces; do not guess.
- On an active-scan or other 409, report the conflict and stop rather than
forcing or duplicating work.
- On an unrecoverable error, report the HTTP method, endpoint path, status, and
redacted response body.
## Retry and safety rules
- Send `Authorization: Bearer ` without logging the header.
- Credit-balance GET requests are safe to retry with bounded backoff.
- Reuse the same idempotency key and identical request body only after a
transport error, timeout, or 5xx from scan creation.
- After correcting a definitive 4xx, use a new idempotency key.
- Never change source mode or workspace without caller confirmation. The scan
type must remain `standard`.
- Never create a second scan merely because a request timed out or the client
restarted.
- Do not improvise CLI commands or alternative authentication flows.
## Output
Return immediately after HTTP 202 in this shape:
Apex scan started
- Scan type: standard
- Source mode:
- Workspace ID:
- Scan ID:
- Accepted status:
- Workspace: https://ai.cantina.xyz/workspace/
- Scan: https://ai.cantina.xyz/workspace/?scanId=
- Status API:
- Findings API: (available after completion)
Do not include elapsed time or finding counts because this task does not wait
for completion.
```
## Why this returns immediately
* The scan type is fixed to Standard, and the caller chooses and confirms the
source before any upload or scan is created.
* Source compatibility and the authenticated Standard balance snapshot filter
the choices before the caller confirms one.
* It returns stable workspace and scan identifiers plus clickable handoff links
as soon as Apex accepts the scan.
* Monitoring and findings retrieval are separate, resumable tasks, so the
initiating agent does not remain attached for a multi-hour scan.
See the [Apex service API guide](/apex/api) for request examples, archive limits,
scan-type constraints, status values, and retry behavior.
# Apex CLI guide
Source: https://docs.cantina.security/apex/cli
Install Apex CLI, wire it into Claude Code, Codex CLI, or GitHub Copilot CLI, and run scans from the terminal or an agent.
* **Read:** 12 min
* **Updated:** August 13, 2026
* **Audience:** Developers
## § 01 What Apex CLI is
Apex CLI is the standalone Apex client. It ships an interactive shell, a scripted command surface, and a stable apex-mcp server over stdio. apex setup registers Apex with Claude Code, Codex CLI, and GitHub Copilot CLI and installs their skills. This page reflects `@cantinasecurity/apex-cli` 0.1.26 and its current command surface.
> **Building a headless integration?**
> CLI and MCP use device login for people and coding agents. Use the Apex service API when a serverless function, cron job, or internal audit hub needs HTTP and a static organization service key.
## § 02 Install the CLI
```javascript theme={null}
npm install -g @cantinasecurity/apex-cli
# or
pnpm add -g @cantinasecurity/apex-cli
```
The npm package requires Node.js 20 or newer. The install commands use the latest npm dist tag. Run `apex update` to replace an older global install.
Then register Apex with installed agent CLIs and install skills:
```javascript theme={null}
apex setup # registers with whichever CLIs are installed
apex setup claude # Claude Code only
apex setup codex # Codex CLI only
apex setup copilot # GitHub Copilot CLI only
apex update # upgrade in place
```
> **What apex setup does**
> Registers Apex as an MCP server in installed Codex, Claude Code, and GitHub Copilot CLI clients, installs the Codex skill into `$CODEX_HOME/skills/apex-cli`, installs the Claude project skill into `.claude/skills/apex-cli` in the current repository, and installs the GitHub Copilot CLI skill into `$COPILOT_HOME/skills/apex-cli` or `~/.copilot/skills/apex-cli`. Re-run setup after upgrading if you want to refresh copied skill files.
## § 03 Sign in to Apex
```javascript theme={null}
apex login # starts device login
apex doctor # validates auth, source detection, workspace binding, materialization
```
The default host is `https://ai.cantina.xyz/`. Use `APEX_BASE_URL` only when testing against a non-production Apex host.
`APEX_SERVICE_KEY` authenticates the hosted REST API only. It does not authenticate CLI or MCP commands, which use device login. `apex doctor` reports this distinction when it detects an Apex service key but no device-login session. `APEX_API_KEY` is recognized for that migration diagnostic, but `APEX_SERVICE_KEY` is the documented REST variable.
## § 04 Use with Claude Code
```javascript theme={null}
apex setup claude
# or, manually:
claude mcp add apex --scope user -e APEX_MCP_CLIENT=claude -e APEX_CLIENT_INTEGRATION=claude -- apex-mcp
```
Expected result: Apex appears as a connected MCP server inside Claude Code and apex-\* tools are available.
## § 05 Use with Codex CLI
```javascript theme={null}
apex setup codex
# or, manually:
codex mcp add apex --env APEX_MCP_CLIENT=codex --env APEX_CLIENT_INTEGRATION=codex -- apex-mcp
```
## § 06 Use with GitHub Copilot CLI
```javascript theme={null}
apex setup copilot
# or, manually:
copilot mcp add apex --tools "*" -- apex-mcp
```
## § 07 Prompt examples
Phrases that work well from inside Claude Code, Codex CLI, GitHub Copilot CLI, or any other MCP-aware agent.
* Scan this repo and summarize findings.
* Set up Apex in this repo for the first time.
* Dry-run with apex-doctor.
* Export the latest findings.
* Triage critical and high findings only.
* Run an audit scan for this workspace.
* Run a Lite scan for this workspace.
* Run a PR scan for pull request 42.
* Mark KERN2-25 fixed with this PR and start a fix review scan.
## § 08 Interactive shell
Bare apex opens the interactive shell. Slash commands inside it:
```javascript theme={null}
/credits
/scan [standard|audit|lite]
/scan pr
/scans
/findings [scan-id]
/findings workspace [filter...]
/findings comment
/findings feedback valid [comment]
/findings feedback invalid [comment]
/findings fix-review
/export [scan-id]
/workspaces
/workspace use [
/workspace name
/cancel-scan [scan-id]
/status
/doctor
/repos
/company [id|handle]
/connect github
/connect gitlab
/open
/clear
/update
/claim
/logout
/help
/exit
```
## § 09 Scripted commands
```javascript theme={null}
apex credits
apex scan
apex scan --mode audit
apex scan --mode lite
apex scan --mode pr --pr [--pr ] [--pr-path ]
apex scans
apex findings [--scan ]
apex findings --workspace [--company ] [--workspace-ref ] [--finding-state all|open] [--filter <[!]facet:value>]
apex findings comment --content [--parent-comment ] [--scan ]
apex findings feedback [comment] [--comment ] [--scan ] [--suggested-severity extreme|critical|high|medium|low|informational] [--dismissal-reason false-positive|by-design|not-relevant] [--label acknowledged|fixed] [--fix-pr-url ]
apex findings fix-review [--scan ]
apex export findings [--scan ] [--format markdown|json|gitlab-sast] [--output ]
apex workspaces
apex workspace
apex workspace use
apex cancel-scan [scan-id]
apex status [--scan ]
apex doctor
apex login
apex redeem [--replace] [--json]
apex claim [--no-open] [--json]
apex logout
apex service-key create --name [--company ] [--scope ] [--expires-at ] [--json]
apex service-key list [--company ] [--json]
apex service-key revoke [--company ] [--json]
apex setup [all|codex|claude|copilot]
apex telemetry [status|enable|disable]
apex update
apex connect github
apex connect gitlab
```
### Common flags
| Flag | Description |
| - | - |
| `--company ` | Target a specific company |
| `--workspace-name ` | Pin or create a named workspace |
| `--scan ` | Select a specific scan for status, findings, or export |
| `--workspace` | Use the cross-scan workspace findings view |
| `--workspace-ref ` | Select a workspace for `apex findings --workspace` only |
| `--finding-state all\|open` | Return all findings or only findings needing review |
| `--filter <[!]facet:value>` | Filter workspace findings (repeatable) |
| `--format markdown\|json\|gitlab-sast` | Output format for exports |
| `--output ` | Output path for exports |
| `--limit ` | Cap list length |
| `--mode standard\|audit\|lite\|pr` | Scan mode |
| `--pr ` | Select one or more GitHub PRs for PR scans |
| `--pr-path ` | Limit a single PR scan to changed paths |
| `--source-mode auto\|remote\|local` | Source resolution mode |
| `--repo ` | Constrain to a repo path (repeatable) |
| `--force` | Skip confirmation |
| `--replace` | Replace an existing guest trial session |
| `--json` | Machine-readable output |
| `--no-open` | Don't open the browser |
| `--non-interactive` | Fail fast in scripts |
| `--content ` | Body for a finding comment |
| `--comment ` | Rationale for finding feedback |
| `--dismissal-reason false-positive\|by-design\|not-relevant` | Dismissal reason for invalid feedback |
| `--suggested-severity extreme\|critical\|high\|medium\|low\|informational` | Suggested severity for feedback |
| `--label acknowledged\|fixed` | Finding label |
| `--fix-pr-url ` | Attach one or more Fix PR URLs |
## § 10 Run a scan
```javascript theme={null}
apex scan
apex scan --mode audit
apex scan --mode lite
apex scan --mode pr --pr 42
apex scan --mode pr --pr 42:src/auth.ts,src/policy.ts
apex scan --source-mode local
apex scan --repo ./services/api --repo ./services/worker
apex status # progress on the latest scan
apex status --scan
apex scans # recent scans
apex findings # latest scan's findings
apex findings --scan
apex findings --workspace --workspace-ref BEDR9 --company apex-internal --finding-state open
apex export findings --format markdown --output findings.md
```
1. **Let Apex resolve the workspace** - Run apex scan from the repository root. Apex uses the current folder as the default workspace name unless you pass --workspace-name.
2. **Keep source planning explicit when needed** - By default, Apex scans the current directory. Use --repo for specific roots and --source-mode local when you want a snapshot of the exact working tree.
3. **Use the current scan-mode names** - Use standard for normal scans, audit for audit scans, lite for beta-enabled Lite scans, and pr with --pr for GitHub pull request scans. The old ultra mode is still accepted only as a legacy alias for audit.
`--workspace-ref` is supported only by `apex findings --workspace`. To list scans or export findings for a different workspace, bind it first with `apex workspace use `. Unsupported or misspelled flags fail instead of silently falling back to the current local binding.
> **Local snapshots and provider-backed scans**
> Standard scans can use local snapshot uploads for dirty git worktrees and plain directories. Audit and Lite scans require provider-backed GitHub or GitLab sources that Apex can materialize remotely; Lite scans also require beta access. PR scans require one provider-backed GitHub repository.
## § 11 Review findings
Apex CLI can now add finding comments, mark findings valid or invalid, attach Fix PR URLs, and start fix review scans.
```javascript theme={null}
apex findings comment KERN2-25 --content "Needs auth boundary check"
apex findings feedback KERN2-25 valid --comment "Reproduced on latest build"
apex findings feedback KERN2-25 invalid --dismissal-reason false-positive --comment "Unreachable path"
apex findings feedback KERN2-25 valid --label fixed --fix-pr-url https://github.com/acme/app/pull/123 --comment "Fixed in PR #123"
apex findings fix-review KERN2-25
```
> **Feedback authentication**
> Finding comments, feedback, and fix review scans use the same Apex CLI device-login credentials as read operations. MCP clients should complete `apex-auth-start` and `apex-auth-wait`, then call the finding write tools without asking users to paste browser cookies or auth tokens.
## § 12 MCP tools
Agent clients should prefer the Apex MCP server over shelling out. Use `apex setup` for automatic registration, or manually point clients at the stable `apex-mcp` binary.
| Tool | Description |
| - | - |
| apex-auth-status / apex-auth-start / apex-auth-wait | Check auth and complete device login without opening a browser |
| apex-trial-status | Inspect local guest-session and claim deadlines without exposing secrets |
| apex-doctor | Validate auth, detected sources, provider access, workspace binding, and source materialization |
| apex-workspaces / apex-workspace-use | List workspaces and bind the current directory by name, prefix, or ID |
| apex-scan | Start standard, audit, Lite, or PR scans with explicit cwd, repoPaths, sourceMode, pullRequests, and force inputs |
| apex-status / apex-scans / apex-cancel-scan | Monitor the latest or selected scan, list workspace scans, and cancel scans |
| apex-findings / apex-export-findings | Inspect or export one scan's findings |
| apex-workspace-findings | Inspect findings across a selected workspace, including an open-finding view |
| apex-finding-comment / apex-finding-feedback | Leave comments or valid/invalid feedback on a finding |
| apex-finding-fix-review | Start a fix review scan after fixed feedback has a Fix PR URL |
```javascript theme={null}
codex mcp add apex --env APEX_MCP_CLIENT=codex --env APEX_CLIENT_INTEGRATION=codex -- apex-mcp
claude mcp add apex --scope user -e APEX_MCP_CLIENT=claude -e APEX_CLIENT_INTEGRATION=claude -- apex-mcp
copilot mcp add apex --tools "*" -- apex-mcp
```
> **Plugin installs use the published package**
> Marketplace and plugin installs launch the pinned npm package with `npx -y -p @cantinasecurity/apex-cli@0.1.26 apex-mcp`, so users do not need a global `apex` install before enabling the plugin.
## § 13 Usage telemetry
Apex CLI 0.1.26 emits first-party, privacy-preserving usage telemetry for direct CLI, interactive shell, and MCP usage. Telemetry is enabled by default and can be inspected or disabled locally:
```javascript theme={null}
apex telemetry status
apex telemetry disable
apex telemetry enable
APEX_TELEMETRY_DISABLED=1 apex scan
```
Telemetry records lifecycle events, duration, success or failure category, CLI version, Node and platform basics, anonymous install and session IDs, and sanitized command metadata. It does not send raw cwd paths, repository URLs, finding IDs, scan IDs, PR URLs, comments, file paths, tokens, bearer credentials, or raw flag values.
## § 14 Troubleshooting
* If apex isn't found, confirm your global bin directory is on PATH.
* Apex CLI requires Node.js 20 or newer.
* If setup skips a client, confirm the claude, codex, or copilot CLI is installed. Explicit setup targets require the matching CLI.
* Make sure MCP clients launch apex-mcp directly, not pnpm mcp without --silent.
* A service key in `APEX_SERVICE_KEY` or `APEX_API_KEY` does not sign the CLI in. Use `apex login` for CLI device authentication, or use the [service API](/apex/api) for headless workflows.
* If you need to inspect or opt out of local usage telemetry, run apex telemetry status, apex telemetry disable, or set APEX\_TELEMETRY\_DISABLED=1.
* If browser launch fails during login, copy the verification URL manually.
* If sources aren't found, run apex doctor from the repository root or pass `--repo `.
* If remote materialization fails, retry with --source-mode local unless you specifically need provider-backed remote materialization.
* Audit and Lite scans require provider-backed GitHub or GitLab sources. Local snapshot fallback is for standard scans.
* Lite scans also require the Lite Scan beta feature and an available Lite scan entitlement.
* PR scans require a provider-backed GitHub repository and `--mode pr --pr `.
* If a scan is already active, use apex status, pass `--scan ` for a specific scan, or pass --force when you intentionally want to start another scan.
* Finding comments, feedback, and fix review scans use the same Apex login as read commands.
# Client onboarding guide
Source: https://docs.cantina.security/apex/onboarding
How repository access works, what Apex needs during setup, and what to send before the first scan.
* **Read:** 8 min
* **Updated:** Apr 28, 2026
* **Audience:** Workspace owners
## § 01 What onboarding looks like
Apex does not need personal access from every engineer. GitHub usually connects through a GitHub App. GitLab supports OAuth or a service-account token. Connecting a provider unlocks repository import - teams still choose repos, refs, and docs before scans run.
1. **Connect a code host** - Done once per company or workspace.
2. **Create a workspace** - Choose the exact repositories in scope.
3. **Pick a ref for each repository** - Branch, pull request, or commit.
4. **Add supporting context** - Docs, API specs, architecture notes, sharp edges.
5. **Run the scan** - Only after scope and context look right.
## § 02 Why Apex needs access
* Show repositories available to the connected company or workspace.
* Load branches, pull requests, commits, and repository trees during workspace setup.
* Pull selected source at the exact ref chosen for a scan.
* Keep private repositories in scope without asking users to package or upload code manually.
## § 03 GitHub onboarding
* Apex starts a GitHub App installation flow.
* An organization owner or repository admin may need to approve the installation.
* After installation, the team still chooses exact repositories per workspace.
* If approval is pending, workspace setup can continue and reconnect once approved.
*Workspace setup - connect options*
]![GitHub App authorization screen]()
*GitHub App authorization screen*
![Workspace setup after GitHub is connected]()
*Workspace setup after GitHub is connected*
## § 04 GitLab onboarding
* [GitLab.com](http://GitLab.com) connects through the shared OAuth app.
* Self-hosted GitLab can connect through OAuth or token setup.
* Token setup accepts a personal access token or service-account token with API scope.
* A service-account token is the recommended default over an individual engineer token.
## § 05 What to send ahead
Send these before kickoff and the first workspace usually takes minutes, not days.
* Provider: GitHub, [GitLab.com](http://GitLab.com), or self-hosted GitLab.
* Organization, account, or group owner - plus the person who can approve the connection.
* Repositories in scope and expected default branches, pull requests, or commits.
* Documentation: architecture, permissions, trust boundaries, key integrations, deployment shape.
* Priority-shaping context: sharp edges, sensitive flows, threat-model constraints, bug classes that matter.
## § 06 FAQ
**Does Apex need personal access to every codebase?**
No. Provider connections happen once at the company or workspace level.
**Does connecting a provider start a scan?**
No. You still pick repositories, refs, and context first.
**What if GitHub App approval is pending?**
Workspace setup can continue. Reconnect after approval lands.
**Can scope be limited?**
Yes - to selected repositories and specific refs (branch, PR, or commit).
![Workspace setup - connect options]()
*Workspace setup - connect options*
# Apex scan manual
Source: https://docs.cantina.security/apex/scan-manual
A practical guide to scoping scans, timing them well, and giving Apex enough context to return useful findings.
* **Read:** 12 min
* **Updated:** Apr 28, 2026
* **Audience:** Workspace owners
## § 01 How to think about Apex
Treat Apex like a fast auditing team. It works best on whole systems rather than tiny diffs, with context about architecture, permissions, invariants, and integrations.
> **Key idea**
> Apex works best as a standalone scan of a coherent system. Aim it at one deployable unit at a time, not at every PR.
## § 02 When to run a scan
* Run after a meaningful batch of merged changes - not on every PR.
* Re-scan before major launches, risky refactors, upgrade work, or new external integrations.
* Avoid back-to-back scans on near-identical code.
* The first scan on a system is usually the highest-yield pass.
## § 03 Audit vs normal scans
Two scan modes, picked by what you already know about the system and how much is riding on the result.
**Normal scan**
* After a meaningful batch of changes, when you already understand the system.
* Follow-up passes on stable scope.
* When the change matters enough to re-check, but isn't a launch-grade event.
* When repos, trust boundaries, threat model, and focus areas are already known.
**Audit scan**
* First scan of a system, protocol, or large codebase.
* Before launch, major release, or external security review handoff.
* After changes to auth, permissions, upgrade paths, signing, payments, settlement, or privileged flows.
* When risk lives in interactions and trust boundaries rather than one file.
> **Don't burn an Audit on**
> A small PR (unless it crosses a critical trust boundary), a repeat scan on near-identical code, a tiny isolated change, or work where fast iteration matters more than assurance.
## § 04 Threat model guidance
Apex does not infer priorities from code alone. A few sentences in plain language change the output significantly.
* Say directly if griefing or DoS is out of scope.
* Say directly if privileged role abuse, signer misuse, upgrade risk, or fee math matters.
* Specify if only critical and high-severity findings matter.
## § 05 Scope and inputs
* Use one scan for one coherent system whenever possible.
* Provide the best documentation you have: README, architecture notes, trust boundaries, permissions, external integrations.
* Split unrelated apps, services, contracts, and infrastructure into separate scans.
* Do not expand scope just because everything lives in one repository.
### Helpful inputs
* Repository selections that map to one deployable unit or review target.
* Current docs explaining architecture, permissions, upgrade paths, and integrations.
* Focused notes on assumptions, legacy paths, sharp edges, and sensitive flows.
## § 06 Splitting large repos
A large monorepo is rarely one review target. The split you want is the split a security reviewer would draw if they had to read the whole thing.
1. **Split by deployable system** - When services ship independently, scan them independently.
2. **Split by trust boundary** - Isolate areas that handle secrets, auth, payments, signing, or other privileged actions.
3. **Split by runtime** - Contracts, backend services, frontend apps, and infrastructure are materially different systems.
4. **Keep code together only when** - It should be reasoned about as a single security surface.
| Repository shape | Typical scan count | Why |
| - | - | - |
| Focused repository | 1 scan | One deployable unit, one review target. |
| Small monorepo, a few distinct systems | 2–3 scans | One scan per coherent system; don't merge unrelated surfaces. |
| Large monorepo or mega-repo | 4+ scans | One scan per major subsystem; separate by deployable or trust boundary first. |
| Two directories, unclear shared review target | Separate | If you can't justify them as one review target, they aren't one. |
## § 07 Planning template
Use this skeleton to decide how to split a repository or mega-repository into Apex scans.
**Apex Scan Planning Template**
```javascript theme={null}
# Apex Scan Planning Template
# Decide how to split a repository into Apex scans.
Repository:
name:
url:
type: single-app | monorepo | mega-repo
top_level: [apps/, services/, contracts/, infra/]
runtimes: [ts, go, solidity]
sensitive: [auth, payments, signing, upgrade]
existing_docs:
known_excludes: [vendor/, generated/, build/]
Goals:
- Decide scan count for this repo
- Explain why each scan is its own review target
- Call out what NOT to group together
- Identify missing docs / context to add first
# Rules of thumb
# - One scan per coherent security surface
# - Split contracts / backend / frontend / infra / admin tooling
# - Split by deployable or trust boundary first
# - Skip generated, vendor, build, dependency directories
# - Keep PR-review scans separate from broad baseline scans
Recommended split: # example output
- scan_1: contracts/ + shared protocol libs
- scan_2: services/* (backend)
- scan_3: infra/ + deployment logic
Do not combine: contracts with backend — different runtimes & trust models
Add before scanning: upgrade-path notes, signer permissions, fee math invariants
```
# Scheduled scans
Source: https://docs.cantina.security/apex/scheduled-scans
Run recurring workspace scans or fix reviews on a fixed cadence so monitoring keeps up with the code without manual effort.
* **Read:** 5 min
* **Updated:** Jul 10, 2026
* **Audience:** Workspace owners
## § 01 What scheduled scans are
A workspace schedule can start a recurring scan, recurring fix reviews of eligible public findings, or both. Instead of starting each run by hand, you set one cadence and choose which actions Apex should trigger using the workspace scope and context you already configured.
Scheduled runs appear in the workspace alongside manual scans and fix reviews, so there is no separate place to look for their results.
> **Key idea**
> Scheduling is best for a coherent, long-lived workspace you want to keep watching over time. Scope and context still come from the workspace, so keep them accurate.
## § 02 Why schedule scans
* Keep monitoring a workspace continuously instead of remembering to start each scan by hand.
* Catch regressions and newly introduced issues automatically as the code keeps changing.
* Recheck eligible public findings across the workspace scan history without starting each fix review by hand.
* Keep findings fresh on long-lived systems where the security surface shifts over time.
## § 03 Enable a schedule
Scheduling is configured from the workspace scan list. The steps below walk through turning it on.
1. **Open the workspace** - Go to the workspace you want to monitor and stay on the scan list view.
2. **Open the schedule dialog** - Select Schedule in the scan list header to open the Auto-trigger scans dialog.
3. **Choose what to schedule** - Enable Auto-trigger scan, Auto-trigger fix review, or both. For fix reviews, choose whether each repository should use its workspace/default branch or the same named branch override.
4. **Choose a cadence** - Set the interval with Every and a number, then pick Days or Weeks. Weekly schedules also let you choose the day of the week the schedule runs.
5. **Save the schedule** - Select Save schedule. Apex records the schedule and shows the next run date.
> **Fix review scope and branches**
> Scheduled fix reviews preflight public findings from every non-archived, non-fix-review scan in the workspace, then start only the eligible reviews. They are not limited to the latest scan.
>
> Workspace branch lets each repository use its default or configured workspace branch. A named branch override is applied to every repository in the workspace, so use it only when that branch exists across the repository set.
## § 04 Choosing a cadence
The interval is an Every value paired with a unit. Pick the granularity that matches how often the workspace changes.
* Days: run every N days, up to 365.
* Weeks: run every N weeks, up to 52, on a chosen day of the week.
* The enabled scan and fix-review actions share the same cadence.
* The dialog summarizes the schedule (for example, "Every 2 weeks on Mon") and shows the next run date.
> **First run**
> After you save, Apex evaluates each enabled action at the next scheduled time. A scheduled fix review preflights existing public findings in the workspace scan history using the selected branch behavior; it does not create a new workspace scan first.
## § 05 Manage or turn off
Open the Schedule dialog again at any time to change the cadence, day of the week, fix-review branch, or which actions are enabled. The dialog also shows the next run. Its Last successful value tracks successful Auto-trigger scan starts; fix-review-only runs do not update that value.
Auto-trigger scan and Auto-trigger fix review can be turned off independently. Turn both off and save to stop the schedule while leaving manual scans and fix reviews untouched.
# Client API Reference
Source: https://docs.cantina.security/api
REST endpoints available to client organizations
> REST endpoints available to client organizations
The Cantina REST API gives client organizations programmatic access to the same data and actions exposed in the dashboard. Use it to manage your company, browse and update repositories, retrieve audit reports, and connect events to downstream tools.
For information on generating an API key and authenticating requests, see [API Access](/security-teams/getting-started/api-access).
***
## Companies
Manage company accounts, members, manager roles, GitHub App installations, and SSO configuration.
* **Companies** - Company accounts, users, GitHub, and SSO endpoints
## Reports
Retrieve audit reports for finished engagements.
* **Reports** - List and fetch audit reports
## Repositories
Browse repositories you have access to, read files and findings, manage teams, and interact with comments.
* **Repositories** - Repository, file, finding, and team endpoints
## Zapier
Subscribe to Cantina events from Zapier or any other workflow tool that can call HTTP webhooks.
* **Zapier** - Event subscription endpoints
# MCP access
Source: https://docs.cantina.security/api/mcp-access
Connect external MCP clients (Claude Code, Cursor, CI scripts) to your Clarion workspace.
> Connect external MCP clients (Claude Code, Cursor, CI scripts) to your Clarion workspace.
> **Note:** Clarion exposes a workspace-scoped Model Context Protocol (MCP) server so external clients can - without the Clarion web UI - read alerts, incidents, tasks, monitors, and signals; operate the scheduler; author and edit agents and skills; browse and instantiate templates; and manage the workspace's default agent instructions. There are two ways to connect: OAuth (for IDE/agent clients) and long-lived API tokens (for headless ones).
## Where it lives
In Clarion, go to **Settings > MCP access**. The page has two tabs:
* **API tokens** - mint, list, and revoke long-lived bearer tokens. One row per token; the plaintext is shown exactly once at creation time.
* **OAuth setup** - copy-paste snippets for Claude Code and Claude Desktop, plus a generic note for other MCP clients. No secrets to manage.
The MCP endpoint itself is at `https:///api/mcp` (the OAuth setup tab fills in the right URL for your environment).
***
## Choosing a flow
| | OAuth | Long-lived token |
| - | - | - |
| Best for | Claude Code, Cursor, any IDE/agent client that can open a browser | CI jobs, cron workers, headless scripts |
| Setup | One browser sign-in, no secret to copy | Mint a token, copy it into the client config |
| Revocation | From the client's settings | Revoke the row in **Settings > MCP access** |
| Appears in token list | No | Yes |
If a client supports OAuth, use it. The browser flow handles re-auth automatically when access expires; long-lived tokens never rotate and stay valid until revoked.
***
## Connecting via OAuth
### Claude Code (CLI)
1. Open **Settings > MCP access > OAuth setup** and copy the `claude mcp add` command shown there. It already contains the right URL for your workspace.
2. Run it:
```bash theme={null}
claude mcp add --transport http clarion https:///api/mcp
```
3. Start a session. On the first tool call Claude Code opens the Clarion OAuth grant page - pick the workspace and approve. The token is captured by Claude Code's local callback.
### Claude Desktop
1. Open **Settings > MCP access > OAuth setup** and copy the JSON snippet.
2. Paste it into `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on Windows/Linux:
```json theme={null}
{
"mcpServers": {
"clarion": {
"type": "http",
"url": "https:///api/mcp"
}
}
}
```
3. Restart Claude Desktop. The first tool call triggers the same browser grant flow as the CLI.
### Other MCP clients
Point any MCP client that speaks the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) at `https:///api/mcp`. The first unauthenticated request returns a `WWW-Authenticate` challenge that points at `/.well-known/oauth-protected-resource`; any spec-compliant client follows the metadata to discover the authorization server and complete the OAuth flow without extra config.
***
## Connecting via a long-lived API token
Use this when the client can't drive an interactive browser sign-in.
1. In **Settings > MCP access > API tokens**, click **New token**.
2. Give it a label that lets you recognize it later (e.g. `CI nightly drift check`, `Cron worker`).
3. Click **Create token**. The dialog swaps to a one-time reveal - copy the plaintext **now**. Once you close the dialog the secret is gone for good.
4. Paste the token into your MCP client config as a `Bearer` credential:
```json theme={null}
{
"mcpServers": {
"clarion": {
"type": "http",
"url": "https:///api/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}
```
> **Warning:** A long-lived token grants full workspace access over MCP - not just reads and light triage, but **creating and editing configuration**: agents, skills, schedules, and the workspace's default agent instructions. Treat it like any other secret - keep it out of source control and rotate (revoke + re-mint) on a cadence that matches your other credentials.
### Revoking a token
In the **API tokens** tab, click the revoke icon on the row, confirm, and the token stops authenticating immediately. Any client still using it gets a 401 on its next request. Revocation is one-way; revoked rows stay in the list with a "Revoked" badge so you can audit who created them and when.
***
## Available tools
After connecting, the client sees the following workspace-scoped tools under the `clarion` server (so each one appears as `mcp__clarion__`). Every tool is scoped to the token's workspace: reads filter by workspace, cross-workspace lookups return an error rather than another tenant's data, and mutations are attributed to the operator who minted the token.
### Read & triage
**Alerts**
* `list_alerts` - paginated list, filterable by status / severity / search
* `get_alert` - full alert detail by display number
* `complete_remediation_item` - toggle a checklist item on an alert's remediation list
* `retrigger_alert` - re-run triage agents for an alert (e.g. after deploying a fix)
**Incidents**
* `list_incidents` - paginated list with the same filters as alerts, plus search
* `get_incident` - incident detail including linked alerts
**Tasks**
* `list_tasks` - paginated list, filter by status / priority / `alertNumber` (useful for "has this alert been escalated yet?")
* `get_task` - single task by id
**Monitors & integrations**
* `list_monitors`, `get_monitor` - the workspace's ingestion sources, with sanitized per-type config (webhook secrets stripped)
* `list_integrations`, `get_integration_health` - integration sync health (consecutive failures, pause state, auth errors); credentials are never returned
**Signals**
* `list_signals`, `get_signal` - the raw ingested events that feed alerts, before any alert fires
**Schedules**
* `list_schedules`, `get_schedule` - discover what's running in the workspace
* `list_schedule_runs`, `get_schedule_run` - poll-friendly run snapshots
* `run_schedule_once` - fire a schedule out-of-band without changing its cron cadence
* `cancel_schedule_run` - cancel a pending or running execution
* `create_schedule`, `update_schedule`, `set_schedule_enabled`, `delete_schedule` - full CRUD on recurring tasks
### Configure the workspace
> **Note:** Skill and instruction content is exchanged as **markdown** (with inline `` pills) and converted to/from Clarion's rich-text format automatically - you never handle the raw editor JSON.
**Agents**
* `list_agents`, `get_agent` - the workspace's triage agents and their linked skills/monitors
* `create_agent`, `update_agent` - manage an agent's name, active state, linked skills, and linked **existing** monitors. Monitor *creation* stays in the Clarion UI - it involves webhook secrets and registration that aren't exposed over MCP.
**Skills**
* `list_skills`, `get_skill` - reusable workspace skills, instructions returned as markdown
* `create_skill`, `update_skill` - author or edit a skill from markdown; tools are extracted from the inline `` pills, and edits snapshot a new version
**Templates**
* `list_skill_templates`, `get_skill_template` - browse the curated skill-template catalog
* `create_skill_from_template` - instantiate a skill template into a *managed* workspace skill (auto-updates when the template changes; idempotent - returns the existing copy if already instantiated)
* `list_agent_templates`, `get_agent_template` - browse the published agent-template catalog
* `create_agent_from_template` - scaffold an agent plus its managed skills from a template, created inactive so you can review before it runs
**Workspace**
* `list_workspace_tools` - the action tools currently **available** to agents in this workspace. Only tools whose backing integration (and any required credentials or pauser config) is actually connected are returned - unconfigured ones are omitted - so this reflects what a skill can reference *today*. Includes the workspace's custom MCP servers, custom API/CLI toolsets, and Microsoft Sentinel tools.
* `get_workspace_instructions`, `set_workspace_instructions` - read or replace the default agent instructions (markdown) applied to every agent in the workspace
> **Note:** Templates are a shared, platform-curated catalog. These tools only **browse** it and **instantiate** copies into your workspace - creating, editing, or deleting templates is admin-only and is not exposed over MCP.
> **Info:** The agent-side MCP server used by Clarion's own triage agents has a separate (broader) tool surface - agents see integration tools like `mcp__slack__*`, `mcp__okta__*`, `mcp__cloudtrail__*` etc. that aren't exposed externally. External MCP clients only see the workspace tools listed above. `list_workspace_tools` surfaces the *names* of the available integration tools so a skill you author can reference them by their `` type, but those tools still execute agent-side during triage.
# Clarion security operations documentation
Source: https://docs.cantina.security/clarion
Set up Clarion to connect security tools, correlate alerts, preserve business context, and run governed response with security agents.
[Clarion](https://clarion.cantina.xyz) is Cantina's agentic security operations platform. It ingests signals from every security tool, correlates threats in real time, and executes response playbooks autonomously, so your SOC team focuses on strategy while Clarion handles the noise.
Reduce alert fatigue through intelligent deduplication and prioritization across all your security tools.
Provide 24/7 instant threat response with AI-powered agents that act outside business hours.
Capture team expertise in executable skills that persist when staff leave.
## Why Clarion?
Security teams are overwhelmed by fragmented tooling, alert fatigue, and manual response processes. Clarion unifies your security operations into a single orchestration layer:
* **Signal ingestion** — Consolidate signals from SIEM, EDR, WAF, SOAR, IAM, NDR, and more into one platform.
* **Real-time correlation** — Automatically correlate threats across sources to surface what matters and eliminate false positives.
* **Agentic response** — Execute response playbooks autonomously with AI agents that triage, escalate, and remediate.
* **Proactive monitoring** — Monitor DNS records, HTTP endpoints, smart contracts, and infrastructure with configurable checks.
* **Signal rules** — Define custom rules to automatically route, escalate, and act on security signals.
## Start with Clarion
Connect the first integration, invite members, and activate an agent.
Learn how alerts, incidents, tasks, agents, skills, and tools fit together.
Give agents the business and technology context they need during investigations.
Follow the setup guide for the security, cloud, identity, and collaboration tools in your stack.
For a product-level explanation of how Clarion fits into Cantina, see the [Cantina platform overview](https://www.cantina.security/platform).
# Getting started
Source: https://docs.cantina.security/clarion/getting-started
Set up your Clarion workspace, create your first agent, and start triaging issues.
This guide walks you through the essential steps to go from a fresh workspace to a live agent triaging real issues.
## 1. Create your workspace
Sign in at [clarion.cantina.xyz](https://clarion.cantina.xyz). You may already have a workspace set up for you by the Cantina team. If not, you can create one yourself — all new workspaces require approval from the Cantina team before they go live.
## 2. Invite your team
Open **Settings → Members** to invite teammates. Members receive notifications, review agent decisions, and approve sensitive actions when an agent asks.
See [Members](/clarion/learn/settings#members) for role details.
## 3. Create your first agent
The fastest way to get value out of Clarion is to spin up an agent. Each agent watches a set of monitors, triages incoming issues, and runs your response playbooks — connecting integrations happens as part of this flow.
1. Open **Agents** and click **New agent**.
2. Pick a template that matches your stack (Identity & Access, DNS Infrastructure, Smart Contract Security, Cloud Posture) or start from a blank agent.
3. **Connect the integrations the agent needs.** Each template lists its required integrations alongside its monitors — click through to connect each one (Okta, AWS, Cloudflare, etc.). For tools that aren't natively supported, use **Generic webhook**.
4. Review the bundled monitors, skills, and alert filters.
5. Activate the agent.
See [Creating agents](/clarion/learn/agents#creating-agents) for the full walkthrough.
## 4. Set up notifications
Notifications are how the agent reaches you — for approval requests, clarifications, and routine updates. Slack is the most common channel.
1. Open **Integrations** and connect **Slack**.
2. Pick the channel(s) the agent should post to.
3. In the agent's notification preferences, route approvals, clarifications, and updates to the Slack channel.
See [Notifications](/clarion/learn/notifications) for other options.
## 5. Review tools and approvals
Skills give agents access to **tools** — actions like revoking a session, posting to Slack, or changing a DNS record. Some tools run automatically; others pause for human approval before running.
For each tool, you can require approval, allow it to run autonomously, or disable it entirely. Sensitive actions (revoking access, modifying production infrastructure) should always require approval.
See [Tools](/clarion/learn/tools) for the full list.
## 6. Watch your first triage
Once activated, the agent picks up matching issues and produces a triage report with disposition, summary, and recommendations.
* View live activity under **Issues**.
* Approve or reject sensitive actions from the in-app feed or the Slack channel you wired up in step 4.
Agents only do what their skills tell them to do. To change behavior, edit the skill — not the agent. See [Skills](/clarion/learn/skills).
## What's next
How issues, agents, skills, and tools fit together.
Every integration Clarion supports.
Decide where Clarion sends approvals and updates.
Invite teammates and assign roles.
# 1Password
Source: https://docs.cantina.security/clarion/integrations/1password
Connect 1Password to Clarion to monitor audit events, sign-in attempts, and item usage events from your 1Password Business account.
This guide walks you through connecting your 1Password Business account to Clarion via the 1Password Events Reporting API. Once connected, Clarion polls 1Password every minute for audit events, sign-in attempts, and item usage events, and uses them to detect suspicious activity and open issues.
**Estimated time:** 5 minutes. You will need **1Password Business** with permission to set up Events Reporting integrations.
## Prerequisites
* A **1Password Business** account with access to **Integrations → Directory**
* A **Clarion workspace** with the 1Password integration page open
* A secure place to store the bearer token generated in 1Password
***
## Step 1 — Create a bearer token in 1Password
1. Sign in to your [1Password account](https://start.1password.com/).
2. Go to **Integrations** → **Directory**.
3. Under **Events Reporting**, click **Other** and set up a new integration.
4. Select the event types to report:
* Audit events
* Sign-in attempts
* Item usage events
5. Copy the generated **bearer token**.
Copy the bearer token immediately — it will only be shown once. Store it securely.
***
## Step 2 — Enter the bearer token in Clarion
1. In Clarion, open **Integrations** → **1Password**.
2. Paste the **Bearer Token** from 1Password.
3. Click **Connect**.
Clarion validates the token and begins polling the Events Reporting API for new events every minute.
***
## What happens next
Once connected, Clarion will:
* Poll 1Password every minute for audit events, sign-in attempts, and item usage events
* Open issues from suspicious activity based on your configured alert filters
* Use 1Password event data to enrich investigations and triage
You can manage which events open issues from the **Alert Filters** section on the 1Password integration page.
***
## Update or rotate the bearer token
To replace the bearer token (for example, after rotating it in 1Password):
1. Generate a new bearer token in 1Password under **Integrations → Directory → Events Reporting**.
2. In Clarion, open **Integrations** → **1Password**.
3. Paste the new token into **Update Bearer Token** and click **Update Token**.
***
## Troubleshooting
### The connection fails or events stop arriving
* Confirm the bearer token was generated for the correct 1Password account and has not been revoked
* Verify the integration in 1Password still includes audit events, sign-in attempts, and item usage events
* Use **Sync now** on the 1Password integration page in Clarion to trigger an immediate poll
# Apex
Source: https://docs.cantina.security/clarion/integrations/apex
Connect Apex to Clarion to ingest security findings from your repositories and code scanning workflows.
This guide walks you through connecting Apex to Clarion. Once connected, Apex sends security findings into Clarion, where the Apex agent can triage them and drive incident response.
**Estimated time:** 2-5 minutes. You will need access to your **Apex dashboard** with permission to manage company settings, and a **Clarion workspace**.
## Prerequisites
* Access to your **Apex dashboard** with permission to manage **Company Settings**
* A **Clarion workspace** with the Apex integration available
***
## Step 1 — Enable the Apex integration in Clarion
1. In Clarion, navigate to **Integrations**.
2. Find the **Apex** card and click **Connect** to enable the integration.
***
## Step 2 — Open Company Settings in Apex
1. Open your **Apex dashboard**.
2. Go to **Company Settings**.
![]()
***
## Step 3 — Connect Clarion from Apex
1. In Company Settings, click **Connect Clarion**.
![]()
2. Review the workspace shown in the connection screen and confirm it's the correct Clarion workspace before connecting.
![]()
***
## Step 4 — Add the Apex agent in Clarion
Once the connection is established:
1. In Clarion, go to **Agents**.
2. Click **Create Agent**.
3. Add the **Apex agent** so findings from Apex are picked up and triaged automatically.
![]()
Without the Apex agent enabled, findings will arrive in Clarion but won't be triaged. Don't skip this step.
# AWS
Source: https://docs.cantina.security/clarion/integrations/aws
Connect your AWS account to Clarion for CloudTrail events, CloudWatch alarms, GuardDuty findings, and IAM agent tools.
Clarion connects to AWS to ingest CloudTrail events, CloudWatch alarms, GuardDuty findings, and Amazon Inspector vulnerability findings, and to run agent tools (CloudTrail lookup, Route 53, CloudWatch queries) against your account.
There are a few different ways to get your AWS telemetry into Clarion. Pick the path that matches how your AWS logging is already set up — you can combine more than one.
## Choose a setup path
The complete setup. Forward CloudTrail management events, GuardDuty findings, and Amazon Inspector vulnerability findings to Clarion in real time through EventBridge and SNS, wire up CloudWatch alarms, and create the IAM role for agent tools.
Already logging CloudTrail to S3 (or using a tool like Red Canary)? Have Clarion read each new log file from the bucket via an S3 event notification. Ideal for organization-wide, centralized logging.
## How AWS data reaches Clarion
Every path delivers events to Clarion through an **SNS topic** that publishes to a Clarion **webhook URL** over HTTPS. They differ in how events get *into* that topic:
| Path | How events are produced | Best for |
| - | - | - |
| [EventBridge & SNS](/clarion/integrations/aws/eventbridge) | An EventBridge rule matches CloudTrail / GuardDuty / Amazon Inspector events and targets an SNS topic; CloudWatch alarms and other sources publish to SNS directly | Real-time CloudTrail management events, GuardDuty findings, CloudWatch alarms, and Amazon Inspector vulnerability findings |
| [CloudTrail via S3](/clarion/integrations/aws/cloudtrail-s3) | S3 event notifications fire when CloudTrail writes a new log file to the bucket | Existing or consolidated CloudTrail-to-S3 logging, org-wide trails |
Clarion only accepts SNS messages from topic ARNs you have saved on the matching monitor. Whichever path you choose, copy the exact SNS topic ARN into Clarion before confirming the subscription.
CloudTrail via S3 sends Clarion a pointer to a log file, not the CloudTrail event body. Clarion must be able to assume an AWS role that can read that S3 object. See [CloudTrail via existing S3 bucket](/clarion/integrations/aws/cloudtrail-s3) for the required IAM setup.
## Agent tools
Running Clarion's AWS agent tools (CloudTrail lookup, Route 53, CloudWatch queries, Athena) requires an IAM role that Clarion can assume. That role is covered in the [AWS via EventBridge](/clarion/integrations/aws/eventbridge#step-4-iam-role-for-agent-tools) guide and in the [CloudTrail via S3](/clarion/integrations/aws/cloudtrail-s3) guide — set it up once per connected account.
# CloudTrail via existing S3 bucket
Source: https://docs.cantina.security/clarion/integrations/aws/cloudtrail-s3
Ingest CloudTrail events into Clarion from an existing S3 bucket using S3 event notifications and SNS — ideal for centralized, organization-wide logging.
CloudTrail writes its events as log files to an S3 bucket. If you have already set up CloudTrail, you most likely turned on delivery to an S3 bucket — or you use an existing solution such as Red Canary that consolidates CloudTrail logs there. Either way, every CloudTrail event ends up stored in S3.
To bring those events into Clarion, you configure the bucket to publish an **SNS notification whenever a new log file is added**, and Clarion subscribes to that topic. Each new file is fetched and turned into signals.
```
CloudTrail
↓
S3 bucket (new log file added)
↓
S3 event notification
↓
SNS topic
↓
Clarion webhook
```
![]()
This is one of two ways to connect AWS. For real-time CloudTrail management events, GuardDuty findings, or CloudWatch alarms delivered over SNS, see [AWS via EventBridge and SNS](/clarion/integrations/aws/eventbridge).
This setup sends Clarion an S3 object pointer, not the CloudTrail event body. Clarion must assume the customer-side IAM role configured in your AWS integration and read the referenced log file from S3. If the role is missing or cannot read the bucket, Clarion drops the pointer and those CloudTrail events are not ingested.
If the SNS subscription is confirmed but CloudTrail events are not appearing in Clarion, check the IAM role first. Clarion may be receiving the S3 notification but failing to fetch the referenced log object because the role does not have S3 read access.
***
## Before you start
**Pick the right account.**
* **Organization-level integration** — if your CloudTrail logging is centralized from all accounts into one bucket, use the **log-archive account** (or management account) that owns the CloudTrail bucket. One bucket, one SNS topic, and one Clarion subscription cover the whole organization.
* **Single account** — select the account that owns the trail and bucket.
You already have an existing S3 bucket for this flow. You can confirm exactly which bucket your trail writes to from the trail's **log location** in CloudTrail (covered in [Step 5](#step-5-notify-clarion-when-new-log-files-arrive)).
For organization-level trails, the role Clarion assumes must be able to read the bucket owned by the log-archive account. A role in only the member account that produced the CloudTrail event cannot read the centralized log object.
***
## Step 1 — Connect AWS and configure the IAM role
1. In Clarion, open the **AWS** integration page and click **Connect** at the bottom of the page.
2. Set up the IAM role first. For reading CloudTrail logs from S3, select these permission sets:
* **Athena S3 log queries**
* **S3 SSE-KMS log decryption**, only if your bucket uses SSE-KMS
The **Athena S3 log queries** permission set is the one that gives Clarion S3 read access for the log objects. The **CloudTrail events** permission set only grants CloudTrail API calls and is not enough for S3-backed ingestion.
3. The generated policy JSON appears on the right. You have two options to apply it — the **AWS Console** or the **AWS CLI** — and the instructions for both are shown there.
4. Once you have run the AWS CLI commands (or finished the setup in the AWS Console), set the **default region** and the **IAM Role ARN** you created.
5. Click **Configure IAM**.
The generated policy uses `Resource: "*"` on every statement for convenience. Before production, deselect any permission sets you don't use and replace `"*"` with specific ARNs for your resources, such as S3 log buckets and KMS keys. Expand each permission set in the picker for per-set scope-down guidance.
If your CloudTrail bucket uses **SSE-KMS** encryption, the **S3 SSE-KMS log decryption** permission is what lets Clarion read the encrypted log files. If the bucket's KMS key does not delegate to IAM, you also need to allow the Clarion role on the key policy — see [AWS via EventBridge → SSE-KMS](/clarion/integrations/aws/eventbridge#step-1b-cloudtrail-via-consolidated-s3-logging).
6. You can ignore the popup that offers to create an agent for now — we'll [create the agent in Step 6](#step-6-create-an-agent). First we need to set up SNS so Clarion is notified when new files are added to the S3 bucket.
![]()
***
## Step 2 — Create an SNS topic
1. Open the Amazon **SNS** console and click **Create topic**.
![]()
2. Select the **Standard** type, give the topic a name (e.g. `clarion-cloudtrail-notifications`), and create it.
![]()
3. On the created topic, click **Create subscription**.
![]()
4. Copy the **Topic ARN** shown in the details — you'll paste it into Clarion next.
![]()
S3 event notifications deliver only to an SNS topic in the **same region** as the bucket. Create the topic in the region of your CloudTrail bucket.
***
## Step 3 — Create the CloudTrail monitor in Clarion
1. Navigate back to Clarion and, on the AWS integration page, click **Add monitor**.
![]()
2. Select **AWS CloudTrail**.
![]()
3. Paste the SNS topic ARN into Clarion. Click **Add recommended filters** to apply Clarion's detection rules, then hit **Continue**.
![]()
4. Copy the **webhook URL**. You can ignore the rest of the instructions in the modal — simply close it by clicking **Done**.
***
## Step 4 — Subscribe Clarion to the SNS topic
Back on the SNS topic's **Create subscription** screen, point the subscription at the Clarion webhook:
1. Set the protocol to **HTTPS**.
2. Paste the Clarion webhook URL as the **Endpoint**.
3. Create the subscription. Clarion auto-confirms it.
![]()
***
## Step 5 — Notify Clarion when new log files arrive
Now configure the S3 bucket to publish to the SNS topic whenever CloudTrail writes a new log file.
1. Open **CloudTrail** and select your existing trail.
![]()
2. Under the trail details, find the **Trail log location** — this is the S3 bucket your CloudTrail logs are stored in.
![]()
3. Click the **Trail log location** link to open the bucket.
![]()
4. Using the breadcrumb navigation at the top, navigate up to the bucket itself (out of the log-location folder).
![]()
5. Open the **Properties** tab.
![]()
6. Scroll down to **Event notifications** and click **Create event notification**.
![]()
7. Add an event name and select **All object create events**.
![]()
8. Scroll down to **Destination**, select **SNS topic** as the destination, and use the dropdown to select the SNS topic you created in Step 2. Then hit **Save changes**.
![]()
Clarion is now subscribed and S3 will notify it on every new CloudTrail log file. Next, create an agent so those events get triaged.
***
## Step 6 — Create an agent
1. Back in Clarion, select **Agents** on the left and click **Create agent**.
2. Select the **Cloud Security (AWS)** agent template and click **Continue**.
![]()
3. Next to **Monitors**, click **Add** and select **AWS CloudTrail**.
![]()
4. You'll see the monitor you created earlier — select it, and it's assigned to your agent.
![]()
The agent's status automatically changes to **Watching** — you're all set.
![]()
Done! Clarion now ingests CloudTrail events from your existing S3 bucket and your Cloud Security (AWS) agent triages them.
# EventBridge and SNS
Source: https://docs.cantina.security/clarion/integrations/aws/eventbridge
Connect your AWS account to Clarion for CloudTrail events, CloudWatch alarms, GuardDuty findings, Amazon Inspector vulnerabilities, and IAM agent tools.
This guide walks you through connecting your AWS account to Clarion. By the end, Clarion will receive CloudTrail events, CloudWatch alarms, GuardDuty findings, and Amazon Inspector vulnerability findings — and have IAM permissions to run agent tools (CloudTrail lookup, Route 53, CloudWatch queries).
***
## Prerequisites
* An AWS account with admin or IAM-capable permissions.
* Access to the Clarion dashboard.
***
## Step 0 — Generate a Webhook URL in Clarion
Before configuring AWS subscriptions, open your Clarion workspace and generate a webhook URL.
![]()
You will use this URL as the HTTPS subscription endpoint for your SNS topics in the steps below.
Keep this URL handy — you'll need it for CloudTrail, CloudWatch, and GuardDuty setup. Clarion also requires the exact SNS topic ARN for each topic that publishes to the webhook.
SNS messages are accepted only from topic ARNs saved in Clarion. Existing AWS monitors with no saved SNS topic ARN must be updated before Clarion can confirm subscriptions or receive notifications.
***
## Step 1 — CloudTrail via EventBridge
Send CloudTrail management events (API calls and console sign-ins) to Clarion through an SNS topic and an EventBridge rule.
This path sends the CloudTrail event body through EventBridge and SNS. Clarion does not need S3 bucket access for this delivery mode.
### 1.1 Create an SNS topic
1. Open the Amazon SNS console and go to **Topics**.
2. Create a new **Standard** topic (e.g. `clarion-cloudtrail`).
3. Copy the topic ARN, paste it into Clarion's SNS topic ARN field for the CloudTrail monitor, and save the monitor.
Currently encryption of the topic is not supported, but Amazon SNS provides in-transit encryption by default.
![]()
### 1.2 Subscribe Clarion to the topic
1. On the topic you just registered in Clarion, click **Create subscription**.
2. Set the protocol to **HTTPS** and paste the webhook URL from Clarion.
3. SNS will send a confirmation request — Clarion auto-confirms it.
![]()
### 1.3 Create an EventBridge rule
1. Open the Amazon EventBridge console and create a new rule.
![]()
![]()
![]()
2. Use the following event pattern to forward all CloudTrail events to Clarion:
![]()
```json theme={null}
{
"detail-type": [
"AWS API Call via CloudTrail",
"AWS Console Sign In via CloudTrail",
"AWS Console Signin via CloudTrail",
"AWS Service Event via CloudTrail"
]
}
```
EventBridge detail-type matching is **case-sensitive**. The pattern above
includes both known casing variants of the console sign-in detail-type
(`Sign In` and `Signin`) to ensure events are captured regardless of
the variant your account emits. Do **not** add a `source` filter — the
`source` field varies by originating AWS service (e.g. `aws.iam`,
`aws.ec2`, `aws.signin`) and filtering on it would silently drop events.
These detail-types cover the following CloudTrail event categories:
| Detail type | What it captures | Examples |
| - | - | - |
| `AWS API Call via CloudTrail` | All management and data API calls | `DeleteUser`, `PutBucketPolicy`, `RunInstances` |
| `AWS Console Sign In via CloudTrail` | Console login and logout events | `ConsoleLogin` (success, failure, MFA) |
| `AWS Service Event via CloudTrail` | Non-API events triggered by AWS services | Log file delivery, automated key rotation, service-linked role actions |
Clarion has signal rules that depend on console sign-in events (login failures,
MFA checks, root account logins, multi-IP detection), so including the
console sign-in detail-types is important for full coverage.
A fourth detail-type, `AWS Insight via CloudTrail`, exists for
[CloudTrail Insights](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-insights-events-with-cloudtrail.html)
anomaly detection events. Add it to the pattern if you have Insights enabled
on your trail.
3. Set the target of the rule to the SNS topic you created (`clarion-cloudtrail`).
***
## Step 1B — CloudTrail via Consolidated S3 Logging
An [AWS Organizations trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/creating-trail-organization.html) writes CloudTrail events from every member account and region into a single S3 bucket — typically a dedicated log-archive account. Clarion subscribes to that bucket's S3 event notifications, fetches each new log file, and creates one signal per CloudTrail record. One SNS topic and one Clarion subscription cover the whole organization.
For this consolidated S3 path, Clarion must be able to read each CloudTrail log object from S3. See [CloudTrail via existing S3 bucket](/clarion/integrations/aws/cloudtrail-s3) for the required IAM setup.
### 1B.1 Place the Clarion IAM role in the log-archive account
Configure the Clarion IAM role from Step 4 **in the account that owns the consolidated CloudTrail bucket** — usually the AWS Organizations log-archive account. The role needs S3 read access to the CloudTrail log objects.
### 1B.2 Create an SNS topic for S3 notifications
1. In the log-archive account, open the SNS console and create a **Standard** topic in the same region as the consolidated log bucket (e.g. `clarion-cloudtrail-s3`).
2. Copy the topic ARN, add it to Clarion's **SNS topic ARN** list on the CloudTrail monitor, and save.
S3 event notifications deliver only to SNS topics in the same region as the bucket.
### 1B.3 Subscribe Clarion to the topic
1. On the topic, click **Create subscription**.
2. Set the protocol to **HTTPS** and paste the webhook URL from Step 0.
3. Clarion auto-confirms the subscription.
### 1B.4 Configure S3 event notifications on the bucket
1. In the log-archive account, open the consolidated CloudTrail bucket in the S3 console.
2. Go to **Properties → Event notifications → Create event notification**.
3. Restrict the trigger to the CloudTrail prefix (e.g. `AWSLogs/`) and suffix `.json.gz`.
4. Event types: **All object create events** (`s3:ObjectCreated:*`).
5. Destination: **SNS topic**, then select the topic from 1B.2.
### 1B.5 (SSE-KMS only) Allow the Clarion role to use the bucket's KMS key
If the consolidated log bucket uses SSE-KMS, the CMK's key policy must allow the Clarion IAM role from Step 4 to call `kms:Decrypt`. Keys created through the CloudTrail setup wizard delegate to IAM by default, in which case Clarion's role policy is sufficient and no key-policy change is needed. Otherwise, add the following statement to the CMK's key policy, replacing ``:
```json theme={null}
{
"Sid": "AllowClarionDecrypt",
"Effect": "Allow",
"Principal": { "AWS": "" },
"Action": "kms:Decrypt",
"Resource": "*"
}
```
***
## Step 2 — CloudWatch Alarms
Send CloudWatch alarm state changes to Clarion by publishing to an SNS topic subscribed to your webhook URL.
1. Create a new SNS **Standard** topic for CloudWatch alarms (e.g. `clarion-cloudwatch`), or reuse a topic you have already registered in Clarion.
2. Copy the topic ARN, paste it into Clarion's SNS topic ARN field for the CloudWatch monitor, and save the monitor.
3. Add an **HTTPS** subscription using the webhook URL from Clarion. Wait for Clarion to auto-confirm.
4. In the CloudWatch console, open the alarm(s) you want Clarion to monitor.
5. Edit the alarm's notification actions and set it to publish to the SNS topic you created.
You can point multiple alarms at the same SNS topic — no need to create one per alarm.
***
## Step 3 — GuardDuty Findings
Route GuardDuty findings to Clarion through EventBridge and SNS.
### 3.1 Create an event bus
1. Open the Amazon EventBridge console.
2. You can use the **default** event bus, or create a new custom event bus if you want to isolate GuardDuty events (e.g. `clarion-guardduty-bus`).
### 3.2 Create an EventBridge rule for GuardDuty
1. Within the event bus, create a new rule.
2. Set the event source to GuardDuty findings.
3. Make sure you're using the following event pattern:
```json theme={null}
{
"source": ["aws.guardduty"],
"detail-type": ["GuardDuty Finding"]
}
```
4. Set the target to the SNS topic you created for Clarion. If you create a dedicated `clarion-guardduty` topic, copy that topic ARN into Clarion's SNS topic ARN field for the GuardDuty monitor and save before creating the HTTPS subscription.
5. Give the rule a descriptive name (e.g. `clarion-guardduty-findings`), review, and save.
![]()
![]()
![]()
![]()
Make sure GuardDuty is enabled in your AWS account. If it's not yet active, enable it in the GuardDuty console first.
***
## Step 3B — Amazon Inspector Findings
Route Amazon Inspector v2 vulnerability findings to Clarion through EventBridge and SNS. Clarion creates a vulnerability issue for each finding and triages it against your connected AWS assets to estimate blast radius.
### 3B.1 Create an SNS topic
1. In the Amazon SNS console, create a topic (e.g. `clarion-inspector`).
2. Copy the topic ARN, paste it into Clarion's SNS topic ARN field for the Amazon Inspector monitor, and save the monitor.
### 3B.2 Subscribe Clarion to the topic
1. On the topic, create a subscription with protocol **HTTPS** and paste the webhook URL from Step 0.
2. Clarion confirms the subscription automatically once the topic ARN is saved on the monitor.
### 3B.3 Create an EventBridge rule for Inspector
1. In the Amazon EventBridge console, create a new rule on your event bus.
2. Set the event source to Amazon Inspector findings using the following event pattern:
```json theme={null}
{
"source": ["aws.inspector2"],
"detail-type": ["Inspector2 Finding"]
}
```
3. Set the target to the `clarion-inspector` SNS topic.
4. Give the rule a descriptive name (e.g. `clarion-inspector-findings`), review, and save.
Make sure Amazon Inspector is enabled in your AWS account. If it's not yet active, enable it in the Inspector console first. Note that findings created before the rule is active are not replayed by EventBridge — only new and changed findings are delivered.
***
## Step 4 — IAM Role for Agent Tools
Clarion needs an IAM role to run agent tools (CloudTrail lookup, Route 53, CloudWatch queries). You can set this up via the AWS Console or the AWS CLI.
The generated policy uses `Resource: "*"` on every statement for convenience. Before production, deselect any permission sets you don't use and replace `"*"` with specific ARNs for your resources, such as SNS topics, S3 log buckets, Route 53 zones, and CloudWatch log groups. Expand each permission set in Clarion's permission picker for per-set scope-down guidance.
***
### Option A — AWS Console
#### 1. Check for an existing role
![]()
Go to **IAM console** > **Roles** and search for `ClarionIntegrationRole`. If it exists, skip to step 3 to update the trust policy.
#### 2. Create the policy and role
1. Go to **IAM console** > **Policies** and create a new policy with the JSON below.
2. Then go to **IAM console** > **Roles** and create a new role.
3. Select **Custom trust policy** and paste the trust policy JSON below.
4. Attach the policy you just created.
#### 3. Verify or update the trust policy
1. Open the role's **Trust relationships** tab.
2. Verify (or update) the trust policy to match:
Trust Policy
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::762233769489:role/ClarionBridgeRole-20260319110823845000000001"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": ""
}
}
}
]
}
```
#### 4. Copy the Role ARN
![]()
Verify the permission policy is attached, then copy the **Role ARN** and paste it into Clarion.
***
### Option B — AWS CLI
IAM Permission Policy
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ClarionRoute53",
"Effect": "Allow",
"Action": [
"route53:ListHostedZones",
"route53:GetHostedZone",
"route53:ListResourceRecordSets",
"route53:ChangeResourceRecordSets"
],
"Resource": "*"
},
{
"Sid": "ClarionCloudWatch",
"Effect": "Allow",
"Action": [
"cloudwatch:ListMetrics",
"cloudwatch:DescribeAlarms",
"cloudwatch:GetMetricData"
],
"Resource": "*"
},
{
"Sid": "ClarionCloudTrail",
"Effect": "Allow",
"Action": [
"cloudtrail:LookupEvents",
"cloudtrail:DescribeTrails",
"cloudtrail:GetTrailStatus"
],
"Resource": "*"
},
{
"Sid": "ClarionSNS",
"Effect": "Allow",
"Action": [
"sns:CreateTopic",
"sns:DeleteTopic",
"sns:Subscribe",
"sns:Unsubscribe",
"sns:SetTopicAttributes",
"sns:ListTopics",
"sns:GetTopicAttributes",
"sns:ListSubscriptionsByTopic"
],
"Resource": "*"
},
{
"Sid": "ClarionEventBridge",
"Effect": "Allow",
"Action": [
"events:PutRule",
"events:DeleteRule",
"events:PutTargets",
"events:RemoveTargets",
"events:ListRules",
"events:DescribeRule"
],
"Resource": "*"
},
{
"Sid": "ClarionAwsDescribe",
"Effect": "Allow",
"Action": [
"ec2:Describe*",
"ec2:List*",
"ec2:Get*",
"elasticloadbalancing:Describe*",
"elasticloadbalancing:List*",
"elasticloadbalancing:Get*",
"eks:Describe*",
"eks:List*",
"ecr:Describe*",
"ecr:List*"
],
"Resource": "*"
}
]
}
```
![]()
![]()
![]()
![]()
Run these commands in your terminal. Replace the Principal ARN and External ID with the values shown in your Clarion integration wizard.
#### 1. Check if the role already exists
```bash theme={null}
aws iam get-role \
--role-name ClarionIntegrationRole \
--query 'Role.Arn' --output text 2>/dev/null
```
If this prints an ARN, the role already exists — skip to step 4 to update its trust policy. Otherwise, continue with step 2.
#### 2. Create the IAM policy
```bash theme={null}
aws iam create-policy \
--policy-name ClarionIntegrationPolicy \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ClarionRoute53",
"Effect": "Allow",
"Action": [
"route53:ListHostedZones",
"route53:GetHostedZone",
"route53:ListResourceRecordSets",
"route53:ChangeResourceRecordSets"
],
"Resource": "*"
},
{
"Sid": "ClarionCloudWatch",
"Effect": "Allow",
"Action": [
"cloudwatch:ListMetrics",
"cloudwatch:DescribeAlarms",
"cloudwatch:GetMetricData"
],
"Resource": "*"
},
{
"Sid": "ClarionCloudTrail",
"Effect": "Allow",
"Action": [
"cloudtrail:LookupEvents",
"cloudtrail:DescribeTrails",
"cloudtrail:GetTrailStatus"
],
"Resource": "*"
},
{
"Sid": "ClarionSNS",
"Effect": "Allow",
"Action": [
"sns:CreateTopic",
"sns:DeleteTopic",
"sns:Subscribe",
"sns:Unsubscribe",
"sns:SetTopicAttributes",
"sns:ListTopics",
"sns:GetTopicAttributes",
"sns:ListSubscriptionsByTopic"
],
"Resource": "*"
},
{
"Sid": "ClarionEventBridge",
"Effect": "Allow",
"Action": [
"events:PutRule",
"events:DeleteRule",
"events:PutTargets",
"events:RemoveTargets",
"events:ListRules",
"events:DescribeRule"
],
"Resource": "*"
},
{
"Sid": "ClarionAwsDescribe",
"Effect": "Allow",
"Action": [
"ec2:Describe*",
"ec2:List*",
"ec2:Get*",
"elasticloadbalancing:Describe*",
"elasticloadbalancing:List*",
"elasticloadbalancing:Get*",
"eks:Describe*",
"eks:List*",
"ecr:Describe*",
"ecr:List*"
],
"Resource": "*"
}
]
}'
```
#### 3. Create the IAM role with trust policy
```bash theme={null}
aws iam create-role \
--role-name ClarionIntegrationRole \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": ""
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": ""
}
}
}
]
}'
```
#### 4. Update the trust policy (existing role only)
Run this instead of step 3 if the role already existed:
```bash theme={null}
aws iam update-assume-role-policy \
--role-name ClarionIntegrationRole \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": ""
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": ""
}
}
}
]
}'
```
#### 5. Attach the policy to the role
```bash theme={null}
aws iam attach-role-policy \
--role-name ClarionIntegrationRole \
--policy-arn "arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ClarionIntegrationPolicy"
```
After running these commands, copy the Role ARN from step 1 (existing role) or step 3 (new role) and paste it into Clarion.
***
## Step 4B — Connecting Multiple AWS Accounts
Agent MCP tools (`aws_describe`, `aws_logs_insights`, `aws_athena`, `aws_cloudtrail`, `inspect_alb_auth`) can target any account you connect to the workspace. Repeat Step 4 once per account: create a `ClarionIntegrationRole` in each account, give it the same trust policy and IAM policy, and add the role ARN to Clarion's AWS integration as a new connected account.
When invoking an AWS MCP, the agent passes an `accountId` parameter to select which account the call should hit. Omitting the parameter falls back to the primary account.
### 4B.1 Pick a primary
Exactly one connected account is marked **primary**. The primary's role is used whenever an MCP call omits `accountId`. Pick the account you query most often — typically the AWS Organizations log-archive account if you also use the consolidated-S3 ingest from [Step 1B](#step-1b-cloudtrail-via-consolidated-s3-logging).
### 4B.2 External ID
By default every connected account uses the same workspace external ID, so you paste the same value into every role's trust policy. If you want stricter isolation between accounts (a separate external ID per account so a leak in one does not compromise the others), generate a per-account external ID in the Clarion UI's account-list panel and use that in the corresponding role's trust policy.
### 4B.3 IAM policy
Every connected account's role uses the same IAM policy JSON from Step 4. Permission selection (the `iamPermissionGroupIds` list) is workspace-wide for now — every connected account is expected to honor the same set of granted permissions.
Agents discover connected accounts through the MCP tool schema: passing an unknown `accountId` returns a structured error listing the known accounts so the agent can self-correct and retry. The agent does not have to enumerate accounts ahead of time — it can start with the account ID from a CloudTrail event's `recipientAccountId` and Clarion will route accordingly.
***
## Step 5 — Activate Monitors in Clarion
1. Go back to Clarion and add the **CloudTrail** monitor.
2. Enable all the rules, then confirm.
3. Review the listed event types and click to enable all relevant ones.
4. If you set up GuardDuty or CloudWatch, add the **GuardDuty** and **CloudWatch** monitors as well. These monitors receive GuardDuty findings and CloudWatch alarms directly, so you don't have to configure additional rules.
You're done! Clarion is now receiving CloudTrail events, CloudWatch alarms, and GuardDuty findings from your AWS account.
# Better Stack
Source: https://docs.cantina.security/clarion/integrations/betterstack
Uptime monitoring, incident alerts, and telemetry queries — connect Better Stack so agents can investigate and act on outages.
Better Stack brings uptime incidents into Clarion and gives agents a wide tool surface over both **Uptime** (incidents, monitors, heartbeats, on-call, status pages) and **Telemetry** (log and metric queries, dashboards).
**Estimated time:** 3 minutes. You will need a Better Stack **API token**.
## Prerequisites
* A **Better Stack** account with Uptime and/or Telemetry
* An API token with access to the resources you want Clarion to read
## Connect
1. In Better Stack, create an **API token**.
2. In Clarion, open **Integrations** and find **Better Stack**.
3. Paste the **API Token** and click **Connect**.
## What Clarion ingests
Uptime incidents and alerts feed the [Infrastructure & Ops](/clarion/learn/agents#our-agents) agent's outage runbook.
## What agents can do
Better Stack has one of the broadest tool surfaces in Clarion. The highlights:
**Incidents** — list and read incidents, read the incident timeline and comments, add a comment, acknowledge, resolve, create, and escalate an incident; read escalation options, policies, and severities.
**Monitoring** — list and read monitors, heartbeats, and their availability and response-time history.
**On-call** — read the current on-call, on-call events, and rotations.
**Status pages** — list and read status pages and their resources, and publish a status-page report and updates.
**Telemetry** — run log and metric queries, build explore and metric queries, read sources and their fields, inspect errors and update their state, list releases and applications, and create or edit dashboards and charts.
Several of these write to Better Stack — resolving an incident, publishing a status-page update, creating a dashboard. They are gated by your workspace's tool policy and ask for approval unless explicitly allowed.
## Disconnect
Click **Disconnect** on the integration page. The stored token is deleted and the tools disappear from agent skills.
# Cantina Bug Bounty
Source: https://docs.cantina.security/clarion/integrations/cantina-bbp
Route Cantina bug bounty submissions into Clarion for automatic triage, spam filtering, and remediation PRs.
If you run a bug bounty program on [Cantina](https://cantina.xyz), this integration delivers submissions into Clarion as issues so an agent can triage them before a human spends time on them.
**Estimated time:** 2 minutes. You will need a Cantina bug bounty program.
## Connect
1. In Clarion, open **Integrations** and find **Cantina BBP**.
2. Click **Connect**. Submissions from your programs start flowing in as issues.
## What the agent does
The [Cantina Bug Bounty](/clarion/learn/agents#our-agents) agent triages each submission:
* **Closes spam** and low-quality reports without escalating.
* **Notifies** your team on submissions that look real, with an assessment of impact.
* **Opens a remediation pull request** where the fix is tractable, using the [GitHub](/clarion/integrations/github) integration.
Connect GitHub as well. Without it the agent can assess a finding but not act on it.
## Disconnect
Click **Disconnect** on the integration page. New submissions stop reaching Clarion; existing issues are unaffected.
# Claude Code
Source: https://docs.cantina.security/clarion/integrations/claude-code
Ingest OpenTelemetry from your developers' Claude Code installs to govern MCP servers, spot external accounts, and catch credential-shaped tool use.
Claude Code emits OpenTelemetry. Point it at Clarion and you get a security view of how your engineering org actually uses AI coding agents: which MCP servers they connect, whose accounts are outside your company, and which sessions read a credential and then reached the network.
**Estimated time:** 10 minutes. You will need admin access to your organization's Claude managed settings.
## Prerequisites
* Claude Code deployed across your developer fleet
* Ability to push **managed settings** to those installs
* Your company's domains set in [Workspace settings](/clarion/learn/settings#workspace) — the external-account rule reads every account as external until they are
## Step 1 — Create the monitor in Clarion
1. In Clarion, open **Integrations** and find **Claude Code**.
2. Click **Connect** and create a monitor. Clarion generates:
* An **ingest endpoint URL** carrying the monitor id.
* A **bearer secret**, shown exactly once.
Copy the secret when it is shown. Clarion does not display it again. The secret travels in an OTLP header, never in the URL.
## Step 2 — Push managed settings
Clarion generates the JSON block to paste into your Claude managed settings:
```json theme={null}
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_TRACES_EXPORTER": "otlp",
"OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
"OTEL_EXPORTER_OTLP_ENDPOINT": "https:///api/webhooks/claude-code/",
"OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer ",
"OTEL_LOG_TOOL_DETAILS": "1",
"OTEL_METRICS_INCLUDE_ENTRYPOINT": "true"
}
}
```
Copy it from the integration page rather than from here — it comes pre-filled with your endpoint and secret.
Findings are only as complete as your telemetry. If OTEL logging is partial across the fleet, so is the picture Clarion builds. `OTEL_LOG_TOOL_DETAILS` is what makes tool-level governance possible; without it, MCP server use is invisible.
## What Clarion builds from it
**MCP server governance.** Every MCP server your developers connect is inventoried with who uses it and how often. Servers sit in an undecided bucket until somebody rules on them — and the [Claude Code Governance](/clarion/learn/agents#our-agents) agent sweeps that bucket weekly and puts the whole batch in front of a human as **one** decision rather than a trickle of prompts. Use of a server somebody already denied raises an issue immediately.
**Identity.** Telemetry reported from an account outside your company's domains is surfaced and triaged. This is how a personal account doing company work, or a contractor still connected after offboarding, shows up.
**Credential-shaped tool use.** Sessions that read a credential-shaped path and then reached the network are flagged for triage — the pattern behind an agent exfiltrating a key, whether deliberately or by accident.
## Related agent
The [Claude Code Governance](/clarion/learn/agents#our-agents) agent ships four skills: MCP server governance triage, MCP inventory review sweep, external account triage, and credential-harvesting triage.
## Disconnect
Click **Disconnect** on the integration page, then remove the OTEL environment variables from your managed settings. Telemetry sent after disconnection is rejected.
# Cloudflare
Source: https://docs.cantina.security/clarion/integrations/cloudflare
Connect Cloudflare to Clarion for Cloudflare Notifications webhooks, Logpush detection monitors, and optional API-powered DNS and analytics agent tools.
This guide walks you through connecting Cloudflare to Clarion and configuring Cloudflare Notifications monitors. By the end, Clarion will receive Cloudflare notification policies through one or more Cloudflare Notifications monitors, and optionally have an API token available for DNS tools and WAF/DDoS firewall-event investigation during incident response.
For Cloudflare Logpush detection windows, use the dedicated [Cloudflare Logpush](/clarion/integrations/cloudflare/logpush) guide.
**Estimated time:** 5-10 minutes. You will need a **Clarion workspace** and access to the **Cloudflare dashboard** for the account or zones you want to monitor.
## Prerequisites
* A **Clarion workspace**
* Access to **Cloudflare**
* Permissions to create **webhook destinations** and **notification policies** in Cloudflare
***
## Step 1 — Connect Cloudflare in Clarion
1. In Clarion, go to **Settings > Integrations**
2. Find **Cloudflare**
3. Click **Connect**
This creates the Cloudflare integration in Clarion. Use the integration to save an optional API token for Clarion agent tools, and use Cloudflare Notifications monitors to generate webhook URLs and secrets for notification delivery.
***
## Step 2 — Optional: Save a Cloudflare API token
If you want Clarion agents to use Cloudflare DNS, zone-management, and WAF/DDoS Analytics tools during investigations, save an API token on the Cloudflare integration.
1. In the Cloudflare integration page in Clarion, open the **API Token** section
2. In Cloudflare, go to **Manage Account > Account API Tokens**
3. Create an **account-owned API token**
4. Grant **Zone:Read**, **DNS:Read**, **DNS:Edit**, **Account Settings:Read**, and **Zone Analytics:Read**
5. Paste the token into Clarion
6. Wait for Clarion to verify it, then click **Save**
The token should include these permissions:
* **Zone:Read**
* **DNS:Read**
* **DNS:Edit**
* **Account Settings:Read**
* **Zone Analytics:Read**
This token is optional for Cloudflare Notifications delivery. You only need it if you want Clarion agents to use Cloudflare API tools.
Cloudflare Notifications can trigger WAF/DDoS triage without Cloudflare Logpush. With **Zone Analytics:Read**, Clarion agents can query Cloudflare GraphQL Analytics for sampled firewall events, compare a current wave against a prior window, and report source IPs/ASNs, paths, user agents, countries, rules, action mix, and any allowed traffic. Use [Cloudflare Logpush](/clarion/integrations/cloudflare/logpush) only when you want Clarion to ingest and detect from Logpush events directly.
Use an account-owned token instead of a user token for shared integrations. Account-owned tokens are more durable because they are not tied to one person's profile.
***
## Step 3 — Add one or more Cloudflare Notifications monitors
1. In Clarion, add a **Cloudflare Notifications** monitor from the Integrations page or the agent monitor setup flow
2. Give the monitor a clear name for the Cloudflare notification policy or policy group it will receive
3. Save the monitor
When each monitor is created, Clarion generates:
* A **Webhook URL**
* A **Webhook secret**
Copy both values from the monitor configuration screen. You can create multiple Cloudflare Notifications monitors when you want different Cloudflare notification policies to use different webhook destinations, secrets, or Clarion agents.
If you replace the webhook secret in Clarion later, update the same secret in Cloudflare before sending new notifications.
***
## Step 4 — Create Cloudflare webhook destinations
In Cloudflare:
1. Go to **Notifications > Destinations > Webhooks**
2. Click **Create**
3. Give the destination a name you will recognize later
4. Paste the **Webhook URL** from Clarion into the destination URL field
5. Paste the **Webhook secret** from Clarion into the secret field
6. Click **Save and Test**
Create one Cloudflare webhook destination for each Clarion monitor you want to route separately. Each destination is what the selected notification policies will send to.
***
## Step 5 — Create notification policies in Cloudflare
After the webhook destination exists:
1. Go to **Notifications > Add**
2. Select the notification type you want to send to Clarion
3. Fill in the required fields for that notification
4. When Cloudflare shows a delivery or destination section, choose the webhook destination for the Clarion monitor that should receive that policy
5. Save the notification policy
Common notification policies to forward to Clarion include:
* **DDoS**
* **Origin errors**
* **Health checks**
* **WAF events**
* **SSL or certificate events**
You can attach multiple Cloudflare notification policies to the same Clarion webhook destination, or split policies across multiple Clarion monitors by using different webhook destinations.
If a Cloudflare notification form only shows **Notification email** fields and does not show a webhook destination selector, Cloudflare is not offering webhook delivery for that notification in your current account.
If your Cloudflare account only has **Free** zones, this is expected. Cloudflare Notifications webhooks are not available on a free-only account, so you will only be able to use email delivery.
Cloudflare's docs say webhook availability depends on account eligibility and the highest zone plan in the account. If the account has at least one eligible paid zone, Cloudflare may expose webhook destinations for supported notification types.
***
## What happens next
Once configured, Clarion will:
* Receive Cloudflare Notifications webhooks at the monitor webhook URL
* Open issues from supported Cloudflare notification events
* Triage those issues with Clarion agents
* Query Cloudflare Analytics for WAF/DDoS firewall-event evidence when an API token with **Zone Analytics:Read** is saved
If notifications stop arriving after rotating the secret, verify that the secret stored in the Clarion monitor matches the one configured on the Cloudflare webhook destination.
# Logpush
Source: https://docs.cantina.security/clarion/integrations/cloudflare/logpush
Send Cloudflare firewall_events Logpush batches to Clarion for L7 DDoS-like detection windows.
This guide walks you through configuring a Cloudflare Logpush monitor in Clarion. Clarion receives Cloudflare zone `firewall_events` rows, builds compact detection windows, and opens issues on L7 DDoS-like security-event flood patterns.
Cloudflare Logpush is available on Enterprise plans. Clarion does not backfill historical Logpush data; detections start from the time Cloudflare begins sending rows to the monitor.
## Prerequisites
* A **Clarion workspace**
* A connected **Cloudflare** integration in Clarion
* Access to a Cloudflare Enterprise zone
* Permission to create zone Logpush jobs
* The hostname or hostnames you want Clarion to evaluate
## Step 1 — Add a Cloudflare Logpush monitor
1. In Clarion, go to **Settings > Integrations > Cloudflare**
2. Open the **Monitors** tab
3. Click **Add monitor**
4. Choose **Cloudflare Logpush**
5. Enter a zone name and, optionally, the Cloudflare zone ID
6. Choose the host scope:
* **Exact host** for one hostname
* **Selected hosts** for multiple hostnames
7. Enter plain hostnames only, such as `app.example.com` or `api.example.com`
8. Choose a sensitivity level
9. Save the monitor
Clarion generates a **Webhook URL** and **Webhook secret**. Copy both values before configuring Cloudflare.
If you rotate the secret in Clarion, update the Cloudflare Logpush destination header before sending more data.
Clarion matches Logpush rows against `ClientRequestHost`. Do not include schemes, paths, ports, or wildcards in the host list.
## Step 2 — Create the Logpush job in Cloudflare
In the Cloudflare dashboard, open the same zone you configured in Clarion, then go to **Analytics & Logs > Logpush** and create a Logpush job.
Use these settings:
| Cloudflare setting | Value |
| - | - |
| Dataset | `firewall_events` |
| Destination type | HTTP destination |
| Destination URL | The Clarion **Webhook URL** |
| Destination parameter name | `header_cf-webhook-auth` |
| Destination parameter value | The Clarion **Webhook secret** |
| Output type | `ndjson` |
| Timestamp format | `rfc3339` |
Cloudflare sends destination parameters that start with `header_` as HTTP headers. The `header_cf-webhook-auth` parameter makes Cloudflare send the Clarion secret in a `cf-webhook-auth` header.
If you configure Logpush through the Cloudflare API or Terraform, put the header parameter in `destination_conf` and URL-encode the secret:
```text theme={null}
?header_cf-webhook-auth=
```
Do not put the webhook secret in the monitor name, host scope, or any other descriptive field. Store it only as the Cloudflare HTTP destination header value.
## Step 3 — Include the required Logpush fields
Configure the Logpush job to include these `firewall_events` fields:
```text theme={null}
Datetime
RayID
Action
ClientRequestHost
ClientRequestPath
ClientCountry
ClientASN
OriginResponseStatus
EdgeResponseStatus
ClientIP
RuleID
Source
Description
MatchIndex
```
Clarion uses these fields to deduplicate rows, scope detections to the configured hostnames, aggregate hot paths and source traits, and classify Cloudflare mitigation actions.
Clarion does not store raw Logpush rows. It summarizes rows for detection and hashes client IP values before retaining compact aggregates.
## Step 4 — Save and validate the Logpush job
Cloudflare validates HTTP destinations with a gzipped JSON test upload (`{"content":"tests"}`). Clarion accepts that validation upload and returns success when the monitor secret matches.
After validation succeeds, enable the Logpush job. New detections can be created once Cloudflare begins delivering current `firewall_events` rows to the monitor.
## Step 5 — Understand direct delivery limits
Cloudflare can send batches smaller than 5 MB, but its `max_upload_bytes` setting cannot be configured below 5 MB. If a zone produces an unusually large Logpush batch, delivery may be rejected and retried by Cloudflare. Keep the host scope focused on the hostnames you want Clarion to monitor.
## What Clarion detects
Clarion monitors for DDoS-like L7 security-event flood patterns visible in Cloudflare `firewall_events`.
This detector does not claim to detect allowed-only traffic floods or total origin traffic volume. It relies on Cloudflare security events such as blocked, challenged, managed challenge, and rate-limited traffic.
The initial detection pack is **Zone Security** with the **L7 DDoS** detector. Sensitivity controls the event-volume thresholds Clarion uses before opening high or critical detections.
## Operational notes
* Multiple Cloudflare Notifications monitors and multiple Cloudflare Logpush monitors can coexist.
* Use separate Logpush monitors when different host groups should route to different Clarion agents.
* Cloudflare limits Logpush to four jobs per dataset per zone.
* Rows should be delivered promptly; significantly delayed rows may not be evaluated.
* If Cloudflare retries the same batch, Clarion deduplicates rows and replayed request bodies.
## Troubleshooting
If Cloudflare validation fails:
* Confirm the destination URL exactly matches the Clarion **Webhook URL**
* Confirm the destination parameter is named `header_cf-webhook-auth`
* Confirm the destination parameter value matches the Clarion **Webhook secret**
* If you replaced the secret in Clarion, update the Cloudflare destination before testing again
If Logpush delivers successfully but Clarion does not open detections:
* Confirm `ClientRequestHost` exactly matches the monitor host scope
* Confirm the Logpush job is sending the `firewall_events` dataset
* Confirm the required fields are included in the job output
* Check whether traffic is below the selected sensitivity threshold
* Remember that allowed-only origin floods are outside this detector's scope
References: [Cloudflare Logpush](https://developers.cloudflare.com/logs/logpush/), [Cloudflare HTTP destinations](https://developers.cloudflare.com/logs/logpush/logpush-job/enable-destinations/http/), [Cloudflare firewall\_events fields](https://developers.cloudflare.com/logs/logpush/logpush-job/datasets/zone/firewall_events/).
# Confluence
Source: https://docs.cantina.security/clarion/integrations/confluence
Connect Confluence Cloud to Clarion with an Atlassian service account so agents can read and search documentation for context during triage.
This guide shows how to connect Confluence Cloud to Clarion using an Atlassian service account and OAuth 2.0 client credentials.
**Estimated time:** 10-15 minutes. You need access to:
* A **Clarion workspace**
* **Atlassian Administration** for your Confluence site
* A service account that can view and search content in the Confluence spaces you want Clarion to use
## Prerequisites
Before connecting Confluence in Clarion, make sure you have:
* Your Confluence site URL, for example `https://example.atlassian.net`
* A Confluence service account with access to the relevant spaces
* An OAuth 2.0 credential created for that service account
* These credential scopes (granular — Clarion uses the Confluence REST API v2):
* `read:page:confluence`
* `read:space:confluence`
* `search:confluence`
Clarion uses the service account’s client credentials to request short-lived Confluence access tokens automatically. You do not need to reconnect the integration just because an access token expires.
***
## Step 1 - Create a Confluence service account
1. In **Atlassian Administration**, open **Directory** and create a **service account**.
2. Grant the service account access to **Confluence**.
3. Make sure the service account has access to the spaces Clarion will read.
The service account should be able to:
* Search content
* View page content
* List spaces
***
## Step 2 - Create OAuth 2.0 credentials for the service account
1. Open the service account in **Atlassian Administration**.
2. Go to **Credentials**.
3. Create an **OAuth 2.0** credential.
4. Grant only these scopes:
* `read:page:confluence`
* `read:space:confluence`
* `search:confluence`
5. Copy the **Client ID** and **Client secret**.
Keep the client secret somewhere safe. You will paste it into Clarion during setup.
***
## Step 3 - Connect Confluence in Clarion
1. In Clarion, go to **Integrations**.
2. Open **Confluence**.
3. Enter:
* **Site URL**
* **Client ID**
* **Client Secret**
* **Default Space Key** (optional)
4. Click **Connect Confluence**.
***
## Step 4 - Verify and maintain the connection
After connecting:
1. Review the saved Confluence site and client ID.
2. Set or update **Default Space Key** if you want Clarion to scope searches to a space automatically.
3. Click **Save** after any changes.
4. Click **Verify Connection** to confirm Clarion can access Confluence successfully.
5. Use **Disconnect** if you want to remove Confluence access from the workspace.
Agents can still pass a space in CQL per tool call. If omitted, Clarion uses the configured default space key when scoping a search.
***
## How Confluence tools use this integration
When Confluence tools are enabled, Clarion can:
* Search pages with CQL
* Read a page by id
* List spaces
Clarion manages Confluence access tokens automatically from the stored client credentials.
***
## Troubleshooting
### "Failed to resolve Confluence cloud ID"
Check that **Site URL** is exactly your Confluence Cloud URL, for example:
* `https://example.atlassian.net`
Do not include a path such as `/wiki`, `/spaces`, or `/display`.
### "Confluence credential is missing required scopes"
Recreate or update the OAuth 2.0 credential so it includes:
* `read:confluence-content.all`
* `read:confluence-space.summary`
* `search:confluence`
### Verify Connection fails even though the credential is valid
Make sure the service account itself has Confluence product access and space-level permissions in the spaces Clarion needs to read.
# CrowdStrike Falcon
Source: https://docs.cantina.security/clarion/integrations/crowdstrike
Connect CrowdStrike Falcon to Clarion to poll detections and cases from your Falcon tenant and surface them as signals and issues.
This guide walks you through connecting a CrowdStrike Falcon tenant to Clarion via the Falcon OAuth2 API. Once connected, Clarion polls Falcon every minute for new detections and cases, uses them to drive issues and agent triage, and discovers your Falcon host roster into the Brain as device assets.
**Estimated time:** 5 minutes. You will need a **CrowdStrike Falcon** account with permission to create API clients.
## Prerequisites
* A **CrowdStrike Falcon** tenant and access to **Support and resources → API clients and keys**
* A **Clarion workspace** where you can add a monitor
* A secure place to store the **Client ID** and **Client Secret** generated in Falcon
***
## Step 1 — Pick your Falcon cloud region
In Clarion, open **Integrations** → **CrowdStrike**, then **Add Monitor**. On the configuration screen, choose the cloud region that matches your Falcon Console URL:
| Region | Console URL |
| - | - |
| US-1 | `https://falcon.crowdstrike.com` |
| US-2 | `https://falcon.us-2.crowdstrike.com` |
| EU-1 | `https://falcon.eu-1.crowdstrike.com` |
| US-GOV-1 | `https://falcon.laggar.gcw.crowdstrike.com` |
| US-GOV-2 | `https://falcon.us-gov-2.crowdstrike.com` |
The "Sign in to your Falcon Console" link in the form updates to point at the region you select.
***
## Step 2 — Create an API client in Falcon
1. Sign in to the **Falcon Console** for your region.
2. Go to **Support and resources** → **API clients and keys**.
![]()
3. Click **Create API client** and grant the scopes listed in the Clarion setup instructions.
### Scopes
Grant **Read** access to the following scopes so Clarion can poll detections, cases, and supporting context:
Alerts, App Logs, Apps, Cases, Correlation Rules, Custom IOA rules, Detections, Device Content, Device control policies, Hosts, Firewall management, IOC Management, IOCs (Indicators of Compromise), Prevention policies, Quarantined Files, Real time response (admin), Real time response app, Real time response audit, Real time response, Response policies, Event streams.
**Hosts (Read)** is what powers device discovery into the Brain — keep it granted even if you trim the list above.
If you want Clarion to interact with Cases, Real-Time Response, and similar surfaces and make remediation or containment actions, also grant **Write** access to the relevant scopes. Most write actions require human approval in Clarion before the agent executes them.
**Next-Gen SIEM (optional)** — to let Clarion run searches against your NG SIEM during triage, grant **`NGSIEM: READ`**. Read is sufficient: the Write variant of this scope covers uploading lookup files, which Clarion does not do. Searching does not let Clarion modify data, ingest into your SIEM, or change correlation rules. Clarion detects the capability automatically and the tool appears within a day of the scope being granted.
4. Copy the generated **Client ID** and **Client Secret**.
Copy the Client Secret immediately — Falcon only shows it once. Store it securely.
***
## Step 3 — Enter the credentials in Clarion
1. Back in the Clarion monitor form, paste the **Client ID** and **Client Secret**.
2. Click **Save**.
Clarion validates the credentials and begins polling Falcon every minute for new detections and cases.
***
## What happens next
Once connected, Clarion will:
* Poll Falcon every minute for new **detections** (surfaced as signals) and **cases** (surfaced as issues)
* Run your configured signal rules against incoming detections to promote matching events into issues
* Hand issues to any connected triage agents
* Discover your Falcon **host roster** into the Brain as **device** assets (OS, platform, serial, last-seen). When a workstation's last login matches a synced identity (Okta / Google Workspace), the device is linked to its owner, so an issue involving that user surfaces their endpoints. Devices refresh on each asset sync (manual **Sync** or the scheduled auto-update).
You can manage the monitor — pause polling, rotate credentials, or view sync status — from the **Monitors** section on the CrowdStrike integration page.
## Agent tools
Once connected, your triage agents can use CrowdStrike tools to investigate and respond to alerts directly in Falcon:
* **Endpoint Detection & Response** — Investigate Falcon alerts, inspect hosts, contain compromised endpoints, manage IOCs, and run Real-Time Response sessions.
Attach these tools to a skill in the skill editor. Destructive actions (host containment, IOC creation, Real-Time Response commands) require human approval by default and can be reviewed before the agent executes them.
***
## Monitoring multiple Falcon tenants
CrowdStrike is configured **per monitor**: each Falcon tenant (each Client ID / Client Secret pair) is its own monitor in Clarion, with its own cursors and sync health. To monitor a second tenant, click **Add Monitor** again on the integration page and enter that tenant's credentials.
***
## Sync historical cases
The monitor only polls forward from the moment it's connected. To pull in cases and detections from before that point:
1. Open the monitor from the **Monitors** section on the **Integrations → CrowdStrike** page.
2. Click **Sync historical cases**.
3. Confirm the action.
Clarion rewinds the monitor's cursors to **7 days ago** and replays everything Falcon has created since. Items already imported are deduplicated by Falcon id, so this is safe to re-run.
***
## Update or rotate credentials
To replace a Client Secret (for example, after rotating it in Falcon):
1. Generate a new Client Secret in Falcon under **Support and resources → API clients and keys**.
2. In Clarion, open the monitor.
3. Paste the new secret into **Update Client Secret** and click **Save**. Leave the field blank to keep the existing secret when you only want to change the cloud region or Client ID.
***
## Troubleshooting
### The connection fails or events stop arriving
* Confirm the cloud region matches your Falcon Console URL exactly (e.g. a US-2 tenant paired with a US-1 selection will not authenticate).
* Verify the API client in Falcon has the scopes listed in the Clarion setup instructions and has not been revoked.
* Use **Sync now** on the monitor to trigger an immediate poll and surface the underlying Falcon error in the toast.
# Custom MCP
Source: https://docs.cantina.security/clarion/integrations/custom-mcp
Connect any MCP-compatible HTTP server to extend Clarion agents with your own tools.
This guide walks you through connecting a custom MCP server to Clarion. Once connected, every tool your server exposes becomes available to Clarion agents during triage and response.
**Estimated time:** 2 minutes. You will need a **Clarion workspace** with permission to manage integrations and an MCP-compatible HTTP server that Clarion can reach over the public internet.
## Prerequisites
* A **Clarion workspace** with permission to manage integrations
* An **MCP server** that speaks the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) and is reachable from Clarion
* (Optional) an **API key** if your server requires authentication — Clarion sends it as `Authorization: Bearer ` on every request
***
## Step 1 — Add an MCP server
1. In Clarion, go to **Settings > Integrations**
2. Scroll to the **Custom MCPs** section and click **Add MCP Server**
3. Fill in the form:
* **Name** — a short label for this server (e.g. `My Security Scanner`). Clarion slugifies the name and registers the server as `custom-` so it can never shadow a built-in MCP server
* **Server URL** — the HTTP endpoint of your MCP server (e.g. `https://mcp.example.com`)
* **API key** *(optional)* — sent as `Authorization: Bearer ` on every request to your server
4. Click **Connect**
Clarion validates the connection before saving — if the server is unreachable or doesn't speak MCP, the form surfaces the error and nothing is stored.
You can add multiple custom MCP servers to a single workspace. Each one shows up as its own card on the Integrations page.
***
## Step 2 — Verify the tools
Once connected, the server card shows the number of tools Clarion discovered. Open the card's **View tools** menu to see each tool's name and description as advertised by your server.
If you don't see the tools you expect, double-check that your server returns them from the MCP `tools/list` method and that the names contain no underscores in the server segment.
***
## What Clarion can do
After connecting, agents can:
* **Invoke any tool** your MCP server exposes — Clarion forwards the call through a proxy that authenticates the agent and attaches your API key on every request
* **See tool descriptions** straight from your server, so updating the description on your side is enough to update what the agent sees
Clarion does not modify or cache your tool schemas — every agent run pulls the live list from your server.
***
## Security model
* Your **server URL** and **API key** are stored encrypted and only decrypted server-side when a Clarion agent needs to call your server. The API key is never bundled into agent sandbox code or exposed to agent prompts.
* Requests from Clarion agents are proxied through Clarion's backend — your server only ever sees traffic from Clarion's IPs, never from the agent sandbox directly.
* Clarion validates the upstream URL before each call to prevent SSRF against internal addresses.
* Treat the tools your MCP server exposes as **attacker-controlled input** to Clarion agents. Tool descriptions and outputs can contain instructions — Clarion already redacts secrets in transcripts, but only connect servers you trust.
***
## Remove an MCP server
To remove a server:
1. Open **Settings > Integrations** in Clarion
2. Find the server card under **Custom MCPs**
3. Click the menu (**⋯**) and choose **Remove**
4. Confirm the dialog
Removing a server deletes its stored URL and API key from Clarion immediately and revokes agent access to its tools. Anything your server already did on Clarion's behalf stays in place — only the connection is removed.
# Custom toolset (API)
Source: https://docs.cantina.security/clarion/integrations/custom-toolset
Turn any REST API into agent tools by pointing Clarion at its documentation.
When a system has no Clarion integration and no MCP server, a **custom toolset** closes the gap. Give Clarion the API's base URL and its documentation, and it infers the tools — which you then review before any agent sees them.
This is different from a [custom MCP server](/clarion/integrations/custom-mcp). Use custom MCP when the vendor already ships an MCP server. Use a custom toolset when they don't.
## Create one
1. In Clarion, open **Integrations → Custom toolsets** and click **Add**.
2. Give it a **name** — this becomes the tool namespace agents see.
3. Enter the API's **base URL**.
4. Configure **authentication**:
| Auth | Sends |
| - | - |
| **None** | Nothing — for public APIs |
| **Bearer** | `Authorization: Bearer ` |
| **Header** | A custom header name and value |
| **Basic** | Username and password |
| **Query** | A key as a query parameter |
5. Provide **documentation** — paste text, link a URL, or upload a file.
6. Click **Scan**. Clarion reads the docs and proposes a list of tools.
Credentials are encrypted at rest and attached to the request outside the sandbox, so an agent never sees the key it is authenticating with.
## Review before enabling
The inferred tool list is a **proposal**, not a live surface. Every tool is disabled until you enable it, and only enabled tools are exposed to agents. Review each one's name, description, and parameters before turning it on — the description is what an agent reasons about when deciding to call it.
Enable the narrowest set that does the job, and be deliberate about anything that writes. A tool an agent can call is a tool an agent can be talked into calling.
Responses pass through secret redaction before they reach a transcript or the UI.
## Rescans
Clarion hashes the normalized documentation. Rescanning after an unchanged doc is a no-op; when the docs change, you get a fresh proposal to review rather than silent drift in what your agents can do.
## Use in skills
Once enabled, a custom toolset's tools appear in the skill editor's tool picker like any other integration's, and can be embedded in skill content.
## Delete
Delete the toolset from **Integrations → Custom toolsets**. Stored credentials are removed, and skills referencing its tools surface them as missing.
# Datadog
Source: https://docs.cantina.security/clarion/integrations/datadog
Connect Datadog so agents can query your logs, APM, events, and service catalog — and manage Datadog cases — during triage.
This guide walks you through connecting Datadog to Clarion. Once connected, AI agents can pull observability context from Datadog while they triage — searching logs, APM spans, events, and the service catalog — and manage [Datadog cases](https://docs.datadoghq.com/service_management/case_management/) to track their findings alongside your team.
**Estimated time:** 5-10 minutes. You will need permission to create **API** and **Application keys** in your Datadog organization, plus access to the Clarion workspace where you want to connect Datadog.
## What you'll configure
| What | Purpose |
| - | - |
| **Datadog site** | The region your organization runs in (e.g. US1, EU1). Clarion uses it to reach the correct Datadog API and dashboard. |
| **API key** | Identifies your Datadog organization on every request. |
| **Application key** | Authorizes the specific actions agents can take. The scopes you grant it determine which tools work — see [Step 3](#step-3-create-an-application-key). |
Clarion talks to Datadog through Datadog's official [Bits AI MCP server](https://docs.datadoghq.com/bits_ai/mcp_server/). Your keys are stored encrypted and injected server-side when an agent calls a Datadog tool — they are never exposed to the agent's sandbox or written into transcripts.
## Prerequisites
* A **Datadog** account on a [supported site](#step-1-choose-your-datadog-site)
* Permission to create **API keys** and **Application keys** (Organization Settings)
* Datadog's **MCP server (Bits AI)** available for your organization — see [Datadog's setup docs](https://docs.datadoghq.com/bits_ai/mcp_server/setup/)
* A **Clarion workspace** with the Datadog integration page open
***
## Step 1 — Choose your Datadog site
Clarion supports the regions where Datadog publishes its MCP server:
| Site | Value |
| - | - |
| US1 | `datadoghq.com` |
| US3 | `us3.datadoghq.com` |
| US5 | `us5.datadoghq.com` |
| EU1 | `datadoghq.eu` |
| AP1 | `ap1.datadoghq.com` |
| AP2 | `ap2.datadoghq.com` |
Check the URL you use to reach Datadog to confirm your site. US1-FED and US2-FED (GovCloud) are not supported.
***
## Step 2 — Create an API key
1. In Datadog, go to **Organization Settings → API Keys**.
2. Click **New Key**, give it a name (e.g. `Clarion`), and create it.
3. Copy the key value.
***
## Step 3 — Create an Application key
The Application key's **scopes** decide which tools agents can use. Create it with the full set below so every Datadog tool works; grant a subset if you only want certain capabilities.
1. In Datadog, go to **Organization Settings → Application Keys**.
2. Click **New Key**, name it (e.g. `Clarion`), and add these scopes:
| Scope | Unlocks |
| - | - |
| `mcp_read` | Base scope required for **all** Datadog tools |
| `logs_read_data`, `logs_read_index_data`, `built_in_features` | Log Search (Datadog's MCP server checks `built_in_features` for log search even though its docs don't list it) |
| `apm_read` | APM Span Search |
| `apm_service_catalog_read` | Service Catalog & Service Dependencies |
| `teams_read` | Service Dependencies and services owned by a team |
| `events_read`, `timeseries_query` | Event Search |
| `cases_read` | Case search and read (cases and projects) |
| `cases_write` | Create / update cases, add comments, link Jira |
| `user_access_read` | User Search (resolving case assignees) |
3. Copy the key value.
If an Application key is missing a scope, the matching tools fail at call time rather than at setup. If a tool returns a permissions error during triage, re-check the key's scopes here.
***
## Step 4 — Connect Datadog in Clarion
1. In Clarion, open **Integrations** and find **Datadog**.
2. Select your **Datadog site** from Step 1.
3. Paste your **API Key** (Step 2) and **Application Key** (Step 3).
4. Click **Save**.
To rotate keys later, return to this page and enter new values. To remove the integration entirely, see [Disconnect](#disconnect).
***
## What agents can do
Once connected, agents on this workspace can use the Datadog tools below. Add the ones you want to a skill the agent runs (for example, an enrichment skill that gathers observability context, or a triage skill that opens a case for confirmed issues).
### Observability (read-only)
| Tool | What it does |
| - | - |
| **Log Search** | Search logs by service and time range |
| **APM Span Search** | Search APM spans — request URLs, headers, and body tags |
| **Event Search** | Search deployments, monitor alerts, and infrastructure changes |
| **Service Catalog** | List services with their runtime and topology |
| **Service Dependencies** | Map upstream and downstream service dependencies |
### Case Management
| Tool | Type | What it does |
| - | - | - |
| **Case Search** | Read | Find cases by status, priority, project, or assignee |
| **Case Details** | Read | Full case, including timeline and custom attributes |
| **Case Projects / Project Details** | Read | List and inspect the projects cases live in |
| **User Search** | Read | Resolve a Datadog user to assign a case to |
| **Create Case** | Write | Open a case to track an investigation |
| **Update Case** | Write | Change status, priority, assignee, or other fields |
| **Add Case Comment** | Write | Post a markdown comment to a case's timeline |
| **Link Jira to Case** | Write | Link a Jira issue to a case for cross-platform tracking |
The case **write** tools (Create, Update, Add Comment, Link Jira) require approval by default — the agent pauses and waits for a human before it changes anything in your Datadog workspace. You can adjust this per tool or per action under **Workspace → Tools**. **Link Jira to Case** also requires a Jira integration configured on the Datadog side.
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Datadog**.
2. Click **Disconnect**.
This deletes the stored API and Application keys. Agents on this workspace will no longer see the Datadog tools, and any saved skills that reference them will surface the integration as missing until you reconnect.
***
## Troubleshooting
### A Datadog tool returns a permissions error
The Application key is missing the scope that tool needs. Re-create the key in **Organization Settings → Application Keys** with the full scope set from [Step 3](#step-3-create-an-application-key), then re-save it in Clarion.
### Case tools don't work
The case tools need `cases_read` and `cases_write` (and `user_access_read` for assignee lookup). Confirm those scopes are on the Application key, and that the case tools are added to the skill the agent is running.
### "Unknown Datadog site" or no data returned
The selected site doesn't match your organization's region. Check the URL you use to reach Datadog and pick the matching site in [Step 1](#step-1-choose-your-datadog-site). US1-FED and US2-FED are not supported.
### Tools don't appear at all
Confirm Datadog's MCP server (Bits AI) is available for your organization — see [Datadog's setup docs](https://docs.datadoghq.com/bits_ai/mcp_server/setup/) — and that the integration shows as connected in Clarion.
Forwarding Datadog **monitor alerts** into Clarion as issues is coming soon. Today the Datadog integration powers the agent tools described above.
# Devin
Source: https://docs.cantina.security/clarion/integrations/devin
Connect a Devin Teams organization so Clarion agents can read and write org skills, search sessions, ask Devin to investigate a question, and, with an Admin service user, look up members.
This guide walks you through connecting a Devin Teams organization to Clarion. Once connected, agents on the workspace can read and write org skills, search sessions, read a session's recent messages, and start a Devin session that investigates a question and reports back. Listing and reading organization members is available only when the service user has the Admin role.
**Estimated time:** 5 minutes. You need access to **Settings > Devin API** in a **Devin Teams** organization so you can create a service user.
## Prerequisites
* A **Devin Teams** organization
* Permission to create a **service user** under **Settings > Devin API**
* A **Clarion workspace** with the Devin integration page open
One Clarion workspace connects one Devin organization. The key you paste acts as that service user. Personal access tokens and legacy `apk_` or `apk_user_` keys are rejected. Create a service-user key that starts with `cog_`.
***
## Step 1 — Create a service-user key in Devin
1. Sign in to Devin for the Teams organization you want to connect.
2. Open **Settings > Devin API**.
3. Create a **service user**. Choose **Member** if agents only need skills and sessions. Agents need the service user to hold `ViewOrgSessions` to read sessions and `ManageOrgSessions` to start them. Choose **Admin** if they also need to list and read organization members.
4. Copy the key. It begins with `cog_`.
Copy the key immediately and store it securely. Devin shows it once. A personal access token, or a legacy `apk_` / `apk_user_` key, will be rejected.
***
## Step 2 — Enter the key in Clarion
1. In Clarion, open **Integrations** and find **Devin** under Development & Planning.
2. Paste the **service-user API key**.
3. Click **Connect**.
Clarion checks the key with Devin before saving it, and checks whether that service user can list organization members. If the key is a personal token, a legacy key, or does not belong to one organization, you'll see a clear error and nothing is stored.
After it connects, the page shows the organization id and the service user's name. Those values are read-only. To replace the key, paste a new one and save. Saving re-runs the member-access check. If the check fails, skills and sessions still work, and member tools stay unavailable until you save an Admin-role key.
***
## What agents can do
| Tool | What it does |
| - | - |
| `get_devin_skill` | Read one org skill by name, or list the skill names Clarion itself has written |
| `create_devin_skill` | Create an org skill that does not exist yet. Asks for approval by default |
| `update_devin_skill` | Replace one org skill's full document. Asks for approval by default |
| `delete_devin_skill` | Delete one org skill by name. Asks for approval by default |
| `search_devin_sessions` | Search sessions in this organization. Returns titles and status, not message text |
| `create_devin_session` | Start a session that investigates a question and reports its findings. Asks for approval by default. Returns only the session id, URL, and status |
| `get_devin_session` | Read one session's status, so the agent knows when the answer is ready |
| `get_devin_session_messages` | Read the most recent messages of one session, up to 200. For a session longer than 2000 messages, the result is flagged and holds the tail of the first 2000, not the latest. |
| `list_users` | List organization members. Requires an Admin-role service user |
| `get_user` | Read one organization member. Requires an Admin-role service user |
A Member role is enough for skills and sessions. `list_users` and `get_user` need an Admin role.
Skill writes and session creation ask for approval by default. A workspace can turn that off the same way it does for other write tools.
### Asking Devin to investigate
`create_devin_session` is for gathering information, not for authoring content. Clarion adds an instruction to every prompt telling Devin to report its findings as a message in the session and not to open pull requests, push commits, or change external systems. The prompt is limited to 4,000 characters, and prompts, titles, or tags that look like secrets are rejected.
By default, a person approves each session before it starts. If a workspace turns that approval off, the instruction Clarion adds to the prompt is the only limit on what the session is asked to do, and Devin acts with the access its organization grants. Sessions run asynchronously: the create call returns right away with the session id, URL, and status. The agent then checks `get_devin_session` until the session is finished or waiting for input, and reads the answer with `get_devin_session_messages`.
Clarion only knows skills it wrote. Devin has no skill list endpoint, so a skill created outside Clarion does not appear in that list. An agent can still read or update it if you already know the name.
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Devin**.
2. Click **Disconnect**.
This deletes the stored key. Agents lose the Devin tools, and any saved skills that reference the Devin action will surface the integration as missing until you reconnect.
***
## Troubleshooting
### "Devin rejected the key"
The key is malformed, unknown, or revoked, or it is not a `cog_` service-user key. Create a fresh service-user key in **Settings > Devin API** and connect again. Personal access tokens and legacy `apk_` keys are not accepted.
### "Devin connect requires a service-user API key"
The key authenticated as a person rather than a service user. Create a service user in **Settings > Devin API** and paste that key.
### Member tools are missing
The connected service user is not an Admin, so it cannot list organization members. Skills and sessions still work. Create an Admin-role service user, paste its key, and save. Saving re-runs the check.
# DNS Monitor
Source: https://docs.cantina.security/clarion/integrations/dns
Built-in DNS monitoring — watch your zones for record, subdomain, and email-authentication changes with no external service.
The DNS Monitor is built into Clarion. There is no vendor to connect and no credential to store: you name the domains to watch, and Clarion resolves them on a schedule, comparing each result against the last.
**Estimated time:** 2 minutes. You need only the domains you want monitored.
## Connect
1. In Clarion, open **Integrations** and find **DNS Monitor**.
2. Click **Connect** — the integration activates immediately.
3. Add a monitor per domain you want watched.
## What it detects
Each check compares the current answer against the previous one and raises an issue on a meaningful difference:
* **Record changes** — A, AAAA, CNAME, MX, NS, and TXT records that changed unexpectedly
* **Email-authentication changes** — SPF, DKIM, and DMARC records, the ones that gate whether someone can spoof your domain
* **New subdomains** — names that appeared since the last scan
* **Nameserver and registrar changes** — the signature of a domain hijack
* **Certificate and TLS posture** on the resolved hosts
These feed the [DNS & Domain Security](/clarion/learn/agents#our-agents) agent, which carries seven skills covering record change, subdomain change, email-auth change, new subdomain discovery, registrar compromise, DNS tunneling, and DDoS amplification.
## What agents can do
The DNS tools are available to every agent, whether or not the monitor is watching a given name:
| Tool | What it returns |
| - | - |
| `dns_lookup` | Resolve a name across record types |
| `dns_dig` | A raw `dig`-style query for a specific record type |
| `dns_compare` | Compare a name's answers across resolvers |
| `whois_lookup` | Registrar and registration data for a domain |
| `spf_check` / `dkim_check` / `dmarc_check` | Email-authentication posture for a domain |
| `tls_check` | Certificate chain, expiry, and TLS configuration for a host |
## Acting on findings
The DNS Monitor detects; it does not change records. To let an agent *fix* a DNS problem, connect [Cloudflare](/clarion/integrations/cloudflare) — that integration carries the record write and zone rollback tools, and the [Dangling Subdomain Agent](/clarion/learn/agents#our-agents) uses it for its daily sweep.
## Disconnect
Click **Disconnect** on the integration page. Monitors under it stop running.
# Envoy
Source: https://docs.cantina.security/clarion/integrations/envoy
Workplace context — office locations, employees, and who is signed in on site — for physical-world corroboration during triage.
Envoy is a workplace platform. Connecting it gives agents a read-only view of your office locations, employee directory, and visitor and employee sign-in entries.
**Estimated time:** 3 minutes. You will need admin access to your Envoy account.
## Prerequisites
* An **Envoy** account with admin access
* A Client API key
## Step 1 — Create a Client API Key in Envoy
1. In Envoy, go to **Settings → Integrations → API keys**.
2. Create a **Client API Key**.
3. Copy the key.
## Step 2 — Connect in Clarion
1. In Clarion, open **Integrations** and find **Envoy**.
2. Paste the key and click **Connect**.
The key is stored encrypted and never enters the agent sandbox.
## What agents can do
| Tool | What it returns |
| - | - |
| `get_company` | Your Envoy company record |
| `list_locations` | Office locations |
| `list_employees` / `get_employee` | Employee directory lookups |
| `list_entries` / `get_entry` | Sign-in entries — who was on site, and when |
## Why a security agent wants this
Envoy answers a question the rest of the stack cannot: **was this person physically there?**
An impossible-travel alert reads very differently when the badge record puts the employee in the London office at the time of the London login. A suspicious out-of-hours access from a corporate network is more interesting when nobody was in the building. Envoy turns those from assumptions into evidence.
## Disconnect
Click **Disconnect** on the integration page. The stored key is deleted.
# Falco
Source: https://docs.cantina.security/clarion/integrations/falco
Runtime security on your hosts over SSH — ingest Falco alerts and let agents inspect and kill suspicious sessions.
Falco is runtime threat detection for Linux hosts and containers. Clarion connects to a host over SSH to receive Falco's alerts and to act on suspicious sessions.
**Estimated time:** 10 minutes. You will need SSH access to the host running Falco and the ability to create a dedicated key.
## Prerequisites
* A host running **Falco**, reachable over SSH from Clarion
* A dedicated SSH user for Clarion, with only the access it needs
* An SSH private key for that user (a passphrase is supported)
Give Clarion its own SSH user rather than reusing an operator account. This integration can terminate sessions on the host, so the account's blast radius is the integration's blast radius.
## Connect
1. In Clarion, open **Integrations** and find **Falco**.
2. Enter the **Host** — an IP address or hostname, e.g. `192.168.1.100` or `host.example.com`.
3. Enter the **SSH Username**.
4. Paste the **SSH Private Key**, and its **passphrase** if it has one.
5. Click **Connect**.
Credentials are stored encrypted and never enter the agent sandbox.
## What Clarion ingests
Falco runtime alerts — unexpected process execution, suspicious file access, container escapes, privilege escalation, and outbound connections that break policy. These feed the [Infrastructure & Ops](/clarion/learn/agents#our-agents) agent, alongside Grafana and Better Stack.
## What agents can do
| Tool | What it does |
| - | - |
| `list_sessions` | List active sessions on the host |
| `kill_sessions` | Terminate one or more sessions |
`kill_sessions` disconnects a live user. It is a containment action and is gated behind approval by default.
## Disconnect
Click **Disconnect** on the integration page. The stored SSH credentials are deleted.
# Generic Webhook
Source: https://docs.cantina.security/clarion/integrations/generic-webhook
Send events from any service to Clarion via HTTP webhook for AI-powered triage and response.
This guide walks you through setting up a Clarion Generic Webhook monitor — a flexible endpoint that accepts JSON events from any service that can make an HTTP POST request. Use it to bring custom alerts, deploy events, CI failures, or any JSON payload into Clarion.
**Estimated time:** 5 minutes. You will need a **Clarion workspace** and the ability to configure outbound webhooks in the source service.
## Prerequisites
* A **Clarion workspace**
* A service that can send HTTP `POST` requests with a JSON body (CI systems, bespoke scripts, SaaS tools with webhook outputs, Slack-style senders, etc.)
***
## Step 1 — Create a Generic Webhook monitor
1. In Clarion, go to **Settings > Integrations**
2. Find **Webhook** and click **Add Monitor**
3. Give the monitor a **name** — it is prefixed onto issue titles, so different monitors are easy to tell apart
4. Pick an **authentication method** (see the next section)
5. Pick a **default severity** for issues opened by the monitor
6. Click **Create**
Clarion generates a **webhook URL** and, depending on the auth method, a **signing secret** or **bearer token**. Copy them right away.
Copy any generated secret immediately — it is only displayed once. You can rotate it later from the monitor's Configure page, but you cannot view the current value.
***
## Step 2 — Choose an authentication method
| Mode | How requests are authenticated | When to use |
| - | - | - |
| **HMAC-SHA256 signature** | Sender signs the raw request body with the shared secret and sends the hex digest in `X-Webhook-Signature` (also accepts `X-Hub-Signature-256` with the `sha256=` prefix) | Production senders that can compute HMAC |
| **Bearer token** | Sender includes `Authorization: Bearer ` | Services with a simple token field in their webhook config |
| **No authentication** | Any request is accepted | Trusted internal networks only |
"No authentication" accepts any POST. Only use it for traffic that is already restricted by a private network or VPN.
The authentication method is fixed at creation. To switch, create a new monitor.
### Signature format
Some senders cannot put their signature in our header. With HMAC auth selected, the **Signature format** dropdown adds that sender's header to what the monitor accepts:
| Format | Also accepts |
| - | - |
| **X-Webhook-Signature** (default) | nothing extra |
| **X-Payload-Digest** | `X-Payload-Digest`, with the algorithm named in `X-Payload-Digest-Alg`. Set the sender to SHA256 or SHA512 — the deprecated SHA1 option is refused |
| **Custom header** | the header you name, with the algorithm (SHA256/SHA512) and encoding (hex/base64) you pick — and, for senders that sign a timestamp with the body, that timestamp header too |
Unlike the authentication method, this can be changed at any time — it does not affect your secret.
#### Senders that sign a timestamp with the body
Some senders — Immunefi and Slack among them — do not sign the body alone. They send a Unix timestamp in a **second header** and sign the two joined together, so a captured delivery cannot be replayed later. Under **Custom header**, fill in **Timestamp header** to accept those:
| Field | What it means |
| - | - |
| **Timestamp header** | Header carrying the Unix timestamp, in **seconds**. Leave empty when the digest covers the body alone |
| **Signed string** | How the sender joins them, via `{timestamp}` and `{body}` — each exactly once. Defaults to `{timestamp}.{body}` |
| **Tolerance** | How old a signed delivery may be, in seconds. Defaults to 300 (5 minutes); 30–3600 allowed |
A digest may arrive with a `sha256=`, `sha512=` or version (`v1=`) prefix — Clarion strips it before comparing.
Both header values must stand alone: the timestamp header holds bare digits, and the signature header holds the digest (with at most one of those prefixes). A sender that packs both into a single header — Stripe's `Stripe-Signature: t=…,v1=…` — is not covered.
Once a timestamp header is set, the monitor stops honouring body-only digests in `X-Webhook-Signature` — otherwise the replay window you just configured would sit next to a door that ignores it. Deliveries outside the window are refused with `401` and recorded on the monitor's health as a stale timestamp, told apart from a wrong secret, so a sender whose clock has drifted is diagnosable.
##### Example: Immunefi
Immunefi sends `X-Immunefi-Signature: v1=` and `X-Immunefi-Timestamp: `, signing `timestamp + "." + raw body`, and recommends a five-minute tolerance. That is:
| Field | Value |
| - | - |
| Signature format | **Custom header** |
| Header name | `x-immunefi-signature` |
| Algorithm / Encoding | SHA256 / Hex |
| Timestamp header | `x-immunefi-timestamp` |
| Signed string | `{timestamp}.{body}` (the default) |
| Tolerance | `300` (the default) |
Verify it yourself against the monitor's secret:
```bash theme={null}
BODY='{"type":"report.created","message":"New report"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -X POST "https:///api/webhooks/generic-webhook/" \
-H "Content-Type: application/json" \
-H "X-Immunefi-Signature: v1=$SIG" \
-H "X-Immunefi-Timestamp: $TS" \
-d "$BODY"
```
***
## Step 3 — Send events from your service
Point the source service at the webhook URL Clarion gave you. Use `POST` with a JSON **object** body, up to 100 KB.
### Minimal example
```bash theme={null}
curl -X POST "https:///api/webhooks/generic-webhook/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{"type": "deploy.failed", "message": "Production deploy failed", "severity": "high"}'
```
### What goes in the payload
Any valid JSON object is accepted. Clarion looks at the payload's `type`, `event`, `eventType`, or `event_type` field (in that order) to derive an **event type** — used for matching filters and included in the issue title. If none of those fields is present, the event is treated as `generic`.
Fields used by the default issue template:
| Field | How it's used |
| - | - |
| `type` / `event` / `eventType` / `event_type` | Event type — filter matching and issue title |
| `message` | Included as the body of the issue description |
| `severity` | Shown under "Reported severity" in the description |
| `source` | Shown under "Source" in the description |
All other fields are attached to the issue for reference — no field is dropped.
### Optional headers
| Header | Purpose |
| - | - |
| `X-Webhook-Signature` or `X-Hub-Signature-256` | HMAC-SHA256 hex digest of the body (required when the monitor uses HMAC auth) |
| `X-Payload-Digest` | Only accepted when the monitor's signature format is set to **X-Payload-Digest** |
| Your sender's own signature and timestamp headers | Only accepted when the monitor's signature format is set to **Custom header** and names them |
| `Authorization: Bearer ` | Required when the monitor uses Bearer auth |
| `X-Idempotency-Key` or `X-Request-Id` | If present, retries of the same value are treated as duplicates and will not create a second issue |
***
## The default "All webhook events" filter
When you create the monitor, Clarion adds an **All webhook events** filter that opens an issue for every incoming event with the default severity you chose. From the monitor's Configure page you can:
* **Change the default severity** — it applies to the default filter immediately
* **Disable** the default filter if you only want issues for specific events
* **Add more filters** that match by event type, payload fields, or conditions (e.g. only alert when `severity = critical`)
Each issue's title includes the monitor name and the time the event arrived; the description surfaces common payload fields (`message`, `severity`, `source`) alongside the event type.
***
## Using as a Slack replacement
Many services offer a "Slack incoming webhook URL" field for sending notifications. Because the Generic Webhook accepts arbitrary JSON, you can drop the Clarion webhook URL into those fields instead — your notifications become Clarion issues that get triaged by AI agents.
To set this up:
1. Create a Generic Webhook monitor with **No authentication** (most Slack-style senders don't sign requests) or **Bearer token** if the source service lets you add an `Authorization` header
2. Copy the webhook URL from the monitor
3. In the source service, paste the Clarion webhook URL wherever it asks for a Slack webhook URL
4. Send a test notification — it will appear as an issue in Clarion
Slack-compatible senders usually put the notification body in a `text` field, which isn't one of the event-type fields Clarion looks at — so those events are treated as `generic` and the default **All webhook events** filter still catches them.
For nicer issue titles, edit the default filter's title template to reference the fields your sender actually uses (for example `{{text}}` for Slack-style payloads).
***
## What happens next
Once configured, Clarion will automatically:
* Accept JSON events at the monitor's webhook URL
* Apply the default **All webhook events** filter (and any custom filters you add) to open issues
* Triage incoming issues using AI agents and surface actionable insights
# GitHub
Source: https://docs.cantina.security/clarion/integrations/github
Connect GitHub so Clarion ingests repository security events, discovers your repos into the Brain, and lets agents open remediation pull requests.
GitHub is the integration behind Clarion's code and supply-chain coverage. Once connected, Clarion ingests repository security events, discovers your repositories into the [Brain](/clarion/learn/agents#the-brain), and gives agents the ability to investigate code and open remediation pull requests.
**Estimated time:** 5 minutes. You will need permission to install a GitHub App on your organization.
## Prerequisites
* A **GitHub organization** where you can install applications
* A **Clarion workspace** with the GitHub integration page open
## Connect
1. In Clarion, open **Integrations** and find **GitHub** under Essentials.
2. Click **Connect** and complete the GitHub App installation.
3. Choose whether to grant access to **all repositories** or a selected subset.
4. Return to Clarion — the integration shows as connected once the installation callback lands.
### Commit identity
Under the integration's settings you can set the **name** and **email** Clarion uses when an agent authors a commit. Pick something that reads clearly in your history, e.g. `Clarion Agent `.
GitHub Enterprise Server is supported by setting a custom **Endpoint URL** on the integration.
## What Clarion ingests
Repository security events feed the **Code & Supply Chain** and **Dependabot Alerts** agents:
* Secret-scanning and code-scanning alerts
* Dependabot vulnerability alerts
* Branch-protection and ruleset changes
* Repository visibility changes
* Force pushes to default branches
* Organization owner additions
* Tag and release activity
## Repository discovery into the Brain
Clarion discovers your repositories as assets, along with the governance metadata that makes them judgeable: rulesets, workflows, open alert counts, org custom properties, and CODEOWNERS. Repositories correlate with cloud resources and observability services that reference them, so an alert on a service resolves to the repository that builds it.
Software bills of materials are captured per repository, which is what lets the Dependabot agent reason about reachability rather than just CVE presence.
## People discovery into the Brain
Clarion also discovers the members of each connected organization as identity assets, carrying their GitHub handle, display name, and org role. A member whose address GitHub exposes joins the same person as their Okta, Slack, or Teams account, so an alert naming a GitHub login resolves to a whole human rather than a handle.
Reading the roster needs a permission Clarion did not originally ask for, so GitHub holds it until one of your **organization owners** approves the request under **Settings → GitHub Apps → Clarion**. Until someone does, repository discovery is unaffected and the Brain's Sources card notes that the roster was not readable.
GitHub only exposes member email addresses for organizations on **Enterprise Cloud** that have [verified their domains](https://docs.github.com/en/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization) and accepted the Corporate Terms of Service. On any other plan GitHub returns no addresses at all, so members are still inventoried — handle, name, role — but not joined to their accounts in other tools.
## What agents can do
* Read repository contents, history, and pull requests during an investigation.
* Assess the blast radius of a code finding across the organization.
* Open a **remediation pull request**, push commits to it, and iterate until CI is green.
* Comment on and label issues and pull requests.
Write actions are gated by your workspace's tool policy. An agent asks for approval before pushing or opening a PR unless you have explicitly allowed it.
## Related agents
Repository integrity, CI/CD, and org governance.
Auto-fix PRs driven to green CI.
## Disconnect
Open **Integrations → GitHub** and click **Disconnect**, then uninstall the Clarion app from your GitHub organization. Agents lose the GitHub tools, and skills referencing them surface the integration as missing until you reconnect.
# Google Calendar
Source: https://docs.cantina.security/clarion/integrations/google-calendar
Sync the on-call rotation to a Google Calendar so anyone on the team can see who is on call at a glance.
This guide shows how to connect Google Calendar to Clarion. Once connected, Clarion automatically writes on-call shifts to a calendar you choose and keeps them updated as the rotation changes.
**Estimated time:** 2 minutes. You need access to:
* A **Clarion workspace** with permission to manage integrations
* A **Google account** with permission to authorize third-party apps for the calendar you want to use
## Prerequisites
* A Google account with access to the calendar you want Clarion to write to. Any Google account works — personal Gmail, Google Workspace, or a shared account.
* An on-call rotation defined in Clarion under **Settings → Agents → Escalation & notifications**. If the rotation is empty, the connection is still allowed but no events appear until you add slots.
***
## Step 1 - Connect Google Calendar
1. In Clarion, open **Integrations** and find **Google Calendar**.
2. Click **Connect Google Calendar**. You'll be redirected to Google to authorize Clarion.
3. Review the requested permissions in Google, then click **Continue**.
Google redirects you back to Clarion with the connection established. Clarion now needs one more choice: which calendar to write to.
***
## Step 2 - Choose a target calendar
On the Google Calendar integration page, pick where Clarion should write the on-call shifts:
* **Create a new Clarion On-Call calendar** *(recommended)*: Clarion creates a dedicated calendar in the connected Google account named **Clarion On-Call**. Best for teams who want a clean, isolated view of the rotation.
* **Use an existing calendar**: Pick any calendar you have write access to. Best when you already have a shared team calendar.
Click **Save target calendar**. Clarion runs an initial sync and writes the next 12 weeks of on-call shifts. Each shift is an all-day event titled with the on-call member's name.
The on-call member is added as an **attendee** on their shift, so the event also appears on their personal calendar automatically. Google emails each new attendee once when Clarion first schedules them — subsequent edits (rotation reorders, description tweaks) stay quiet.
***
## What Clarion syncs
Every event Clarion writes:
* Is an **all-day** event covering the full length of the shift (7 days for weekly rotations, 14 days for biweekly).
* Has the on-call member(s) as attendees, so shifts also appear on their personal calendars.
* Sets a **24-hour popup reminder** on the shared Clarion calendar. Each attendee's personal copy uses their own Google Calendar default reminders — you can override per-event or globally in Google Calendar settings.
* Includes a link back to the Clarion **Settings → Agents → Escalation & notifications** page for context.
When the rotation changes — new member added, slots reordered, cadence changed — Clarion patches the affected events on the next sync (immediately after you save the rotation, plus a daily background pass).
***
## Manually resync
On the Google Calendar integration page, click **Sync now** to reconcile the calendar immediately. Useful when:
* You just updated the rotation and don't want to wait for the automatic sync.
* Someone deleted a Clarion event manually — resync restores it.
* The last-sync line shows an error.
***
## Reconnecting after Google revokes access
If Google revokes Clarion's access (for example, when the person who connected removes Clarion from their Google account), the integration surfaces a **Reconnect Google Calendar** button on the settings page. Clicking through the OAuth flow again restores the sync — the target calendar setting is remembered, so no manual re-picking is needed.
***
## Disconnect
To stop syncing:
1. Open the **Google Calendar** integration in Clarion.
2. Click **Disconnect**.
3. Confirm the dialog.
Behavior depends on the target calendar:
* If Clarion **created** the calendar for you, that calendar is deleted from Google along with its events.
* If you pointed Clarion at an **existing** calendar, only the events Clarion added are removed. Everything else on the calendar is left untouched.
# Google Cloud
Source: https://docs.cantina.security/clarion/integrations/google-cloud
Connect Google Cloud monitors and runtime credentials for agent triage.
Google Cloud support is split into monitor types. Use **GCP Cloud Logging** for audit log streams, **GCP Cloud Monitoring** for alert policy incidents, and **GCP Security Command Center** for SCC findings.
## Runtime credentials
Configure runtime credentials on the Google Cloud integration page before agents use GCP tools. These credentials let Clarion read audit logs, inspect IAM state, fetch SCC findings, and query Cloud Monitoring policy and metric context during triage.
The runtime credential project can be different from the projects or SCC scopes you monitor.
Clarion supports two runtime auth modes:
* **Keyless via Workload Identity Federation**: recommended whenever Clarion's central GCP bridge is configured. Guided setup provisions this by default and stores only non-secret metadata.
* **JSON service account key**: fallback for local development or environments where WIF is not available. Clarion stores the private key encrypted.
Switching to WIF clears Clarion's stored private key. It does not delete any existing service account keys in Google Cloud; delete remote keys after validating WIF if your organization no longer needs them.
## Monitor options
* **GCP Cloud Logging**: one monitor per GCP project. Use this for Admin Activity audit logs, IAM changes, service account key creation, compute launches, logging changes, storage, KMS, secrets, GKE, serverless, SQL, and network/perimeter changes.
* **GCP Cloud Monitoring**: one monitor per GCP project. Use this for incidents from selected Cloud Monitoring alert policies.
* **GCP Security Command Center**: one monitor per SCC organization, folder, or project scope and location. Use this for active SCC findings, including Event Threat Detection findings.
## Recommended setup
1. Go to **Integrations > Google Cloud**.
2. Click **Connect** and complete Google Cloud setup in the dialog.
3. Open the **Monitors** section.
4. Add a **GCP Cloud Logging**, **GCP Cloud Monitoring**, or **GCP Security Command Center** monitor.
5. Use guided setup when available. It provisions keyless runtime auth on Vercel and grants the monitor-specific IAM roles. If you are developing locally, use JSON service account key mode.
See the monitor-specific guides for the exact setup fields:
* [GCP Cloud Logging](/clarion/integrations/google-cloud/cloud-logging)
* [GCP Cloud Monitoring](/clarion/integrations/google-cloud/cloud-monitoring)
* [GCP Security Command Center](/clarion/integrations/google-cloud/security-command-center)
# Cloud Logging
Source: https://docs.cantina.security/clarion/integrations/google-cloud/cloud-logging
Send Google Cloud audit logs to Clarion with one monitor per GCP project.
GCP Cloud Logging monitors ingest Google Cloud audit logs through Pub/Sub push delivery. Each monitor is scoped to one GCP project, so webhook delivery, OIDC verification, and signal rules stay bound to that project.
## Setup options
Use **guided setup** when possible. Clarion will create or update the Pub/Sub topic, log sink, push subscription, OIDC signer, and IAM grants for the selected project.
Use **manual setup** when you need to provision GCP resources yourself. Clarion will show the monitor webhook URL and ask you to save the Pub/Sub subscription resource plus the OIDC service account metadata.
## Runtime credentials
Before agent tools can investigate issues from GCP, configure runtime credentials on the GCP integration page. These credentials authenticate Clarion's outbound GCP API calls.
The runtime credential project is separate from the monitored project. Add a GCP Cloud Logging monitor for each project you want to ingest, then grant the runtime service account the required roles in that target project.
Guided setup uses **Keyless via Workload Identity Federation** by default when Clarion's central GCP bridge is configured. This creates or reuses the `clarion-agent` service account and grants Clarion's central bridge service account permission to impersonate it, storing only non-secret metadata (no private key). Use **JSON service account key** mode only for local development or fallback.
## Guided setup
1. Go to **Integrations > GCP**.
2. Connect runtime credentials if they are not already configured. Guided setup will prefer keyless WIF on Vercel.
3. Add a **GCP Cloud Logging** monitor.
4. Choose **Run guided setup**.
5. Select the GCP project to monitor.
6. Approve the setup steps and save the monitor.
Clarion seeds a curated managed Admin Activity signal-rule set for the monitor, including IAM, logging, storage, KMS, Secret Manager, GKE, Cloud Run, Cloud Functions, Cloud SQL, and network/perimeter detections. The catch-all template remains available for explicit testing or heavily pre-filtered sinks, but it is not enabled by default.
## Manual setup
1. Create or open a **GCP Cloud Logging** monitor in Clarion.
2. Copy the monitor webhook URL.
3. In Google Cloud, route Cloud Logging entries to a Pub/Sub topic with a log sink.
4. Grant the log sink writer identity `roles/pubsub.publisher` on the topic.
5. Create a Pub/Sub push subscription that targets the monitor webhook URL.
6. Enable OIDC authentication on the push subscription.
7. Save these values on the monitor:
* GCP project ID
* Pub/Sub subscription resource
* OIDC service account email
* OIDC client ID, if configured
The OIDC token audience must match the webhook URL shown by Clarion.
## Multiple projects
Create one active GCP Cloud Logging monitor per workspace/project pair. Reuse the same runtime credentials, then run guided setup or apply manual IAM grants for each target project.
# Cloud Monitoring
Source: https://docs.cantina.security/clarion/integrations/google-cloud/cloud-monitoring
Send Google Cloud Monitoring incidents to Clarion from selected alert policies.
GCP Cloud Monitoring monitors ingest Monitoring incident notifications through Pub/Sub push delivery. Each monitor is scoped to one monitored GCP project. Guided setup attaches Clarion only to the alert policies you select.
## What Clarion ingests
Clarion creates one issue per Cloud Monitoring `incident_id` and updates that issue as Google sends lifecycle events.
* `open` opens or reopens a Clarion issue.
* Re-notifications update issue data without resetting the user's workflow status.
* `closed` closes the existing Clarion issue and sets the resolution time from the incident when available.
Some Google alert policy types may not send close notifications. In those cases, close the Clarion issue manually after investigation.
Clarion currently accepts Google Cloud Monitoring notification schema version `1.2`; test newer Google schema versions before broadening ingestion.
When Google publishes a new notification schema version, compare it against Google's schema documentation, add parser tests for open and closed incidents, then update Clarion's accepted versions before enabling production ingestion.
## Severity mapping
Cloud Monitoring severity maps to Clarion severity as follows:
* `CRITICAL` → Critical
* `ERROR` → High
* `WARNING` → Low
* Missing or unknown severity → the monitor's fallback severity
Use allowed severities on the monitor to filter which incidents open or reopen issues. Once an issue is open, later Google updates refresh the stored severity even if that severity is outside the allowlist. Close notifications can still resolve an existing issue.
Because Google `WARNING` maps to Clarion Low, keep Low selected if you want those incidents to open issues.
Cloud Monitoring re-notifications do not start another Clarion triage run; they refresh the existing issue data to avoid duplicate investigations.
## Guided setup
1. Go to **Integrations > Google Cloud**.
2. Choose **Guided Setup**.
3. Select **Cloud Monitoring monitor**.
4. Select the monitored project.
5. Select at least one alert policy.
6. Run setup.
Clarion creates or reuses:
* Pub/Sub topic for Monitoring incidents
* Pub/Sub push service account
* Pub/Sub push subscription with OIDC authentication
* Cloud Monitoring Pub/Sub notification channel
* Runtime service account identity for read-only triage
Guided setup also grants the Cloud Monitoring notification service agent `roles/pubsub.publisher` on the topic and patches the selected alert policies so they include the Clarion notification channel.
Multiple Cloud Monitoring monitors in the same delivery project can share the same Pub/Sub topic. Each monitor has its own push subscription, so non-matching monitors may reject fan-out deliveries with `403` while the matching monitor accepts the incident.
When Clarion runs on Vercel, guided setup provisions the runtime identity with keyless Workload Identity Federation. JSON service account keys remain available as a fallback for local development or environments where WIF cannot be used.
## Manual setup
Use manual setup when your Google Cloud resources are managed outside Clarion.
1. Create or open a **GCP Cloud Monitoring** monitor in Clarion.
2. Copy the monitor webhook URL.
3. In Google Cloud, create a Pub/Sub topic.
4. Create a Pub/Sub push subscription that targets the Clarion webhook URL.
5. Enable OIDC authentication on the push subscription.
6. Create a Cloud Monitoring Pub/Sub notification channel for the topic.
7. Attach that notification channel to the alert policies you want Clarion to receive.
8. Save these values on the monitor:
* monitored project ID
* optional delivery project ID
* Pub/Sub subscription resource name
* OIDC service account email
* OIDC client ID, if configured
* Cloud Monitoring notification channel resource name
* fallback severity and allowed severities
The OIDC token audience must match the webhook URL shown by Clarion.
## Permissions
The Google account used for guided setup needs permission to:
* list and patch Cloud Monitoring alert policies in the monitored project
* create Monitoring notification channels
* create Pub/Sub topics and push subscriptions in the delivery project
* create service accounts and, on Vercel, workload identity pools/providers for Clarion runtime credentials
* grant Pub/Sub publisher access to the Monitoring notification service agent
For agent triage, Clarion's runtime service account needs `roles/monitoring.viewer`, `roles/logging.viewer`, and `roles/iam.securityReviewer` on the monitored project. Guided setup grants these roles. The Cloud Monitoring tools are read-only and scoped to the issue's configured monitor project.
# Security Command Center
Source: https://docs.cantina.security/clarion/integrations/google-cloud/security-command-center
Send active Google Security Command Center findings to Clarion.
GCP Security Command Center monitors ingest active SCC findings through Pub/Sub push delivery. Each monitor is scoped to one SCC organization, folder, or project and one SCC location.
## What Clarion ingests
Clarion opens an issue for each active, unmuted SCC finding with medium, high, or critical severity. Event Threat Detection findings are included when they arrive through Security Command Center.
## Setup options
Use **guided setup** when possible. Clarion creates the Pub/Sub topic, push subscription, OIDC signer, SCC notification config, SCC-to-Pub/Sub publish grant, and read-only role grants for triage.
Use **manual setup** when your Google Cloud resources are managed outside Clarion. Manual setup still needs GCP runtime credentials in Clarion if agents should triage SCC findings with GCP tools.
Guided setup provisions the shared runtime identity with keyless Workload Identity Federation whenever Clarion's central GCP bridge is configured. JSON service account keys remain available as a fallback for local development or environments where WIF cannot be used.
## Manual setup
1. Create or open a **GCP Security Command Center** monitor in Clarion.
2. Select the SCC scope type: organization, folder, or project.
3. Enter the SCC scope ID and location.
4. Enter the Pub/Sub delivery project ID.
5. Copy the monitor webhook URL.
6. In Google Cloud, create a Pub/Sub topic for SCC findings.
7. Create a Pub/Sub push subscription that targets the Clarion webhook URL.
8. Enable OIDC authentication on the push subscription.
9. Create an SCC notification config that sends active findings to the Pub/Sub topic.
10. Grant the SCC notification config service account `roles/pubsub.publisher` on the Pub/Sub topic.
11. Save these values on the monitor:
* Pub/Sub subscription resource
* OIDC service account email
* OIDC client ID, if configured
* SCC notification config resource name
The OIDC token audience must match the webhook URL shown by Clarion.
## Permissions
The runtime service account needs read-only access to SCC findings for the selected scope. Guided setup grants the SCC findings viewer role. For manual setup, grant equivalent read-only SCC finding access at the organization, folder, or project you monitor.
For agent triage on SCC findings, the runtime service account also needs read-only access in the Pub/Sub delivery project for audit log and IAM lookups. Guided setup creates or reuses this runtime identity, prefers keyless WIF on Vercel, and grants `roles/logging.viewer` and `roles/iam.securityReviewer` on that project. For manual setup, first connect GCP runtime credentials in Clarion, then grant those same read-only roles.
The Google account used for guided setup needs permission to create Pub/Sub resources in the delivery project and manage SCC notification configs at the selected SCC scope.
# Google Workspace
Source: https://docs.cantina.security/clarion/integrations/google-workspace
Connect Google Workspace Alert Center to Clarion for real-time security alert ingestion and AI-powered triage.
This guide walks you through connecting Google Workspace Alert Center to Clarion. Once configured, Clarion receives workspace security alerts (suspicious logins, data exfiltration, device compromises, etc.) in real time and can triage and respond using AI agents.
## Setup Options
There are two ways to set up the integration:
![]()
1. **Automated Setup** — Navigate to the Integrations section and use the automated setup flow. This requires an existing GCP project and admin permissions.
2. **Manual Setup** — Follow the step-by-step instructions below to configure the integration manually.
![]()
The manual setup has three parts:
1. **GCP Project & Service Account** (shared prerequisite)
2. **Alert Center > Pub/Sub > Clarion webhook** (inbound alerts)
3. **Admin SDK agent tools** (optional — user lookup, suspend, revoke tokens, etc.)
No environment variables or code changes are needed — everything is configured per-workspace via the Clarion UI.
**Estimated time:** 20-30 minutes. You will need **GCP Project Admin** access and **Google Workspace Super Admin** access.
***
## Part 1: GCP Project & Service Account
### Step 1: Create a Google Cloud Project (or use existing)
1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Click the project selector dropdown at the top > **New Project**
3. Enter a project name, select your organization > **Create**
4. Note your **Project ID** (e.g. `clarion-workspace`)
### Step 2: Enable Required APIs
In **APIs & Services > Library**, search for and enable each of these:
* **Google Workspace Alert Center API** (`alertcenter.googleapis.com`)
* **Cloud Pub/Sub API** (`pubsub.googleapis.com`)
* **Gmail API** (`gmail.googleapis.com`) — required for email investigation agent tools
### Step 3: Create a Service Account
1. Go to **IAM & Admin > Service Accounts** > **Create Service Account**
2. Name: e.g. `clarion-pubsub-push`
3. Click **Create and Continue** > **Done** (no roles needed)
4. Click the new service account > **Keys** tab > **Add Key** > **Create new key** > **JSON**
5. Save the downloaded JSON file — you'll need it for the Alert Center configuration script (Part 2) and optionally for Clarion Admin SDK credentials (Part 3)
6. Note the service account email (e.g. `clarion-pubsub-push@your-project.iam.gserviceaccount.com`)
**Org policy note:** If your organization enforces `iam.disableServiceAccountKeyCreation`, you'll need to temporarily disable it:
1. Go to **IAM & Admin > Organization Policies**
2. Search for `iam.disableServiceAccountKeyCreation`
3. Click it > select **Override parent's policy** > set to **Not enforced** > **Set policy**
4. Create the key
5. **Re-enable the policy** by switching back to **Inherit parent's policy**
***
## Part 2: Inbound Alerts (Alert Center via Pub/Sub)
### Step 1: Create a Pub/Sub Topic
1. Go to **Pub/Sub > Topics > Create Topic**
2. Name it (e.g. `clarion-alerts`, full name: `projects/YOUR_PROJECT/topics/clarion-alerts`)
3. Click **Create**
4. On the topic page, go to the **Permissions** tab > **Grant Access**
5. Add principal: `alerts-api-push-notifications@system.gserviceaccount.com`
6. Role: **Pub/Sub Publisher**
7. Click **Save**
This is a Google-managed service account that the Alert Center uses internally to publish alerts into Pub/Sub. Without this permission, alert delivery to the topic will be rejected.
### Step 2: Enable Domain-Wide Delegation
The Alert Center API is a Google Workspace API (not a standard GCP API), so configuring it requires domain-wide delegation. This same delegation is reused by Part 3 (Admin SDK tools) if you set that up later.
1. Go to **IAM & Admin > Service Accounts** and click the service account from Part 1
2. Expand **Advanced settings**
3. Under **Domain-wide Delegation**, click **Edit** and enable **Google Workspace Domain-wide Delegation**
4. Note the **Client ID** (numeric, e.g. `107729743480716689292`)
### Step 3: Grant the Alert Center Scope in Google Workspace Admin Console
1. Go to [Google Workspace Admin Console](https://admin.google.com) as a **Super Admin**
2. Navigate to **Security > Access and data control > API controls**
3. Click **Manage Domain Wide Delegation**
4. Click **Add new**
5. Enter:
* **Client ID**: the numeric client ID from Step 2
* **OAuth Scopes**: `https://www.googleapis.com/auth/apps.alerts`
6. Click **Authorize**
**Both sides are required.** Enabling delegation on the service account (Cloud Console) says "I want to use delegation." Authorizing the client ID with scopes (Admin Console) says "I allow this service account to use these scopes." Both must be configured or delegation calls will fail with `unauthorized_client`.
**Propagation delay:** Changes can take up to 24 hours to propagate, though they typically take effect within a few minutes. If you get `unauthorized_client` errors immediately after setup, wait 2-3 minutes and retry.
### Step 4: Configure Alert Center to Publish to Pub/Sub
There is no UI for this step — it requires the Alert Center API. Save the following as `alert_setup.py` and run it in Google Cloud Shell or locally:
```python theme={null}
import json, urllib.request, urllib.error
from google.oauth2 import service_account
from google.auth.transport.requests import Request
creds = service_account.Credentials.from_service_account_file(
'/path/to/your-service-account-key.json',
scopes=['https://www.googleapis.com/auth/apps.alerts'],
subject='admin@yourdomain.com' # Must be a Super Admin
)
creds.refresh(Request())
req = urllib.request.Request(
'https://alertcenter.googleapis.com/v1beta1/settings',
method='PATCH',
headers={
'Authorization': 'Bearer ' + creds.token,
'Content-Type': 'application/json'
},
data=json.dumps({
"notifications": [{
"cloudPubsubTopic": {
"topicName": "projects/YOUR_PROJECT_ID/topics/clarion-alerts",
"payloadFormat": "JSON"
}
}]
}).encode()
)
try:
resp = urllib.request.urlopen(req)
print(resp.status, resp.read().decode())
except urllib.error.HTTPError as e:
print(f"Error {e.code}: {e.read().decode()}")
```
Replace:
* `/path/to/your-service-account-key.json` with the path to your service account JSON key
* `admin@yourdomain.com` with your Super Admin email
* `YOUR_PROJECT_ID` with your Google Cloud project ID
A successful response looks like:
```json theme={null}
{"notifications":[{"cloudPubsubTopic":{"topicName":"projects/YOUR_PROJECT/topics/clarion-alerts","payloadFormat":"JSON"}}]}
```
**Why not `gcloud` CLI?** The `gcloud auth print-access-token` command stamps tokens with the `cloud-platform` scope, which covers most Google Cloud APIs. But the Alert Center API is a **Google Workspace API** that requires the `apps.alerts` scope — and gcloud has no flag to request it. The Python script uses the same service account key but explicitly requests the correct scope.
### Step 5: Connect Clarion
1. Open Clarion > Integrations > Google Workspace
2. Select which alert severities to ingest
3. Click **Connect** — this creates the integration
4. Copy the generated **Webhook URL** and **OIDC Audience** — you'll need them for the next step
### Step 6: Create a Pub/Sub Push Subscription
1. Go to **Pub/Sub > Subscriptions > Create Subscription**
2. Configure:
* **Subscription ID**: e.g. `clarion-alerts-push`
* **Topic**: select the topic from Step 1
* **Delivery type**: **Push**
* **Endpoint URL**: paste the webhook URL from Clarion
* **Enable authentication**: toggle on
* **Service account**: select the service account from Part 1
* **Audience**: enter the OIDC Audience from Clarion. If you did not customize the audience, this is the same as the webhook URL.
* **Message retention**: 7 days (default)
* **Acknowledgement deadline**: 30 seconds
3. Click **Create**
4. Copy the subscription's full resource name, for example `projects/YOUR_PROJECT_ID/subscriptions/clarion-alerts-push`
5. Return to Clarion and save:
* **Pub/Sub OIDC signer service account**: the service account email from Part 1
* **Pub/Sub subscription resource**: the full subscription resource name from this step
* **OIDC signer client ID**: optional, but recommended if you have the numeric client ID
Clarion rejects Google Workspace Pub/Sub deliveries until the OIDC signer service account and full subscription resource are saved. If Clarion shows **Action required: reconnect Pub/Sub delivery**, enter the existing subscription details from Google Cloud or rerun guided setup to refresh the Pub/Sub delivery configuration.
If you get a permission error on the service account, grant your user the `iam.serviceAccounts.actAs` permission on that service account.
### Step 7: Verify
* Check **Admin Console > Security > Alert Center** for existing alerts
* Verify issues appear in Clarion — Pub/Sub will retry delivery if the webhook returns a non-2xx status
* Most security alerts (suspicious login, leaked password, phishing) are on by default. Custom alerts (DLP violations, activity rules) require additional rule configuration in the Admin Console.
***
## Part 3: Admin SDK Agent Tools (Optional)
This enables Clarion's AI agents to look up users, suspend accounts, revoke OAuth tokens, investigate emails, and more. It uses the same service account and delegation from Part 2 — you just need to add the Admin SDK and Gmail scopes.
### Step 1: Add Admin SDK and Gmail Scopes
1. Go to [Google Workspace Admin Console](https://admin.google.com) as a **Super Admin**
2. Navigate to **Security > Access and data control > API controls**
3. Click **Manage Domain Wide Delegation**
4. Find the existing entry for your service account's Client ID (added in Part 2, Step 2)
5. Click **Edit** and update the OAuth Scopes to include all six (comma-separated, no spaces):
```
https://www.googleapis.com/auth/apps.alerts,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.modify
```
6. Click **Authorize**
**Gmail scopes**: `gmail.readonly` enables the agent to search and read emails during investigation. `gmail.modify` enables trashing malicious emails. Both scopes use domain-wide delegation to impersonate the affected user's mailbox — the service account does not need direct mailbox access.
**Propagation delay:** Scope changes can take up to 24 hours to propagate, though they typically take effect within a few minutes.
### Step 2: Upload Credentials in Clarion
1. In the Clarion integration settings, go to the **Agent Tools (Admin SDK)** tab:
* Enter the **Super Admin Email** (e.g. `admin@yourdomain.com`) — this is the account the service account will impersonate
* Upload the **JSON key file** from Part 1, Step 3
2. Click **Save**
### Step 3: Verify
* When an issue is opened and triggers an agent, the agent should be able to use Google Workspace tools (user lookup, suspend, etc.)
* You can test by ensuring the service account can impersonate the admin: if credentials are wrong, agent tool calls will fail with auth errors
***
## Troubleshooting
### `Request had insufficient authentication scopes`
The token doesn't include the required scope. This happens when using `gcloud auth print-access-token` for Workspace APIs. Use the Python script method (Part 2, Step 4) which explicitly requests the correct scope.
### `unauthorized_client: Client is unauthorized to retrieve access tokens using this method`
Domain-wide delegation is not configured correctly. Verify both:
1. **Cloud Console**: Service account has domain-wide delegation enabled (Advanced settings)
2. **Admin Console**: Client ID is authorized with the required scopes (Security > API controls > Domain-wide Delegation)
If both are set, wait a few minutes for propagation and retry.
### `Service account key creation is disabled`
Your organization enforces `iam.disableServiceAccountKeyCreation`. See the note in Part 1, Step 3 for how to temporarily override this policy.
### `Google Workspace Alert Center API has not been used in project ... before or it is disabled`
Enable the Alert Center API in **APIs & Services > Library**. Search for "Google Workspace Alert Center API" and click **Enable**.
***
## Summary Checklist
| Task | Where |
| - | - |
| Create Google Cloud project | Google Cloud Console |
| Enable Alert Center + Pub/Sub + Gmail APIs | Google Cloud Console |
| Create service account with JSON key | Google Cloud Console |
| Create Pub/Sub topic with Alert Center publisher permission | Google Cloud Console |
| Enable domain-wide delegation on service account | Google Cloud Console (service account Advanced settings) |
| Authorize `apps.alerts` scope in Admin Console | Google Workspace Admin Console |
| Configure Alert Center to publish to topic | Python script |
| Connect integration in Clarion + create monitor | Clarion UI |
| Create push subscription with OIDC auth | Google Cloud Console |
| (Optional) Add Admin SDK + Gmail scopes in Admin Console | Google Workspace Admin Console |
| (Optional) Upload service account credentials in Clarion | Clarion UI |
# Grafana
Source: https://docs.cantina.security/clarion/integrations/grafana
Connect Grafana to Clarion to receive alerting notifications for AI-powered triage and response.
This guide walks you through connecting Grafana to Clarion. Grafana's unified alerting system sends webhook notifications to Clarion, where AI agents triage and respond to your infrastructure and application alerts.
**Estimated time:** 5-10 minutes. You will need access to your **Grafana instance** (with Alerting permissions) and a **Clarion workspace**.
## Prerequisites
* A **Grafana** instance (self-hosted or Grafana Cloud) with unified alerting enabled
* Alerting admin or editor permissions in Grafana
* A **Clarion workspace** with the Grafana integration available
***
## Step 1 — Create a monitor in Clarion
1. In Clarion, go to **Settings > Integrations**
2. Find **Grafana** and click **Add Monitor**
3. After you select the default severities Clarion generates a **webhook URL** and a **webhook secret** (Bearer token)
4. Copy both values — you'll need them in the next steps
Copy the webhook secret immediately — it is only displayed once. If you lose it, you'll need to regenerate the monitor.
***
## Step 2 — Create a contact point in Grafana
1. In your Grafana instance, navigate to **Alerting > Contact points**
2. Click **+ Create contact point**
![]()
3. Configure the contact point:
* **Name**: Give it a descriptive name (e.g. `Clarion`)
* **Integration type**: Select **Webhook**
* **URL**: Paste the webhook URL from Clarion
* **HTTP Method**: Leave as `POST`
* **Authorization Header — Credentials**: Paste the webhook secret from Clarion
![]()
Setting the **Credentials** field in the Authorization Header section causes Grafana to send the secret as a `Bearer` token in the `Authorization` header, which is how Clarion authenticates incoming requests.
4. Click **Save contact point**
***
## Step 3 — Route alerts to the Clarion contact point
You can route alerts to Clarion by updating your **notification policy** or by adding Clarion as a contact point on individual alert rules.
### Option A — Default notification policy
1. Go to **Alerting > Notification policies**
2. Edit the **default policy** (or create a nested policy)
3. Set the **Contact point** to the Clarion contact point you created
4. Save the policy
### Option B — Per-rule contact point
1. Go to **Alerting > Alert rules**
2. Open the alert rule you want to forward to Clarion
3. In the **Notifications** section, override the contact point and select the Clarion contact point
4. Save the rule
Repeat for each alert rule you want Clarion to receive.
***
## Severity mapping
Clarion maps the `severity` label from your Grafana alerts to its own severity levels:
| Grafana `severity` label | Clarion severity |
| - | - |
| `critical` | Critical |
| `high` | High |
| `warning`, `medium` | Medium |
| `low`, `info`, `informational` | Low |
| *(missing or unrecognized)* | Medium |
To control how Clarion prioritizes your alerts, add a `severity` label to your Grafana alert rules (e.g. `severity = critical`). If no severity label is present, alerts default to **Medium**.
***
## What happens next
Once configured, Clarion will automatically:
* Receive alerts from Grafana in real time via the webhook
* Parse alert metadata including labels, annotations, dashboard links, and panel URLs
* Triage incoming alerts using AI agents and surface actionable insights
# Guardrail
Source: https://docs.cantina.security/clarion/integrations/guardrail
Connect Guardrail to Clarion to receive Guard alerts for AI-powered triage and response.
This guide walks you through connecting your Guardrails account to Clarion. The setup involves creating a webhook-based Response Channel in Guardrails and linking it to a Clarion monitor.
**Estimated time:** 5-10 minutes. You will need access to your **Guardrails dashboard** and **Clarion workspace**.
The Clarion integration wizard generates the webhook URL and signing secret for you. Keep the wizard open alongside your Guardrails dashboard.
## Prerequisites
* Access to your **Guardrails** dashboard with permissions to create Response Channels
* A **Clarion workspace** with the Guardrails integration wizard open
***
## Part 1: Create the Webhook Response Channel in Guardrails
### Step 1 — Open the Responses menu
1. Log in to your **Guardrails** dashboard
2. Open the **Responses** menu and click **Create new response channel**
![]()
### Step 2 — Select Webhook as the channel type
1. Under **Create response channel**, select **Webhook** as the channel type
![]()
***
## Part 2: Configure the Webhook in Clarion
### Step 3 — Create a new monitor in Clarion
1. In Clarion, go to **Integrations**
2. Navigate to **Guardrails** and click **Create a new monitor**
### Step 4 — Connect the webhook URL
1. Copy the **Webhook URL** generated by the Clarion integration wizard
2. In Guardrails, paste this URL into the webhook configuration for your new Response Channel
3. Click **Add webhook integration**
### Step 5 — Add the signing secret
1. In Guardrails, copy the **Signing Secret** displayed after adding the webhook
2. In Clarion, paste this value into the **HMAC Key** field
Make sure you copy the signing secret exactly — this is used to verify that incoming webhooks are authentic.
### Step 6 — Finish creating the Response Channel
1. Complete the remaining fields and save the Response Channel in Guardrails
***
## Part 3: Assign the Response Channel to Your Guards
### Step 7 — Assign to Guards
1. Once the Response Channel is created, click **Assign to Guards**
![]()
2. From the list, select the Guards you want to send alerts to Clarion for
***
## What happens next
Once configured, Clarion will automatically:
* Receive alerts from Guardrails in real time via the webhook
* Analyze and triage incoming Guard events using AI agents
* Surface actionable insights and recommended responses
# Halo
Source: https://docs.cantina.security/clarion/integrations/halo
Connect Halo (HaloPSA) to Clarion so agents can triage the tickets your service desk raises, and search, create, update, close, and comment on Halo tickets during investigations.
This guide walks you through connecting your Halo (HaloPSA / HaloITSM) instance to Clarion. Once connected, Clarion agents can call Halo's REST API on your behalf to look up existing tickets, open new ones, update and close them, and add comments as part of an investigation.
**Estimated time:** 5 minutes. You will need **Halo administrator** access to register an API application.
## Prerequisites
* A **Halo** instance and administrator access to **Configuration → Integrations → Halo API**
* The ability to create a **Client Credentials** application in Halo
* A **Clarion workspace** with the Halo integration page open
***
## Step 1 — Register a Client Credentials application in Halo
1. Sign in to Halo as an administrator.
2. Go to **Configuration → Integrations → Halo API**.
3. Select **Authorise a new application**.
4. Choose **Client Credentials** as the authentication method.
5. Copy the generated **Client ID** and **Client Secret**.
Copy the Client Secret immediately and store it securely — Halo may only show it once. Consider using a dedicated service application rather than one tied to a personal account.
6. On the application's **Permissions** tab, grant the permissions needed to read and create tickets (for example, the ticket read/write scopes, or `all`).
7. If you use a **hosted** Halo solution, note your **Tenant** identifier and your **Authorisation server URL** from the same **Halo API** page — you may need them in the next step.
***
## Step 2 — Enter credentials in Clarion
1. In Clarion, open **Integrations** and find **Halo (HaloPSA)** under Development & Planning.
2. Enter your **Halo URL** — your web-app base address, e.g. `https://acme.halopsa.com`. Clarion derives the REST API (`/api`) and authorisation server (`/auth`) from it.
3. Paste the **Client ID** and **Client Secret** from Halo.
4. **Hosted solutions only:** enter your **Tenant**, and an **Authorisation server URL** if it differs from your Halo URL.
5. Click **Connect**.
Clarion verifies the credentials by requesting an access token and making a lightweight ticket query before saving. If the credentials or URL are wrong, you'll see a clear error and nothing is persisted.
***
## Step 3 — Ingest tickets with a Halo monitor (optional)
Steps 1 and 2 let agents *act* on Halo. This step lets Halo *start* the work: a webhook sends tickets to Clarion, and filters you control decide which of them an agent triages.
**Add the monitor.**
1. In Clarion, open **Integrations → Halo (HaloPSA) → Monitors** and click **Add Monitor**.
2. Pick **Halo**. Clarion generates a webhook URL and a one-time password — copy both now, the password is not shown again.
**Add the webhook in Halo.**
1. Go to **Configuration → Integrations → Webhooks** and create a new webhook.
2. Set **Webhook type** to **Standard webhook**, **Method** to **POST**, and paste the Clarion URL as the **Payload URL**.
3. Set **Authentication** to **Basic Authentication**, with the username `clarion` and the one-time password as the password.
Halo has no custom-header field, so Basic Authentication is how a delivery proves it came from your instance. Clarion rejects any delivery without it. Never put the password in the payload URL.
4. Under **Events**, add the event profile Clarion should see — for example **New Ticket Logged**. Each event's own conditions decide which tickets are sent, so start narrow: a webhook that fires on every ticket sends your whole service-desk volume to Clarion.
5. Leave the payload on **Full object with linked objects** and save.
Clarion only needs the ticket id from the delivery — it reads the summary, details, status, priority, client, and assigned agent back through the credentials from Step 2, so what an agent sees is the current ticket rather than a snapshot of whatever the payload carried. The smaller payload shapes work too, and the whole delivery is kept on the signal either way so you can see exactly what Halo sent.
**Name the event so filters can match it.**
Halo's built-in payload shapes do not say which event profile fired, so every delivery arrives as the generic event type `halo_ticket`. To route on the event, switch the payload to **Custom payload** and add an `event` field naming the profile:
```json theme={null}
"event": "new ticket logged"
```
Clarion lowercases it and replaces the spaces, so a filter matches the event type `new_ticket_logged`. Keep the ticket id in the body alongside it — that is the one field the read-back needs.
A `link`, `url`, or `permalink` field in the payload is carried onto the issue too, so an agent can open the ticket in one click. Clarion only honours it when it points at your own Halo instance — the body is public once the webhook URL leaks, and an off-host URL on an issue is a phishing risk.
A `…/ticket?id=N` link also tells Clarion *which* ticket to read back, which is worth knowing: Halo prepends its own `id` for the delivery row to every payload, so a custom payload whose only other identifier is that bare `id` would otherwise be matched to the wrong ticket. A link, an `object_id`, or a `ticket_id` all resolve it unambiguously — include one of them.
The value is literal text, not a variable, so it describes whichever profile *this* webhook fires on. Create one webhook per event profile — one for **New Ticket Logged** sending `"event": "new ticket logged"`, another for **Ticket Reassigned** sending `"event": "ticket reassigned"` — rather than one webhook subscribed to several.
**Choose what opens an issue.**
Each delivery becomes a *signal*. A new monitor starts with an **All Halo tickets** filter, so every delivery opens a Clarion issue out of the box. Narrow it by editing that filter or adding your own — conditions can match `ticket.priority`, `ticket.client`, `ticket.type`, `ticket.category`, or any field on the delivered payload, and a filter's event type matches the `event` you named above.
Halo priorities are configured per instance. When a ticket's priority is one of Halo's defaults (Critical, High, Medium, Low), Clarion maps it onto the issue's severity; otherwise the monitor's **Default severity** applies. To route a renamed priority, add a filter that matches `ticket.priority` directly.
***
## What agents can do
Once connected, agents on this workspace gain access to the `/halo` action, which exposes these tools:
| Tool | What it does |
| - | - |
| `search_tickets` | Search tickets, optionally filtered by a free-text query, open/closed state, client, or agent |
| `get_ticket` | Fetch a single ticket's details by its numeric ID |
| `create_ticket` | Open a new Halo ticket with a summary and details |
| `update_ticket` | Change an existing ticket's summary, details, status, priority, assigned agent, client, or type |
| `close_ticket` | Close a ticket by running your instance's own closing action, with an optional closing note |
| `add_comment` | Add a note/action to an existing ticket (private by default, or visible to the end user) |
| `list_statuses` | List the ticket statuses configured on your instance, with their IDs and whether each counts as closed |
| `list_clients` | List the clients (end-customers) on your instance, with their IDs, optionally filtered by name |
| `list_agents` | List the agents (technicians) on your instance, with their IDs, optionally filtered by name, team, or client access |
| `list_actions` | Read a ticket's history — the notes, replies, and actions already recorded on it |
| `list_outcomes` | List the actions your instance can perform on a ticket, including which status each moves it to |
| `execute_action` | Perform one of those actions on a ticket, running whatever workflow the outcome carries |
`create_ticket`, `update_ticket`, `close_ticket`, `add_comment`, and `execute_action` write to Halo, so they require human approval before they run — you stay in control of when a ticket is actually changed. `search_tickets`, `get_ticket`, `list_actions`, `list_outcomes`, `list_statuses`, `list_clients`, and `list_agents` are read-only. Approval policies are managed in **Settings → Tools**.
Work in Halo happens through **actions**: applying an outcome is what runs a workflow, moves the status, holds the SLA, and sends notifications. `execute_action` exposes that directly, and `list_outcomes` tells the agent which outcomes your instance configures, which of them close a ticket, and which send an email.
Outcomes that email a recipient they don't name need care: Halo asks for an "Email To" when the action is posted, and choosing who gets mailed is a notification decision rather than a ticket edit. Run the action with `sendEmail` false to apply the outcome without sending its email — nothing is mailed, so no recipient has to be chosen — or set that outcome's **Email To** in Halo. `close_ticket` suppresses the email automatically when its closing outcome needs a recipient, and says so in the result.
`close_ticket` is the same mechanism with the outcome chosen for you: it applies your instance's own closing action, so the closure workflow fires rather than the status being edited behind Halo's back. The outcome decides the resulting status — which may be a pending-closure one — and the result reports the ticket as Halo left it. Pass an explicit status ID to skip the workflow and set one specific status instead; that is also the fallback on an instance where no outcome closes. A closing note is recorded either way — the closing action carries it, and the direct-status path records it as a private note.
`add_comment` is retry-safe: if the ticket's most recent note is already identical, it returns that note instead of posting a duplicate. Halo requires every action to carry an outcome, so the note is posted with your instance's own private- or public-note outcome depending on the visibility you asked for.
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Halo (HaloPSA)**.
2. Click **Disconnect**.
This deletes the stored credentials. Agents on this workspace will no longer see the `/halo` action, and any saved skills that reference it will surface the integration as missing until you reconnect.
***
## Troubleshooting
### "Halo rejected the client credentials"
The Client ID or Secret is wrong, the application is not set to the **Client Credentials** method, or it lacks ticket permissions. Re-check the application in **Configuration → Integrations → Halo API**.
### "Halo returned 404"
The Halo URL is likely wrong. Use your web-app base URL (e.g. `https://acme.halopsa.com`), not the `/api` or `/auth` path. For hosted solutions, confirm your **Tenant** and **Authorisation server URL**.
### No issues appearing from the webhook
Confirm the Halo monitor exists and is attached to an agent, that the webhook's events actually match the tickets you expect, and that the monitor's filters have not narrowed everything away.
### Deliveries rejected
Check the webhook's **Authentication** in Halo. It must be **Basic Authentication** with the one-time password as the password — not None, and not the password pasted into the payload URL. If you have lost the password, rotate it on the monitor and set the new one in Halo.
### Tickets arrive without a summary or detail
Clarion could not read the ticket back through the API, so it ingested the delivered payload instead — the issue's description shows exactly what arrived. Check that the integration is still connected and that the webhook's payload carries the ticket id.
# Hexagate
Source: https://docs.cantina.security/clarion/integrations/hexagate
Connect Hexagate to Clarion to receive on-chain monitor alerts for AI-powered triage and response.
This guide walks you through connecting your Hexagate account to Clarion. The setup involves adding a Clarion webhook to your Hexagate monitors so that alerts are forwarded automatically.
**Estimated time:** 5-10 minutes. You will need access to your **Hexagate dashboard** and **Clarion workspace**.
The Clarion integration wizard generates the webhook URL for you. Keep the wizard open alongside your Hexagate dashboard.
## Prerequisites
* Access to your **Hexagate** dashboard with permissions to manage Monitors
* A **Clarion workspace** with the Hexagate integration wizard open
***
## Part 1: Get the Webhook URL from Clarion
### Step 1 — Open the Clarion integration wizard
1. In Clarion, go to **Integrations**
2. Navigate to **Hexagate** and start the setup wizard
3. Copy the **Webhook URL** generated by Clarion — you will need this in the next steps
***
## Part 2: Add the Webhook to a Hexagate Monitor
### Step 2 — Open Hexagate and navigate to your Monitors
1. Log in to your **Hexagate** dashboard
2. Navigate to **Monitors**
![]()
### Step 3 — Open a monitor you want to connect
1. Select one of your existing monitors
2. Navigate to the **Actions** step within the monitor configuration
### Step 4 — Add the Clarion webhook channel
1. Click **Add a new channel**
![]()
2. Select **Webhooks** as the channel type
3. Paste the **Webhook URL** you copied from the Clarion wizard
![]()
4. Add it to the monitor
**Important:** Make sure you paste the webhook URL exactly as provided by Clarion — any extra spaces or missing characters will prevent alerts from being delivered.
***
## Part 3: Assign the Webhook to Additional Monitors
### Step 5 — Repeat for each monitor
1. For every additional monitor you want to send alerts to Clarion, open the monitor and navigate to **Actions**
2. Select the **Clarion webhook** you created in Step 4 from the available channels
3. Save the monitor
You only need to create the webhook channel once. After that, you can select it from the channel list on any monitor.
***
## What happens next
Once configured, Clarion will automatically:
* Receive alerts from Hexagate in real time via the webhook
* Analyze and triage incoming monitor events using AI agents
* Surface actionable insights and recommended responses
Hexagate **Info**-severity events are mapped to **Low**-severity issues in Clarion. If you do not want these events to open issues, disable **Low** severity for the Hexagate monitor. This also suppresses Hexagate **Low**-severity events, since both map to Clarion **Low**.
# Huntress
Source: https://docs.cantina.security/clarion/integrations/huntress
Connect Huntress to Clarion for endpoint detection and response (EDR) data enrichment during issue triage.
This guide walks you through connecting your Huntress account to Clarion. Huntress provides endpoint detection and response (EDR) data that Clarion uses to enrich issue triage with real endpoint intelligence.
**Estimated time:** 5 minutes. You will need **Huntress Admin** access.
## Prerequisites
* Access to your **Huntress Dashboard** as an admin
* A **Clarion workspace** with the Huntress integration wizard open
***
## Step 1 — Generate API Credentials in Huntress
1. In the Huntress dashboard, click the **menu button** in the upper-right corner.
![]()
2. Select **API Credentials**.
3. In the **User API Credentials** section, click **Add**.
![]()
4. Select the appropriate user and copy the generated **API Key** and **API Secret**
Copy the API Secret immediately — it will only be shown once. Store it securely.
***
## Step 2 — Enter Credentials in Clarion
1. In Clarion, open the **Huntress integration** from your workspace settings
2. Paste the **API Key** and **API Secret** from Huntress
3. Click **Connect** to activate the integration
Clarion checks the credentials against Huntress before saving them, so a mistyped key or secret is reported straight away instead of failing quietly later.
***
## Step 3 — Choose the organization
Huntress only issues API credentials at the account level. If you are an MSP, that means a single key can read every client organization in your account — so Clarion asks which one this workspace represents.
1. In the connected **Huntress integration**, find the **Organization** section.
2. Open the picker and **search by the client's name** as it appears in Huntress. The list is not ordered to match your Clarion workspace names, so searching is usually faster than scrolling.
3. Select the organization and click **Save**.
Once an organization is set, Clarion restricts everything Huntress-related to that client: incident polling, webhook events, and the Huntress data available to triage agents.
If you are a direct Huntress customer rather than an MSP, leave this set to **Entire account (all organizations)** — the default.
Changing the organization restarts ingestion for the new scope, picking up its currently open incidents. Issues already created for the previous organization are left untouched.
***
## Step 4 — Set up webhook alerts (optional)
Webhooks let Huntress push **Incident Reports** and **Escalations** to Clarion in real time, where they become issues and flow through automated triage.
Configuring webhooks in Huntress requires the **account admin** role.
1. In Clarion, open the connected **Huntress integration** and find the **Webhook alerts** section. Copy the **Webhook URL**.
2. In the Huntress dashboard, go to **Integrations → Add an Integration → Webhooks** and click **Add Endpoint**.
3. Paste the Clarion **Webhook URL** as the destination URL.
4. Enable only the **Incident Reports** and **Escalations** categories.
5. Open the endpoint's **⋯** menu and choose **View Signing Secret**. Copy it.
6. Back in Clarion, paste the signing secret into the **Signing secret** field and click **Save**.
7. In Huntress, use the endpoint's **Send Test** option to confirm Clarion receives deliveries.
***
## What happens next
Once configured, Clarion will (within the organization you selected):
* Query Huntress for endpoint data during triage (e.g. matching IP addresses to known managed endpoints)
* Use EDR context to validate or dismiss suspicious sign-in alerts from other integrations (e.g. Okta)
* Provide agents with visibility into which devices are protected and their current status
* Turn incoming **Incident Report** and **Escalation** webhooks into issues and run automated triage on them (if webhooks are configured)
# Hypernative
Source: https://docs.cantina.security/clarion/integrations/hypernative
Connect Hypernative to Clarion for on-chain threat monitoring and AI-powered alert triage.
This guide walks you through connecting Hypernative to Clarion. Hypernative monitors on-chain threats and protocol risks — once connected, its alerts flow into Clarion for AI-powered triage and incident response.
**Estimated time:** 5-10 minutes. You will need access to your **Hypernative dashboard** and a **Clarion workspace**.
## Prerequisites
* Access to your **Hypernative dashboard** with permission to manage Actions and Custom Agents
* A **Clarion workspace** with the Hypernative integration available
***
## Step 1 — Generate the webhook URL and header secret in Clarion
1. In Clarion, open the agent that should triage Hypernative alerts
2. Add a **Hypernative** monitor in the agent's **Monitors** section
3. Clarion generates a **webhook URL** and a **Clarion binding header secret** for that monitor
4. Copy both values exactly as shown — you'll need them in the next step
The Clarion binding header secret is shown only during setup or after rotating it. Do not put the secret in the webhook URL.
***
## Step 2 — Create a webhook Action in Hypernative
1. In the Hypernative dashboard, go to **Actions**
![]()
2. Click **Add action**
3. Select **Webhook** as the action type
![]()
4. Configure the action:
* **Name**: Give it a descriptive name (e.g. `Clarion Webhook`)
* **URL**: Paste the webhook URL from Clarion
* **Request header**: Add `X-Clarion-Webhook-Secret` with the Clarion binding header secret from Clarion
5. Click **Save**
**Important:** Do not use the "Send test alert" button — Hypernative does not send test alerts for webhook action types.
***
## Step 3 — Attach the Action to your Custom Agents
1. In Hypernative, go to **Custom Agents**
2. For each agent you want to send alerts to Clarion, click to edit it
3. Add the newly created webhook Action to the agent's action list
![]()
4. Save the agent
Repeat for all agents whose alerts you want Clarion to receive.
***
## Step 4 — Attach the Action to your Watchlists
1. In Hypernative, go to **Watchlists**
2. Open each watchlist and add the Clarion webhook to Actions under the **Configure Alert Policy**
![]()
3. Navigate to Actions, and configure the webhook
![]()
***
## Step 5 — Verify the integration
Since Hypernative doesn't support test webhooks, use **Alert Replay** to verify:
1. Go to **Risk Insights > Alerts** in Hypernative (alternatively you can replay alerts from a Watchlist > Alerts as well)
2. Remove the default date filter to see recent historical alerts
3. Open any recent alert, make sure it was triggered from Watchlists
4. Click **Alert Replay** to re-trigger the alert
![]()
**Important:** Alert replay is only available for **Watchlists** and not for **Custom agents**.
**Caution:** Alert Replay triggers the alert across **all** configured action destinations and notification channels — not just Clarion. Make sure you're okay with that before replaying.
5. Check the Clarion **Issues** page — the replayed event should show up within a few seconds
# incident.io
Source: https://docs.cantina.security/clarion/integrations/incident-io
Connect incident.io to Clarion so agents can create alerts in incident.io and use its incident-management tools during triage.
This guide walks you through connecting incident.io to Clarion. Once connected, agents can create alerts in incident.io — handing them off to your on-call and escalation policies — and, optionally, use incident.io's incident-management tools (incidents, alerts, on-call schedules, escalations) to investigate during triage.
**Estimated time:** 5 minutes. You'll need permission to create an **HTTP alert source** in incident.io, and (optionally) an **API key** for the incident-management tools.
## Prerequisites
* An **incident.io** account with permission to manage alert sources
* A **Clarion workspace** with the incident.io integration page open
***
## Step 1 — Create an HTTP alert source in incident.io
For each destination Clarion should be able to raise alerts on:
1. In incident.io, go to **Alerts → Alert sources**.
2. Create a new **HTTP** alert source and give it a recognisable name, for example *Clarion — Production*.
3. Copy the **alert source config ID** shown in the source's URL and the **bearer token** incident.io generates for it.
Each alert source maps to one incident.io routing configuration. Create one per scenario if you want different alerts to follow different paths.
***
## Step 2 — Add the alert source in Clarion
1. In Clarion, open **Integrations** and find **incident.io**.
2. Under **Alert sources**, click **Add alert source**.
3. Enter a **name**, the **alert source config ID**, and the **bearer token** from Step 1.
4. Click **Connect incident.io** (or **Add alert source** if already connected).
Use the **Test** button next to a source to send a test alert and immediately resolve it, confirming the config ID and token are valid.
***
## Step 3 (optional) — Enable the incident-management tools
To let agents look up and manage incidents, alerts, on-call schedules, and escalations during triage:
1. In incident.io, create an **API key** under **Settings → API keys**.
2. In Clarion's incident.io integration page, paste the key under **MCP access** and click **Save**.
Write actions (creating or updating incidents, responding to escalations, starting analyses) always pause for human approval before they run.
***
## Using incident.io in a skill
Add the **incident.io** tools to a skill or your [agent behavior](/clarion/learn/settings#agent-behavior) so the agent can create an alert — or take other incident-management actions — when it decides, based on what it found during triage, that a situation warrants it. The incident.io alert links back to the originating Clarion issue.
# Iru
Source: https://docs.cantina.security/clarion/integrations/iru
Connect Iru to Clarion so agents can look up devices, users, applications, and vulnerabilities from your Iru tenant during issue triage.
This guide walks you through connecting your Iru tenant to Clarion. Once connected, Clarion agents can call Iru's REST API on your behalf to enrich investigations with device, user, application, and vulnerability data, and Clarion discovers your device fleet into the Brain as device assets.
**Estimated time:** 5 minutes. You will need **Iru Admin** access to your tenant and the ability to create API tokens.
## Prerequisites
* An **Iru** tenant (US or EU) with admin access to **Settings → Access**
* Your tenant API host — for example `acme.api.kandji.io` (US) or `acme.api.eu.kandji.io` (EU)
* A **Clarion workspace** with the Iru integration page open
***
## Step 1 — Create an API token in Iru
1. Sign in to your **Iru** tenant as an admin.
2. Go to **Settings → Access**.
![]()
3. Click **Add API Token**.
4. Copy the generated **API token**.
Copy the API token immediately — Iru only shows it once. Store it securely. Avoid tying the token to an admin account that may be removed; consider a dedicated service admin.
5. **Configure permissions.**
6. Grant the token the following **read** permissions:
* **Devices** (required) — list devices, fetch device details, activity, status, and installed apps
* **Users** (required) — look up users by email or ID
* **Prism** (required) — inventory queries for device information, launch agents/daemons, local users, and applications
**Devices (read)** is also what powers device discovery into the Brain — keep it granted so Clarion can sync your device fleet.
7. Grant the token the following **write** permissions under **Device Actions**:
* **Daily Check-In** — trigger an immediate MDM check-in to refresh device state
* **Lock Device** — remotely lock a managed device
* **Update Location** — request the device's current location
***
## Step 2 — Enter credentials in Clarion
1. In Clarion, open **Integrations** and find **Iru** under device management.
2. Enter your tenant **API URL**:
* US tenants: `acme.api.kandji.io`
* EU tenants: `acme.api.eu.kandji.io`
You can paste the bare hostname or a full `https://` URL — Clarion parses out the subdomain and region automatically.
3. Paste the **API token** from Iru.
4. Click **Connect**.
Clarion verifies the token by calling Iru's `/users` endpoint before saving. If the token is invalid or the URL is wrong, you'll see a clear error and nothing is persisted.
***
## What agents can do
Once connected, agents on this workspace gain access to the `/iru` action, which exposes a curated set of read-only Iru tools:
| Tool | What it returns |
| - | - |
| `list_devices` | Device summaries, optionally filtered by platform (`mac`, `iphone`, `ipad`, `appletv`) |
| `get_device_details` | Full device record — general info, hardware, network, MDM state |
| `find_devices_for_user` | Devices assigned to a given email address |
| `get_user` / `get_user_by_id` / `list_users` | Iru user lookups |
| `list_vulnerabilities` | CVEs detected on a specific device |
| `get_device_status` | Blueprint and library-item status for a device |
| `get_device_activity` | Recent activity/event stream for a device |
| `list_device_apps` | Applications installed on a single device |
| `list_audit_events` | Workspace-wide audit log events (cursor-paginated, newest first) |
| `prism_device_information` | Iru Prism — device information records |
| `prism_launch_agents_and_daemons` | Iru Prism — LaunchAgents/Daemons (macOS) |
| `prism_local_users` | Iru Prism — local OS user accounts (macOS) |
| `prism_applications` | Iru Prism — installed application inventory across devices |
***
## Device discovery into the Brain
Beyond on-demand agent lookups, Clarion discovers your device fleet into the Brain as **device** assets (name, model, platform, OS version, serial number, last check-in). When a device's assigned user matches a synced identity (Okta / Google Workspace), the device is linked to its owner — so an issue involving that user surfaces their devices as related assets.
Devices refresh on each asset sync (the manual **Sync** action or the scheduled auto-update). No extra configuration is needed beyond the **Devices** read permission granted above.
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Iru**.
2. Click **Disconnect**.
This deletes the stored credentials. Agents on this workspace will no longer see the `/iru` action, and any saved skills that reference it will surface the integration as missing until you reconnect.
***
## Troubleshooting
### "Iru returned 404 for tenant"
The tenant subdomain or region is wrong. Double-check the API host in **Iru → Settings → Access**:
* US tenants use `*.api.kandji.io`.
* EU tenants use `*.api.eu.kandji.io`.
The subdomain (e.g. `acme`) must match the prefix shown in your Iru admin URL.
# Jira
Source: https://docs.cantina.security/clarion/integrations/jira
Connect Jira Cloud to Clarion with an Atlassian service account so agents can create, look up, and search issues during triage.
This guide shows how to connect Jira Cloud to Clarion using an Atlassian service account and OAuth 2.0 client credentials.
**Estimated time:** 10-15 minutes. You need access to:
* A **Clarion workspace**
* **Atlassian Administration** for your Jira site
* A service account that can view, search, and create issues in the Jira projects you want Clarion to use
## Prerequisites
Before connecting Jira in Clarion, make sure you have:
* Your Jira site URL, for example `https://example.atlassian.net`
* A Jira service account with access to the relevant projects
* An OAuth 2.0 credential created for that service account
* These credential scopes:
* `read:jira-work`
* `write:jira-work`
Clarion uses the service account’s client credentials to request short-lived Jira access tokens automatically. You do not need to reconnect the integration just because an access token expires.
***
## Step 1 - Create a Jira service account
1. In **Atlassian Administration**, open **Directory** and create a **service account**.
2. Grant the service account access to **Jira**.
3. Make sure the service account has the Jira project permissions it needs in the projects Clarion will use.
The service account should be able to:
* Search issues
* View issue details
* Create issues in the target project
***
## Step 2 - Create OAuth 2.0 credentials for the service account
1. Open the service account in **Atlassian Administration**.
2. Go to **Credentials**.
3. Create an **OAuth 2.0** credential.
4. Grant only these scopes:
* `read:jira-work`
* `write:jira-work`
5. Copy the **Client ID** and **Client secret**.
Keep the client secret somewhere safe. You will paste it into Clarion during setup.
***
## Step 3 - Connect Jira in Clarion
1. In Clarion, go to **Integrations**.
2. Open **Jira**.
3. Enter:
* **Site URL**
* **Client ID**
* **Client Secret**
* **Default Project Key** (optional, but recommended)
4. Click **Connect Jira**.
***
## Step 4 - Verify and maintain the connection
After connecting:
1. Review the saved Jira site and client ID.
2. Set or update **Default Project Key** if you want Clarion to fall back to a project automatically.
3. Click **Save** after any changes.
4. Click **Verify Connection** to confirm Clarion can access Jira successfully.
5. Use **Disconnect** if you want to remove Jira access from the workspace.
Agents can still pass `projectKey` explicitly per tool call. If omitted, Clarion falls back to the configured default project key.
***
## How Jira tools use this integration
When Jira tools are enabled, Clarion can:
* Create issues
* Fetch issue details
* Search issues with JQL
Clarion manages Jira access tokens automatically from the stored client credentials.
***
## Troubleshooting
### "Failed to resolve Jira cloud ID"
Check that **Site URL** is exactly your Jira Cloud URL, for example:
* `https://example.atlassian.net`
Do not include a path such as `/jira`, `/projects`, or `/browse`.
### "Jira credential is missing required scopes"
Recreate or update the OAuth 2.0 credential so it includes:
* `read:jira-work`
* `write:jira-work`
### Verify Connection fails even though the credential is valid
Make sure the service account itself has Jira product access and project-level permissions in the projects Clarion needs to read or create issues in.
### "Project key is required" when creating issues
Set **Default Project Key** in the Jira integration, or pass `projectKey` directly in the Jira tool call.
# JumpCloud
Source: https://docs.cantina.security/clarion/integrations/jumpcloud
Connect JumpCloud to Clarion to ingest directory and identity events via Insights Rule webhooks and enable agent-driven investigation and response using a JumpCloud service account.
This guide explains how to connect JumpCloud to Clarion. Once configured, Clarion receives directory and identity events from JumpCloud Insights Rules through a webhook notification channel and can use a JumpCloud service account to investigate and respond to issues.
**Estimated time:** 10-15 minutes. You will need **JumpCloud Admin** access and access to the Clarion workspace where you want to connect JumpCloud.
## Prerequisites
* Access to a JumpCloud organization with permission to manage Notification Channels, Insights Rules, and Service Accounts
* Access to the Clarion workspace where you want to configure the JumpCloud integration
## Create a webhook notification channel in JumpCloud
1. Sign in to the **JumpCloud Admin Portal**.
2. Open **Settings** and navigate to the **Notification Channels** tab.
![]()
3. Select **Webhook** and click to add a new channel.
## Get the webhook URL and secret from Clarion
1. Open Clarion and go to **Integrations** > **JumpCloud**.
![]()
2. Click **Connect** to generate a webhook URL and secret for this workspace.
![]()
3. Copy the **Webhook URL** and **Secret**. You will paste these into JumpCloud in the next step.
## Configure the webhook channel in JumpCloud
1. Return to the JumpCloud Notification Channel you started creating.
2. Enter a name for the channel, for example `Clarion`.
3. Paste the **Webhook URL** from Clarion into the URL field.
4. Set the authentication type to **Token** and paste the **Secret** from Clarion as the **Auth Token**.
![]()
5. You can use **Test Webhook** to send a sample payload to Clarion. An example payload looks like:
```json theme={null}
{
"type": "user_lockout",
"tags": [
{ "key": "user_id_123", "value": "user_123" },
{ "key": "event_type", "value": "lockout" }
],
"channels": {
"channel_object_ids": ["channel_456"]
},
"organization_object_id": "org_789"
}
```
6. When the test succeeds, save the webhook channel.
## Link the channel to Insights Rules
For each Insights Rule you want to forward to Clarion:
1. Open the rule in JumpCloud.
2. Under **Actions**, add the **Clarion** webhook channel as a notification channel.
![]()
3. Click **Save**.
Clarion now receives events from the rules you linked to the Clarion webhook channel.
## Create a JumpCloud service account for agent tools
Connecting a JumpCloud service account lets Clarion agents call the JumpCloud API to investigate issues and, optionally, remediate them.
1. In the JumpCloud Admin Portal, open **Settings** and select the **Service Accounts** tab.
2. Click **Create a new service account**.
![]()
3. Name the service account `Clarion` and select a role that matches the access you want Clarion to have. To allow Clarion to remediate issues, select the **Manager** role.
![]()
4. Set the **Secret Lifetime** to **365 days**.
5. Copy the **Client ID** and **Client Secret** shown. The secret is only displayed once.
## Connect the service account in Clarion
1. In Clarion, open again the **Integrations** > **JumpCloud** integration page.
2. Paste the **Client ID** and **Client Secret** from JumpCloud.
3. Click **Save Service Account**.
Clarion can now use the JumpCloud API to support investigation and response actions on incoming issues.
## Troubleshooting
### Test webhook returns an authentication error
* Confirm the authentication type is set to **Token** in the JumpCloud webhook channel
* Confirm the **Auth Token** matches the secret shown in Clarion exactly, with no leading or trailing whitespace
* If the secret has been rotated, reconnect the integration in Clarion to generate a new secret and update the JumpCloud channel
### Issues are not arriving in Clarion
* Confirm the Clarion webhook channel is attached to each Insights Rule you want to forward
* Confirm the rule is enabled and has recently matched events in JumpCloud
* Re-run **Test Webhook** from JumpCloud to verify the channel still reaches Clarion
### Service account credentials are rejected
* Confirm the service account is active in the JumpCloud Admin Portal
* Confirm the role assigned to the service account includes the permissions required for the actions you want Clarion to perform
* If the client secret is lost or expired, generate a new secret in JumpCloud and save the new **Client ID** and **Client Secret** in Clarion
# Linear
Source: https://docs.cantina.security/clarion/integrations/linear
Connect Linear to Clarion so agents can create issues authored by the Clarion app, not by a person on your team.
This guide shows how to connect Linear to Clarion. Once connected, Clarion agents can create issues during triage. Issues are authored by **Clarion** in Linear, so they appear separate from any human team member's account.
**Estimated time:** 2 minutes. You need access to:
* A **Clarion workspace** with permission to manage integrations
* A **Linear workspace** with permission to authorize OAuth applications
## Prerequisites
* A Linear account with permission to install OAuth applications in your Linear workspace
* At least one Linear team where Clarion should create issues
***
## Step 1 - Connect Linear
1. In Clarion, open **Integrations** and find **Linear**.
2. Click **Connect Linear**. You'll be redirected to Linear to authorize Clarion.
3. Review the requested permissions in Linear, then click **Authorize**.
Linear redirects you back to Clarion with the integration connected.
Issues Clarion creates will be authored by the Clarion app in Linear, not by you personally. Linear shows the Clarion app icon next to each issue Clarion creates.
***
## Step 2 - Choose a default team (optional)
After connecting, you can pick a **default team** in the Linear integration page. When an agent creates an issue without specifying a team, Clarion uses the default. Without a default, agents must always pass an explicit team.
***
## What Clarion can do
After connecting Linear, agents can:
* **Create issues** with a title, description, and optional priority
* **Choose the Linear team** for each issue, or use the default
Clarion does not currently read or update existing issues — issue creation is one-way from Clarion to Linear.
***
## Disconnect Linear
To disconnect:
1. Open the **Linear** integration in Clarion.
2. Click **Disconnect**.
3. Confirm the dialog.
Clarion revokes its Linear access token immediately. Issues Clarion previously created remain in Linear unchanged.
# Microsoft Defender XDR
Source: https://docs.cantina.security/clarion/integrations/microsoft-defender-xdr
Poll Defender XDR security incidents from Microsoft Graph and triage them with identity-aware playbooks.
Clarion polls **Microsoft Defender XDR** incidents through the Microsoft Graph security API using app-only authentication, hydrates each incident with its constituent alerts, and routes it to the right scenario playbook.
**Estimated time:** 10 minutes. You will need a **Global Administrator** or **Privileged Role Administrator** in the Microsoft tenant to grant app-only consent.
## Prerequisites
* A Microsoft tenant with **Defender XDR** licensed and generating incidents
* Ability to grant admin consent for application permissions in Microsoft Entra ID
## Connect
1. In Clarion, open **Integrations** and find **Microsoft Defender XDR**.
2. Click **Connect** and complete the Microsoft admin-consent flow.
3. Grant the requested **application** permissions for reading security incidents and alerts.
4. Return to Clarion; the integration appears as connected and polling begins.
Only workspace admins can change the connection. Members can view the integration's state.
## What Clarion ingests
Correlated Defender XDR incidents, hydrated with their alerts so the agent sees the whole incident rather than a headline. Clarion reports **severity drift** between the incident and its alerts, and names which Microsoft products contributed.
## What agents can do
| Tool | What it returns |
| - | - |
| `list_incidents` | Defender XDR incidents, filterable |
| `get_incident` | One incident hydrated with its alerts |
## Better together with Entra
Connect [Microsoft Entra](/clarion/integrations/microsoft-entra-id) as well. With it, the Defender XDR agent can pivot a principal named in an incident through your directory — group membership, role assignments, sign-in risk — and carry out approved identity remediation. Without it, the agent reports and escalates rather than acting.
## Related agents
The [Microsoft Defender XDR](/clarion/learn/agents#our-agents) agent ships five skills: incident triage plus identity scenario playbooks for impossible travel, MFA and session hijacking, OAuth and app abuse, and admin compromise.
If you also run **Microsoft Sentinel**, use the combined [Microsoft Sentinel & Defender XDR](/clarion/learn/agents#our-agents) agent instead — it adds KQL hunting, phishing, endpoint forensics, ransomware scoping, Azure control-plane investigation, and UEBA anomaly analysis.
## Disconnect
Click **Disconnect** on the integration page. This removes the workspace's Clarion binding and any Defender XDR monitors under it. It does **not** revoke the Clarion application in your Microsoft tenant — do that from Entra ID if you want the consent removed.
# Microsoft Entra ID
Source: https://docs.cantina.security/clarion/integrations/microsoft-entra-id
Connect Microsoft Entra ID (Azure AD) to Clarion to enforce enterprise single sign-on for your organization.
This guide explains how to register an app in Microsoft Entra ID (formerly Azure AD) and connect it to Clarion. Once configured, users who sign in with a mapped email domain are required to authenticate through Microsoft Entra.
**Estimated time:** 10-15 minutes. You will need **Microsoft Entra admin** access and access to the Clarion workspace where you want to configure SSO.
## Prerequisites
* Access to the [Microsoft Entra admin center](https://entra.microsoft.com) with permission to register applications
* Access to the Clarion workspace settings as a company manager
## Register an app in Microsoft Entra ID
1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to **Identity** > **Applications** > **App registrations**.
3. Click **New registration**.
4. Enter a name (for example, `Clarion SSO`) and click **Register**.
5. On the app overview page, copy the **Application (client) ID** — you will need this in Clarion.
6. Note your **Directory (tenant) domain** shown under **Overview** (for example, `contoso.onmicrosoft.com`).
## Create a client secret
1. In your registered app, go to **Certificates & secrets**.
2. Click **New client secret**, enter a description and expiry, then click **Add**.
3. Copy the **Value** immediately — it is shown only once.
## Add the SSO connection in Clarion
1. Open Clarion and go to **Settings** > **Single Sign-On (SSO)**.
2. Click **Add Connection**.
3. Enter the following values:
* **Tenant Domain** — your Microsoft Entra tenant domain, for example `contoso.onmicrosoft.com`
* **Client ID** — the Application (client) ID from your app registration
* **Client Secret** — the secret value you copied
* **Email Domain** — the email domain whose users will be required to sign in via Entra, for example `contoso.com`
4. Click **Create Connection**.
## Verify the connection
After saving:
* The connection appears in the **Microsoft Entra / Azure AD** section of the SSO settings page showing the tenant domain, client ID, and mapped email domain.
* Users who sign up or sign in with the mapped email domain will be redirected to Microsoft Entra for authentication.
## Remove a connection
To remove an SSO connection, click the trash icon next to the connection on the SSO settings page and confirm the deletion. Users on the mapped domains will no longer be required to sign in via Microsoft Entra.
## Troubleshooting
### `401 Unauthorized` when saving
* Confirm you are signed in to Clarion with an account that has manager access to the workspace.
### The tenant domain is rejected
* Enter only the domain portion, for example `contoso.onmicrosoft.com`. Do not include `https://`.
### Users are not redirected to Entra after setup
* Confirm the **Email Domain** matches the domain part of the users' email addresses exactly (for example `contoso.com`, not `contoso.onmicrosoft.com`).
* Allow a few minutes for the connection to propagate after creation.
# Microsoft Sentinel
Source: https://docs.cantina.security/clarion/integrations/microsoft-sentinel
Connect Microsoft Sentinel to Clarion to poll incidents as issues and give triage agents Sentinel and Defender investigation tools.
This guide explains how to connect Microsoft Sentinel to Clarion. Once connected, Clarion polls a Sentinel workspace for new incidents and alerts, ingests them as Clarion issues, and your triage agents gain Microsoft Sentinel and Defender tools to investigate and hunt during triage.
**Estimated time:** 5–10 minutes. You will need **Microsoft Entra admin** access to grant tenant-wide consent, plus access to the Clarion workspace where you want to connect Sentinel.
## What this integration provides
Connecting Sentinel unlocks two things, both covered by a single connection:
| Capability | What it does |
| - | - |
| **Sentinel Incidents monitor** | Polls Microsoft Sentinel incidents from a specific data-lake workspace and ingests them as Clarion issues. |
| **Agent tools** | **MS Sentinel Triage** — list and fetch Sentinel/Defender incidents and alerts, hunt across Defender tables, look up files / IPs / users / machines, and read user-related sign-in sessions during triage. **MS Sentinel Data Lake** — run KQL queries against the Sentinel data lake (sign-ins, audit logs, partner sources) and search the table catalog for cross-source hunting. |
## How the connection works
Unlike the [Microsoft Entra ID SSO](/clarion/integrations/microsoft-entra-id) integration, you do **not** register your own app. Clarion ships a single multi-tenant Entra application — **Clarion Sentinel** — and a tenant admin grants it consent inside your tenant.
* **One consent per workspace.** A single tenant-wide admin-consent screen covers incident polling, KQL queries, and the Sentinel triage tools. You don't manage client IDs or secrets.
* **Monitors are configured separately.** The connection only stores the OAuth credential. You pick which workspace(s) to poll, and with what filters, when you add a monitor.
* **One workspace per monitor.** Add a second monitor to ingest from another workspace under the same Entra tenant.
## Prerequisites
* A **Microsoft Entra admin** account that can grant tenant-wide admin consent
* A Microsoft Sentinel workspace with incidents you want to ingest
* Access to the Clarion workspace where you want to connect Sentinel
* *(Recommended)* Your tenant onboarded to the **Microsoft Sentinel data lake** — required for the **Data lake** workspace picker and the Data Lake KQL tools. Incident polling works without it (see [Troubleshooting](#troubleshooting)).
## Step 1 — Connect Sentinel in Clarion
1. Open Clarion and go to **Integrations** → **Microsoft Sentinel**.
2. Click **Connect with Microsoft**. You'll be redirected to Microsoft to sign in.
![Microsoft Sentinel integration page with the Connect with Microsoft button]()
## Step 2 — Grant tenant-wide admin consent
Sign in with a **Microsoft Entra admin** account. Microsoft shows a **Permissions requested** screen for the **Clarion Sentinel** app. It requests:
| Permission | Why |
| - | - |
| **Maintain access to data you have given it access to** | Lets Clarion refresh its access offline so polling continues without re-prompting (`offline_access`). |
| **Sign in and read user profile** | Identifies the consenting tenant and account (`openid`). |
| **Read securitycenter information by MCP** | Grants the Sentinel/Defender **triage** tools — incidents, alerts, and advanced hunting. |
| **Sentinel Platform Delegated API Access** | Grants the **data lake** tools — KQL queries and workspace listing. |
Review and click **Accept**.
![Microsoft admin-consent screen for the Clarion Sentinel app]()
Microsoft labels the app as **unverified** / "not published by Microsoft." That's expected for a tenant-consented line-of-business app — consent is granted inside *your* tenant and applies only there.
After you accept, Microsoft redirects you back to Clarion and the integration shows **Connected**, along with your tenant. You can **Disconnect** here at any time.
## Step 3 — Add a Sentinel Incidents monitor
On the connected integration page, click **Add monitor**.
![Connected Sentinel integration with the Add monitor button]()
Fill in the monitor form:
![Create Microsoft Sentinel Monitor dialog]()
* **Name** — a label for this monitor, e.g. `Microsoft Sentinel` or a per-region name like `Sentinel EU`.
* **Sentinel workspace** *(required)* — two tabs cover the two ways to provide it:
* **SIEM workspace** *(default)* — paste the workspace identifier. It's shown as **Workspace ID** on the **Log Analytics workspace overview** in the Azure portal.
* **Data lake** — pick the workspace from a dropdown listing the workspaces the connected tenant can see. Requires your tenant to be onboarded to the **Microsoft Sentinel data lake**.
To find your Workspace ID, see [Finding your workspace ID](#finding-your-workspace-id) below.
* **Severity filter** *(optional)* — all severities are checked by default. Uncheck **Critical / High / Medium / Low** to skip incidents of those severities. The filter is applied after Sentinel returns incidents. Unchecking *everything* disables the filter — incidents of every severity are ingested.
* **Search** *(optional)* — a substring matched against each incident's title and description. For example, type `phishing` to ingest only incidents whose title or description contains "phishing." Leave empty to ingest every incident that matches the severity filter.
Click **Save** (or **Continue** when attaching the monitor to an agent). Clarion begins polling that workspace for new incidents.
### Finding your workspace ID
On the **SIEM workspace** tab you enter the workspace identifier by hand. In the Azure portal, open **Microsoft Sentinel**, confirm the **selected workspace**, then read the **Workspace ID** from that workspace's **Log Analytics workspace** overview.
![Identifying the Sentinel workspace in the Azure portal]()
## How incident polling works
* Clarion polls each connected monitor about **once a minute** and opens a Clarion issue for every new Sentinel incident that passes your severity and search filters.
* Polling is **forward-only** — a monitor ingests incidents created *after* it's connected, tracked by each incident's creation time.
* Incidents are **deduplicated by their Sentinel incident ID**, so retries and overlapping polls never create duplicate issues.
* Each issue carries the Sentinel incident title, description, severity, and a deep link back to the Defender/Sentinel portal, plus the full incident payload for agents to read without an extra round-trip.
### Severity mapping
Clarion maps Sentinel's severity onto its own issue severities:
| Sentinel severity | Clarion severity |
| - | - |
| `critical` | critical |
| `high` | high |
| `medium` | medium |
| `low` | low |
| `informational` | low |
| `unknown` | medium |
## Agent tools
Once connected, attach Sentinel tools to a skill in the skill editor so your triage agents can investigate alerts directly:
* **MS Sentinel Triage Tools** — list and fetch Sentinel and Defender incidents and alerts, run advanced hunting across Defender tables, and look up files, IPs, users, machines, and user-related sign-in sessions.
* **MS Sentinel Data Lake Tools** — run KQL queries against the Sentinel data lake (sign-ins, audit logs, partner sources) and search the table catalog for cross-source hunting.
Clarion ships a built-in **Sentinel security** agent with skills for incident triage and advanced-hunting pivots that already use these tools.
**Incident ID formats differ.** The triage tools' *Get Incident By Id* expects a **Sentinel** incident identifier (a GUID or numeric Sentinel ID), which is **not** the Defender incident number shown in the Defender portal. If a lookup by number fails, use *ListIncidents* to find the incident and its correct identifier first.
## Monitoring multiple workspaces
Each monitor polls exactly **one** workspace. To ingest from several workspaces in the same tenant, click **Add monitor** again and pick a different workspace — each monitor keeps its own filters and sync health. You only consent once per Clarion workspace, no matter how many Sentinel workspaces you poll.
## Disconnect
Click **Disconnect** on the integration page to remove the Sentinel connection. This also removes all Sentinel monitors for the workspace so polling stops cleanly. Other integrations are unaffected.
## Troubleshooting
### Re-connect required
If the integration shows **Re-connect required**, the stored credentials are no longer usable — typically because a tenant admin reset consents or the refresh token expired. Click **Connect with Microsoft** and sign in again to resume incident polling and agent queries. You don't need to disconnect first.
### Couldn't list workspaces
> The tenant may not be onboarded to the Microsoft Sentinel data lake, or the integration may need to be reconnected.
The **Data lake** workspace picker and the Data Lake KQL tools require your tenant to be onboarded to the **Microsoft Sentinel data lake**; **incident ingestion does not.** If listing fails, switch to the **SIEM workspace** tab and enter the **Workspace ID** — the monitor will still poll incidents normally. If you expect the data lake to be available, reconnect the integration.
### Required Microsoft service not enabled (AADSTS650052)
This means your tenant has no service principal for one of the Microsoft resources the connection requires — Microsoft only provisions these for some clients while the feature is in preview. Consent can't be recorded against a resource that doesn't exist in your tenant, so the connect flow stops with `AADSTS650052`.
Two resources are required, and **either** can be the missing one:
| Resource | Backs | Resource app ID |
| - | - | - |
| **Sentinel Platform Services** | Data lake tools and workspace listing | `4500ebfb-89b6-4b14-a480-7f749797bfcd` |
| **Microsoft Defender MCP** | Sentinel/Defender triage tools | `7b7b3966-1961-47b5-b080-43ca5482e21c` |
Clarion's error message names the specific service that's missing and includes the exact command to run. A tenant administrator creates the missing service principal by running the matching command in **Azure Cloud Shell** ([shell.azure.com](https://shell.azure.com)):
```bash theme={null}
# Sentinel Platform Services
az ad sp create --id 4500ebfb-89b6-4b14-a480-7f749797bfcd
# Microsoft Defender MCP
az ad sp create --id 7b7b3966-1961-47b5-b080-43ca5482e21c
```
To check whether a service principal already exists, run `az ad sp show --id ` — a "does not exist" response confirms it's the one to create. Then connect again.
### "Microsoft did not return a refresh token"
The Clarion Sentinel app needs the `offline_access` permission to poll on your behalf. Ask your Entra admin to grant **offline\_access** and try connecting again.
### "The sign-in used a different tenant than the one that granted consent"
The account you signed in with at the second screen belongs to a different tenant than the one that granted admin consent. Reconnect using the **same account** that approved the consent.
### No incidents are arriving
* Confirm the **Workspace ID** is correct and matches a workspace that actually receives incidents.
* Check the monitor's **severity filter** — if you checked only `Critical`, lower-severity incidents are skipped by design.
* Check the **Search** filter — a substring that doesn't match any incident title/description will suppress everything.
* Remember polling is **forward-only**: incidents created before the monitor was connected aren't backfilled.
# Microsoft Teams
Source: https://docs.cantina.security/clarion/integrations/microsoft-teams
Connect Microsoft Teams to Clarion so agents can post notifications to channels and chats, request approvals via Adaptive Cards, and reach the right people during incidents.
This guide walks you through connecting Microsoft Teams to Clarion. Once configured, Clarion can post issue notifications to Teams channels and chats, request approvals through interactive Adaptive Cards, and let agents send messages to users in your Microsoft Entra tenant.
The setup has four parts and is driven entirely from the Clarion UI:
1. **OAuth admin consent** — grant Clarion access to your Microsoft Entra tenant.
2. **Bot installation** — add the Clarion bot from the Microsoft Teams app store.
3. **Member mapping** — link Clarion workspace members to their Teams accounts.
4. **Notification channel** — pick a default Teams channel or chat for notifications.
**Estimated time:** 15-20 minutes. You will need **Microsoft Entra admin** access (to grant tenant-wide consent), permission to add apps to your **Microsoft Teams** organization, and access to the Clarion workspace where you are configuring the integration.
## Prerequisites
* A **Clarion workspace** with permission to manage integrations
* A **Microsoft Entra** (Azure AD) account with permission to grant admin consent for tenant-wide applications
* Permission to add apps from the Microsoft Teams app store (or [Teams Admin Center](https://admin.teams.microsoft.com) access if your organization blocks store apps)
* A team and channel (or chat) in Microsoft Teams where Clarion should post notifications
***
## Step 1 — Connect with Microsoft
1. In Clarion, open **Integrations** and find **Microsoft Teams**.
2. Click **Connect with Microsoft**. A new tab opens to the Microsoft admin consent screen.
3. Sign in with a Microsoft Entra account that can grant tenant-wide consent.
4. Review the requested permissions and click **Accept** to grant consent for the entire tenant.
![]()
Microsoft redirects back to Clarion and the integration is marked as connected.
Clarion uses the **admin consent** flow with app-only (client credentials) tokens. The consenting account does not need to be the same account that uses Clarion day-to-day, because admin consent applies to your whole Microsoft Entra tenant.
After connecting, Clarion shows a banner that setup is not complete until the remaining steps are finished. Click **Finish setup** to continue, or open **Integrations → Microsoft Teams → Open Teams configuration** at any time.
***
## Step 2 — Install the Clarion bot in Teams
OAuth gives Clarion access to your tenant's directory and chats, but posting messages requires the Clarion bot app to be installed in your organization's Teams app catalog. The bot is published on the Microsoft Teams app store, so you can add it directly without uploading a package.
1. On the **Setup** page, find the **Bot Installation** card.
![]()
2. Click **Open in Teams app store** to open the [**Clarion by Cantina**](https://teams.cloud.microsoft/l/app/24e750bb-eba3-4abb-be8c-023749e0faf8) listing.
3. Click **Add** to install the bot for your organization.
4. Back in Clarion, click **Verify Installation**.
When verification succeeds, the card shows a **Verified** badge and Clarion stores the bot's catalog ID for your tenant.
The bot only needs to be installed once per Microsoft Entra tenant. If you reconnect Clarion later, the existing bot installation is reused.
### Install the app for everyone
Adding the bot to your app catalog makes it **available**, but by default only the person who added it — and the workspace members you map in Step 3 — can act on Clarion's Adaptive Cards from inside Teams. When someone the app is not installed for clicks a button on an approval or clarification card, Teams blocks the click before it reaches Clarion and shows:
> This action can't be performed since the app does not exist or has been uninstalled.
To let **any teammate in a Teams chat or channel** — including guests and people without a Clarion account — respond to approval and clarification requests, install the Clarion app for everyone in your tenant:
1. Open [Teams Admin Center → Manage apps → **Clarion by Cantina** → Users and groups](https://admin.teams.microsoft.com/policies/manage-apps/24e750bb-eba3-4abb-be8c-023749e0faf8/users-and-groups?action=installs).
2. With **Installs** selected, click **Edit installs** and choose **Everyone**, then save.
![]()
This pairs with two settings:
* **Anyone can respond to human input** (**Settings → Workspace**): lets any workspace member (including read-only users) and any teammate in the linked chat answer approvals and clarifications, even without a Clarion account.
* **Allow agents to post to any channel** (**Settings → Agents → Escalation & notifications**): lets agents deliver those cards to any chat or channel, not only the ones named in skills or instructions.
Installing the app for everyone is what makes those responders able to click the card buttons; the audit log still records who unblocked the agent. Guests and federated (cross-tenant) users cannot be provisioned this way — Clarion's bot is single-tenant, so they will still see the error.
### Alternative: manual upload
If your organization blocks apps from the Teams app store, you can side-load the bot package instead:
1. In the **Bot Installation** card, click **Download Bot Package** to download the Clarion bot manifest (a `.zip` file).
2. Open [Microsoft Teams Admin Center → Manage apps](https://admin.teams.microsoft.com/policies/manage-apps). You can also click the **Manage apps** link in the Bot Installation card to jump straight there.
3. Click **Upload new app** and select the downloaded package.
![]()
4. Approve the app for your organization, then click **Verify Installation** back in Clarion.
***
## Private-label the bot (MSPs)
Managed service providers running one Clarion workspace per client can rename the Teams bot so the client sees the provider's brand instead of Clarion. This is a beta feature. Ask your Clarion contact to enable it for a workspace.
When it is on, the **Setup** page shows a **Bot branding** card above **Bot Installation**:
1. Enter a **Bot name** (up to 30 characters; Microsoft rejects longer names) and, optionally, a **Publisher** name. Save.
2. Click **Download Bot Package**. The manifest carries your brand.
3. Upload it in [Microsoft Teams Admin Center → Manage apps](https://admin.teams.microsoft.com/policies/manage-apps) → **Upload new app**, and approve it for the organization.
4. Back in Clarion, click **Verify Installation**.
Your client then sees your name and publisher on the app in Teams, a description with no mention of Clarion, and a welcome message that omits the Cantina sign-up, docs, and support buttons the default bot shows.
Branded workspaces skip the app store. Clarion verifies the installation by bot name, and the store listing is named "Clarion by Cantina", so a store install will not match the name you set.
Renaming after the package is uploaded invalidates the installed app. The uploaded package still carries the old name, so verification fails until you download the new package, upload it again, and re-verify. Each save increments the manifest version, which is what makes Admin Center treat the re-upload as an update instead of rejecting it as a duplicate.
### Known limitations
* **Developer links stay Cantina's.** Teams requires website, privacy, and terms URLs in every manifest; branded packages still point at `cantina.xyz`. These appear in the app's About page in Teams.
* **Issue cards deep-link to Clarion.** The "View Details" button on an issue card opens `clarion.cantina.xyz`, because that is where the issue lives.
* **Icons are Clarion's.** Custom icons are not supported yet; the package ships the default color and outline icons.
* **One brand per Microsoft tenant.** The tenant app catalog holds a single entry per app, so two workspaces on the same Entra tenant cannot use different bot names. Clarion rejects the second, conflicting brand.
* **Branded tenants are upload-only.** There is no store listing under your name, so every install goes through Admin Center.
* **Clearing a brand needs a fresh install.** Reverting to default branding resets the manifest version to `1.0.0`, which Admin Center will not accept as an update over a branded package. Remove the uploaded app first, then install "Clarion by Cantina" from the store.
***
## Step 3 — Link workspace members to Teams accounts
For approval cards and direct messages to reach the right person, Clarion needs to know each workspace member's Microsoft Teams identity.
1. On the **Member Mapping** card, click **Auto-match** to link members whose Clarion email matches a Microsoft Entra user.
2. For any members who did not auto-match, use the dropdown next to their name to pick the correct Teams user.
3. At least one member must be linked before you can run the test connection in Step 4.
Member mapping is stored as the user's Microsoft Entra object ID. If you re-invite a workspace member or they change email, you may need to re-link them.
***
## Step 4 — Test the connection
1. On the **Test Connection** card, click **Create Test Chat**.
2. Clarion creates a small group chat in Teams that includes the linked members and posts a test message.
3. Open Teams and confirm the message arrived. The card also shows a direct link to the test chat.
If the test succeeds, the integration is ready to use. If it fails, check the troubleshooting section below.
***
## Step 5 — Choose a default notification channel
Click **Back to Teams settings** to return to the main configuration page.
![]()
The **Default notification channel** section lets you pick where Clarion posts notifications and approval requests by default.
![]()
You can choose between two target types:
* **Channel** *(recommended for broadcasts)* — pick a team, then a channel within that team. Anyone in the channel can see and respond to Clarion's messages and approval cards.
* **Chat** — pick an existing Teams chat, or have Clarion create a new ad-hoc group chat with the workspace members you choose.
Agents can still post to other channels or chats per-call when needed; this default is used when an agent does not specify a target.
***
## What Clarion can do
Once Microsoft Teams is fully connected, agents can:
* **Post messages to a Teams channel** — broadcast incident updates to a team channel.
* **Post messages to a Teams chat** — send updates to an existing chat (group or 1:1) by chat ID.
* **List channels and chats** the bot has access to, so agents can pick the right destination.
* **Create an ad-hoc group chat** with specific users — used as a last resort when no existing channel or chat fits.
* **List users in your Microsoft Entra directory** to look up who to message.
Clarion also sends **issue notifications** and **approval cards** to the default target. Approval buttons (Approve / Reject) inside Teams are wired back to Clarion through the bot, so on-call responders can resolve approval requests without leaving Teams.
***
## Disconnect Microsoft Teams
To disconnect:
1. Open the **Microsoft Teams** integration in Clarion.
2. Click **Disconnect** in the status card and confirm.
Clarion stops sending notifications to Teams and clears the stored tenant credentials. The Clarion bot app remains in your Teams Admin Center until you remove it manually from **Manage apps**.
# NightVision
Source: https://docs.cantina.security/clarion/integrations/nightvision
Bring DAST findings into Clarion so agents can look up vulnerability issues, scans, and targets during triage.
NightVision is a dynamic application security testing (DAST) scanner. Connecting it gives agents read-only lookups over your findings, scans, targets, and projects — so a vulnerability report can be checked against what the scanner actually observed.
**Estimated time:** 3 minutes. You will need a NightVision **service token**.
## Prerequisites
* A **NightVision** account with scans configured
* A service token with read access
## Connect
1. In NightVision, create a **service token**.
2. In Clarion, open **Integrations** and find **NightVision**.
3. Paste the **API token** and click **Connect**.
The token is stored encrypted and never enters the agent sandbox.
## What agents can do
| Tool | What it returns |
| - | - |
| `list_issues` | Vulnerability issues, filterable |
| `get_issue` | Full detail for one issue |
| `list_scans` | Scan history |
| `list_targets` | Configured scan targets |
| `list_projects` | Projects in your NightVision account |
This integration is **read-only**: no ingest, no poller, and no scan triggering. It exists to enrich an investigation with DAST evidence, not to run the scanner.
## Where it helps
Pair NightVision with the vulnerability-domain skills. When a bug-bounty submission or a dependency finding claims an exploitable path, the agent can check whether your own DAST already saw it — and whether the target is in scope at all.
## Disconnect
Click **Disconnect** on the integration page. The stored token is deleted.
# NinjaOne
Source: https://docs.cantina.security/clarion/integrations/ninjaone
Connect NinjaOne to Clarion to triage RMM conditions, let agents look up device health, patching, software and access during an investigation, and optionally run scripts or restart services with human approval.
This guide walks you through connecting your NinjaOne tenant to Clarion. Once connected, Clarion turns NinjaOne's triggered conditions into issues your agents can triage, and gives those agents read-only lookups across every managed device.
**Estimated time:** 5 minutes. You will need **NinjaOne system administrator** access to create the app.
## Prerequisites
* Access to your NinjaOne instance as a **system administrator**
* A **Clarion workspace** with the NinjaOne integration open
* For the OAuth method, a NinjaOne technician account the connection will run as
***
## Step 1 — Choose an authentication method
Clarion connects to NinjaOne one of two ways. Pick before you create the app, because the **Application platform** you choose in NinjaOne decides which grant types the app can use — and a machine-to-machine app cannot run scripts no matter what it is granted.
| | API services (machine to machine) | Web (PHP, Java, .Net Core, etc.) |
| - | - | - |
| Who is involved | Nobody — it is an application | A NinjaOne technician authorizes once |
| Runs as | An application | That technician |
| Reads (devices, patching, conditions…) | Yes | Yes |
| Service control, patch jobs | Yes | Yes |
| **Run a script** | **No** — NinjaOne refuses | Yes |
| Keeps working if that person leaves | n/a | No — authorize again as someone else |
**API services** is the default and what every existing connection uses. Choose **Web application** if you want agents to run scripts from your automation library.
NinjaOne checks a script run against a technician's device and script-category permissions, and an application has none, so it answers `user_context_required`. Adding scopes does not change this: NinjaOne's machine-to-machine documentation says Management covers running scripts, but the API enforces a user context regardless.
***
## Step 2 — Create the app in NinjaOne
1. In NinjaOne, go to **Administration → Apps → API**.
2. Open the **Client app IDs** tab and click **Add**.
3. Set **Application platform** first — NinjaOne pre-fills the rest from it:
| Method | Application platform | Allowed grant types | Redirect URIs |
| - | - | - | - |
| API services | **API Services (machine to machine)** | **Client credentials** | not used |
| Web application | **Web (PHP, Java, .Net Core, etc.)** | **Authorization code**, **Client credentials** and **Refresh token** | the **Callback URL** Clarion shows |
4. Under **Scopes**, select **Monitoring** and **Management**. Management is only needed for [device actions](#step-6-optional-device-actions), but it costs nothing to grant now and adding it later means editing the app. Clarion never asks for **Control**, so it cannot start remote sessions either way.
5. Under **Allowed grant types**, select the ones for your method from the table above.
6. On the Web platform, **Redirect URIs** is required: paste the **Callback URL** from Clarion's connect form exactly as shown.
7. Save, then copy the **Client ID** and **Client Secret**.
Copy the client secret immediately — NinjaOne shows it only once. If you lose it, create a new app rather than reusing an old one.
***
## Step 3 — Connect in Clarion
1. In Clarion, open the **NinjaOne integration** from your workspace settings.
2. Choose the **Authentication** method you created the app for.
3. Choose your **Region**. This is the NinjaOne instance you sign in to — for example `app.ninjarmm.com` for the United States or `eu.ninjarmm.com` for Europe. Credentials issued in one region will not work against another.
4. Paste the **Client ID** and **Client Secret**.
5. **API services:** click **Connect**. Clarion verifies the credentials against NinjaOne before saving them, so a mistyped secret or the wrong region is reported straight away.
**Web application:** click **Authorize with NinjaOne** and sign in as the technician the connection should run as. The connection is not live until that finishes.
You can change methods later from the connected view — it is the same form, and your organization scope, ingestion mode and device-action setting are kept.
***
## Step 4 — Add a NinjaOne monitor
The integration on its own gives your agents device lookups. To turn NinjaOne's triggered conditions into Clarion issues, add a **NinjaOne monitor**:
1. Open the agent you want to receive NinjaOne conditions.
2. Add a **NinjaOne** monitor.
3. Optionally narrow what gets ingested:
* **Severity filter** — leave everything selected to ingest every severity. Unchecked severities are dropped before an issue is created.
* **Organizations** — a comma-separated list of NinjaOne organization IDs. Leave it empty to cover the whole tenant.
Only *triggered conditions* become issues. The rest of NinjaOne's activity log — job progress, policy edits, condition resets — is not turned into issues, though your agents can still read it per device.
***
## Step 5 — Choose how conditions reach Clarion
Under **Ingestion** on the integration page you can pick one of two delivery methods.
**Polling (default).** Clarion checks NinjaOne every minute for new triggered conditions. Nothing to configure, and it works on any tenant.
**Webhook.** NinjaOne pushes each triggered condition to Clarion the moment it fires, which removes the polling delay. Turning the switch on registers the webhook in NinjaOne for you.
NinjaOne supports **one webhook destination per API client app**. Enabling the webhook for a second monitor repoints NinjaOne at that monitor rather than adding a second delivery.
Two things can stop the webhook from being registered:
* The API client app was not created by a **system administrator**.
* The same client app already has a **PSA channel** configured, such as ConnectWise or Autotask.
In either case, either create a separate API client app for Clarion, or stay on polling. Polling delivers the same conditions with the same filters — only the delay differs.
Switching back to polling deregisters the webhook in NinjaOne automatically.
***
## Step 6 (optional) — Device actions
By default agents can only read from NinjaOne. **Device actions** lets them also change something on a machine: run a script from your automation library, start/stop/restart a Windows service, or start a patch scan or apply.
To enable it:
1. Make sure your NinjaOne app has the **Management** scope (**Administration → Apps → API**).
2. In Clarion, open the NinjaOne integration and turn on **Allow scripts, service control and patch jobs** under **Device actions**.
Clarion checks that the app actually grants Management before storing the setting, so an app still limited to Monitoring is rejected there and then rather than failing later during an investigation.
Running **scripts** additionally requires the **Web application (OAuth)** method from Step 1 — service control and patch jobs work either way. On that method, the technician who authorized needs permission for the automation categories of the scripts your agents run; if a script belongs to several categories, they need all of them.
This lets an agent execute code from your script library on a customer's endpoint. Every such call still requires a person to approve that specific call, and each one is recorded against the issue — but the scripts themselves are yours, and the agent can run any of them on any device inside this workspace's organization scope.
It also covers patch **apply**, which installs patches and can reboot a machine. Read the approval prompt before accepting one against a server.
Review what is in your automation library before turning this on, and leave it off for workspaces that only need investigation.
NinjaOne accepts these without reporting what they did, so agents confirm the outcome afterwards by reading the device's activity log — a submitted action is never reported as a completed one.
Turning the switch back off takes effect immediately and never calls NinjaOne, so it works even when NinjaOne is unreachable.
***
## Step 7 (optional) — The ClarionBot script
Device actions let an agent run a script that is **already** in your automation library. ClarionBot is the other half: one library entry that lets an agent run a PowerShell command it composed for the investigation — read a log file, check a registry value, run a diagnostic cmdlet — and get the output back in the same call.
It is one script, created once per NinjaOne tenant. Clarion looks it up by name every time it runs, so the ID NinjaOne assigns it can differ between your environments and nothing has to be configured in Clarion.
It builds on the two steps above and needs both: **Device actions** turned on ([Step 6](#step-6-optional-device-actions)), and the **Web application (OAuth)** method ([Step 1](#step-1-choose-an-authentication-method)), because NinjaOne refuses every script run that is not made on behalf of a technician.
This lets an agent run PowerShell it wrote itself, as LocalSystem, on any Windows device inside this workspace's organization scope. That is a wider capability than the rest of Device actions: the other tools run scripts *you* reviewed and put in the library.
Every call still requires a person to approve that specific command, and the approval shows the exact command before you accept it — read it. Leave this script uncreated for workspaces where reviewed scripts are enough.
### Create the script
1. In NinjaOne, go to **Administration → Library → Automation**.
2. Click **Add → New Script**.
3. Paste this as the script body:
```powershell theme={null}
Param(
[Parameter(Mandatory=$true)]
[string]$code
)
$bytes = [System.Convert]::FromBase64String($code)
$DecodedCommand = [System.Text.Encoding]::UTF8.GetString($bytes)
# Execute Script Content
iex $DecodedCommand
Write-Host "Ephemeral Agent started"
```
4. Set the script's properties:
| Field | Value |
| - | - |
| Name | **ClarionBot** |
| Language | **PowerShell** |
| Operating System | **Windows** |
| Architecture | **All** |
| Run As | **System** |
The name has to be exactly `ClarionBot` — that is what Clarion resolves. Capitalisation and surrounding spaces do not matter, but a second script by the same name does: Clarion refuses to guess between them.
5. Before leaving the script, add the **script variable** the parameter needs:
1. Click **+ Add** next to **Script Variables**.
2. Select the **String/Text** type.
3. Enter `Code` as the variable name.
4. Click **Add**.
6. Save the script.
You do not need to note the script ID, and you do not need to configure anything on the endpoints. Running as System needs nothing beyond the NinjaOne agent already being installed, and no credential has to exist in NinjaOne's credential store.
### Check it works
Ask an agent to run `whoami` on a Windows device and approve the call. A working setup answers `nt authority\system` followed by `Ephemeral Agent started`.
***
## What your agents can do
With NinjaOne connected, agents triaging *any* issue — not only NinjaOne ones — can look up:
* **Devices** — search by hostname, or list with a NinjaOne device filter
* **Device detail** — OS, organization and location, approval status, and last check-in
* **System** — manufacturer, model, serial, memory, OS build, last boot, pending reboot, CPUs, and your custom fields
* **Health** — NinjaOne's own health rollup for a device
* **Antivirus** — installed product, its reported state, definition freshness, and detected threats
* **Patching** — applicable OS and software patches and their install state
* **Software** — installed applications and versions
* **Services** — Windows service state and start type, filterable by service name
* **Storage** — disks, volumes, free space, and SMART status
* **Network** — interfaces and the last logged-on user
* **Users and access** — which end users are entitled to a device, and who last logged on
* **Tickets** — service and access requests from your NinjaOne ticketing boards, with their comment history
* **Conditions** — what is currently firing, on one device or across the tenant
* **Fleet reports** — any of NinjaOne's inventory reports run across every device in scope, which is how an agent tells a single failing host from an estate-wide problem
* **Jobs and activity** — what is running on a device now, and what ran recently
* **Vulnerability scan imports** — which third-party vulnerability feeds this tenant imports, and whether the last import succeeded. These are import pipelines rather than per-device findings, which NinjaOne's API does not expose; a workspace restricted to specific organizations sees none of them, because a scan group names no organization.
All of the above are read-only. If you enabled **Device actions**, agents can additionally control a Windows service and start a patch scan or apply — and, on the OAuth method, run a script — each behind a human approval. With the [ClarionBot script](#step-7-optional-the-clarionbot-script) in your library they can also run a PowerShell command they composed for the investigation and read its output.
***
## Troubleshooting
**"NinjaOne rejected these credentials."** The client ID or secret is wrong, or the region does not match the instance you sign in to. Check the region first — it is the most common cause.
**"These credentials were accepted but lack the `monitoring` scope."** Edit the app in **Administration → Apps → API** and add the Monitoring scope.
**"This NinjaOne app does not grant the management scope."** You tried to enable Device actions with an app limited to Monitoring. Add the Management scope in **Administration → Apps → API**, then connect again. Reads are unaffected in the meantime.
**"NinjaOne refused this action because it has to run as a NinjaOne user."** The workspace is on the **API services** method, which has no user behind it. Reconnect with the **Web application (OAuth)** method. Adding scopes will not fix this — NinjaOne's machine-to-machine documentation says Management covers running scripts, but the API enforces a user context regardless.
**"NinjaOne no longer accepts Clarion's authorization."** On the OAuth method: the grant was revoked, the app was deleted, or its secret was rotated. Reconnect and authorize again. Reads stop too, since everything runs under that grant.
**"NinjaOne did not return a refresh token."** The Web app is missing the **Refresh Token** grant type. Add it in **Administration → Apps → API** and authorize again.
**"This NinjaOne tenant has no automation script named ClarionBot."** The wrapper script has not been created, or it is named something else. See [Step 7](#step-7-optional-the-clarionbot-script). Clarion matches the name ignoring case and surrounding spaces, but nothing else — `Clarion Bot` and `ClarionBot-v2` will not resolve.
**"This NinjaOne tenant has N automation scripts named ClarionBot."** Two library entries share the name, and picking one would be a guess. Rename or delete the duplicates so exactly one remains.
**"Unable to retrieved credential information."** NinjaOne reports this on a run when it is asked to use a credential role the tenant has not defined. Clarion always runs ClarionBot as System and never names a role, so this points at a different automation — check what else ran on the device around the same time.
**A run returns `running` rather than output.** The command is still executing on the device; it is not a failure and re-running it would execute it twice. The agent can read the device's activity log afterwards to pick up the result. Raise the wait if the commands you expect routinely take longer.
**No issues appearing.** Confirm a NinjaOne monitor exists and is attached to an agent, that the condition you expect is actually firing in NinjaOne, and that its severity is not excluded by the monitor's severity filter.
**Conditions from the wrong customers.** Set the monitor's **Organizations** filter to the organization IDs this workspace should cover.
# Notion
Source: https://docs.cantina.security/clarion/integrations/notion
Connect Notion to Clarion with a connection token so agents can search and read your docs, runbooks, and databases for context during triage.
This guide shows how to connect Notion to Clarion using a Notion connection (a workspace-scoped bot with its own token — previously called an internal integration).
**Estimated time:** 5-10 minutes. You need access to:
* A **Clarion workspace**
* A **Notion workspace** where you are a **workspace owner** (only workspace owners can create connections)
## Prerequisites
Before connecting Notion in Clarion, make sure you have:
* Workspace-owner access in Notion
* A decision about which pages, wikis, and databases Clarion should be able to read
Notion grants access **page by page**, not workspace-wide. Clarion can only see content that you explicitly share with the connection. Sharing a top-level page shares everything nested under it.
***
## Step 1 - Create a Notion connection
Notion calls these "connections" (previously "internal integrations") — a bot scoped to your workspace with its own token.
1. In Notion, go to **Settings** → **Connections** → **Develop or manage connections**. This opens Notion's Developer portal ([app.notion.com/developers](https://app.notion.com/developers)).
2. Click **Create a Connection**, give it a name (e.g. "Clarion"), and pick the workspace to connect.
3. In the connection's **Configuration** tab, enable the read capabilities:
* **Read content**
* **Read user information** (name and email is fine)
Clarion is read-only — you do not need any insert or update capabilities.
4. Copy the connection's token from the **Configuration** tab (it starts with `ntn_`).
If you set an expiration on the token, note the date — Clarion will lose access when it expires and you will need to paste a fresh token.
***
## Step 2 - Share content with the connection
Clarion can only read pages that are shared with the connection. Either:
* **Per page:** open a page, click **•••** → **Connections**, and add your new connection. All sub-pages inherit access.
* **In bulk:** open the connection in the Developer portal and add pages and databases from its content access settings.
Most teams share their top-level engineering wiki or runbooks page once — everything nested under it becomes readable.
***
## Step 3 - Connect Notion in Clarion
1. In Clarion, go to **Integrations**.
2. Open **Notion**.
3. Paste the connection token.
4. Click **Connect**.
Clarion validates the token and shows the connected Notion workspace name.
***
## Step 4 - Verify the connection
After connecting, click **Verify**. This confirms the token still works and that at least one page is shared with the connection.
If verification warns that no pages are shared, go back to [Step 2](#step-2---share-content-with-the-connection) — the token is valid, but agents will get empty search results until content is shared.
***
## How Notion tools use this integration
When Notion tools are enabled, Clarion agents can:
* **Search pages and databases by title.** Notion's API matches titles only, so agents search with distinctive keywords and then read pages in full.
* **Read a page as Markdown**, including runbooks, incident docs, and architecture notes.
* **Query databases** (data sources) with filters and sorts — useful for runbook tables, service catalogs, and on-call rotations.
* **List workspace members** to resolve document owners or mentions.
Clarion never writes to your Notion workspace.
***
## Troubleshooting
### "Notion rejected the token"
* Check you copied the connection's full token from its **Configuration** tab (it starts with `ntn_`).
* The token may have expired (if it was created with an expiration) or been revoked. Create a fresh one and reconnect.
### "The Notion token authenticated but lacks the required read capabilities"
Open the connection in Notion's Developer portal and enable the **read content** and **read user information** capabilities in its **Configuration** tab. Capability changes take effect immediately.
### Searches come back empty
The connection has no shared content. Share pages via a page's **••• → Connections** menu or the connection's content access settings in the Developer portal. Remember access is page-by-page — a valid token alone grants nothing.
### Enterprise workspaces
Notion Enterprise admins can restrict who may install or add connections. If you cannot add the connection to pages, ask a workspace owner to approve it first.
# Okta
Source: https://docs.cantina.security/clarion/integrations/okta
Clarion is a security operations platform that helps teams detect, investigate, and respond to identity and access threats. Install the Clarion Okta app from the Okta Integration Network to connect your Okta org to Clarion.
This guide explains how to install the Clarion Okta API Service integration from the Okta Integration Network (OIN) and connect it to Clarion. Once configured, Clarion can ingest Okta security events, triage suspicious activity, and support response actions from a single workflow.
**Estimated time:** 5-10 minutes. You will need **Okta Admin** access and access to the Clarion workspace where you want to connect Okta.
Use the OIN catalog installation flow described below. Do not create a custom Okta API Services app or manually configure an Okta Event Hook for this integration.
## Prerequisites
* Access to an Okta org with permission to install API Service integrations
* Access to the Clarion workspace where you want to configure the Okta integration
* A secure place to store the client secret shown during the Okta install flow
## Supported Okta scopes
The Clarion Okta app supports the following Okta API scopes:
* `okta.eventHooks.manage` - create, update, verify, and delete the Clarion-managed Okta Event Hook
* `okta.logs.read` - read Okta System Log events used for monitoring and investigation enrichment
* `okta.users.manage` - look up users and their group memberships, and support response actions such as account suspension from Clarion
* `okta.groups.manage` - remove a user from a group to de-escalate group-derived privilege during response (requires human approval in Clarion)
## Install the Clarion app in Okta
1. Sign in to the **Okta Admin Console**.
2. Go to **Applications** > **API Service Integrations**.
![]()
3. Click **Add Integration**.
4. Search for **Clarion by Cantina**.
![]()
5. Select the integration and continue to the authorization step.
6. Review the requested scopes, then click **Install & Authorize**.
![]()
7. Copy the **Client Secret** from the one-time confirmation dialog and store it securely.
8. Open the installed Clarion integration in Okta and copy the **Client ID** from the **General** tab.
9. Note your Okta org domain, for example `company.okta.com`.
When entering the Okta domain in Clarion, you can paste the hostname, a full Okta URL, or an Admin Console hostname such as `company-admin.okta.com`. Clarion automatically normalizes it to the org hostname, such as `company.okta.com`.
## Connect Okta in Clarion
1. Open Clarion and go to **Integrations** > **Okta**.
2. Enter the following values:
* **Okta Domain** - your Okta org hostname only, such as `company.okta.com`
* **Client ID** - the value from the installed Clarion integration in Okta
* **Client Secret** - the value shown during **Install & Authorize**
3. Click **Connect**.
4. Clarion validates the credentials, provisions the managed Okta Event Hook, and saves the integration.
## Verify the connection
After connecting:
* The Okta integration status in Clarion should show **Connected**
* The **Managed Okta connection** section should show the connected org and Event Hook ID
* Clarion should provision the webhook endpoint automatically without requiring additional Okta-side Event Hook setup
## Enable Clarion detection rules
Click **Add recommended filters** to enable Clarion's detection rules. These rules monitor for suspicious activity and open issues, adding an extra layer of security on top of Okta's built-in alerts.
![]()
## Upgrade an existing installation for new scopes
Okta does not add newly approved scopes to an API Service integration that is already installed. For example, an existing Clarion installation does not automatically receive `okta.groups.manage` when Clarion adds group-removal support. Rotating that installation's client secret does not add the scope either.
To authorize the updated scopes:
1. In the **Okta Admin Console**, go to **Applications** > **API Service Integrations** and install **Clarion by Cantina** again.
2. Confirm that the authorization screen includes `okta.groups.manage`, then click **Install & Authorize**.
3. Copy the new **Client ID** and **Client Secret**. Keep the previous Okta installation until the new connection is working.
4. In Clarion, go to **Integrations** > **Okta**, click **Disconnect**, and connect again using the new credentials.
5. Confirm that Clarion shows the integration as **Connected** and has provisioned the managed Event Hook.
6. Revoke the previous Clarion API Service integration in Okta.
The previous client ID and secret continue to authorize only the scopes granted when that integration instance was installed. Okta creates new credentials for the newly authorized instance, so you must save those credentials in Clarion before group-removal actions can work.
## Reconnect an existing Okta integration
If your workspace connected Okta before the OIN-based app flow was introduced, Clarion may show **Reconnect required** instead of **Connected**.
If Clarion still has the saved Okta app credentials, use **Recreate managed hook** to create a fresh Clarion-owned Event Hook without re-entering credentials.
If Clarion asks for new credentials:
1. Install **Clarion by Cantina** from **Applications** > **API Service Integrations** in the same Okta org.
2. Copy your **Okta Domain** and the generated **Client ID** and **Client Secret** from the installed app.
3. Return to Clarion and use **Save credentials and reconnect** on the Okta integration page.
If you no longer have the original client secret, rotate it from the installed Clarion app in Okta before reconnecting.
## What Clarion does after connection
Once connected, Clarion can:
* Receive supported Okta events in real time
* Use Okta System Log data to enrich investigations
* Open issues and triage suspicious activity in Clarion
* Support response actions such as suspending compromised accounts, or removing a user from a group to revoke privilege, when initiated from Clarion workflows
## Troubleshooting
### `401 Unauthorized` during connect
* Confirm you are using the **Client ID** and **Client Secret** from the installed **Clarion by Cantina** API Service integration in the same Okta org
* If you no longer have the client secret, generate a new secret in Okta and reconnect Clarion with the rotated value
### The Okta domain is rejected or the token request fails
* Paste the Okta org hostname or full Okta URL from the same org; Clarion automatically removes protocol, path, trailing dots, and supported Admin Console suffixes
* If the value is still rejected, confirm it belongs to an Okta org domain such as `company.okta.com`, `company.okta-emea.com`, or `company.oktapreview.com`
* Confirm you are using the Client ID and Client Secret from the installed Clarion app in that same Okta org
### The connection succeeds but no hook is created
* Confirm the integration was installed from **Applications** > **API Service Integrations**
* Confirm the authorized app includes the supported scopes listed above
* Retry the Clarion connection or use **Recreate Hook** from the Okta integration page in Clarion
# OpenClaw
Source: https://docs.cantina.security/clarion/integrations/openclaw
Monitor AI agents for policy violations, unusual tool use, and skill activity via ClawSight telemetry.
OpenClaw sends agent telemetry to Clarion through the **ClawSight** plugin, so the AI agents running in your environment are monitored the same way any other workload is.
**Estimated time:** 5 minutes. You will need access to your ClawSight plugin configuration.
## Prerequisites
* OpenClaw with the **ClawSight** plugin installed
* Ability to edit `openclaw.plugin.json`
## Step 1 — Connect in Clarion
1. In Clarion, open **Integrations** and find **OpenClaw**.
2. Enter an **API token** — this is the bearer token ClawSight will authenticate with. Use a strong, unique value.
3. Click **Connect**. Clarion shows you the **platform URL** to use.
## Step 2 — Configure ClawSight
In `openclaw.plugin.json`, set:
* `platformUrl` — the URL Clarion showed you. The plugin appends `/v1/telemetry/ingest` automatically, so do not add it yourself.
* `apiToken` — the same token you entered in Clarion.
Telemetry starts arriving once the plugin reloads.
## What Clarion watches
* **Skill activity** — which skills agents invoke, and how often.
* **Policy violations** — actions that break the policies you configured.
* **Unusual tool use** — tool calls that fall outside an agent's established pattern.
These feed the [AI Agent Monitoring](/clarion/learn/agents#our-agents) agent.
The AI Agent Monitoring template ships without bundled skills. Attach skills from the [library](/clarion/learn/skills#our-skills), or write your own, to define how these events should be triaged.
## Rotate the token
Enter a new value in **Update API Token** on the integration page, then update `apiToken` in the plugin config to match.
## Disconnect
Click **Disconnect** on the integration page. Telemetry sent afterwards is rejected.
# PagerDuty
Source: https://docs.cantina.security/clarion/integrations/pagerduty
Connect PagerDuty to Clarion so agents can page your on-call rotation through PagerDuty's Events API v2 during triage.
This guide walks you through connecting PagerDuty to Clarion. Once connected, agents can trigger PagerDuty incidents from a skill or agent behavior whenever they decide — based on what they found during triage — that an on-call human needs to be paged.
**Estimated time:** 5 minutes. You'll need permission to add an **Events API v2** integration to at least one PagerDuty service.
## Prerequisites
* A **PagerDuty** account with permission to manage services
* One or more **services** in PagerDuty configured with the escalation policies you want Clarion to use
* A **Clarion workspace** with the PagerDuty integration page open
***
## Step 1 — Enable PagerDuty in Clarion
1. In Clarion, open **Integrations** and find **PagerDuty**.
2. Click **Enable PagerDuty**.
The integration is now active but won't deliver anything yet — PagerDuty needs at least one notification channel.
***
## Step 2 — Create an Events API v2 integration in PagerDuty
For each service Clarion should be able to page, generate a routing key:
1. In PagerDuty, open the **service** you want Clarion to page.
2. Go to the **Integrations** tab.
3. Click **Add another integration**.
4. Choose **Events API v2** as the integration type.
5. Give it a recognisable name, for example *Clarion — SecOps*.
6. Click **Add** and copy the **Integration Key** (also called *routing key*) that PagerDuty shows you.
Each routing key targets exactly one PagerDuty service and its escalation policy. If you want different paths for different scenarios (e.g. SecOps vs Platform on-call), create one routing key per service.
***
## Step 3 — Add the channel in Clarion
1. Back on the Clarion PagerDuty integration page, click **Add channel**.
2. Enter a **name** that identifies the rotation — for example *SecOps on-call*.
3. Paste the **routing key** from PagerDuty.
4. Click **Add channel**.
5. Use the **Send test event** button next to the new row to confirm the routing key is valid. Clarion sends a `trigger` event and immediately resolves it, so the test will briefly appear in PagerDuty before clearing itself.
Repeat for any other services you want to wire up.
***
## Step 4 — Reference PagerDuty in a skill or agent behavior
PagerDuty isn't a Clarion escalation channel — operators don't acknowledge pages back into Clarion. Instead, agents call PagerDuty directly when a skill or your [agent behavior](/clarion/learn/settings#agent-behavior) tells them to.
1. Open a **skill** (or **Settings → Agents → Agent behavior**) in Clarion.
2. Type `#` in the editor and pick **PagerDuty** from the channel/notification menu.
3. The block embeds with no extra configuration — the agent picks which PagerDuty channel to page at runtime, so the same skill works in any workspace that has PagerDuty channels configured.
### What the agent can do
When the skill runs and the workspace has at least one PagerDuty channel, the agent gets two tools:
| Tool | Purpose |
| - | - |
| `mcp__pagerduty__list_channels` | List channels the workspace has configured (returns `id` + `name`). The agent calls this first to know which channels exist. |
| `mcp__pagerduty__trigger_alert` | Page a specific channel. The agent passes the channel `id`, a `summary` (the PagerDuty incident title), and a `severity` (`critical` / `error` / `warning` / `info`). Optionally a `dedupKey` to coalesce repeats, and `customDetails` to surface structured fields in PagerDuty's "Custom Details" panel. |
The routing key never leaves the Clarion server — the agent only ever sees the channel id. Clarion resolves the id to the routing key when actually calling the PagerDuty Events API.
### Default approval gating
`trigger_alert` requires human approval by default because it pages on-call humans. The agent pauses, the configured notification channel pings the operator, and execution resumes once the request is approved. You can change this in **Workspace → Tools** for `mcp__pagerduty__trigger_alert` if you want certain skills to page automatically.
### Severity rules of thumb
* `critical` — production is down, someone needs to act in minutes. Routes through PagerDuty's escalation policy at full urgency.
* `error` — urgent but not immediately dangerous. Sensible default for "this is bad, someone should look at it."
* `warning` — action will be needed but not right now. Good for backlog work surfaced during triage.
* `info` — FYI; will not page in most PagerDuty service configurations.
### Coalescing repeat pages with `dedupKey`
If a skill might trigger more than once for the same underlying condition (e.g. the agent runs again on a recurring issue), pass a stable `dedupKey` — for instance the issue id, the affected resource ARN, or any identifier that uniquely names the condition. PagerDuty will *update* the existing incident instead of opening a new one. Omit `dedupKey` and Clarion generates a key based on the channel and summary, so accidental re-fires inside a single agent run still coalesce.
### Alert title and details
Clarion automatically rewrites every PagerDuty alert so the on-call responder can act on it without leaving PagerDuty:
* The incident **summary** is always prefixed with `[Cantina Clarion]` regardless of what the agent supplied.
* The incident's **Custom Details** panel always includes a `clarion_url` field linking back to the source issue in Clarion (or to the workspace if the agent run wasn't issue-driven).
***
## Disconnect
To remove the PagerDuty integration:
1. In Clarion, open **Integrations → PagerDuty**.
2. Remove the individual channels you no longer need, or
3. Disconnect the whole integration from the integrations list.
Disconnecting deletes the stored routing keys. Re-enabling later means re-adding each channel; the PagerDuty services themselves are unaffected.
***
## Troubleshooting
### "PagerDuty test failed: ..."
The routing key was rejected. Common causes:
* The key was copied with extra whitespace — re-copy from PagerDuty.
* The integration in PagerDuty is **Events API v1** rather than v2. Clarion only supports v2.
* The PagerDuty service the integration belongs to has been deleted or suspended.
# Pylon
Source: https://docs.cantina.security/clarion/integrations/pylon
Connect Pylon to Clarion so agents can read customer-support issues, message threads, accounts, and knowledge base articles — and triage the issues your Pylon triggers send over.
This guide walks you through connecting your Pylon workspace to Clarion. Once connected, Clarion gives your agents read access to your support desk during any investigation, and — if you add a monitor — turns the issues your Pylon triggers select into issues an agent triages.
**Estimated time:** 5 minutes. You will need permission to create a **Pylon API token**, and, for the monitor, permission to edit **Webhooks** and **Triggers** in Pylon settings.
## Prerequisites
* A **Pylon account** with access to Settings
* A **Clarion workspace** with the Pylon integration open
***
## Step 1 — Create an API token in Pylon
1. In Pylon, go to **Settings → API tokens**.
2. Create a token and copy it.
The token is organization-wide: Clarion reads and writes exactly what that token is allowed to, which is the same scope as the Pylon dashboard. Actions Clarion takes appear in Pylon under the token's name, so give it a name you will recognise in an audit trail — `Clarion`, for example.
Copy the token immediately — Pylon shows it only once.
***
## Step 2 — Connect in Clarion
1. In Clarion, open the **Pylon integration** from your workspace settings.
2. Choose your **Region** — `api.usepylon.com` for the United States or `api.eu.usepylon.com` for Europe. A token only works in the region its workspace is hosted in, and there is no way to detect that from the token itself, so pick the one you sign in to.
3. Paste the **API token**.
4. Click **Connect**.
Clarion verifies the token against Pylon before saving it, so a mistyped token or the wrong region is reported straight away rather than failing quietly on the first agent run. Once connected, the page names the Pylon organization the token belongs to — a quick way to confirm you connected the workspace you meant to.
***
## Step 3 — Add a Pylon monitor
The integration on its own gives your agents lookups. To have an agent triage support issues as they arrive, add a **Pylon** monitor:
1. Open the agent you want to receive Pylon issues.
2. Add a **Pylon** monitor.
3. Set the **Default severity**. Pylon issues carry no severity of their own, so this is the level Clarion applies unless your trigger's body includes a `priority` field.
4. Clarion generates a webhook URL and a one-time secret. Copy both — the secret is shown once.
***
## Step 4 — Send issues from Pylon
Pylon delivers webhooks in two parts: an **endpoint** that says where to send and what headers to attach, and a **trigger** that decides when to fire.
**Add the endpoint.**
1. In Pylon, go to **Settings → Webhooks**.
2. Add an endpoint with the URL Clarion generated.
3. Add a custom header named `Authorization` with the value `Bearer `, using the secret Clarion showed you.
Clarion rejects any delivery without that header, so nobody who finds the URL can post issues into your workspace.
**Add the trigger.**
1. Go to **Settings → Triggers** and create a trigger whose action is **Send webhook**, pointed at the endpoint you just added.
2. Use the trigger's **When** and **If** conditions to choose which issues an agent should triage. A trigger that fires on every issue will send your whole support volume to Clarion, so start narrow — a tag, a priority, or a specific queue.
3. Set the webhook body to include the issue id:
```json theme={null}
{ "issue_id": "{{issue.id}}" }
```
That is all Clarion needs. It reads the issue's title, state, account, requester, tags, and body back from Pylon using the API token from Step 2, so the issue an agent sees is always the current one rather than a snapshot of whatever the template produced. A richer body still works — Clarion keeps the whole delivery on the issue so you can see exactly what Pylon sent.
If your body includes a `priority` field (`urgent`, `high`, `medium`, or `low`), Clarion maps it onto the issue's severity instead of using the monitor's default.
***
## What your agents can do
With Pylon connected, agents triaging *any* issue — not only Pylon ones — can:
* **Search issues** — by text, state, account, assignee, team, tags, or date range
* **Read an issue** — full detail, including account, requester, tags, custom fields, and SLA breach times
* **Read a message thread** — the whole conversation, with internal notes marked as private
* **Search accounts** — by name, domain, or tag
* **Read an account** — domains, tags, owner, and custom field values
* **Look up a contact or a team member** — to turn an id on an issue into a named person
* **Search and read your knowledge base** — find help-center articles and internal runbooks by text or collection, then read one in full, to check documented behavior and known issues. Unpublished drafts are skipped unless an agent asks for them, and every article carries its visibility so internal content is not mistaken for customer-facing help
Agents can also **open an issue**, **update an issue**, and **update an account**. These change what a customer sees, so they run through your workspace's tool-approval policy — configure it under **Settings → Tools**.
***
## Troubleshooting
**"Pylon rejected the API token."** The token is wrong, or the region does not match the workspace you sign in to. Check the region first — it is the most common cause.
**No issues appearing.** Confirm a Pylon monitor exists and is attached to an agent, that your trigger's conditions actually match the issues you expect, and that the endpoint the trigger points at is the one carrying the `Authorization` header.
**Deliveries rejected.** Check the `Authorization` header on the Pylon endpoint. It must read `Bearer ` followed by the secret, with no extra whitespace. If you have lost the secret, rotate it on the monitor and paste the new one into Pylon.
**Issues arrive without a title or detail.** Clarion could not match the delivery to a Pylon issue, so it ingested the raw body instead — the issue's description shows exactly what arrived. Check that the trigger's body includes the issue id, and that the integration is still connected.
**Rotating the secret.** Open the monitor and rotate it, then update the `Authorization` header in Pylon. Deliveries carrying the old secret are rejected from the moment you rotate, so change both in quick succession.
# Replit
Source: https://docs.cantina.security/clarion/integrations/replit
Connect your Replit Enterprise Account to Clarion so the exposure agent can find deployments that are reachable from the public internet but were never meant to be.
This guide walks you through connecting a Replit Enterprise Account to Clarion. Once connected, Clarion's Exposure Agent sweeps the Account daily: it lists your workspaces and deployments, reads each deployment's privacy setting, checks whether the public ones actually answer on the internet, and opens an issue for anything that looks internal but is reachable by anyone.
**Estimated time:** 5 minutes. You will need to be an **admin of a Replit Enterprise Account**, since the Admin API is only available to Account admins on Enterprise Accounts.
## Prerequisites
* A **Replit Enterprise Account**, and **admin** access to it
* The ability to create an **Admin API key** with read scope
* A **Clarion workspace** with the Replit integration page open
One Clarion workspace connects one Replit Account. The key you paste grants read access to everything in the Account that issued it, so create it from the Account whose deployments you want swept.
***
## Step 1 — Create an Admin API key in Replit
1. Sign in to Replit as an Account admin.
2. Open your **Account** settings and find the **Admin API** section.
3. Create a new API key with **read** scope.
4. Copy the key. It begins with `rpl_`.
Copy the key immediately and store it securely — Replit may only show it once. Grant read scope only; Clarion never writes to Replit.
***
## Step 2 — Enter the key in Clarion
1. In Clarion, open **Integrations** and find **Replit** under Development & Planning.
2. Paste your **Admin API key**.
3. Click **Connect**.
Clarion checks the key against Replit before saving it. If the key is wrong or the Account is not entitled to the Admin API, you'll see a clear error and nothing is stored. To rotate a key later, paste the new one and connect again — it replaces the old one.
***
## What the exposure agent does
The Exposure Agent runs a daily sweep of every provider you have connected. For Replit it:
| Step | What happens |
| - | - |
| Enumerate | Lists the Account's workspaces and their deployments |
| Read posture | Records each deployment's privacy as `public`, `password`, or `private` |
| Check reachability | Requests the root of public deployments only, and records the response status — never the page content |
| Classify | Separates deployments that show a login page from those serving open content |
| File | Opens and escalates an issue for each reachable deployment that looks internal, up to ten per run |
| Remember | Records each verdict so an intentionally public site stops being re-reported |
Deployments set to `password` or `private` are recorded as gated and never contacted.
The reachability check is read-only: Clarion requests the deployment's root address, follows at most two redirects, and keeps only the status code, byte count, and whether the page mentioned signing in. No page content, headers, or cookies are stored, shown, or sent to the agent.
### Agent tools
Once connected, agents on this workspace gain access to the `/replit` action, which exposes these read-only tools:
| Tool | What it does |
| - | - |
| `list_workspaces` | List every workspace in the connected Account |
| `list_projects` | List a workspace's projects, including who owns each |
| `list_deployments` | List a workspace's deployments with their privacy setting, status, and address |
| `get_deployment` | Fetch one deployment's current privacy setting and status |
| `list_members` | List a workspace's members, used to route a finding to its owner |
| `probe_deployment_root` | Check whether one public deployment answers on the internet |
All six are read-only and need no approval. None of them can change anything in Replit.
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Replit**.
2. Click **Disconnect**.
This deletes the stored key. The exposure agent stops sweeping Replit, and any saved skills that reference the `/replit` action will surface the integration as missing until you reconnect.
***
## Troubleshooting
### "Replit rejected the key"
The key is malformed, unknown, revoked, or expired. Create a fresh Admin API key in your Replit Account settings and connect again. Check that you copied the whole key, including the `rpl_` prefix.
### "The key needs read scope and Enterprise Admin API entitlement"
Replit authenticated the key but refused the request. Either the key was issued without read scope, or the Account is not an Enterprise Account with Admin API access. Confirm both with your Replit administrator.
### A deployment I expected is missing from the sweep summary
If the summary says coverage was **incomplete**, Replit returned more results than a single sweep walks, and some deployments were not examined. Each run starts from the beginning rather than resuming where the last one stopped, so the same deployments are examined every time and the ones past the limit stay unexamined until the limit is raised. The summary reports this per run, so incomplete coverage is always stated rather than implied. If you see it, let us know how many workspaces and deployments your Account has.
# SentinelOne
Source: https://docs.cantina.security/clarion/integrations/sentinelone
Forward Singularity Endpoint threat detections from SentinelOne into Clarion as issues.
This guide explains how to connect SentinelOne to Clarion. Once configured, every threat SentinelOne raises on your chosen site becomes a Clarion issue that agents can triage and investigate.
**Estimated time:** 10-15 minutes. You will need **Site Admin** (or higher) access in SentinelOne, plus access to the Clarion workspace where you want to connect SentinelOne.
## What you'll configure
Connecting SentinelOne takes three things:
| What | Purpose |
| - | - |
| **Clarion webhook URL + secret** | SentinelOne posts threats to this URL. The secret, sent as the `x-webhook-secret` header, authenticates them. Both are generated when you click **Connect**. |
| **SentinelOne API token** | A Service User token with the **SOC role** that lets Clarion enrich each issue with the full threat details and run response actions (mitigate, isolate, set verdict/status). Without it, issues are sparse. |
| **Console URL** | Your tenant URL, used for the "View in SentinelOne console" deep link on issues. |
## Prerequisites
* A SentinelOne console with at least one Linux, macOS, or Windows agent enrolled
* An admin role on the SentinelOne account or site you want to forward
* Access to the Clarion workspace where you want to configure the integration
## Step 1 — Connect SentinelOne in Clarion
1. Open Clarion and go to **Integrations** → **SentinelOne**.
2. Click **Connect**. Clarion generates the webhook URL and a webhook secret for this workspace.
3. **Copy the webhook URL and secret immediately.** The secret is shown only once; if you lose it you'll have to disconnect and reconnect to generate a new one.
Keep these on your clipboard or paste them into a password manager — you'll need them in steps 3 and 4.
## Step 2 — Create a SentinelOne Service User (SOC role)
You can use a personal API token (tied to your user) for testing, but for the actual integration we recommend a dedicated **Service User** so the token survives if the original creator's account changes.
1. In the SentinelOne console: **Policies and settings → User management → Service Users**.
2. Click **+ New Service User**.
3. Fill in:
* **Name:** `clarion-integration`
* **Description:** `Used by Clarion to enrich and action threats.`
* **Scope:** prefer **Site** (the specific site you're forwarding from) over Account — least privilege.
* **Role:** **SOC**. This grants both read and edit access on Threats, so Clarion can enrich issues *and* run response actions (mitigate, isolate, set verdict/status). A custom role with equivalent Threats read/edit access also works. A read-only role (e.g. Viewer) only enriches issues and cannot action threats.
* **Expiration:** set to 1 year; rotate annually.
4. Save → the console shows the **API Token** once. Copy it immediately.
## Step 3 — Paste console URL and API token into Clarion
Back on Clarion's SentinelOne configure page, fill in **Console details**:
* **Console URL** — your tenant URL, e.g. `https://your-tenant.sentinelone.net`. No trailing slash.
* **Site ID / Account ID** — optional; populated automatically once the first real threat lands but you can pre-fill them if you have them.
* **API token** — paste the token from step 2.
Click **Save**. The page will show `API token (stored — leave blank to keep)` next to the field on subsequent visits, confirming the token is set.
## Step 4 — Configure the SentinelOne side
SentinelOne sends webhooks via the **Singularity Webhook** marketplace app. The built-in Notifications channels (SMTP, Syslog) don't support arbitrary headers, so the marketplace app is required for auth to work.
### 4a. Install Singularity Webhook
1. SentinelOne console → **Marketplace**.
2. Search for **Singularity Webhook**.
3. **Install** (or **Add Configuration** if already installed). Scope to the site you want to forward from.
### 4b. Configure Threat Response Action 1
In the configuration screen:
* Toggle **Make Response Actions available as Manual Response Actions from Threats** to **on** (so you can also fire the webhook manually from a threat in the SentinelOne console).
* Under **Advanced**, leave **Auto-Disable on Unauthorized Error** on.
* Expand **Threat Response Action 1**:
* **Name:** `Clarion`
* **Description:** `Forward threats to Clarion`
* **Automation Trigger Options:** `All Threats`
* **URL:** paste the **Clarion webhook URL** from step 1.
* **Action:** `POST`
* **Webhook Request Body:** switch to **Custom** (the presets ship without custom headers, so they can't authenticate).
### 4c. Custom Body
The webhook body only needs the threat ID — Clarion fills in the rest. Paste this as **Define custom message body**:
```json theme={null}
{ "threatId": "${activity.threatInfo.threatId}" }
```
Use the `${activity.…}` placeholder syntax (braces, not `$(…)` parentheses). `${activity.threatInfo.threatId}` and `${activity.id}` both resolve to the threat ID and work equally well.
### 4d. Headers
Set **Headers** to:
```json theme={null}
{"Content-Type": "application/json", "x-webhook-secret": "${Var1}"}
```
Then scroll down to the **Secret variables** section:
* **Var1 — Secret variable description:** `Clarion webhook secret`
* **Var1 — Secret variable value:** paste the **Clarion webhook secret** from step 1.
Click **Install**.
### 4e. Test the connection
In the Threat Response Action 1 view, click **Test Connection**. SentinelOne should report `Status 200` (or `201`) — and you should see a corresponding `webhook accepted: alert created` log line in your Clarion environment.
SentinelOne's "Test Connection" sends the template with `${activity.…}` placeholders unsubstituted (because there's no threat in scope during the test). A test issue *will* be created in Clarion with literal-string placeholder values in the payload — that's expected. A real threat detection produces the resolved payload.
## Step 5 — Verify with EICAR
The cleanest end-to-end test is the [EICAR test file](https://www.eicar.org/download-anti-malware-testfile/). On any enrolled endpoint:
```bash theme={null}
echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > /tmp/eicar.com
```
Within \~1 minute SentinelOne mitigates the file, posts the thin webhook to Clarion, and Clarion calls back to fetch the full threat. You should see an issue titled `[SentinelOne] eicar.com — ` under **Issues**, with full description (file path, SHA256, mitigation status, endpoint IP, site name, deep link back to the console).
## How severity is mapped
SentinelOne's payload doesn't include a `severity` field — only `confidenceLevel: "malicious" | "suspicious" | …`. Clarion maps it like this:
| SentinelOne `confidenceLevel` | Clarion severity |
| - | - |
| `malicious` | high |
| `suspicious` | medium |
| anything else | medium (default) |
If a custom template ever sends a `severity` field with `Critical`/`High`/`Medium`/`Low`/`Informational`, Clarion uses that directly and ignores the confidence fallback.
## Troubleshooting
### `webhook rejected: missing authentication header` in Clarion logs
The `x-webhook-secret` header isn't reaching Clarion. Most common causes:
* You switched the Singularity Webhook body mode from **Custom** to a preset; presets drop custom headers.
* The `Var1` value field is blank, while the headers JSON references `${Var1}`.
* The headers JSON has a syntax error and SentinelOne is silently sending no headers.
### `webhook rejected: invalid authentication token`
The `x-webhook-secret` value doesn't match what's stored on the Clarion integration. You probably rotated the secret in Clarion (disconnect + reconnect) and forgot to update Var1 in SentinelOne, or vice versa. Reconnect in Clarion and re-paste the new secret into Var1.
### Issues are created but with empty fields
The API token is missing, expired, or scoped to the wrong account/site, so Clarion can't pull the threat details. Regenerate the token in SentinelOne and re-paste it into Clarion's **API token** field.
### `${activity.…}` placeholders showing as literal text in the issue payload
You're most likely seeing a Test Connection issue, where placeholders don't substitute by design — see step 4e. If a real detection also shows the literal `${activity.threatInfo.threatId}` string, re-paste the minimal template exactly as shown in step 4c (braces, not `$(…)` parentheses).
### `Authentication issue occurred while running automated_response_actions. (1) Invalid json value for Body field`
SentinelOne validates the Custom Body as JSON at save time, before any substitution. A bare `${activity}` or `$(activity)` is not valid JSON. Only string-position placeholders (`"threatId": "${activity.threatInfo.threatId}"`) work.
## Why the API token matters
With the minimal body above, the webhook only carries the threat ID — Clarion needs the API token to turn that into a complete issue (threat name, classification, host, file, mitigation status, console link). The same token also lets Clarion run response actions back in SentinelOne (mitigate, isolate, set verdict/status), which is why we recommend the **SOC role** rather than a read-only one. Without a token, issues will be sparse, so we strongly recommend configuring one.
# Slack
Source: https://docs.cantina.security/clarion/integrations/slack
Install the Clarion app for Slack — what Clarion does, how it works inside Slack, where to find the Add to Slack button, and how your data is handled.
This page is the home of the **Clarion app for Slack**: what Clarion does, how it integrates with your Slack workspace, how to install and configure it, and how your data is handled.
## What Clarion does
[Clarion](https://clarion.cantina.xyz) is [Cantina](https://www.cantina.security)'s agentic security orchestration platform. Security teams are overwhelmed by fragmented tooling, alert fatigue, and manual response processes. Clarion connects to the tools in your security stack — SIEM, EDR, WAF, IAM, cloud providers, on-chain monitors, and more — ingests their signals into a single place, correlates related events in real time, and uses AI agents to triage, investigate, and respond: autonomously where you allow it, with human approval where you don't.
Slack is where your team meets Clarion. Agents deliver issue updates to your channels, ask for approval before running sensitive actions, and answer questions when you mention the app — so most of the day-to-day workflow happens without leaving Slack.
## How Clarion integrates with Slack
### Messages Clarion sends
Clarion posts to Slack in these situations:
* **Issue notifications** — when a monitor or a connected security tool raises something that needs attention, Clarion posts a summary to your configured notification channel.
* **Approval requests** — when an agent wants to run a gated action (for example, suspending a user account), it posts an approval request with interactive **Approve** / **Reject** buttons. The agent stays paused until someone responds or the request times out.
* **Clarification requests** — when an agent needs input to continue (a choice between options, or freeform input), it asks in the channel or via direct message.
* **Agent updates during investigations** — agents can post progress updates, reply in threads, and send direct messages to linked workspace members (for example, paging the on-call engineer).
* **Incident channels** — during incident response, agents can create a dedicated channel and invite the relevant responders. Creating a channel requires human approval by default; change this for **Create Slack Channel** in **Settings → Tools**.
* **Weekly triage summary** — every Monday morning Clarion posts last week's triage numbers (issues opened, triage runs, resolved, false-positive rate) together with the issues still waiting on a human and any integrations that need fixing. It posts to your Agent notifications channel by default, and is on by default — both can be changed on **Integrations → Slack**.
Agents can only post to channels and people that are explicitly configured as notification destinations or mentioned in your agent behavior and skills — they cannot pick arbitrary destinations.
![Clarion posting a critical issue notification and a tool-approval request in a Slack channel]()
### Messages Clarion responds to
* **@-mentions** — mention the Clarion app in any channel it has been invited to (for example, `@Cantina Clarion what happened with issue #42?`) to start a conversation. The app acknowledges with a 👀 reaction, then an agent replies in a thread. Mention it again in the same thread to ask follow-ups.
* **Button clicks** — **Approve** / **Reject** buttons on approval requests and option buttons on clarification requests are wired back to Clarion and resume the paused agent run.
![Mentioning the Clarion app in Slack and getting an agent reply in a thread]()
Only members of the connected Clarion workspace can converse with the app: if someone else mentions it, the app replies with a short explanation instead of answering.
***
## Installing — where the "Add to Slack" button is
The Clarion app for Slack is installed from inside the Clarion dashboard, so the install button becomes visible after you sign in:
1. Go to [clarion.cantina.xyz](https://clarion.cantina.xyz) and click **Log in** in the top-right corner — or **Get started** to create an account.
2. Once you're in your workspace, open **Integrations** in the sidebar.
3. Select **Slack** in the integrations catalog.
4. Click **Install Slack App** — this is the app's "Add to Slack" button. A new tab opens to Slack's standard authorization screen.
5. Check that the correct Slack workspace is selected in the top-right of Slack's page, review the requested permissions, and click **Allow**.
6. Slack confirms the installation and redirects you back to Clarion. Return to **Integrations → Slack** — the integration now shows **Installed app** along with your Slack workspace's name.
The bot token is captured automatically from Slack during installation; there are no keys to copy or paste.
**Estimated time:** about 5 minutes. You need access to a Clarion workspace with permission to manage integrations, and permission to install apps in your Slack workspace — some Slack workspaces require admin approval for new apps.
## After installing — first steps
1. **Choose a default notification channel.** On **Integrations → Slack**, the **Default notification channel** section appears once the app is installed. Type to search your channels, pick the one where Clarion should post notifications and approval requests by default — or click **Create channel** to make a fresh one such as `#clarion-alerts` — then click **Save**. Saving points agents at that channel for routine notifications and routes investigation approvals there; both can be changed later in your workspace settings.
2. **Give the channel list a moment.** Slack has no channel-search API, so Clarion keeps its own searchable copy of your channel list and syncs it in the background. Right after installing, a large Slack workspace can take a few minutes to finish; the picker shows the progress and how recently it synced. New channels and renames arrive within seconds after that.
3. **Using a private channel?** Invite the app by mentioning it in that channel — it becomes searchable straight away. Click **Refresh** if you'd rather re-sync the whole list.
4. **Link your team members.** Approval requests and direct messages reach people through their Slack identity. Members whose Slack email matches their Clarion email are linked automatically; everyone else can set their Slack handle in their notification settings. See [Members](/clarion/learn/settings#members).
5. **Check the weekly summary.** The **Weekly triage summary** section on **Integrations → Slack** controls the Monday digest: switch it off to opt out, point it at a different channel than your Agent notifications channel, or press **Send summary now** to post last week's digest immediately and confirm it lands where you expect.
6. **Say hello.** Invite the app to a channel and mention it — `@Cantina Clarion summarize the open issues` — to confirm everything works.
To learn more about how agents use notifications and approvals, see [Notifications](/clarion/learn/notifications).
## Permissions the app requests
| Slack scope | Why Clarion needs it |
| - | - |
| `chat:write`, `chat:write.public` | Post notifications, approval requests, and agent replies |
| `app_mentions:read` | See when someone mentions the Clarion app so it can respond |
| `channels:read`, `groups:read`, `im:read`, `mpim:read` | List channels and conversations so you can pick notification destinations |
| `channels:history`, `groups:history` | Read messages in channels the app is a member of, for incident context |
| `channels:join` | Join public channels it needs to post in |
| `channels:manage`, `groups:write` | Create incident channels and invite responders |
| `im:write` | Open direct messages with users, for example to page the on-call |
| `reactions:write` | Acknowledge messages with emoji reactions |
| `team:read` | Read your Slack workspace name to label the connection |
| `users:read`, `users:read.email` | Match Clarion members to Slack users for approvals and direct messages |
## Privacy and data handling
When you install the app, Clarion stores your Slack workspace ID and name and the bot access token (encrypted at rest). To operate, it also stores a searchable list of the channels the app can see (name, whether it is private or archived, and channel ID — never message content), the channels you configure for notifications, the mapping between Clarion workspace members and their Slack user IDs, and the Slack conversations the app takes part in — mentions of the app, its replies, and messages agents read for incident context — which are processed by Clarion's AI agents to generate responses.
Cantina's privacy policy explains in full how third-party data is collected, managed, stored, and deleted:
* **Privacy policy:** [cantina.security/privacy-policy](https://www.cantina.security/privacy-policy)
* **Terms of use:** [cantina.security/terms-of-use](https://www.cantina.security/terms-of-use)
* **Support:** [support@cantina.security](mailto:support@cantina.security)
## Reinstall or remove the app
* **Reinstall** — if the connection breaks or Clarion requests new permissions, the button on **Integrations → Slack** reads **Reinstall Slack App**; click it to run the authorization flow again.
* **Remove** — uninstall Clarion from your Slack workspace's app management page (**Settings & administration → Manage apps** in Slack). This revokes the bot token and stops all Clarion messages to that workspace.
# Splunk
Source: https://docs.cantina.security/clarion/integrations/splunk
Connect Splunk to Clarion so agents can forward an issue's details and original payload to your Splunk HTTP Event Collector (HEC) during triage.
This guide walks you through connecting Splunk to Clarion using the **HTTP Event Collector (HEC)**. Once connected, Clarion agents can forward the issue they are triaging — its details plus the original payload Clarion ingested — to Splunk as an event, so your issues and investigations land in your SIEM alongside the rest of your data.
**Estimated time:** 5 minutes. You will need access to **Splunk → Settings → Data Inputs → HTTP Event Collector** and the ability to create a token.
## Prerequisites
* A **Splunk** deployment (Splunk Cloud or Splunk Enterprise) with the **HTTP Event Collector** enabled
* Permission to create an **HEC token**
* Your **HEC endpoint URL**, including the port (Splunk Cloud and most self-hosted deployments use `8088`)
* The HEC endpoint must be reachable from Clarion's servers
* A **Clarion workspace** with the Splunk integration page open
***
## Step 1 — Create an HEC token in Splunk
1. Sign in to **Splunk**.
2. Go to **Settings → Data Inputs → HTTP Event Collector**.
3. Confirm the collector is enabled under **Global Settings** (toggle **All Tokens** to **Enabled**). Note the **HTTP Port Number** (default `8088`).
4. Click **New Token**.
5. Give the token a name (for example, `Clarion Integration`) and complete the wizard. You can optionally set a default **index**, **source**, and **sourcetype**.
6. Copy the generated **token value**.
Treat the HEC token like a password. Anyone with the token and endpoint can send events into your Splunk indexes.
***
## Step 2 — Find your HEC URL
The HEC endpoint depends on your Splunk deployment. Your stack's **web URL is not** the HEC endpoint.
| Deployment | HEC URL | Port |
| - | - | - |
| **Splunk Cloud (production)** | `https://http-inputs-.splunkcloud.com` | 443 (default) |
| **Splunk Cloud on GCP/Azure** | `https://http-inputs..splunkcloud.com` | 443 (default) |
| **Splunk Cloud free trial** | `https://.splunkcloud.com` | 8088 |
| **Self-hosted Splunk Enterprise** | `https://` | 8088 |
`` is the identifier in your Splunk Cloud URL (e.g. `prd-p-abc12` in `prd-p-abc12.splunkcloud.com`). Note the required `http-inputs-` prefix for production Cloud stacks.
Splunk Cloud **free-trial** stacks (and many on-prem deployments) present a **self-signed certificate**. For those, enable **Allow self-signed certificate** on the configuration form (see Step 3). Production Cloud stacks have valid certificates — leave it off.
## Step 3 — Enter credentials in Clarion
1. In Clarion, open **Integrations** and find **Splunk** under **Security & Monitoring**.
2. Enter your **HEC URL** from the table above. The `https://` scheme is optional (Clarion adds it), and you don't need the `/services/collector` path — Clarion appends it. Include `:8088` only for trial/self-hosted stacks.
3. Paste the **HEC token** from Step 1.
4. Optionally set a default **index**, **source**, and **sourcetype**. Leave these blank to use the defaults configured on the token.
5. If your stack serves a self-signed cert (trial / on-prem), enable **Allow self-signed certificate**.
6. Click **Connect**.
Clarion validates the endpoint and token by sending a single test event before saving. If the endpoint is unreachable or the token is rejected, you'll see a clear error and nothing is persisted.
***
## Step 4 — Verify events reached Splunk
Because **Connect** sends one test event, you can confirm data is landing right away.
1. In Splunk, open **Search & Reporting**.
2. Search the last 15 minutes for the test event:
```spl theme={null}
index=* "Clarion Splunk HEC connection test"
```
If you set a default **index** on the integration, scope to it (e.g. `index=security ...`). Otherwise events land in the index bound to your HEC token — use `index=*` if you're unsure which.
3. One matching event (with `forwarded_by=clarion`) confirms the endpoint, token, and index are all working.
To verify **agent-forwarded issues** later, search for the events Clarion sends during triage:
```spl theme={null}
index=* forwarded_by=clarion
```
Each event is JSON, so Splunk auto-extracts fields you can filter and report on:
| Field | Example | Meaning |
| - | - | - |
| `forwarded_by` | `clarion` | Marks events Clarion sent |
| `subject_kind` | `issue` | What was forwarded |
| `subject.reference` | `ISS-1423` | Clarion issue reference |
| `subject.severity` | `high` | Severity at forward time |
| `subject.url` | `https://app.clarion.com//issues/1423` | Link back to Clarion |
| `triage_summary` | `Confirmed benign…` | The agent's note, when provided |
| `original_payload.*` | — | The untouched payload Clarion ingested |
To find one specific issue, search by its reference — for example `index=* "ISS-1423"`. If you set a **sourcetype** (e.g. `clarion:issue`), `sourcetype="clarion:issue"` also scopes to Clarion's events.
***
## What agents can do
Once connected, agents on this workspace gain access to the `/splunk` action. When an agent uses it during triage, Clarion forwards a single event to your HEC endpoint containing:
* **Issue details** — number, title, description, severity, status, source, disposition, and a link back to the issue in Clarion
* **The original payload** — the untouched event Clarion ingested for the issue
* **The agent's triage summary** — an optional note the agent attaches describing its findings
The agent can override the destination **index**, **source**, or **sourcetype** per event; otherwise the defaults you configured are used. The event is sent to your collector's `/services/collector/event` endpoint.
To make an agent forward issues, add the **Splunk** action to a skill the agent runs (for example, a skill that forwards every confirmed threat to your SIEM).
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Splunk**.
2. Click **Disconnect**.
This deletes the stored HEC URL and token. Agents on this workspace will no longer see the `/splunk` action, and any saved skills that reference it will surface the integration as missing until you reconnect.
***
## Troubleshooting
### "Splunk rejected the HEC token"
The token is disabled or incorrect. In **Settings → Data Inputs → HTTP Event Collector**, confirm the token is **Enabled**, that **All Tokens** is enabled under **Global Settings**, and that you copied the full token value.
### "Splunk returned 404 — that URL isn't an HEC collector"
You're pointing at the wrong host — most often the stack's **web UI** instead of HEC. Use the HEC URL from the table in Step 2 (for production Splunk Cloud, the `https://http-inputs-.splunkcloud.com` form), and confirm HEC is enabled (**Global Settings → All Tokens → Enabled**). Clarion appends `/services/collector/event`, so enter only the base URL.
### "Self-signed certificate" / TLS errors
Your stack presents a certificate Clarion doesn't trust — common on Splunk Cloud **free-trial** stacks and on-prem deployments. Enable **Allow self-signed certificate** on the configuration form. Leave it off for production Cloud stacks (which have valid certificates).
### "Failed to reach the Splunk HEC endpoint"
The endpoint isn't reachable from Clarion's servers. If your collector is on a private network, expose it (or its HEC port) so Clarion can deliver events, then reconnect.
# Status Page
Source: https://docs.cantina.security/clarion/integrations/status-page
Crawl a third-party status page and raise an issue when your vendors publish an incident.
Your dependencies publish incidents on status pages nobody watches at 3am. This integration crawls them for you and turns each newly published incident into a Clarion issue — so a vendor outage reaches your queue as fast as one of your own alerts.
**Estimated time:** 2 minutes per page. You need only the status page URL.
## Prerequisites
* The public URL of a status page you want watched
* The page must be an **Atlassian Statuspage** or an **Instatus** page
## Connect
1. In Clarion, open **Integrations** and find **Status Page**.
2. Click **Connect** — the integration activates immediately; there is no credential.
3. Add a monitor per page, pasting its URL.
Clarion detects the provider and resolves the machine-readable source automatically: the `incidents.json` v2 API for Atlassian Statuspage, or the validated RSS/Atom feed for Instatus (which often lives on a different host).
Set a **default severity** per monitor so a page whose incidents always matter to you can be escalated harder than one that rarely does.
## How the crawl works
Each page is polled every two minutes. Clarion tracks the newest incident it has seen plus a set of recent incident ids, which is what makes new-incident detection reliable across both providers.
The first poll **seeds** the page rather than importing its entire history — you get the next incident, not a backlog. A page that is quiet on its first poll is still marked as seeded, so the first real incident afterwards is queued rather than being mistaken for backlog.
Per-monitor sync health is tracked like every other poller, so a page that moves or breaks surfaces as an integration health issue rather than going quietly silent.
## Where it helps
Status-page incidents give an agent the cheapest possible answer to "is this us?". A spike in errors that coincides with your CDN publishing a degradation is a very different investigation from the same spike with every vendor green.
## Disconnect
Click **Disconnect** on the integration page, or disable an individual monitor to stop watching one page.
# Supabase
Source: https://docs.cantina.security/clarion/integrations/supabase
Give agents read-only access to a Supabase project — security advisors, auth and Postgres logs, schema, and SQL — during an investigation.
Supabase is a hosted Postgres platform. Connecting it lets agents check what your database is actually doing while triaging: whether row-level security is off on an exposed table, whether the auth log shows a burst of failed sign-ins, when a schema change landed, and what a bounded query returns.
**Estimated time:** 2 minutes. You authorize Clarion through Supabase — there is no token to create or paste.
## Prerequisites
* A **Supabase** account with at least one project
* Permission to authorize an OAuth application for that organization
## Connect
1. In Clarion, open **Integrations** and find **Supabase**.
2. Click **Connect with Supabase**. You will be sent to Supabase to authorize Clarion for one organization.
3. Back in Clarion, choose the **project** agents may read.
Agents have no Supabase tools until a project is selected — the project is what scopes the connection. Access is stored encrypted, expires on its own, and is renewed automatically; it never enters the agent sandbox.
To revoke access outside Clarion, remove the Clarion app under your organization's **OAuth apps** in Supabase.
## Read-only by design
Clarion connects to Supabase in read-only mode, scoped to the single project you choose:
* Queries run as a **read-only Postgres user**, so a write fails rather than taking effect.
* The connection is **scoped to one project**, which also puts organization-level actions out of reach — agents cannot see, create, pause, or restore any other project in your organization.
* Only the **database** and **debugging** tool groups are enabled. Migrations, edge-function deploys, branching, and storage settings are not available at all.
* Every tool Supabase advertises is checked before an agent is given it, and anything that writes is refused — including a tool Supabase labels read-only but names as a write.
This is why the integration is safe to point at a production project. There is no setting that turns writes on.
Supabase's MCP server does not yet accept read-only OAuth grants — it currently requires an app to be granted every scope — so read-only rests on the four controls above rather than on the authorization itself. We will narrow the grant as soon as Supabase supports per-scope consent.
## What agents can do
The tool list is mirrored from Supabase and refreshed daily, so a read tool Supabase adds becomes available without waiting on a Clarion release. Today that is:
| Tool | What it returns |
| - | - |
| `get_advisors` | Supabase's own security and performance lints — RLS disabled on an exposed table, tables with RLS but no policy, `SECURITY DEFINER` views, mutable `search_path`, missing indexes |
| `query_logs` | Project logs from the last 24 hours — `auth`, `postgres`, `api`, `edge-function`, `storage`, `realtime` |
| `list_tables` | Tables and RLS status; columns, keys, and constraints when the agent asks for the verbose form |
| `list_extensions` | Installed Postgres extensions and versions |
| `list_migrations` | Applied migrations, so a schema change can be lined up with an incident |
| `execute_sql` | Rows from a read-only SQL query |
## Where it helps
Start with `get_advisors` for any question about exposure — it returns findings rather than customer data, and it is usually the fastest route from "is this project exposed?" to a concrete answer. Use `query_logs` with the `auth` service when investigating suspicious sign-in activity, and `list_migrations` when you need to know whether a schema change lines up with the start of an incident.
`execute_sql` reads your production data, and what it returns becomes part of the investigation record. Secret-shaped values are redacted before anything is stored or displayed, but that catches credentials, not personal data — nothing bounds which columns a query selects. If a project holds data you would rather no investigation ever surface, connect a project that does not.
## Change projects
The connection is bound to one project ref. To point Clarion at a different project, disconnect and reconnect with the new ref.
## Disconnect
Click **Disconnect** on the integration page. The stored token is deleted.
# Swif
Source: https://docs.cantina.security/clarion/integrations/swif
Connect Swif to Clarion so your managed device fleet and employee directory are discovered into the Brain as assets.
This guide walks you through connecting your Swif organization to Clarion. Once connected, Clarion discovers your managed devices into the Brain as **device** assets and your employee directory as **identity** assets, so an issue involving a person surfaces the laptops they carry — and their compliance posture — alongside it.
**Estimated time:** 3 minutes. You will need admin access to your Swif organization so you can generate an API token.
## Prerequisites
* A **Swif** organization, on either the US / Global or the EU tenant
* Admin access to **Settings → API token** in Swif
* A **Clarion workspace** with the Swif integration page open
***
## Step 1 — Generate an API token in Swif
1. Sign in to **Swif** as an admin.
2. Go to **Settings → API token**.
3. Click **Generate API key**.
4. Copy the generated token.
Copy the token immediately — Swif shows it once. Store it securely. The token is scoped to a single organization, so generate one per organization you want Clarion to see.
***
## Step 2 — Enter credentials in Clarion
1. In Clarion, open **Integrations** and find **Swif** under **Identity & Access**.
2. Pick your **Region**:
* **US / Global** for organizations on the global tenant
* **EU** for organizations on the European tenant
3. Paste the **API token** from Swif.
4. Click **Connect**.
A token generated on one tenant does not authenticate against the other. If Clarion reports that Swif returned a 404, try the other region.
Clarion verifies the token against your device inventory before saving. If the token is invalid or the region is wrong, you'll see a clear error and nothing is persisted.
***
## What Clarion discovers
Discovery runs on each asset sync — the manual **Sync** action or the scheduled auto-update. No extra configuration is needed beyond the token.
| Asset | What Clarion records |
| - | - |
| **Devices** | Name, model, device type, OS and build, serial number, enrollment and last check-in |
| **Device posture** | Disk encryption, antivirus, and password-manager status |
| **Employees** | Name, email, employment status, title, department, start and end dates |
### Linking devices to people
When a device's assigned owner in Swif matches a person Clarion already knows — from Okta, Google Workspace, or another connected directory — the device is linked to that person. Opening an issue that involves them shows their devices as related assets, so you can see at a glance whether the machine in question is encrypted and enrolled.
Swif employees are matched to people the same way, by email address. Because Swif's roster is typically fed from your HRIS or identity provider, these rows corroborate people Clarion already tracks rather than creating duplicates.
***
## Disconnect
To remove the integration:
1. In Clarion, open **Integrations → Swif**.
2. Click **Disconnect**.
This deletes the stored token. Devices and employees already discovered remain in the Brain as historical assets and simply stop refreshing.
***
## Troubleshooting
### "Swif rejected the API token"
The token is invalid, was revoked, or belongs to a different organization. Generate a fresh one under **Settings → API token** in Swif and reconnect.
### "Swif returned 404"
Your organization is almost certainly on the other regional tenant. Disconnect, then reconnect choosing the other **Region**.
### Only some devices appear
Each sync covers up to the first 10,000 devices and the first 10,000 employees Swif returns — fewer if the run's time budget is reached first — and Clarion notes the shortfall on the sync result. Swif's API exposes no changed-since filter, so every run re-reads the roster from the start — re-syncing will not reach the tail of a fleet larger than that. If your fleet is under 10,000 and the count still stays short, check that the token has not been scoped to a subset of your organization.
# Tailscale
Source: https://docs.cantina.security/clarion/integrations/tailscale
Connect Tailscale to Clarion to receive network and identity events — device approvals, key expiry, policy changes, and user lifecycle — as issues.
This guide explains how to connect Tailscale to Clarion. Once configured, Clarion receives Tailscale webhook events and opens issues that agents can triage and investigate.
**Estimated time:** 5-10 minutes. You will need **Tailscale Owner or Admin** access and access to the Clarion workspace where you want to connect Tailscale.
## Prerequisites
* A Tailscale account with Owner or Admin role
* Access to the Clarion workspace where you want to configure the integration
## Add a Tailscale monitor in Clarion
The Tailscale webhook is configured as a **monitor**, so each one has its own URL and signing secret.
1. Open Clarion and go to **Integrations** → **Tailscale**.
2. In the **Monitors** section, click **Add monitor** and choose **Tailscale**.
3. Copy the generated **Webhook URL** and **Secret** shown on the monitor. You will paste these into Tailscale in the next step.
## Configure the webhook in Tailscale
1. Sign in to the [Tailscale admin console](https://login.tailscale.com/admin).
2. Navigate to **Settings** → **Webhooks**.
3. Click **Add endpoint**.
4. Paste the **Webhook URL** from Clarion into the **Endpoint URL** field.
5. Paste the **Secret** from Clarion into the **Secret** field.
6. Select the event types you want to receive. Clarion handles all Tailscale event types:
* **Device events**: `nodeNeedsApproval`, `nodeApproved`, `nodeKeyExpiringSoon`, `nodeKeyExpiryDisabled`, `nodeKeyExpiryEnabled`, `nodeNotSeen`
* **Policy events**: `policyUpdate`
* **User events**: `userNeedsApproval`, `userApproved`, `userSuspended`, `userRoleUpdated`, `userCreated`, `userDeleted`
7. Click **Save**.
8. Use **Send test event** to verify the connection. Clarion will create a test issue to confirm delivery.
## Enable agent tools (API access)
Beyond receiving events, you can let Clarion agents act on your tailnet — investigating devices, users, keys, DNS, and ACL policy, and (with approval) running remediation such as deauthorizing a device or suspending a user. This uses a Tailscale **OAuth client**; the client secret is stored encrypted and is never exposed to agents.
1. Sign in to the [Tailscale admin console](https://login.tailscale.com/admin).
2. Go to **Settings** → **OAuth clients** and click **Generate OAuth client**.
3. Grant the client the scopes for the capabilities you want. The minimal set for the full tool suite is:
* `devices:core` — list/get devices, authorize/deauthorize, expire, set tags
* `devices:routes:read` — list device subnet routes
* `auth_keys:read` — list auth keys
* `users` — list/get users, suspend/restore
* `dns:read` — read DNS nameservers, preferences, and search paths
* `policy_file:read` — read the ACL policy file
* `account_settings:read` — read tailnet contacts
Grant only the scopes you need — for read-only investigation, use the `:read` scopes and omit `devices:core` and `users`.
4. Copy the **Client ID** and **Client secret** (the secret is shown only once).
5. In Clarion, go to **Integrations** → **Tailscale** → **API access (agent tools)**, paste the Client ID and secret, and click **Save**. Leave **Tailnet** blank to use the OAuth client's default tailnet.
The five write actions — authorize/deauthorize a device, set device tags, expire a device, and suspend/restore a user — require explicit human approval before an agent can run them. You can review and adjust approval requirements per tool under **Settings** → **Tools**.
## How severity is mapped
| Event | Severity |
| - | - |
| `nodeNotSeen`, `userSuspended`, `nodePolicyViolation` | Critical |
| `nodeNeedsApproval`, `userNeedsApproval` | High |
| `policyUpdate`, `userRoleUpdated`, `nodeKeyExpiringSoon`, `nodeKeyExpiryEnabled` | Medium |
| All other events | Low |
## Verifying the connection
After saving the webhook in Tailscale, send a test event from the Tailscale admin console. A test issue will appear in Clarion under **Issues**, confirming the integration is working.
# Telegram
Source: https://docs.cantina.security/clarion/integrations/telegram
Deliver Clarion approvals, clarifications, and alerts to a Telegram chat through your own bot.
Telegram is a [notification channel](/clarion/learn/notifications): agents deliver approval requests, clarification questions, and escalations into a Telegram chat, and replies resume the run.
**Estimated time:** 5 minutes. You will need the ability to create a bot with Telegram's **@BotFather**.
## Prerequisites
* A **Telegram** account
* A group or channel you want Clarion to post into
## Step 1 — Create a bot
1. In Telegram, open a chat with **@BotFather**.
2. Send `/newbot` and follow the prompts to name your bot.
3. BotFather replies with a **bot token** in the form `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`.
The bot token is a credential. Anyone holding it can post as your bot. Store it securely and rotate it from BotFather if it leaks.
## Step 2 — Add the bot to your chat
1. Add the bot to the group or channel you want notifications in.
2. Grant it permission to post messages.
3. Note the **chat ID** for that conversation — group and channel IDs are negative numbers, e.g. `-1001234567890`.
## Step 3 — Connect in Clarion
1. In Clarion, open **Integrations** and find **Telegram**.
2. Paste the **bot token** and click **Connect**.
3. Under **Add Channel**, give the destination a **name** (e.g. `Alerts`) and paste its **chat ID**.
You can add several channels — each becomes selectable as a [notification destination](/clarion/learn/notifications).
## What agents can do
| Tool | What it does |
| - | - |
| `send_message` | Post a message to a configured Telegram channel |
| `list_channels` | List the Telegram channels configured on this workspace |
## Rotate the token
Open **Integrations → Telegram** and enter a **New bot token**. Existing channels keep working.
## Disconnect
Click **Disconnect** on the integration page. Configured channels are removed, and any notification destination pointing at Telegram stops delivering.
# Tenderly
Source: https://docs.cantina.security/clarion/integrations/tenderly
Connect Tenderly to Clarion to receive smart contract monitoring alerts for AI-powered triage and response.
This guide walks you through connecting your Tenderly account to Clarion. By the end, Clarion will receive Tenderly alerts via webhooks and have API access to your Tenderly project for monitoring smart contracts and transactions.
***
## Prerequisites
* A Tenderly account with access to the project you want to monitor.
* Access to the Clarion dashboard.
***
## Step 1 — Generate a Tenderly Access Token
1. Open Tenderly and go to **Settings**.
2. Under settings, find the **Integrations** section and click **Generate Access Token**.
![]()
3. Give the token a descriptive name (e.g. `Clarion`).
![]()
4. Copy the access token immediately — it is only displayed once.
Store this token somewhere safe temporarily. You'll need it in the next step and won't be able to view it again.
***
## Step 2 — Connect Tenderly to Clarion
1. In Clarion, navigate to **Integrations** and find the **Tenderly** integration.
2. Paste the access token you copied in Step 1 and click **Connect**.
![]()
3. Once connected, click **Configure** on the integration page.
***
## Step 3 — Create a Monitor in Clarion
1. Switch to the **Monitor** tab and click **Add New Monitor**.
![]()
2. Go back to Tenderly **Settings** and copy your **Account Slug** and **Project Slug**.
![]()
3. Paste both slugs into the corresponding fields in Clarion.
4. Leave the **Webhook Secret** field empty for now — you'll fill it in after setting up the webhook in Tenderly.
5. Click **Create Monitor**. Clarion will generate a webhook URL that you'll need in the next step.
![]()
Copy the generated webhook URL — you'll use it to set up the destination in Tenderly.
***
## Step 4 — Set Up the Webhook Destination in Tenderly
1. In Tenderly, go to **Alerts** and switch to the **Destinations** tab.
![]()
2. Select **Webhook** as the type under **Add Destination**.
3. Paste the webhook URL generated by Clarion in Step 3.
4. Save the destination. Once created, Tenderly will display a **Signing Secret** for this webhook.
5. Copy the **Signing Secret**.
![]()
***
## Step 5 — Add the Signing Secret to Clarion
1. Go back to Clarion and open the monitor you created in Step 3.
2. Click on the monitor.
![]()
3. Paste the **Signing Secret** from Tenderly into the **Webhook Signing Secret** field.
![]()
4. Save the monitor.
Your Tenderly monitor is now fully configured and secured with the signing secret.
***
## Step 6 — Attach the Webhook to Your Alerts
1. In Tenderly, go to **Alerts** and review each alert rule that is defined.
2. For every alert you want Clarion to receive, edit the rule and ensure the Clarion webhook is set as a destination.
![]()
***
You're done! Clarion is now connected to Tenderly and will receive alerts for all configured monitors.
# Threat Intel
Source: https://docs.cantina.security/clarion/integrations/threat-intel
Bring vulnerability advisories, supply chain threats, and security feeds into Clarion for AI-powered triage and response.
The **Threat Intel** integration brings external security intelligence into Clarion for AI-powered triage. It is a built-in, auto-connected integration — there is no third-party account to link. Pick the monitor that matches how your intelligence is delivered; you can add both.
## Choose a monitor
Receive structured vulnerability advisories and supply chain threat payloads from a scanner or threat-intel service via a signed inbound webhook. Real time.
Subscribe to a published RSS or Atom feed — vendor security blogs, CERT/CSIRT bulletins, advisory feeds. Clarion crawls it and opens an issue for each new item.
## Which one do I need?
| | [Threat Intel webhook](/clarion/integrations/threat-intel/webhook) | [RSS Feed](/clarion/integrations/threat-intel/rss-feed) |
| - | - | - |
| **Direction** | Your sender pushes to Clarion | Clarion pulls from a URL |
| **Input** | Signed JSON (`vulnerability` / `threat`) | RSS 0.9/1.0/2.0 or Atom feed |
| **Latency** | Real time | Crawled every 6 hours (or on demand) |
| **Best for** | Scanners, vuln / supply-chain services | Security blogs, CERT bulletins, advisory & release feeds |
Threat Intel is auto-connected, so it already appears on the Integrations page — you only need to add the monitor you want. Both monitor types are managed from the same **Threat Intel** integration.
Clarion ships a built-in **Threat Intelligence** agent that triages advisories and feed items, correlating them to your environment. Assign it to either monitor (or both) to automate the first pass.
# RSS Feed
Source: https://docs.cantina.security/clarion/integrations/threat-intel/rss-feed
Subscribe Clarion to an RSS or Atom feed — security blogs, CERT/CSIRT bulletins, advisory feeds — and open an issue for each newly-published item.
The **RSS Feed** monitor subscribes Clarion to a published **RSS or Atom feed** — security advisory feeds, vendor security blogs, CERT/CSIRT bulletins, or release/changelog feeds. Clarion crawls the feed and opens an issue for each newly-published item, then triages it with AI agents.
**Estimated time:** 5 minutes. You will need a **Clarion workspace** and a public `https://` feed URL.
***
## Step 1 — Create the monitor
1. In Clarion, go to **Settings > Integrations**
2. Find **Threat Intel** and click **Add Monitor**
3. Pick the **RSS Feed** monitor type
4. Enter the **Feed URL** — a public `https://` RSS or Atom feed
5. Pick a **default severity** — RSS items carry no severity of their own, so every issue from this feed uses this value
6. Click **Create**
The feed must be reachable over public `https://`. For safety, Clarion refuses internal, private, or cloud-metadata addresses and re-checks every redirect hop.
***
## How crawling works
* Clarion crawls the feed **every 6 hours** automatically. You can also click **Crawl now** on the monitor's Configure page to fetch immediately.
* Supports **RSS 0.9 / 1.0 / 2.0** and **Atom**.
* The **first crawl** seeds the monitor with the feed's current contents and does **not** open issues for the existing backlog. After that, each newly-published item becomes one issue.
* Items are de-duplicated by their feed GUID, so re-seeing the same entry across crawls never creates a second issue.
***
## Opening issues for backlog items
To open issues for entries that already existed when you connected the feed:
1. Open the monitor's Configure page and click **Load latest**
2. Tick the items you want
3. Click **Create alerts for selected**
A single crawl opens at most 50 new issues, so a churning feed can't flood your workspace — the newest items are kept. Feed content is treated as untrusted: secret-shaped tokens are redacted before anything is stored or displayed.
***
## What happens next
Once configured, Clarion will automatically:
* Crawl your feed every 6 hours (and whenever you click **Crawl now**)
* Open an issue for each newly-published item, at the feed's default severity
* Triage incoming issues with AI agents and surface actionable insights
Clarion ships a built-in **Threat Intelligence** agent that triages feed items and correlates them to your environment. Assign it to this monitor to automate the first pass.
# Webhook
Source: https://docs.cantina.security/clarion/integrations/threat-intel/webhook
Send structured vulnerability advisories and supply chain threats to Clarion via a signed webhook for AI-powered triage.
The **Threat Intel webhook** monitor accepts structured JSON payloads describing a vulnerability or a supply chain threat — for example a scanner posting a CVE finding or a malicious-package detection. Clarion turns each into an issue and triages it with AI agents.
**Estimated time:** 5 minutes. You will need a **Clarion workspace** and a sender that can sign requests with HMAC-SHA256.
***
## Step 1 — Create the monitor
1. In Clarion, go to **Settings > Integrations**
2. Find **Threat Intel** and click **Add Monitor**
3. Pick the **Threat Intel** monitor type and give it a name
4. Click **Create**
Clarion generates a **webhook URL** and a **signing secret**. Copy both right away.
Copy the signing secret immediately — it is only displayed once. You can regenerate it later from the monitor's Configure page, but you cannot view the current value.
***
## Step 2 — Send signed events
Point your sender at the webhook URL with an HTTP `POST`. The body must be a JSON **object** up to **100 KB**, signed with HMAC-SHA256.
* Compute `HMAC-SHA256(raw_request_body, signing_secret)` and send the **hex digest** in the `x-signature` header.
* The payload must contain a `vulnerability` object, a `threat` object, or both. Either one alone is enough.
**`vulnerability` fields**
| Field | Required | Notes |
| - | - | - |
| `package` | Yes | Affected package name |
| `currentVersion` | Yes | Version in use |
| `fixedVersion` | No | Version that resolves the issue |
| `advisory` | No | Advisory ID (e.g. a CVE or GHSA) — prefixed onto the issue title |
| `severity` | No | Drives the issue's severity (see mapping below) |
**`threat` fields**
| Field | Required | Notes |
| - | - | - |
| `type` | Yes | Threat type (e.g. `malware`, `typosquat`) |
| `package` | Yes | Affected package name |
| `detectedVersion` | No | Version observed |
| `advisory` | No | Advisory reference |
| `severity` | No | Drives the issue's severity (see mapping below) |
| `indicator` | No | IOC / indicator string |
Any extra fields you include are preserved on the issue for the triage agent to reason about — nothing is dropped.
```bash theme={null}
SECRET=""
BODY='{"vulnerability":{"package":"lodash","currentVersion":"4.17.20","fixedVersion":"4.17.21","advisory":"CVE-2021-23337","severity":"high"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST "https:///api/webhooks/threat-intel/" \
-H "Content-Type: application/json" \
-H "x-signature: $SIG" \
-d "$BODY"
```
A successful request is accepted asynchronously (HTTP `202`); Clarion validates the payload and opens the issue on its worker. The issue title is derived from the payload — for example `CVE-2021-23337: Vulnerability in lodash@4.17.20` or `Supply chain threat: typosquat (left-pad@1.0.0)`.
***
## Severity mapping
The issue severity comes from the payload's `severity` string (the `vulnerability` value takes precedence over the `threat` value):
| Payload `severity` | Clarion severity |
| - | - |
| `critical` | Critical |
| `high`, `error` | High |
| `medium`, `moderate`, `warning` | Medium |
| `low`, `info`, `informational`, `note` | Low |
| *(missing or unrecognized)* | High |
***
## What happens next
Once configured, Clarion will automatically:
* Accept signed payloads at the monitor's webhook URL
* Open an issue for each vulnerability or threat, with the severity mapped above
* Triage incoming issues with AI agents and surface actionable insights
Clarion ships a built-in **Threat Intelligence** agent that triages advisories and correlates them to your environment. Assign it to this monitor to automate the first pass.
# Twilio (SMS & phone)
Source: https://docs.cantina.security/clarion/integrations/twilio
Reach members by SMS or a voice call for high-urgency events.
Twilio powers Clarion's **SMS** and **phone call** channels. Both are for urgency rather than interaction: an SMS or a call gets a human's attention, and the conversation continues in Clarion, Slack, or Teams.
Twilio is configured by your Clarion platform administrator, not per workspace. If the integration page says Twilio is not yet configured, contact your administrator.
## Prerequisites
* Twilio enabled for your Clarion instance
* Workspace members with a **verified phone number** on their profile
## Connect
1. In Clarion, open **Integrations** and find **Phone**.
2. Click **Connect**.
3. Send a **test SMS** or place a **test call** to a member to confirm delivery.
Members set their own phone number in their profile — see [Members](/clarion/learn/settings#members). A member without a number cannot be reached by SMS or call and will not appear in the picker.
## As a notification destination
SMS can be selected as a [notification destination](/clarion/learn/notifications), targeting one or more workspace members.
SMS is **notification only**. It carries no interactive approval buttons, so an approval request delivered by SMS still has to be answered in Clarion, Slack, or Teams. Pair SMS with an interactive channel rather than using it alone.
## What agents can do
| Tool | What it does |
| - | - |
| `send_sms_to_member` | Text a workspace member |
| `make_call_to_member` | Place a voice call to a workspace member |
| `list_workspace_members` | List members reachable by phone |
Both send actions are scoped to workspace members — an agent cannot dial an arbitrary number.
## Disconnect
Click **Disconnect** on the integration page. SMS destinations stop delivering and the phone tools disappear from agent skills.
# Vanta
Source: https://docs.cantina.security/clarion/integrations/vanta
Connect a Manage Vanta Application so Clarion agents can read live compliance and vendor-risk data and perform separately approved writes.
Clarion's native Vanta integration uses the [Manage Vanta REST API](https://developer.vanta.com/reference/manage-vanta/overview). It queries your Vanta tenant live; it does not copy Vanta vulnerabilities, assets, issues, tests, controls, frameworks, discovered vendors, managed vendors, or documents into Clarion.
You need Vanta administrator access to create a **Manage Vanta Application**. This connection is for automating your own Vanta tenant, not the Vanta public marketplace OAuth flow.
## Create a Manage Vanta Application
1. In Vanta, create a Manage Vanta Application for Clarion.
2. Set the application's **Access level** to **Read and write**. Clarion requests `vanta-api.all:read`, `vanta-api.all:write`, and `vanta-api.documents:upload` during token exchange; Vanta does not ask you to select those scopes individually. See Vanta's [document upload guide](https://developer.vanta.com/docs/guides/upload-a-document).
3. Copy the client ID and client secret.
Clarion requests all three scopes when it validates or refreshes a token. Vanta remains the authority that grants or rejects those scopes. Vanta issues one one-hour token per application and revokes the prior token when another is issued, so use a dedicated Manage Vanta Application for each Clarion workspace and do not reuse it in another token-minting service.
## Connect Vanta in Clarion
1. Open **Integrations → Compliance & GRC → Vanta**.
2. Enter the client ID and client secret.
3. Click **Connect Vanta**.
Clarion validates the credentials server-side before completing setup. The client secret and cached access token are encrypted in Clarion and are never returned to the browser, put in schedule prompts, or sent to agent sandboxes. Use **Verify connection** to run a bounded live health check.
## Agent tools
Connected chats, agents, and scheduled agent runs can read bounded, cursor-paginated pages of Vanta vulnerabilities, vulnerability remediations, tests, documents, controls, frameworks, issues, discovered vendors, discovered-vendor accounts, and managed vendors. They can also inspect managed-vendor risk attributes, assessments, security reviews, findings, and document metadata. Vendor-document tools do not download or return document content or document URLs. Detail tools accept exact opaque Vanta IDs.
Evidence delivery has two separate tools:
* `upload_document_evidence` uploads a trusted Clarion knowledge artifact or server-built issue export to an existing Vanta document as a draft.
* `submit_document` submits that document and makes the evidence auditor-visible.
Both are external writes and require human approval in Clarion, even though the Vanta application has write scopes. Upload never submits implicitly, and a submission requires its own approval. Agents cannot upload from arbitrary URLs, host filesystem paths, or inline base64 data.
`add_discovered_vendor_to_managed` is another separate external write. It converts one exact discovered vendor into a managed Vanta vendor and always requires human approval. Reviewing or recommending a vendor never invokes it implicitly.
## New Vendor Risk Reviewer
The built-in **New Vendor Risk Reviewer** handles operational vendor-risk review. It reads Vanta's live `NEEDS_REVIEW` discovered-vendor queue, gathers bounded account and device usage context, checks for existing managed-vendor duplicates, and includes available risk attributes, assessments, security reviews, findings, and document metadata. It returns an evidence-backed digest and prioritized investigation queue.
For each discovery, the reviewer presents account coverage and pagination completeness in a compact summary table, then lists every distinct associated user's display name and email address in a per-vendor contact table. A separate device table maps each computer display name to the owner's name and email when Vanta provides them; computers without an owner are marked accordingly. The reviewer follows account cursors to completion and does not silently replace the full result with a first-page sample. These contacts show who is associated with the discovery so reviewers can follow up, but they are not treated as confirmed vendor business owners. The reviewer identifies contacts only and never messages them automatically.
This differs from the **SOC 2 Evidence Collector**, which samples Clarion vulnerability issues and delivers approved draft compliance evidence. The vendor reviewer does not collect SOC 2 evidence and does not synchronize Vanta vendors into Clarion.
The reviewer includes a user-editable weekly schedule for Monday at 08:00 UTC. The schedule is pinned to the installed agent, operates live against Vanta, and is strictly read-only: it never converts, ignores, or rejects vendors and never creates tickets or other external records. Deactivating the agent prevents its scheduled runs.
Adding a discovery to managed status is a separate, approval-required action. The current [Manage Vanta OpenAPI specification](https://developer.vanta.com/reference/manage-vanta.json) does not expose mutations for ignoring or rejecting discovered vendors, so those recommendations must be completed manually in Vanta. Richer risk data can also be absent until a discovery becomes a managed vendor; missing Vanta risk data is not proof that a vendor is safe.
The reusable **Review newly discovered Vanta vendors** skill is available independently in Clarion's skill catalog, so it can be attached to custom agents as well as the built-in reviewer.
## SOC 2 Evidence Collector
The built-in **SOC 2 Evidence Collector** runs monthly on the first day of the month at 09:00 UTC. Its schedule is pinned to the created agent and remains editable in Clarion. Deactivating the agent prevents scheduled execution.
The agent samples Clarion vulnerability issues, verifies linked remediation pull requests with the existing GitHub tools, lists Vanta documents live, and asks for clarification if several documents could be the target. An approved upload creates draft evidence. The monthly schedule never submits the document automatically.
If Vanta is disconnected before a run, its tools are omitted and either built-in agent reports the missing integration instead of receiving credentials or repeatedly calling a broken endpoint.
## Disconnect or rotate credentials
Use **Update credentials** after rotating the Vanta client secret. Clarion validates the replacement before persisting it. Use **Disconnect** to delete the workspace's Vanta integration and encrypted credentials; Vanta tools then disappear from new agent runs.
## Troubleshooting
* **Credentials rejected:** verify the client ID/secret and that the application uses the client-credentials grant.
* **Scope or operation denied:** grant all three required scopes to the Manage Vanta Application, then update the credentials in Clarion so they are validated again.
* **Rate limited:** wait and retry. Clarion reuses a valid cached token instead of minting one per tool call.
* **Document is ambiguous:** select or name one intended document; Clarion does not assume tenant-specific document IDs.
This release does not add Vanta MCP, webhooks, automatic polling, bulk synchronization, or public marketplace OAuth.
# Vercel
Source: https://docs.cantina.security/clarion/integrations/vercel
Monitor deployments, runtime errors, firewall attacks, and domain health — and sweep for unintended public exposure.
Connecting Vercel gives Clarion visibility into your deployments and the edge in front of them, and feeds two agents: **Vercel Platform** for operational and security events, and the **Exposure Agent** for finding sites that are public when they shouldn't be.
**Estimated time:** 3 minutes. You will need permission to install an integration on your Vercel team.
## Prerequisites
* A **Vercel** team where you can install integrations
* The Vercel integration configured for your Clarion instance (contact your administrator if the page says otherwise)
## Connect
1. In Clarion, open **Integrations** and find **Vercel**.
2. Click **Install** — you are taken to Vercel to authorize the integration.
3. Choose the team and the projects Clarion may see.
4. Return to Clarion; the integration appears as connected.
## What Clarion ingests
Events that feed the **Vercel Platform** agent:
* Deployment failures and their build output
* Runtime errors
* Firewall and attack-challenge activity
* Domain and certificate health
## Project discovery into the Brain
Clarion discovers your projects and deployments as assets, along with firewall configuration, log drains, and edge configs. Projects correlate with the repositories that build them and the services that observe them, so a deployment failure resolves to the code and the service behind it.
## What agents can do
| Tool | What it returns |
| - | - |
| `list_projects` / `get_project` | Project inventory and configuration |
| `list_deployments` / `get_deployment` | Deployments and their state |
| `get_deployment_events` | Build and runtime event stream for a deployment |
| `list_domains` / `get_domain_config` | Domains and their DNS/certificate configuration |
| `list_members` | Team membership |
| `trigger_redeployment` | Re-deploy — used for production rollback and recovery |
`trigger_redeployment` changes production. It is gated by your workspace's tool policy and asks for approval unless you have explicitly allowed it.
## Exposure sweeps
The [Exposure Agent](/clarion/learn/agents#our-agents) uses this integration for its daily sweep: it enumerates hosts and probes each one's root over read-only HTTPS from the Clarion sandbox, then files an issue per site that is publicly reachable and shouldn't be. Verdicts are written back to the Brain, so a site you confirm as intentionally public stops re-reporting.
Because the probe runs from the sandbox, that sweep requires the **Bash** tool category at *Protected* or above.
## Disconnect
Click **Disconnect** in Clarion, then remove the Clarion integration from your Vercel team.
# Wiz
Source: https://docs.cantina.security/clarion/integrations/wiz
Connect Wiz to Clarion to ingest prioritized cloud security Issues, sync your cloud inventory, and let agents investigate and comment back in Wiz.
This guide walks you through connecting a Wiz tenant to Clarion. Once connected, Clarion ingests prioritized Wiz Issues over a webhook, syncs cloud inventory into the Brain, and lets agents investigate and write back in Wiz with human approval.
**Estimated time:** 20–25 minutes. You need a **Wiz admin** who can create a Custom Integration (GraphQL API) service account, plus `integrations:manage` in the Clarion workspace.
## Prerequisites
* A **Wiz admin** who can create a **Custom Integration (GraphQL API)** service account. Clarion cannot grant provider permissions.
* The **GraphQL API endpoint** from Wiz **Tenant settings**
* A **Clarion workspace** where you have `integrations:manage`
***
## Step 1 — Create the service account
1. In Wiz, go to **Settings → Access Management → Service Accounts** ([direct link](https://app.wiz.io/settings/service-accounts)) and create a service account of type **Custom Integration (GraphQL API)**.
2. Scope it to only the Wiz projects Clarion should see.
### Required scope
| Scope | Covers |
| - | - |
| `read:all` | Issue ingestion and investigation, project and inventory context, vulnerability findings, SBOM, Graph Entity, and CloudEvents |
### Optional writeback scopes
Grant each optional scope only if you want the matching Clarion agent tool:
| Scope | Enables |
| - | - |
| `write:issue_comments` | Add comments to regular Wiz Issues |
| `write:issue_status` | Mark in progress, reopen, and reject regular Issues |
| `write:threat_issue_comments` | Add comments to Threat Detection Issues |
| `write:threat_issue_status` | Mark in progress, reopen, and resolve Threat Detection Issues |
***
## Step 2 — Enter credentials in Clarion
1. Open Clarion and go to **Integrations → Wiz**.
2. Enter the **API URL** — the GraphQL endpoint from Tenant settings, for example `https://api.us1.app.wiz.io/graphql`. Clarion accepts commercial hosts only; government GraphQL hosts are unsupported.
3. Choose the **Token URL** that matches your tenant:
| Provider | Token URL |
| - | - |
| Amazon Cognito (default) | `https://auth.app.wiz.io/oauth/token` |
| Auth0 | `https://auth.wiz.io/oauth/token` |
4. Enter the **Client ID** and **Client Secret**.
5. Click **Save**.
Save validates that Wiz accepts the OAuth client credentials and that the fixed `issuesV2` access check passes. Wiz does not return a trustworthy granted-scope list, so Clarion does not verify the full read surface or the optional write scopes. A missing write permission surfaces when the tool runs.
***
## Step 3 — Add the Issues monitor in Clarion
The Issues monitor is available only after the service account validates.
1. On **Integrations → Wiz**, create the Issues monitor. Clarion generates the webhook URL and a bearer token.
Copy the bearer token immediately — Clarion shows it once.
Keep both values at hand; the next two steps paste them into Wiz.
***
## Step 4 — Create the Webhook integration in Wiz
An Automation Rule can only point at a Webhook integration that already exists, so create the integration before you build the rules. One integration serves both.
1. In Wiz, go to **Settings → Deployments → Integrations** and add an integration. Under **Connect**, search for **Webhook** — or jump straight to [the new-webhook form](https://app.wiz.io/settings/deployments/integrations/new/webhook).
2. Fill in the form:
| Field | Value |
| - | - |
| Name | Anything recognizable, for example `Clarion`. Names must be unique per tenant. |
| Project Scope | The projects Clarion should receive Issues for |
| URL | The webhook URL from Step 3 |
| Authentication | **Token**, with the Clarion bearer token as the value — Wiz then sends `Authorization: Bearer ` |
3. Leave **Additional Headers**, **Custom Certificate Authority**, and **Client Certificate** empty, and leave **This server is only accessible on-premises** unchecked — Clarion's webhook endpoint is public and uses a publicly trusted certificate.
4. Save the integration.
This form has no request body. The body is set per Automation Rule in the next step, so one Webhook integration can serve several rules.
***
## Step 5 — Create the Automation Rules
Two rules cover everything Clarion ingests. Both point at the same Webhook integration and post the same body.
| Rule | Trigger source | Covers | Clarion Issue kind |
| - | - | - | - |
| Risk | **Risk Issue** | Toxic combination and cloud configuration Issues | risk |
| Threat | **Threat** | Threat detection Issues | threat |
For each of the two:
1. In Wiz, go to **Automation → Automation Rules** and click **Create Rule**.
2. Name the rule and set **Project Scope** to the same projects as the Webhook integration.
3. Under **Rule Conditions**, set **WHEN** the trigger source from the table **IS** **Created**.
4. Under **Then**, add an action, choose **POST a Webhook**, and select the Webhook integration you created in Step 4.
5. Replace the default body with the template from the Clarion page exactly (Clarion stores it as `wizIssuesWebhookTemplate`):
```json theme={null}
{
"schemaVersion": "wiz-issues/v2",
"issue": {
"id": "{{issue.id}}"
}
}
```
6. Save the rule and switch it **ON**.
The body is identical for both rules. The payload is thin on purpose: Clarion stores the notification durably, then fetches the authoritative snapshot from Wiz by Issue ID and reads the type from it, so the trigger source needs no marker in the payload.
`{{issue.id}}` is the right variable for both trigger sources. The **Detection** trigger source uses a different shape (`{{detection.issue.id}}`) — Clarion does not ingest it, so do not add a third rule for it.
Keep the rules on these two trigger sources. A Wiz Issue whose type is outside `TOXIC_COMBINATION`, `CLOUD_CONFIGURATION`, and `THREAT_DETECTION` still creates a Clarion Issue, but with no kind set, so it will not match kind-scoped agents or views.
***
## What happens next
* A new active provider Issue creates one Clarion Issue. Later deliveries refresh the Wiz snapshot only and never change Clarion workflow status.
* Connected triage agents pick up new Issues.
* **Sync assets** pulls only the Wiz cloud inventory into the Brain and classifies it into compute, datastore, network, and identity.
***
## Agent tools
Once connected, triage agents can use Wiz tools. Every Wiz write requires explicit human approval in Clarion.
**Read tools:** Issue lookup and search, Issue evidence, project context, Graph Entity, CloudEvents search, vulnerability findings, SBOM artifact groups and component exposure, repositories, technologies, hosted technologies.
**Write tools:** Issue comment, mark in progress, resolve, reject, reopen.
***
## Rotate the bearer token
Rotate the token in Clarion, then replace the **Authentication → Token** value on the Wiz Webhook integration ([Settings → Deployments → Integrations](https://app.wiz.io/settings/deployments/integrations)). Deliveries fail in between. The Automation Rules need no change — they reference the integration, not the token.
***
## Rotate the client secret
Re-save the service account in Clarion with the new secret. Changing credentials invalidates the bound asset-inventory, SBOM, and vulnerability-finding sync state, so the next sync starts clean.
***
## Troubleshooting
### Save fails
* Wrong GraphQL endpoint (a government host is rejected by design)
* Wrong token URL for the tenant
* Missing `read:all`
### Issues stop arriving, or only some types arrive
* Token was rotated in Clarion but not in the Wiz Webhook integration
* A rule is switched **OFF**, or was never created for that trigger source — check both
* A rule and the Webhook integration are scoped to different projects
### A write tool reports a missing permission
The optional scope was never granted. Clarion never probes for it with a test mutation.
# Zscaler
Source: https://docs.cantina.security/clarion/integrations/zscaler
Receive Zscaler Internet Access security and UEBA alerts as Clarion issues over a per-monitor webhook.
Clarion receives **Zscaler Internet Access (ZIA)** Security and UEBA alerts over a webhook, turning each one into an issue for agent triage.
**Estimated time:** 10 minutes. You will need admin access to the ZIA Admin Portal to configure a webhook destination.
## Prerequisites
* A **Zscaler Internet Access** tenant
* Admin rights to configure alert webhooks in the ZIA Admin Portal
## Step 1 — Create the monitor in Clarion
1. In Clarion, open **Integrations** and find **Zscaler**.
2. Click **Connect** and add a monitor.
3. Clarion generates a **webhook URL** and a **shared secret**, shown once.
The secret is per monitor and stored encrypted. It authenticates the webhook — it travels in the request, never in the URL. Copy it when it is shown.
## Step 2 — Configure the webhook in Zscaler
1. In the **ZIA Admin Portal**, open the alert or webhook configuration for Security and UEBA alerts.
2. Add Clarion's webhook URL as the destination.
3. Configure the shared secret so Clarion can verify each delivery.
4. Send a test alert to confirm delivery.
Clarion rejects deliveries that fail verification, so a misconfigured secret shows up immediately rather than silently dropping alerts.
## What Clarion ingests
ZIA **Security** alerts (policy blocks, malware and threat detections, risky destinations) and **UEBA** alerts (anomalous user behaviour). Each becomes an issue with severity mapped from the Zscaler payload.
## Triaging Zscaler alerts
Zscaler alerts route well to the identity and endpoint skill domains — a UEBA anomaly is usually best pursued through the user's identity provider and their device, both of which Clarion can reach if those integrations are connected.
## Disconnect
Click **Disconnect** on the integration page, and remove the webhook destination from the ZIA Admin Portal.
# Knowledge base
Source: https://docs.cantina.security/clarion/knowledge-base
A collection of answers to frequently asked questions.
## Guides
Set up your workspace, connect your first integration, and activate your first agent.
## Looking for something else?
Understand how issues, agents, skills, and tools fit together.
Setup instructions for every tool Clarion connects to.
# Introduction
Source: https://docs.cantina.security/clarion/learn
An overview of how Clarion's core concepts fit together, from incoming events to issues to response.
This section walks through the building blocks of the platform: what each one does, how they relate, and how to put them to work.
## Concepts at a glance
Your integrations feed Clarion two kinds of input. Some send a finished alert, which becomes an **issue** as-is. Others send raw events — **signals** — and those become issues only when an **alert filter** (signal rule) matches one. Issues are the top-level work items; related findings link under a shared parent so a campaign stays one investigation. **Agents** triage them using **skills** and **tools** (integrations that fetch context or take action). **Tasks** track follow-up work that outlives the issue. **Notifications** route approvals and clarifications to whoever needs to answer.
The top-level work items: security events from connected integrations, deduplicated and prioritized for triage.
Work items for follow-ups, agent improvements, and operational actions.
AI responders that investigate issues, execute response actions, and ask for approval when needed.
Reusable playbooks describing how to respond to specific situations.
Integrations agents invoke to take action, like Slack messages, DNS changes, and Jira tickets.
In-app and external notifications, including approval and clarification requests from agents.
Configure your workspace, manage members, and enforce SSO.
## How an issue becomes a response
A typical flow:
1. **Issue opened**: An event arrives from a connected integration, either as a finished alert or after an alert filter matches an incoming signal.
2. **Triage**: An agent picks up the issue, follows the relevant skills, and calls tools to gather context. The agent produces a triage report with disposition and recommendations.
3. **Response**: The agent executes through tools (revoking a token, posting to Slack, opening a Jira ticket) or escalates to your team via notifications. Sensitive actions pause for human approval.
4. **Closure**: You resolve or close the issue once the threat is contained or ruled out. Anything left over becomes a task.
You don't have to build any of this from scratch. Clarion ships with agent templates, alert filter libraries, and skill templates for the most common SOC workflows.
## Beyond the docs
What Clarion does, in one page.
How agentic response works, from the outside in.
The full catalogue of what Clarion connects to.
Security, compliance, and data handling.
# Agents
Source: https://docs.cantina.security/clarion/learn/agents
Learn how agents triage issues, investigate them, and execute response actions in your security stack.
Agents are AI-powered responders that investigate every issue. They pick the right skill to follow, run tools to gather context, and either close the issue, escalate it to your on-call members, or ask a human for approval to continue.
## What an agent is
An agent is a configured responder defined by:
* **Monitors**: The event sources it pays attention to.
* **Skills**: A skill is a reusable playbook that teaches the agent how to perform a specific class of tasks to a known standard, along with the tools available to investigate and remediate security issues.
* **Tools**: The actions it can execute, assigned through skills (Slack, DNS, Jira, AWS, and more).
* **Notification preferences**: How it requests human approval or clarification.
Start from a **template**, with pre-built agents for common SOC workflows like Smart Contract Security, Identity & Access, or DNS Infrastructure, or build one from scratch. For the product-level view of how agentic response works, see [Agents on cantina.security](https://www.cantina.security/agents).
## What an agent does
* **Triages issues**: Produces a summary, report, recommendations, and risk assessment for every issue that matches its monitors.
* **Digs in on escalations**: Runs deeper analysis once an issue is escalated.
* **Executes response**: Calls tools to remediate (revoke a token, change a DNS record, post to Slack, file a Jira ticket).
* **Asks for approval**: Requests human approval before sensitive actions, or clarification when input is needed to proceed.
* **Resumes**: Suspended or paused investigations resume automatically once a human responds.
Agents only do what their skills tell them to do. The right way to change an agent's behavior is to update or add a skill, not to rewrite the agent itself.
Every agent template Clarion ships, and what each one covers.
Build an agent from a template or from scratch.
Configure the event sources your agents pay attention to.
Agents that go looking rather than waiting.
The memory every agent reasons with.
Tiers, failover, your own key, subagents, and batching.
## Our agents
Clarion ships **33 agent templates**. Each one bundles the monitors it listens to, the skills that tell it how to respond, and — for the scheduled ones — a recurring job. Create an agent from a template and it arrives configured; fork any skill afterwards to make it yours.
Templates come in two shapes:
* **Monitor-driven** — the agent wakes up when a connected integration sends an event, and triages the issue that event produces.
* **Scheduled** — the agent has no monitors. It runs a recurring sweep against your connected tools and files issues from what it finds. Deactivating the agent pauses the sweep.
### Cloud & platform
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **Cloud Security (AWS)** | IAM privilege escalation, root-account use, credential exposure, compute compromise, data exfiltration, log tampering | CloudTrail, GuardDuty | 10 |
| **Amazon Inspector** | Package CVE, code vulnerability, and network-reachability triage with AWS asset blast-radius estimation | Amazon Inspector | 2 |
| **Cloud Security (Azure)** | Defender for Cloud alerts, Entra ID and RBAC privilege abuse, Storage and Key Vault exposure, network and compute compromise, Secure Score remediation | Defender for Cloud | 10 |
| **Cloud Security (GCP)** | Audit-log privilege abuse, service-account key compromise, unauthorized compute, Security Command Center findings | Cloud Logging, Security Command Center, Cloud Monitoring | 7 |
| **Wiz** | CNAPP issues routed by type — toxic combinations, threat detections, entitlement findings, vulnerability exposure | Wiz Issues | 5 |
| **Cloudflare Notifications** | DDoS and WAF attacks, origin and edge availability, DNS and zone integrity, certificate lifecycle, client-side security | Cloudflare Notifications | 5 |
| **Cloudflare Logpush** | L7 DDoS detection windows, origin exposure and DNS bypass checks, incident handoff | Cloudflare Logpush (`firewall_events`) | 3 |
| **Vercel Platform** | Deployment failures, runtime errors, firewall attacks, domain health, production rollback | Vercel | 3 |
| **Infrastructure & Ops** | Uptime and outage runbooks, host threats, suspicious SSH activity | Grafana, Better Stack, Falco | 1 |
### Identity & access
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **Identity & Access** | Impossible travel, brute force, MFA attacks and session hijacking, OAuth and app abuse, admin compromise, federation abuse, policy weakening, phishing response | Okta, Google Workspace, JumpCloud | 14 |
| **1Password** | Burst failed sign-ins, user suspension, vault item exports and the grant-then-export sequence | 1Password Events Reporting | 4 |
### Endpoint & detection
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **Microsoft Sentinel & Defender XDR** | Incident triage and KQL hunting, plus scenario playbooks for identity compromise, phishing, endpoint forensics, ransomware scoping, Azure control-plane attacks, UEBA anomalies | Microsoft Sentinel | 8 |
| **Endpoint Monitoring** | Script and LOLBin execution, persistence, credential access, sensor tampering, lateral movement, C2 and exfiltration, ransomware | CrowdStrike Falcon | 9 |
| **Microsoft Defender XDR** | Correlated incident hydration with Entra pivots, routed to identity scenario playbooks | Microsoft Defender XDR | 5 |
| **SentinelOne** | Threat triage, investigation and scoping, gated containment, false-positive handling and exclusions | SentinelOne Singularity | 4 |
| **Huntress** | Verifies the Huntress SOC's report, reconstructs the attack chain, then hands containment to your EDR or identity path — Huntress is read-only in Clarion | Huntress Managed EDR/MDR, ITDR | 3 |
### DNS & external exposure
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **DNS & Domain Security** | Record and subdomain changes, email-auth (SPF/DKIM/DMARC) changes, new subdomain discovery, registrar hijack, DNS tunneling, DDoS amplification | DNS monitor | 7 |
| **Exposure Agent** | Sweeps every connected provider for deployments reachable from the public internet that were not meant to be, and remembers verdicts so known-public sites stop re-reporting | Scheduled — daily | 4 |
| **Dangling Subdomain Agent** | Sweeps every Cloudflare zone for records pointing at a target nobody owns, asking each connected provider whether a live resource still serves it | Scheduled — daily | 2 |
### Code, supply chain & SDLC
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **Code & Supply Chain** | Tag spraying, CI/CD script injection via branch names, force pushes to default branches, repository visibility changes, branch-protection weakening, org-owner additions | GitHub | 7 |
| **Claude Code Governance** | Batched decisions on undecided MCP servers, use of explicitly denied servers, telemetry from outside your email domains, sessions that read a credential-shaped path and then reached the network | Claude Code telemetry + weekly sweep | 4 |
| **Apex** | Apex findings with branch, PR, and issue automation, plus reachability and runtime validation | Apex | 3 |
| **Dependabot Alerts** | Auto-fix PRs driven to green CI, backlog processing, reachability triage | GitHub | 3 |
| **Cantina Bug Bounty** | Closes spam, notifies on real findings, opens remediation PRs where tractable | Cantina BBP | 1 |
| **Risk Assessment** | Shift-left review: rates new epics for security and privacy risk before implementation, opens linked design-review issues | Scheduled — weekly Jira sweep | 1 |
| **AI Agent Monitoring** | ClawSight telemetry — skills, policy violations, unusual tool use | ClawSight | — |
**AI Agent Monitoring** ships without bundled skills. Attach skills from the library, or write your own, when you create it.
### Web3 & threat intelligence
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **Smart Contract Security** | On-chain alert response and multisig signer monitoring, with emergency pause when contracts are compromised | Hypernative, Tenderly, Hexagate, Guardrail | 2 |
| **Threat Intelligence** | Advisory triage and applicability — supply-chain advisories, IOCs, attacker TTPs correlated to your environment | Threat intel webhook, RSS feeds | 1 |
### Program, GRC & platform operations
| Agent | Coverage | Signal source | Skills |
| - | - | - | - |
| **SOC 2 Evidence Collector** | Samples vulnerability-management evidence from Clarion issues, verifies remediation PRs, delivers approved draft evidence to a matching Vanta document | Scheduled — monthly | 1 |
| **New Vendor Risk Reviewer** | Reviews Vanta's newly discovered vendor queue, owner contacts, duplicates, and risk context. Its scheduled run is entirely read-only | Scheduled — weekly | 1 |
| **Vendor Security Questionnaire** | Drafts grounded answers and gathers evidence for inbound SIG, DDQ, VSA, and CAIQ questionnaires | On demand | 1 |
| **Knowledge Maintainer** | Owns periodic ingestion of connected sources into the workspace Brain and holds the editorial policy for extracted knowledge | Scheduled — hourly | 1 |
| **Signal Rule Refinement** | Reviews how your signal rules perform and proposes tuning to cut noise and close detection gaps | Scheduled — weekly | 1 |
| **Health Repair** | Supplemental repair triage for Clarion integration and monitor health issues | Clarion health issues | 1 |
### The Community Library
Templates are the starting point, not the ceiling. The **[Community Library](https://clarion.cantina.xyz/community)** carries agents and skills proven by security teams already running Clarion — take an entire agent with its skills and scheduled jobs, or lift a single skill into an agent you already have. Sign in to read full skill bodies.
Agents and skills shared by teams running Clarion.
Build an agent from a template or from scratch.
Every domain we ship skill templates for.
Configure the event sources your agents pay attention to.
The product-level view of agentic response.
## Creating agents
You can create an agent in two ways: start from a curated template, or build one from scratch.
### Start from a template
Templates are pre-built agents for common workflows. Each bundles a set of monitors, skills, and signal rules tuned for a specific domain.
* **Smart Contract Security**: Monitors on-chain activity, triages exploits, coordinates emergency pause workflows.
* **Identity & Access**: Tracks Okta, Microsoft Entra, JumpCloud, and 1Password events for impossible-travel, MFA bypass, and policy weakening.
* **DNS Infrastructure**: Watches your zones for unauthorized record changes, NS hijack, and dangling subdomains.
* **Cloud Posture**: CloudTrail, GuardDuty, and CloudWatch for AWS, with agent-driven IAM investigation.
To create from a template:
1. Open **Agents** in your workspace and click **New agent**.
2. Pick the template that matches your use case.
3. Review the bundled monitors, skills, and signal rules.
4. Configure notification channels. See [Notifications](/clarion/learn/notifications).
5. Activate the agent.
### Build from scratch
If no template fits, start with a blank agent.
1. Open **Agents** and click **New agent → Blank**.
2. Add monitors for the signals you want the agent to handle.
3. Add skills that describe how to respond. Use the skill library or write custom skills.
4. Configure notification preferences.
5. Activate.
You can fork a template at any time. Forked templates are managed copies you can edit; they keep the lineage so you can reset back to the template default.
[Learn about Skills →](/clarion/learn/skills)
## Monitors
Monitors are the event sources for your agents. Each monitor connects to an external tool, polls an API, or runs an active check.
### Monitor types
Clarion supports monitor types across these categories:
* **Identity & Access**: Okta, Microsoft Entra ID, JumpCloud, 1Password, Google Workspace.
* **Cloud**: AWS CloudTrail, AWS GuardDuty, AWS CloudWatch, Amazon Inspector, GCP Cloud Logging, GCP Cloud Monitoring, GCP Security Command Center, Vercel.
* **Source code**: GitHub, Apex.
* **On-chain**: Hypernative, Hexagate, Tenderly.
* **Endpoint**: CrowdStrike Falcon, Huntress.
* **Observability**: Datadog, Grafana, Falco.
* **Infrastructure checks**: DNS zone monitoring, Better Stack uptime alerts.
* **Generic**: Webhook for any tool that can POST JSON.
Each [Integration](/clarion/integrations/aws) page describes how to set up monitors for that tool.
### What you can do
* **Create** a monitor or multiple monitors for each connected tool, with type-specific configuration.
* **Filter** which events come through by severity or other criteria the monitor type supports.
* **Enable / disable** monitors without losing configuration.
* **Assign monitors to agents** so the right responder picks up each signal.
Signals from a monitor open an issue only when an alert filter matches them. If you're seeing signals but no issues, check the filters attached to that monitor.
## Scheduled & on-demand runs
Not every security problem announces itself. A monitor-driven agent waits for an event; a **scheduled** agent goes and looks. Several of Clarion's templates only exist in the second shape.
### Three ways a run starts
| Trigger | What starts it | Example |
| - | - | - |
| **Monitor** | A connected integration sends an event that matches the agent's monitors. | GuardDuty raises a finding; the AWS agent triages it. |
| **Schedule** | A cron expression fires. | The Exposure Agent sweeps every provider at 09:00 UTC daily. |
| **On demand** | A person clicks **Run now**, retriggers an issue, or asks in [chat](/clarion/learn/chat). | Re-running triage on an issue after new evidence arrives. |
### Scheduled agents
A schedule carries its own **prompt** — the instructions for that run — plus a standard five-field cron expression and an IANA timezone (UTC by default, so a platform schedule doesn't inherit one team's local time). Schedules are enabled or disabled individually, and deactivating the agent is the master off switch for all of them.
Several agent templates ship with a schedule already attached, materialized and pinned to the agent when you create it:
| Agent | Cadence | What the run does |
| - | - | - |
| **Knowledge Maintainer** | Hourly | Drains connected sources into the Brain under the workspace's editorial policy. |
| **Dangling Subdomain Agent** | Daily, 06:00 UTC | Enumerates every Cloudflare zone, resolves each delegation target, and asks connected providers whether a live resource still serves it. |
| **Exposure Agent** | Daily, 09:00 UTC | Probes deployments across connected providers for unintended public exposure. |
| **Claude Code Governance** | Weekly, Monday | Batches every undecided MCP server into one decision for a human. |
| **Signal Rule Refinement** | Weekly, Monday | Reviews signal-rule performance and proposes tuning. |
| **Risk Assessment** | Weekly, Monday | Rates new epics for security and privacy risk before implementation. |
| **New Vendor Risk Reviewer** | Weekly, Monday | Reads Vanta's newly discovered vendor queue. Read-only. |
| **SOC 2 Evidence Collector** | Monthly | Samples vulnerability-management evidence and drafts it into a Vanta document. |
You can add your own schedules to any agent, or edit the ones a template brought.
#### What a scheduled run can do
A scheduled run is a full agent run, not a cut-down cron job:
* It **files issues** from what it finds, with a per-run cap so a bad night cannot flood the queue.
* It can **ask a human for clarification** mid-run and resume when someone answers — an overnight sweep does not have to guess or abort.
* It **writes verdicts back to the Brain**, so tomorrow's run starts with what today's decided and stops re-reporting things a human already parked.
* It **posts a summary** to the workspace's notification destination, including a clean result, so silence is never ambiguous.
#### Failure handling
Each schedule stamps its next firing time on every successful claim, and consecutive spawn failures trip a circuit breaker rather than retrying forever. Run history — start, result, and error — is kept per schedule, and a single run's clarifications are reported together.
### Ad-hoc runs
**Run now** fires a schedule immediately, out of band, without touching its cadence. Multiple in-flight runs are safe: each gets its own run record. This is the usual way to test a schedule's prompt before trusting it overnight, and Members can do it even though authoring schedules is Admin-only.
**Retriggering an issue** re-runs triage on an existing issue — after new evidence lands, after a skill was corrected, or when the first pass was thin.
**Chat** is the fully ad-hoc path: the same tools and skills, driven by a person, with no schedule and no monitor involved. See [AI chat](/clarion/learn/chat).
Which templates are schedule-driven.
The event sources behind monitor-driven runs.
Where a sweep's verdicts are remembered.
Drive the same tools yourself.
## The Brain
**Agents are only as good as what they know.** The Brain is the memory every agent reasons with. It maps your environment, learns your business logic, and gets smarter with every investigation.
An alert names a host. It never says who owns it, what it supports, whether the behaviour is expected, or whether you've seen it before. The Brain is where those answers live, built and kept current from the systems you already run.
The difference shows up before the evidence does. An agent with the Brain starts on the right entity (this person's managed device, the service this host supports, the confirmed note that this pattern is expected) instead of opening five integrations to find it. The discovery work disappears; the investigation starts at the analysis.
### Two halves, side by side
Users, identities, hosts, repos, services, cloud resources, dependencies, tickets, and the security posture attached to each. The facts that have to be exact.
Your business knowledge and the processes you run on: expected behaviour, ownership and escalation paths, prior investigations, what you decided and why. The context that has to be interpreted.
Graphs are connections. Memory is learning. Agents need both.
### What makes it work
Connect an integration and it starts resolving entities and relationships. No modelling, no CMDB import.
Rescans, consumes change events, updates mid-investigation. Every fact carries its source and when it was last seen.
Every claim traces to a system and a timestamp. When it can't cite something, it says so rather than guessing.
Investigations write back what they learn. Once a person confirms a fact, such as a known-benign pattern or an ownership path, later runs use it.
### How the graph is built
**Assets** are the base layer: one row per real resource, keyed by its native provider id — an AWS ARN, a GitHub repo, a Datadog service, a Vercel project, a managed laptop. Re-syncs update the same row in place, so an asset is durable and anything attached to it survives.
**Systems** are the derived layer. A correlation engine reads each asset's identifiers and buckets the ones that agree: the same service name, the same EC2 instance, the same repository URL, the same Aurora cluster, the same GitHub topic or org custom property. Any bucket with two or more members becomes a System — which is how a Datadog service, the AWS resources tagged for it, and the repo it is built from become one thing an agent can reason about.
Systems are rebuilt from scratch on every sync in an atomic swap. If a rebuild fails, the previous ones stay intact and the next sync tries again. That's why annotations and knowledge anchor to the durable asset, never to the derived grouping.
An asset can belong to several Systems at once — one per correlation rule it matches.
#### Where assets come from
* **Integration-discovered** — a provider actually saw it. Cloud resources and their per-account posture, repositories with their rulesets, workflows, alert counts and CODEOWNERS, observability services and monitors, hosting projects and deployments, managed devices and their owners.
* **Correlation-inferred** — synthesized from another asset's identifiers, so a repository referenced in cloud tags still correlates even with no source-control integration connected.
* **Agent-recorded** — written during an investigation for things no integration owns: an attacker IP, a vulnerable package, an external domain. These survive correlation rebuilds.
### Memory and timelines
Signals, rule fires, alerts, issues, remediations, and linked Jira or Linear tickets all point back at assets. Ask for any resource's history and you get a single merged timeline instead of six queries.
Assets are resolved to signals **again at rule-fire time**, so an asset discovered today still picks up the fires that referenced it last week.
### Knowledge and business context
On top of the catalog sits curated knowledge — cards describing systems, services, platforms, datastores, and tools — plus workspace-level business context.
Knowledge arrives two ways:
* **Recurring feeds** pull from Jira and Notion on a cadence, each with its own cursor.
* **One-time intake** parses uploaded documents and URLs, extracts candidate facts, and writes them as **proposals**.
Both paths bridge back to catalog assets, so a card that describes "the payments platform" can point at the real infrastructure it means.
#### Nothing unreviewed reaches a prompt
This is the load-bearing rule. Workspace-scoped facts are filtered before they enter any agent prompt: a fact reaches the model only if a **human authored it** or a **human confirmed it**. An unconfirmed agent proposal is visible in the UI for review and invisible to the prompt.
That is deliberate prompt-injection defence. Agents read attacker-influenced material every day — alert payloads, repository files, external pages, vendor responses. Without the confirmation gate, "the Brain remembers what it learns" would mean "an attacker can write into every future investigation's system prompt." Locked knowledge elements force every change through the same review.
Each proposed fact carries its origin, so a reviewer can see which run produced it and from what.
### Writing back
During a run, an agent can:
* **Annotate** an asset or the workspace with a durable, attributed fact.
* **Record** assets the investigation turned up that no integration owns — every one in a single call.
* **Link** entities that belong together; those links feed correlation as extra join keys, exactly like discovered identifiers.
Writes are permission-gated and every one is attributed to the agent's job, so a claim in the Brain always traces to the run that made it. The [Knowledge Maintainer](/clarion/learn/agents#our-agents) agent owns the periodic drain and the editorial policy for what gets kept.
### What agents actually call
The Brain is exposed to agents as always-on tools, scoped to the workspace and the job: list and read assets, list correlated systems, search knowledge, read business context, search the merged timeline across assets, and the write paths above. There is no configuration step — connect an integration and the tools have something to answer with.
The agents that read and write the Brain.
Sweeps that use the Brain to stop re-reporting.
Query the Brain yourself.
Where investigation procedure lives.
## Models & runtime
Agents run in an isolated sandbox on a model Clarion resolves per run. You can leave that entirely to us, pin a model, bring your own key, or point the whole workspace at your own provider endpoint.
### Tiers, not model names
Callers inside Clarion ask for a **capability tier** rather than a specific model, so a model generation change is one config edit and not a sweep through the codebase.
| Tier | For |
| - | - |
| **Light** | Cheap, high-volume classification and mechanical steps. |
| **Medium** | The default investigative work. |
| **Strong** | The hardest reasoning — correlation across systems, ambiguous evidence, response planning. |
Each tier resolves to an ordered chain of concrete `provider/model` candidates.
### Model failover
Every tier's chain pairs a **primary** with a **cross-provider failover**. When the primary hits a model-access failure — a provider outage, a capacity error, a model withdrawn — the run moves to the next candidate instead of failing.
The failover is deliberately on a *different* provider. A failover to a sibling model on the same provider does not survive the failure mode that actually takes models offline.
Candidates are compared canonically, so a bare model id and its `provider/`-prefixed twin collapse to one entry — the chain never retries the model that just failed under a different spelling.
### Bring your own key (BYOK)
Enable BYOK for the workspace and paste an Anthropic or OpenAI API key in [Settings → Workspace](/clarion/learn/settings#workspace). Clarion infers the provider from the key prefix.
A workspace with its own key runs **only** on its own providers:
* No cross-subsidy — your inference is billed to you.
* No tenant data through Clarion's provider account.
* A run fails terminally rather than silently falling back to a Clarion key.
The key never enters the sandbox. Agent traffic goes through Clarion's proxy, which attaches the credential host-side.
Each tier resolves to a model on your own providers — by default the suggested model for that provider — and only ever fails over to another model on them. Clarion checks at save time that the key can serve every tier.
Until you add a key, a BYOK-enabled workspace runs on the Clarion chain, so enabling the flag before pasting a key never takes the workspace down. Once a key has been added, removing it does **not** return the workspace to Clarion's keys: runs fail until a key is added again.
### What the sandbox can run
Agent runs execute in the **opencode** harness inside the sandbox. Clarion generates the harness's provider configuration per run, which is why the set of usable models is not a fixed allowlist: it is every model opencode can be pointed at over one of the three wire protocols below. Naming a new model on a provider you already registered needs no Clarion release.
### Bring your own provider
Beyond the two platform providers, a workspace can register credentials for **any** provider that speaks one of three wire protocols:
| Protocol | Providers |
| - | - |
| `anthropic-messages` | Anthropic |
| `openai-responses` | OpenAI |
| `openai-chat` | OpenRouter, DeepSeek, Groq, Fireworks AI, Together AI, Mistral, and anything else OpenAI-compatible |
Some gateways resell models from several vendors and serve each over that vendor's own protocol: OpenCode Zen, OpenCode Go and Vivgrid. One key covers the whole gateway: Clarion drives each model over the protocol it needs, so a gateway's Claude models go over Anthropic's API and the rest over OpenAI's.
The picker prefills protocol and endpoint for the curated providers, and a **custom** entry covers anything not listed — you supply the base URL and key. A custom provider's models all use the protocol you choose. Clarion can list the endpoint's models to confirm the credential works before saving.
A registered provider becomes addressable as `provider/model` anywhere a model is named. Any provider other than the two platform ones **requires** a stored credential: the proxy fails closed rather than reaching an unconfigured provider with a platform key.
Provider endpoints must be public HTTPS hosts. Clarion rejects loopback, private-range, link-local, and cloud-metadata addresses.
### Models settings
Workspaces with the BYO Models capability get **Settings → Models**, where you can see the resolved chain and override the model per tier. Without the capability the route is hidden and the workspace runs the platform defaults.
### Subagents
An agent run can **delegate** to a subagent lane — a scoped worker with its own instructions, its own tool subset, and optionally its own model. Lanes are how a run does breadth-first exploration or a mechanical sweep without spending frontier-model context on it.
What matters about Clarion's implementation is where the decision is made: **the trusted backend resolves the lanes, not the sandbox.** Before the run starts, Clarion decides what each lane is, expands its tool scope against the tools the run can actually call, and stamps the answer onto the job. The sandbox receives a resolved answer rather than a declaration it could reinterpret.
Two consequences follow:
* A lane whose tool scope cannot be expressed is **dropped**, not silently degraded. A subagent with an empty toolset is a failure that looks like success, so it is made visible instead.
* A lane bound to a non-inherited model has that model resolved to a concrete `provider/model` up front, under the same BYOK policy as the parent. A binding that cannot be resolved drops the lane — running a cheap-tier sweep on the frontier model, or a BYOK tenant's traffic on a Clarion key, are both worse outcomes than the lane not existing.
Which lanes a workspace's agents may delegate to is itself configurable.
### Tool-call batching
Round trips, not tokens, are what make a long investigation slow. Clarion's tool schemas are written so an agent asks for everything it needs in **one** call rather than one call per item:
* **`get_skill`** takes a list of skill ids. Skills are independent, so batching them costs one round trip instead of one each — and every skill in the batch renders in the run transcript.
* **`record_inferred_asset`** takes every asset an investigation turned up in a single call, up to 50. Duplicates inside a batch collapse to one row.
* **MCP server decisions** are batched by verdict: one call approves or denies many servers, and the result reports per-server outcome so a partly-landed batch is still legible.
* **Clarifications** are batched: several related questions reach the responder together, each labelled with its position in the batch.
* **Tool catalog lookups** batch ids, so a multi-capability triage resolves its whole tool surface at once.
A batched call that partly fails returns what succeeded alongside what didn't, rather than discarding the whole batch — which is the guarantee batching exists to provide.
Where BYOK lives.
The system prompt and the agent behavior layered on it.
The agent templates that run on this stack.
# AI chat
Source: https://docs.cantina.security/clarion/learn/chat
The same agent runtime, driven by you — threat hunting across your stack, remediation, and building agents by asking.
Chat is an agent run with a person in the driver's seat. It executes in the same sandbox, reads the same [Brain](/clarion/learn/agents#the-brain), follows the same [skills](/clarion/learn/skills), and calls the same tools as an autonomous triage run — the only difference is that you decide what it does next.
## Two scopes
**Workspace-wide.** The chat resolves *every* connected integration and *every* skill in the workspace. This is the mode for open-ended work: hunting across sources, answering a question nobody wrote a skill for, or reaching a tool no agent owns.
**Agent persona.** Scope the chat to one agent and it inherits exactly that agent's skills, tools, and instructions. Use it to interrogate what an agent would do — and to test a skill change before an alert exercises it at 3am.
## Threat hunting
Because the chat holds every connected integration at once, a hunt does not mean opening six consoles.
* **Query the detection stack directly** — Microsoft Sentinel KQL and advanced hunting, Splunk searches, Datadog, CrowdStrike Falcon and cloud, SentinelOne, Microsoft Defender XDR, Falco, Wiz, Huntress.
* **Pivot across identity** — Okta, Microsoft Entra, Google Workspace, JumpCloud, 1Password, and the device fleet behind them.
* **Pivot across infrastructure** — AWS, GCP, Cloudflare, Vercel, Replit, Tailscale, DNS lookups, and on-chain address data.
* **Search Clarion's own memory** — signals and signal rules, the issue history, and every asset's merged timeline. "Have we seen this before?" is one question, not an archaeology project.
* **Start from the Brain** — ask who owns a host, what a service supports, or which devices belong to a person, before touching a single provider API.
Findings do not have to stay in the conversation: the chat can open an issue, file a Jira or Linear ticket, post to Slack or Teams, page on-call, or record what it found back into the Brain.
## Automating security work
Anything a skill can instruct an agent to do, the chat can do on request — with the same guardrails.
* **Remediate** through the connected providers: DNS records, cloud IAM, endpoint containment, identity actions.
* **Notify and escalate** to a configured destination, or DM a specific person.
* **Draft and file** tickets, evidence, and questionnaire answers grounded in workspace knowledge.
* **Read the docs** — Clarion's own documentation is a tool, so "how do I configure this" is answerable in place.
Sensitive tools still require **approval**, and the chat still asks for **clarification** when it needs input. Chat does not bypass tool policy; it uses the same gates described in [Notifications](/clarion/learn/notifications).
## Building agents by asking
Authoring — creating agents, writing skills, and setting up schedules from a prompt — runs over Clarion's [MCP server](/clarion/learn/settings#mcp-access) rather than in the in-app chat. Connect Claude Code, Cursor, or any MCP client to your workspace and you get tools to:
* **Create an agent** from scratch or from one of the [agent templates](/clarion/learn/agents#our-agents), and update it afterwards.
* **Create a skill** from scratch or from a [skill template](/clarion/learn/skills#our-skills), and edit it in place.
* **Browse the template library** — list and read agent and skill templates before instantiating one.
* **Operate the scheduler** — create, update, enable, disable, and run [schedules](/clarion/learn/agents#scheduled-on-demand-runs) once.
* **Drive chats programmatically** — start a chat, send messages, and read transcripts from a script.
* **Inspect runs** — read agent jobs and their full transcripts, retrigger an issue, complete a remediation item.
* **Read and write the Brain** — search knowledge, propose and update elements, link assets, and manage agent behavior.
Authoring agents, skills, and schedules is an **Admin** permission wherever it is done, including over MCP — see [Roles & permissions](/clarion/learn/settings#roles-permissions) for why.
## Where chats live
Chats are workspace objects, not browser tabs. They persist, they're listed, and a chat's transcript can be read back later — by a teammate, or by a script over MCP. Assistant chats have their own permission (**Use the assistant**), held by every role.
Slack and Microsoft Teams can also front the assistant, so a question asked in a channel reaches the same runtime as one asked in the app.
The memory chat reasons with.
Connect Claude Code or Cursor to your workspace.
Templates to build from.
What agents and chat can call.
# Issues
Source: https://docs.cantina.security/clarion/learn/issues
How issues get created, and what you can do with one.
Issues are the top-level work items in Clarion. Anything a monitor surfaces becomes an issue, and the agent watching that monitor triages it first. The agent dispositions benign and duplicate findings without you. Some low-severity repeats of a finding already triaged as benign close without a new agent run. See [How triage uses past issues](#how-triage-uses-past-issues).
## How issues get created
Two paths, depending on the monitor.
Integrations that run their own detection (Okta, CrowdStrike, Microsoft Sentinel) hand Clarion a finished alert or case. Each one becomes an issue directly.
Everything else sends raw events, called **signals**. Those become issues only when an **alert filter** (a signal rule) matches them. A filter can match a single event, or a sequence of events grouped by a shared field inside a time window. If signals are arriving but no issues appear, check the filters on that monitor.
Clarion ships alert filter templates for every supported source. Fork one, or write your own.
## What's on an issue
* **Number**: `ISS-1`, `ISS-2`, counting up per workspace.
* **Status**: `New`, `Triaging`, `Open`, `Escalated`, `Resolved`, or `Closed`. See [Status](#status).
* **Kind**: What the issue *is*: a threat, a vulnerability, a risk, and so on. See [Issue kinds](#issue-kinds).
* **Disposition**: The triage verdict. See [Disposition](#disposition).
* **Severity**: `Critical`, `High`, `Medium`, or `Low`. See [Severity](#severity).
* **Action required**: Set when the issue is blocked on a human, either approval for a tool call or an answer to a clarification the agent asked for. This is what fills the **Needs input** queue.
* **Source**: The integration the underlying signal came from.
* **Assignee**: The member driving it.
* **Related issues**: Findings linked under a shared parent. Campaign grouping and escalation chains both show up here.
* **Deduplication key**: The external event ID. A redelivery carrying a key Clarion has already recorded folds into the existing issue instead of opening a second one.
## Status
| Status | What it means |
| - | - |
| `New` | Just created, not yet picked up by triage. |
| `Triaging` | An agent is investigating it now. |
| `Open` | A confirmed problem below the workspace's [escalation bar](/clarion/learn/settings#severities-that-escalate). It waits for someone to pick it up on their own schedule, and notifies nobody. |
| `Escalated` | A confirmed problem that meets the escalation bar. It notifies your team and may page on-call. This is for issues that need attention now. |
| `Resolved` | The threat or vulnerability has been contained or remediated. Human follow-up may still be needed. |
| `Closed` | No further work needed. Usually a false positive, a duplicate, informational, or noise. |
An agent can escalate as soon as it has enough evidence, without waiting for triage to finish.
### Taking an issue off the escalated board is a human decision
Once an issue is `Escalated`, only a person can move it to `Open` or `Closed`, and the app asks them to confirm. An agent that tries is rejected, and the issue stays escalated. Agents can still move it to `Resolved` once the threat is contained. In the same way, only a person can reopen a `Closed` issue.
## Severity
Severity grades the issue itself: `Low`, `Medium`, `High`, or `Critical`. Agents grade the severity the evidence supports and let the escalation bar decide whether it pages. They don't raise a severity to force a page.
Synthetic tests, drills, false positives, and benign noise are graded `Low`. With the default bar, that keeps them from paging anyone.
## Disposition
The disposition records what the issue turned out to be.
| Disposition | When it applies |
| - | - |
| `Unknown` | Not decided yet, including escalations queued for human review. |
| `Benign` | Real activity, but harmless. No threat. |
| `Suspicious` | Unusual and not confirmed either way. It was closed without full confirmation. |
| `Confirmed Threat` | A real threat, handled or escalated. |
| `False Positive` | The detection was wrong. Nothing actually happened. |
| `Duplicated` | Already tracked by another issue. |
## Grouping related issues
Issues about the same underlying problem, such as one campaign or one root cause, are grouped under a single parent instead of being tracked side by side. Each link names how the two issues relate. Linking doesn't change anything else: every issue still gets its own disposition from its own evidence.
When a new issue turns out to be the same problem as one that is already `Escalated`, the agent groups it under that escalated issue. **Grouping is silent.** The parent already notified your team when it escalated, so the child doesn't page again, and agents are blocked from posting separate Slack or Teams messages about it. Updates go on the parent's existing thread.
## Issue kinds
Every issue carries a **kind** that says what it is, separate from its **source** (where it came from) and its **severity** (how bad it is).
| Kind | What it means |
| - | - |
| **Threat** | Signs of active malicious activity against your systems. |
| **Vulnerability** | A weakness an attacker could exploit. |
| **Risk** | An exposure that makes a future incident more likely, such as a posture misconfiguration. |
| **Non-security** | An operational problem with no direct security impact. |
| **Intel** | An external advisory or news item. It's reviewed for relevance, not treated as an event in your estate. |
| **Platform** | Internal Clarion work, like repairing a broken integration. Not a finding. |
### Where the kind comes from
The kind is set when the issue is created:
* **Alert filters** declare the kind of issue they fire. Every Clarion template has one, and filters generated with AI always pick one. Custom filters without a kind produce unclassified issues. A filter can't produce **Platform** issues.
* **Integrations** that hand over finished findings, such as Wiz or GCP Security Command Center, map each finding to a kind.
* **Manual issues** require you to pick a kind in the create dialog.
### How the kind is used
* **Escalation.** When an agent escalates a **Vulnerability** or **Risk**, the issue stays `Open` and pages nobody, since these are remediation backlog rather than incidents. The one exception is a `Critical` finding the agent justifies as imminent danger. Every other kind follows the workspace's [Severities that escalate](/clarion/learn/settings#severities-that-escalate) setting.
* **Closing.** Kinds are closed on different grounds. A **Threat** is judged on whether there's a real attack in your estate. An **Intel** item has no attack to find, so it closes once it's been reviewed and no action is needed in your estate.
* **Finding work.** The issue list can filter and group by kind, so you can separate active threats from the remediation backlog. The kind badge on an issue shows a one-line explanation on hover.
## How triage uses past issues
Clarion uses earlier issues in two ways.
**Low-severity repeats skip triage.** A new `Low` issue closes as `Duplicated` of an earlier issue, with no agent run, when the earlier issue:
* is also `Low` and came from the same source (and the same monitor, when the new issue has one),
* was created in the last 30 days, investigated by an agent, and dispositioned `Benign` or `False Positive`,
* shares the new issue's recurrence key.
| Source | Recurrence key |
| - | - |
| Alert filters over signals | The source's change fingerprint, if it sends one. Otherwise a fingerprint of the event payload that ignores timestamps, UUIDs, IP addresses, long hex IDs, and numbers inside text. |
| AWS Inspector | The finding's CVE-scoped key. |
| Wiz | The issue's logical key. |
Issues from other sources have no recurrence key and always get a full triage. The shortcut applies only to a new issue's first triage; a manual retrigger or an escalation always runs the agent. The closed issue links to the earlier one under **Related issues**, and its status comment names it. To investigate it anyway, reopen it and retrigger triage.
**Similar issues are context, not a verdict.** Before triage, Clarion finds up to five workspace issues with similar titles and gives the agent each one's status, disposition, and the first line of its conclusion. The agent uses them to decide whether the new issue is the same underlying problem and should be grouped. It does not copy their disposition or severity. An earlier `Benign` result is a hypothesis the agent tests against the new evidence.
## What you can do
* **Triage** it yourself, or hand it to an agent for the first pass.
* **Set disposition** as you confirm or rule things out. Marking one `Duplicated` means naming the issue it duplicates.
* **Escalate** to notify on-call and move the issue to `Escalated`. The button only appears while the status is `New` or `Triaging`.
* **Assign** to a member, and reassign as ownership moves.
* **Resolve** from the issue header, or pick any status from the badge dropdown.
* **Link tasks** for follow-up work that outlives the issue.
Status, severity, assignee, and disposition can each be set across a selection of issues at once from the list view.
The **Escalated** and **Needs input** queues collapse child issues under their parent, so a grouped campaign reads as one row. Apply any filter, or search, and the list goes flat. The children reappear and the count jumps; nothing new happened, the filter just stopped collapsing them.
[Learn about Tasks →](/clarion/learn/tasks)
# Notifications
Source: https://docs.cantina.security/clarion/learn/notifications
Multiple destinations, agent-chosen routing, direct messages, and the clarification types agents use to reach you.
Notifications keep your team informed about what Clarion is doing, and let agents reach you when they need approval or clarification before continuing.
## Two kinds of notifications
**In-app notifications** tell you about things that happened: an issue was assigned to you, a task is overdue, an agent finished a triage. They appear in the notification tray.
**Human input notifications** are active requests from agents that need a response before execution can continue. They're delivered to a configured destination and resume the agent run when you reply.
## What triggers a notification
Only **escalation** notifies your team. When an issue moves to `Escalated`, Clarion announces it on the configured channels. Everything else stays quiet:
* **Creating an issue never notifies.** Issues arrive continuously, and paging on each one would be noise.
* **`Open` issues don't notify.** They are confirmed problems below the [escalation bar](/clarion/learn/settings#severities-that-escalate), left on the board for someone to pick up.
* **Grouped issues don't notify again.** An issue folded under an already-escalated parent is covered by the parent's announcement. See [Grouping related issues](/clarion/learn/issues#grouping-related-issues).
Follow-up messages about an issue, such as an agent's updates, approvals, and clarifications, stay in that issue's Slack or Teams thread, so everything about it reads as one conversation.
## Channels
Human-input notifications are delivered over:
* **Slack** — app messages with interactive buttons for approval and clarification. Threaded under the issue's escalation announcement, so a run's approvals, clarifications, and agent posts stay in one place. See the [Slack integration guide](/clarion/integrations/slack).
* **Microsoft Teams** — the same flow, into a Teams channel or chat. See the [Microsoft Teams integration guide](/clarion/integrations/microsoft-teams).
* **Telegram** — bot messages into a chat.
* **SMS** — via Twilio, to workspace members with a verified phone number. Notification only; SMS does not carry interactive approval buttons.
* **Email** — private agent clarifications only, sent when a member selects Email as their preferred contact channel and has a verified account email. The message links to Clarion for the answer; email is not a workspace destination and replies are not processed.
Skills can additionally *act* through general outbound email, a webhook, a phone call, or a PagerDuty page. Those are agent tools rather than workspace human-input destinations: PagerDuty in particular is a way for an agent to page on-call, not a place a human answers an agent from.
## Which severities escalate
**Settings → Agents → Escalation & notifications** also sets the severities that escalate. When an agent escalates an issue at one of those severities, the issue is escalated and announced to your destination. Below the bar, the issue stays `open` for a human to pick up, and nobody is paged. The bar is also written into the agent's system prompt, so agents know when to escalate.
## Multiple destinations per workspace
A workspace no longer has a single notification target. Configure a **set** of destinations in **Settings → Agents → Escalation & notifications**, each with:
* **Channel and target** — the Slack channel, Teams channel or chat, Telegram chat, or the members to text.
* **Label** — a human-facing name, e.g. `#sec-ops`, `Cloud on-call`, `Exec bridge`.
* **Description** — "use this destination when…". This is shown to admins **and** read by the agent when it routes the run.
* **Primary** — exactly one destination is primary. It is the guaranteed fallback.
Leaving the set empty turns human-input notifications off.
### Agents route themselves
Because each destination carries a description, an agent can pick the right one for the run it is on — a DNS change to the infrastructure channel, a suspected identity compromise to the security channel — and pin that choice for the rest of the run.
The choice is bounded: an agent may only select from destinations an admin already configured, the id is validated server-side, and any run without a valid choice falls back to the primary destination. An agent cannot invent a destination.
Give every destination a clear description. It is the only thing the agent has to route on.
### Posting to any channel
By default, agents can only post to Slack and Teams destinations that are explicitly named: the destinations above, plus channels and chats mentioned in a skill or in agent behavior. That scoping is a deliberate safety boundary, because it means a compromised or misled agent cannot pick its own audience.
Workspace admins can lift it with **Allow agents to post to any channel**, below the destination list. With it on:
* **Slack:** agents can post, reply, react and upload files in any public channel, and in private channels the Clarion app has been added to. They still can't invite people to a channel or change its topic unless it is listed or mentioned.
* **Microsoft Teams:** agents can message any chat or channel, look up anyone in your Microsoft directory, and start new group chats. Approval and clarification requests can then be delivered into a group chat the agent created during the run.
* **Slack direct messages** stay limited to the people mentioned in skills or on call.
The setting applies to runs that start after you change it. Workspaces that had **Unrestricted Microsoft Teams messaging** turned on start with this setting on.
Leave this off unless you have a specific need for agents to reach channels you haven't listed, such as ad-hoc war rooms. It widens where agent-authored content can land.
### Private contact
An agent can also address a clarification to **one specific person** through a Slack DM, Teams 1:1 chat, or email instead of posting to a shared channel — useful when the question is "is this you?" or "did you approve this change?". Selecting Email as the preferred contact channel is the member's opt-in and requires a verified account email. The email links to Clarion for the response; email replies are not processed.
The recipient is resolved and validated on Clarion's side rather than taken as an agent's claim, and only the addressed signed-in member can answer a privately delivered clarification. If private delivery fails and Clarion uses the workspace's shared fallback destination, normal workspace response permissions apply.
## Human input types
**Approval** — yes/no on a tool the agent wants to run ("Suspend user account?"). The prompt names the tool, the target, and the agent's rationale.
**Clarification** — a question, in one of three shapes:
| Mode | What the responder sees |
| - | - |
| **Structured options** | A searchable picker of choices the agent supplies, single- or multi-select. |
| **Freeform with suggestion** | A text box pre-filled with the agent's suggested answer. |
| **Freeform** | A text box. |
Clarifications can be marked **skippable**, carry a **default value**, and arrive as a **batch** — several related questions asked together and shown with their position in the batch, rather than one round trip each.
Scheduled runs can ask for clarification too, so an overnight sweep can still put a question in front of a human rather than guessing or aborting.
## Who can respond
By default, only **Admin** and **Member** roles can answer, and Slack or Teams responders must be linked to a workspace member. Turning on **Anyone can respond to human input** in [Workspace settings](/clarion/learn/settings#workspace) opens it to any member — including read-only — and to teammates in the linked channel without a Clarion account. Either way, the audit log records who unblocked the agent.
## Timeouts and escalation
Each request carries a **timeout**. On timeout the agent either auto-aborts the action or escalates to a backup destination, depending on the skill. To deny every unanswered tool approval after 12 hours instead of waiting, turn on **Deny unanswered tool approvals** in [Workspace settings](/clarion/learn/settings#deny-unanswered-tool-approvals).
Which issue severities an agent may escalate on at all is set by [Severities that escalate](/clarion/learn/settings#severities-that-escalate) in **Settings → Agents → Escalation & notifications**.
Approval requests for tool calls are an explicit safety boundary. Agents can never execute a gated tool without a human response. The run pauses until you reply or the timeout fires.
## On-call rotation
**Settings → Agents → Escalation & notifications** also holds the workspace's on-call rotation: which member is on call for which date. Agents read it when a skill says to page whoever is on call, and it can be mirrored into a Google Calendar through the [Google Calendar integration](/clarion/integrations/google-calendar).
## Escalation cards
Escalation messages carry the issue reference and link back to the issue in Clarion. In Slack, an escalated issue can be **closed directly from its card** without opening the app.
Connect Slack for interactive approvals.
Connect Teams for the same flow.
Bot delivery into a Telegram chat.
SMS and voice calls for high-urgency events.
# Settings
Source: https://docs.cantina.security/clarion/learn/settings
Configure your workspace, manage members and access, and customize how your team works in Clarion.
Settings is where you configure your workspace and the people who work in it.
Invite teammates, set communication preferences, and manage workspace access.
The four workspace roles and the permission matrix Clarion enforces.
Domains, human-input and Teams messaging controls, and your own AI provider key.
The read-only system prompt, agent behavior, escalation and notifications, and skills.
Enforce single sign-on through Microsoft Entra ID for centralized identity.
Connect Claude Code, Cursor, or headless scripts to the workspace via MCP.
Workspaces are isolated tenants. Issues, agents, monitors, integrations, and members all belong to one workspace. Most teams have a single workspace; larger organizations sometimes run separate workspaces for different business units or environments.
## Members
Members are the people who can see and act in your workspace. Each member has access to issues, agents, and tools, plus a set of preferences that determine how Clarion reaches them.
### What a member has
* **Profile**: Linked to a Cantina identity (email, name). Your account email is read-only in Clarion and shows its verification status.
* **Communication channels**: Link Slack and Teams identities or verify a phone number. Clarion reads your account email from Cantina; it cannot be replaced with an alternate address.
* **Preferred channel**: The default channel for private agent clarifications. Selecting Email opts you into clarification emails at your verified account address.
* **Email notification settings**: Toggle assignment emails for incidents and tasks separately from the preferred clarification channel.
### What you can do
* **Invite** new members by email.
* **Update** a member's communication channels and preferred channel.
* **Remove** members who no longer need access.
A member's preferred channel determines where agent approval and clarification requests are sent. Make sure each member has at least one verified channel before assigning them to active agents.
Clarification emails contain a link back to Clarion. Sign in as the intended member to answer; replies sent to the email itself are not processed.
## Roles & permissions
Every workspace member holds exactly one role. The role decides which permissions they have, and Clarion enforces those permissions on the server — the UI hides what you cannot do, but the gate is not the UI.
**Settings → Roles** renders the live matrix: every permission Clarion knows about, crossed with every role, derived from the same function the API authorizes with. It cannot drift from what is actually enforced. This page explains the shape of it.
### The four roles
| Role | What it is for |
| - | - |
| **Admin** | Full access to every workspace feature, including members, integrations, and destructive actions. |
| **Member** | Works issues, tasks, and triage, can act on assigned bounty findings, and can trigger runs of existing schedules — but cannot author agents, skills, or schedules, change workspace settings, or manage members. |
| **Bounty triager** | Manages bounty programs and triages submissions. Deliberately holds **no** other Clarion tenant permissions — not even enough to browse the workspace. |
| **Read-only** | Reads workspace data. Writes nothing beyond their own profile, notification preferences, API tokens, and assistant chats. |
### Permission categories
The matrix is grouped the same way the permission catalog is:
| Category | Covers |
| - | - |
| **Triage & investigation** | Issues, tasks, the triage queue, on-call schedules, the assistant, and responding to human input. |
| **Detection engineering** | Signal rules, monitors, and catalog annotations. |
| **Agents & automation** | Agents, schedules, tool policies, and agent pausers. |
| **Audit & dashboards** | Dashboards, the audit log, and escalation routing. |
| **Workspace administration** | Integrations, members, API tokens, and workspace settings. |
| **Bounties** | Bounty program metadata and sensitive submission data. |
### Why authoring is Admin-only
Creating or editing an **agent**, a **skill**, or a **schedule** is Admin-only, and that is a security decision rather than a convenience one.
An agent definition decides what runs, with which tools, against your production systems — and it runs with permissions inherited from its creator. If a Member could author agents, the effective privilege of the Member role would be "whatever an agent can be told to do." Keeping authorship with Admins preserves the invariant that every agent traces back to an Admin who approved what it can reach.
The same logic covers the other Admin-only permissions:
* **Manage tool policies** and **manage agent pausers** — these are the controls that decide which tools require approval and which agents may run at all.
* **Manage escalation routing** — otherwise a non-admin could reroute another agent's pages to a destination they control.
* **Retrigger issues** and **run issue remediation** — audited, but the audit trail is not a substitute for a gate.
* **View all members' API tokens** and **manage all members' API tokens** — every role gets the `:own` variant for self-service; only Admin sees everyone's.
Members *can* run an existing schedule on demand. Triggering something an Admin already authored is a different act from deciding what it does.
### Responding to human input
Every role holds **Respond to open human input requests**, but it is only consumed when **Anyone can respond to human input** is enabled in [Workspace settings](/clarion/learn/settings#workspace).
* **Off** (default): tool approvals and clarifications require **Approve triage actions** — Admin and Member only.
* **On**: any member, including read-only ones, and any teammate in the linked Slack or Teams channel, can unblock the agent. The audit log still records who did.
### Read-only is not "Member minus writes"
Almost, but Read-only cannot **View members**. Neither role has workspace-wide **View bounty submissions**: Members instead read, triage, and decide only findings an Admin or Bounty triager assigns to them. Read-only is the posture used for shared evaluation workspaces, where the member list would tell each prospect who else is in the room.
### Platform permissions
A few permissions in the catalog — the benchmark-scenario surface — are held by **no** workspace role, not even Admin. They are carried only by a Cantina platform credential. The Roles matrix omits them, because a row of empty cells in a table about workspace roles would only mislead.
Invite teammates and assign their role.
The workspace-wide policies these roles gate.
## Workspace
Your workspace is the isolated tenant that holds everything Clarion knows about your security stack — issues, agents, skills, monitors, integrations, and members. **Settings → Workspace** is where you configure the things that apply to *every* agent in it.
Changes here are workspace-wide and take effect on the next agent run. Editing them requires the **Edit workspace settings** permission — see [Roles & permissions](/clarion/learn/settings#roles-permissions).
Agent behavior (formerly *workspace instructions*), the read-only system prompt, severities that escalate, and skills live under [Settings → Agents](/clarion/learn/settings#agents).
### Domains
Your company's top-level domains. Detections use them to tell internal from external: an account outside these domains reporting agent telemetry, a login from a non-company identity, an email-auth change on a domain you own.
Subdomains count as internal automatically — list only the top-level domains (`example.com`, not `mail.example.com`). An agent can also **propose** domains it discovered during investigations for you to confirm.
### Human input and messaging
These settings decide what happens to an agent's approval and clarification requests, and how far its Teams messages can reach. Which severities page your team is set in [Severities that escalate](/clarion/learn/settings#severities-that-escalate).
#### Deny unanswered tool approvals
Decides what happens when nobody answers an agent's request to run a gated tool.
| Setting | Behavior |
| - | - |
| **Off** (default) | The run stays blocked until someone answers. |
| **On** | An approval unanswered after **12 hours** is denied. The agent continues without the action and reports it as not performed. |
Tools set to **auto-decide** in **Settings → Tools** are unaffected: they are judged individually rather than denied outright.
#### Anyone can respond to human input
Controls who may answer an agent's approval and clarification requests.
| Setting | Who can respond |
| - | - |
| **Off** (default) | Only **Admin** and **Member** roles. Slack and Teams responders must be linked to a workspace member. |
| **On** | Any workspace member — including read-only users — and any teammate in the linked Slack or Teams channel, even without a Clarion account. |
Either way, the audit log records who unblocked the agent.
With this on, Microsoft Teams responders need the Clarion app installed for **everyone** in your tenant. Otherwise Teams blocks the card buttons before the response ever reaches Clarion.
### AI provider credentials
Available when your workspace is enabled for **bring-your-own-key (BYOK)**. Paste an Anthropic or OpenAI API key and Clarion infers the provider from the key prefix.
A workspace with its own usable key runs **only** on that key: no cross-subsidy, and no tenant data through Clarion's provider account. See [Models & runtime](/clarion/learn/agents#models-runtime) for how that interacts with tiers and failover.
### Elsewhere in Settings
Invite teammates and set how Clarion reaches them.
The role × permission matrix Clarion enforces.
System prompt, agent behavior, severities that escalate, and skills.
Model tiers, failover, and your own providers.
Enforce single sign-on through Microsoft Entra ID.
Connect Claude Code, Cursor, or scripts to the workspace.
### General
**Settings → General** holds the workspace-level actions you rarely need:
* **Demo data** — load or clear a sample dataset for evaluating Clarion.
* **Health checks** — run Clarion's own integration and monitor health checks on demand.
* **Delete workspace** — permanent, and removes every issue, agent, and integration in it.
## Agents
**Settings → Agents** shapes how every agent in the workspace triages. It opens on the system prompt, so you can see what agents are told before you change anything.
The page has four sections, each linked from the settings sidebar under **Agents**:
| Section | What it holds | Editable |
| - | - | - |
| [System prompt](#system-prompt) | The default prompt every triage run starts from | No |
| [Agent behavior](#agent-behavior) | Standing instructions every agent follows | Yes |
| [Escalation & notifications](#escalation-and-notifications) | Severities that escalate, and where agents send escalations, approvals and questions | Yes |
| [Skills](#skills) | Playbooks agents open on demand | Yes |
Changes take effect on the next agent run. Drafts are kept when you switch between sections.
### System prompt
The default prompt Clarion gives every triage agent in the workspace. Clarion maintains it and you can't edit it; the version shown next to it changes whenever Clarion updates the prompt.
What you *can* change is added on top of it: **Agent behavior** and **Escalation & notifications**. The escalation bar is written into the prompt itself, so the text you see reflects your current setting.
Skills are not part of the prompt. Each agent sees the list of skills assigned to it and opens one only when an issue calls for it, so skills shape how agents work without making every triage longer.
### Agent behavior
Standing instructions every agent run inherits, on top of whatever its skills say. These were previously called *workspace instructions* and lived under **Settings → Workspace**. Over [MCP](/clarion/learn/settings#mcp-access), read and replace them with `get_agent_behavior` and `set_agent_behavior`. Use them for context that doesn't belong to any single skill:
* Your business context, and who owns which system.
* Organization-wide terminology, escalation hierarchy, and on-call conventions.
* Environment-specific quirks ("staging fires this alert nightly; it is expected").
* What agents must never do.
Notification channels do not belong here. Configure them under [Escalation & notifications](#escalation-and-notifications); agents read that set directly and pick a destination per run.
The editor supports the same `@`-references as the skill editor, so instructions can point at a specific skill by name.
Keep instructions short and high-signal. They are added to every run and compete with skill content for the agent's attention. If guidance only applies to one class of issue, it belongs in a skill, not here.
### Escalation and notifications
Decides when an agent pages your team, and where it sends escalations, approval requests and questions. Destinations, routing and the on-call rotation are covered in [Notifications](/clarion/learn/notifications).
#### Severities that escalate
When an agent finishes triaging an issue it considers a real problem, it **escalates** it: the issue moves to `Escalated` and the team is paged. This setting is the bar for that page. The agent escalates only when the issue's severity is one you selected. Anything below the bar moves to `Open` instead, so it still waits for a human, just without a notification.
* **Default:** `High` and `Critical`.
* **Choices:** any combination of `Low`, `Medium`, `High`, and `Critical`.
* **Minimum:** at least one severity. The last one can't be unchecked.
A few things are worth knowing:
* **The bar applies to agents only.** A member who clicks **Escalate** on an issue always escalates it, whatever its severity.
* **Parking an issue in `Open` doesn't change the verdict.** Its disposition and severity stay as triage set them; only the status differs.
* **Some issue kinds are stricter.** Issues of kind **Risk** or **Vulnerability** stay `Open` on an agent's decision regardless of this setting. The one exception is a `Critical` finding the agent justifies as imminent danger. See [Issue kinds](/clarion/learn/issues#issue-kinds).
* **Agents are told the bar.** Your selection is written into the [system prompt](#system-prompt), so the agent works from your policy rather than the default.
Don't restate or override the escalation bar in skills or agent behavior, for example "escalate every Medium finding". An instruction that conflicts with the system prompt confuses the agent, and the setting still decides the final status. To change which severities escalate, change this setting.
Adding `Medium` pages more often and catches more. Narrowing to `Critical` alone keeps pages rare but leaves more for your team to sweep in the `Open` queue. Start from the default and adjust once you see your volume.
### Skills
Step-by-step playbooks agents open on demand for specific kinds of alerts, such as a phishing report or a suspicious sign-in. Each row shows the skill's description, which is the only text an agent uses to decide whether to open it; missing descriptions and broken references are flagged. See [Skills](/clarion/learn/skills) and [Authoring best practices](/clarion/learn/skills#authoring-best-practices).
Domains, human-input toggles, and BYOK.
Destinations, routing, and the on-call rotation.
## SSO
Single Sign-On (SSO) lets your team log into Clarion with their existing identity provider. Clarion currently supports Microsoft Entra ID (formerly Azure AD).
### What SSO gives you
* **Centralized authentication**: Members log in through your IdP. No separate Clarion password.
* **Lifecycle parity**: When a member leaves your organization in your IdP, their Clarion access goes with it.
* **MFA inheritance**: Whatever MFA policy you enforce in your IdP applies to Clarion.
### Setup overview
1. Add Clarion as an enterprise app in Microsoft Entra ID.
2. Assign the users or groups who should have access.
3. Provide the tenant ID and any required claim mappings to Clarion through the SSO settings page.
4. Test sign-in with a non-admin account before enforcing SSO workspace-wide.
See [Microsoft Entra ID](/clarion/integrations/microsoft-entra-id) for the full step-by-step setup.
Once SSO is enforced, members can only sign in through your IdP. Make sure at least one workspace admin has a verified IdP account before enabling enforcement.
## MCP access
Clarion exposes a workspace-scoped Model Context Protocol (MCP) server so external clients can — without the Clarion web UI — read issues, tasks, monitors, signals, signal rules, and enabled Bounty programs; add credential-free monitors; inspect agent-run records and transcripts; run assistant chats; operate the scheduler; author and edit agents and skills; browse and instantiate templates; and manage the workspace's agent behavior. There are two ways to connect: OAuth (for IDE/agent clients) and long-lived API tokens (for headless ones).
### Where it lives
In Clarion, go to **Settings > MCP access**. The page has two tabs:
* **OAuth setup** — copy-paste snippets for Claude Code and Claude Desktop, plus a generic note for other MCP clients. No secrets to manage. This is the tab the page opens on.
* **API tokens** — mint, list, and revoke long-lived bearer tokens. One row per token; the plaintext is shown exactly once at creation time.
The MCP endpoint itself is at `https:///api/mcp` (the OAuth setup tab fills in the right URL for your environment).
***
### Choosing a flow
| | OAuth | Long-lived token |
| - | - | - |
| Best for | Claude Code, Cursor, any IDE/agent client that can open a browser | CI jobs, cron workers, headless scripts |
| Setup | One browser sign-in, no secret to copy | Mint a token, copy it into the client config |
| Revocation | From the client's settings | Revoke the row in **Settings > MCP access** |
| Appears in token list | No | Yes |
If a client supports OAuth, use it. The browser flow handles re-auth automatically when access expires; long-lived tokens never rotate and stay valid until revoked or their owner is removed from the workspace.
***
### Connecting via OAuth
#### Claude Code (CLI)
1. Open **Settings > MCP access > OAuth setup** and copy the `claude mcp add` command shown there. It already contains the right URL for your workspace.
2. Run it:
```bash theme={null}
claude mcp add --transport http clarion https:///api/mcp
```
3. Start a session. On the first tool call Claude Code opens the Clarion OAuth grant page — pick the workspace and approve. The token is captured by Claude Code's local callback.
#### Claude Desktop
1. Open **Settings > MCP access > OAuth setup** and copy the JSON snippet.
2. Paste it into `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on Windows/Linux:
```json theme={null}
{
"mcpServers": {
"clarion": {
"type": "http",
"url": "https:///api/mcp"
}
}
}
```
3. Restart Claude Desktop. The first tool call triggers the same browser grant flow as the CLI.
#### Other MCP clients
Point any MCP client that speaks the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) at `https:///api/mcp`. The first unauthenticated request returns a `WWW-Authenticate` challenge that points at `/.well-known/oauth-protected-resource`; any spec-compliant client follows the metadata to discover the authorization server and complete the OAuth flow without extra config.
***
### Connecting via a long-lived API token
Use this when the client can't drive an interactive browser sign-in.
1. In **Settings > MCP access > API tokens**, click **New token**.
2. Give it a label that lets you recognize it later (e.g. `CI nightly drift check`, `Cron worker`).
3. Click **Create token**. The dialog swaps to a one-time reveal — copy the plaintext **now**. Once you close the dialog the secret is gone for good.
4. Paste the token into your MCP client config as a `Bearer` credential:
```json theme={null}
{
"mcpServers": {
"clarion": {
"type": "http",
"url": "https:///api/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}
```
A long-lived token grants the access permitted by its owner's current workspace role. For Admins, that includes **creating and editing configuration**: agents, skills, schedules, and the workspace's agent behavior. Treat it like any other secret — keep it out of source control and rotate (revoke + re-mint) on a cadence that matches your other credentials.
#### Revoking a token
In the **API tokens** tab, click the revoke icon on the row, confirm, and the token stops authenticating immediately. Any client still using it gets a 401 on its next request. Revocation is one-way; revoked rows stay in the list with a "Revoked" badge so you can audit who created them and when.
***
### Available tools
After connecting, the client sees the following workspace-scoped tools under the `clarion` server (so each one appears as `mcp__clarion__`). Every tool is scoped to the token's workspace: reads filter by workspace, cross-workspace lookups return an error rather than another tenant's data, and mutations are attributed to the operator who minted the token.
**Breaking change — argument names.** Several tools now take the argument names the same tools use everywhere else in Clarion:
| Tool | Was | Now |
| - | - | - |
| `list_tasks` | `issueNumber` | `issue_number` |
| `get_task` | `taskId` | `id` |
| `get_schedule` | `scheduleId` | `schedule_id` |
| `set_issue_status` | `statusComment`, `applyToSubIssues` | `status_comment`, `apply_to_sub_issues` |
| `get_skill` | `skillId` (one) | `skillIds` (a list) |
The old names are **not** accepted and **not** rejected — they are ignored. A call passing `issueNumber` returns an unfiltered list rather than an error. Update any saved prompt or script that passes them.
`get_skill` also changed shape: it now takes a list and returns `{ skills, errors }`, so one unknown id reports itself in `errors` instead of failing the call. `list_skills` gained an optional `search` filter and now returns `{ total, skills }` rather than a bare array. Otherwise only the names changed. `apply_to_sub_issues` stays optional and still defaults to leaving sub-issues alone, and `set_issue_status` still accepts every status including `escalated`.
#### Read & triage
**Issues**
* `list_issues` — paginated list, filterable by status / severity / search. `status: ["escalated"]` narrows to the confirmed problems.
* `get_issue` — full issue detail by display number, including its parent issue and related child issues
* `complete_remediation_item` — toggle a checklist item on an issue's remediation list
* `retrigger_issue` — re-run triage agents for an issue (e.g. after deploying a fix)
* `update_issue` — edit an issue's title, description, or verdict; marking one a duplicate stays in the Clarion UI (requires `issues:write`)
* `set_issue_severity` — change an issue's severity (requires `issues:write`)
* `set_issue_status` — move an issue to a new status, including closing it with a verdict; sub-issues follow only when asked (requires `issues:write`)
**Tasks**
* `list_tasks` — paginated list, filter by status / priority / search / `issue_number`
* `get_task` — single task by `id`
* `set_task_status` — complete or reopen a task (requires `tasks:write`)
**Monitors & integrations**
* `list_monitors`, `get_monitor` — the workspace's ingestion sources, with sanitized per-type config (webhook secrets stripped)
* `create_monitor` — add a monitor of a credential-free type: `dns`, `rss_feed`, or `status_page` (requires `monitors:manage`). The domain or URL is fetched server-side before the monitor is saved. Every other type mints a webhook secret or takes an API key, so it stays in the Clarion UI.
* `update_monitor` — rename or enable/disable any monitor type; edit config only for the credential-free types (`dns`, `rss_feed`, `status_page`), which re-validates the feed/status page (requires `monitors:manage`). A config edit for a secret-bearing type stays in the Clarion UI.
* `delete_monitor` — permanently delete a monitor and its signal rules, tearing down any webhook registrations it created; any type can be deleted (requires `monitors:manage`)
* `list_integrations`, `get_integration_health` — integration sync health (consecutive failures, pause state, auth errors); credentials are never returned
**Signals**
* `list_signals`, `get_signal` — the raw ingested events that feed issues, before any alert filter fires
* `summarize_signals` — one source's signal counts per monitor and event type over the last 1–90 days, each marked with that monitor's signal rules whose steps match it. An event type with no covering rule is a detection gap.
**Signal rules**
* `list_signal_rules`, `get_signal_rule` — the detections that turn signals into issues, per monitor or workspace-wide (the matching sequence is returned by `get_signal_rule`)
* `create_signal_rule` — add a detection on a monitor: a match sequence plus the severity, kind, and title/description of the issue it fires (requires `signal_rules:manage`). The alert source is set server-side.
* `update_signal_rule` — partial-fields edit of a rule; editing a template-managed rule's content forks it from the template, while toggling active state or moving monitor does not (requires `signal_rules:manage`)
* `delete_signal_rule` — permanently delete a signal rule (requires `signal_rules:manage`)
**Bounties**
Bounties tools are registered only when the feature is enabled for an approved workspace and the token owner's current membership is resolved. Program reads require `bounty_programs:read`. Finding, Agent-triage, and comment reads use the application's shared authorization: Admins and BountyTriagers can read all workspace findings; Members can read only findings assigned to them. MCP mutations remain permission-gated: triage requires `bounty_submissions:triage`, and decisions require `bounty_submissions:decide`. Members have read-only Bounties access through MCP, even where the application allows assigned-finding actions. If any gate is off or unresolved, the affected tools do not appear in the client's tool list.
* `bounty_list_programs`, `bounty_get_program` — list or inspect workspace Bounty programs by public slug; internal ids, creator data, and Agent configuration are omitted
* `bounty_list_findings`, `bounty_get_finding` — page and filter Bounty-specific finding projections by program slug and public reference; the detail response derives currently available actions from lifecycle policy
* `bounty_get_agent_triage` — read the latest redacted Bounty Agent run in bounded 200-entry transcript pages
* `bounty_list_finding_comments`, `bounty_list_finding_comment_replies` — page visible finding discussion and reply history
* `bounty_start_manual_triage`, `bounty_submit_triager_assessment` — BountyTriager-only takeover and assessment-handoff actions
* `bounty_mark_finding_spam`, `bounty_mark_finding_duplicate`, `bounty_request_finding_information` — controlled, version-checked, idempotent triage mutations
* `bounty_decide_finding` — accept or reject a finding in triager/client review, or return a client-review finding to the triager, using its current status and version; Admin-only through `bounty_submissions:decide`
`BountyTriager` uses the same workspace credential and endpoint as other workspace roles, but sees only the Bounties tools allowed by its current permissions. Clarion resolves the token owner's current membership and role on every request; removing the owner from the workspace invalidates the credential on its next use.
**Agent runs**
* `get_agent_job` — the execution record of a single non-Bounty agent run (status, error, model, token usage, timing, and what it ran for: a triage investigation, an assistant chat, or a scheduled run); use `bounty_get_agent_triage` for Bounty runs
* `get_agent_job_transcript` — the poll-friendly, step-by-step transcript of an agent run (assistant turns, tool calls, tool results), oldest first
**Assistant chats**
* `list_chats` — the workspace's assistant chats
* `get_chat_transcript` — a chat's messages and tool activity
* `start_chat` — open a new assistant chat with a first user message (optionally booting a specific agent persona); returns an agent-run id to poll
* `send_chat_message` — post a follow-up message into an existing chat
**Schedules**
* `list_schedules`, `get_schedule` — discover what's running in the workspace
* `list_schedule_runs`, `get_schedule_run` — poll-friendly run snapshots
* `run_schedule_once` — fire a schedule out-of-band without changing its cron cadence
* `cancel_schedule_run` — cancel a pending or running execution
* `create_schedule`, `update_schedule`, `set_schedule_enabled`, `delete_schedule` — full CRUD on recurring tasks
#### Configure the workspace
Skill and instruction content is exchanged as **markdown** (with inline `` pills) and converted to/from Clarion's rich-text format automatically — you never handle the raw editor JSON.
**Agents**
* `list_agents`, `get_agent` — the workspace's triage agents and their linked skills/monitors
* `create_agent`, `update_agent` — manage an agent's name, active state, linked skills, and linked monitors. Create the credential-free monitor types with `create_monitor` first; the ones involving webhook secrets and registration stay in the Clarion UI.
**Skills**
* `list_skills`, `get_skill` — reusable workspace skills, instructions returned as markdown
* `create_skill`, `update_skill` — author or edit a skill from markdown; tools are extracted from the inline `` pills, and edits snapshot a new version
* `evaluate_skill` — check a saved skill (`skillId`) or an unsaved `draft` against the [authoring best practices](/clarion/learn/skills#authoring-best-practices); returns `meetsRecommendations`, plus `recommendations` when it does not
**Templates**
* `list_skill_templates`, `get_skill_template` — browse the curated skill-template catalog
* `create_skill_from_template` — instantiate a skill template into a *managed* workspace skill (auto-updates when the template changes; idempotent — returns the existing copy if already instantiated)
* `list_agent_templates`, `get_agent_template` — browse the published agent-template catalog
* `create_agent_from_template` — scaffold an agent plus its managed skills from a template, created inactive so you can review before it runs
**Workspace**
* `list_workspace_tools` — the action tools currently **available** to agents in this workspace. Only tools whose backing integration (and any required credentials or pauser config) is actually connected are returned — unconfigured ones are omitted — so this reflects what a skill can reference *today*. Includes the workspace's custom MCP servers, custom API/CLI toolsets, and Microsoft Sentinel tools.
* `get_agent_behavior`, `set_agent_behavior` — read or replace the workspace's [agent behavior](/clarion/learn/settings#agent-behavior) (markdown), the standing instructions added on top of the read-only system prompt for every agent
Templates are a shared, platform-curated catalog. These tools only **browse** it and **instantiate** copies into your workspace — creating, editing, or deleting templates is admin-only and is not exposed over MCP.
#### Asset catalog & curated knowledge (Brain)
These tools are only registered when the workspace has the **asset-catalog (Brain)** feature enabled. If it's off, none of them appear in the client's tool list. Writes to curated knowledge require the `assets:write` permission.
The Brain surface exposes the workspace's discovered infrastructure and the operator-curated architecture knowledge layered on top of it.
**Assets & systems (read)**
* `list_assets`, `get_asset` — the resources (compute, datastores, repos, services, DNS records, cloud accounts, …) discovered across connected integrations
* `list_systems` — the auto-correlated, cross-provider groupings of those assets
**Annotations (write)**
* `annotate_asset` — record durable, attributed notes/attributes on a resource
* `record_inferred_asset` — persist a triage-inferred narrative asset (attacker IP, involved user, vulnerable package, …) into the catalog
**Curated knowledge (read)**
* `search_knowledge` — text-search knowledge names, page bodies, and references
* `list_knowledge_elements`, `get_knowledge_element` — the hand-curated architecture nodes (systems, services, platforms, …) and their linked assets and references
* `list_knowledge_references` — curated external references filtered by semantic tag (`access_control`, `runbook`, `architecture`, …)
**Curated knowledge (write)**
* `propose_knowledge_element`, `update_knowledge_element`, `remove_knowledge_element` — create/enrich, edit, or delete a curated knowledge node
* `link_knowledge_asset`, `unlink_knowledge_asset` — connect or disconnect a catalog asset and a knowledge node
* `add_knowledge_fact`, `update_knowledge_fact`, `delete_knowledge_fact` — weave, supersede, or retract an atomic claim in a knowledge node's recap
The agent-side MCP server used by Clarion's own triage agents has a separate (broader) tool surface — agents see integration tools like `mcp__slack__*`, `mcp__okta__*`, `mcp__cloudtrail__*` etc. that aren't exposed externally. External MCP clients only see the workspace tools listed above. `list_workspace_tools` surfaces the *names* of the available integration tools so a skill you author can reference them by their `` type, but those tools still execute agent-side during triage.
# Skills
Source: https://docs.cantina.security/clarion/learn/skills
Reusable playbooks that teach agents how to handle specific classes of tasks to a known standard.
A skill is a reusable playbook that teaches the agent how to perform a specific class of tasks to a known standard, along with the tools available to investigate and remediate security issues.
Agents use skills to make decisions during triage. Updating a skill is how you change agent behavior.
## What a skill contains
* **Content**: Rich procedural text describing the playbook, with headings, lists, links, and embedded tools.
* **Tools**: Integrations the skill can invoke during execution, including Slack, Teams, Discord, SMS, email, PagerDuty, webhook, DNS, Jira, AWS, Vercel, Huntress, CrowdStrike, plus custom MCP tools.
* **Domain tags**: Categories like DNS, Identity & Access, Web3, Cloud, SDLC.
* **Versions**: Every save creates a snapshot with editor attribution. Compare and roll back as needed.
* **Lineage**: Skills can be **managed** (synced from a template) or **unmanaged** (forked or custom). Editing a managed skill forks it.
## Skill templates
Clarion ships **131 skill templates** across **13 domains** — Cloud, Identity & Access, Endpoint & Device, SDLC, DNS & Infrastructure, Operations, Vulnerability, Security Incidents, Network, Web3 & Blockchain, Application, Email, and Threat Intelligence.
See [Our skills](/clarion/learn/skills#our-skills) for the full breakdown, and the [Community Library](https://clarion.cantina.xyz/community) for skills shared by other teams running Clarion.
## Agent behavior
Skills describe how to handle a specific class of tasks. For guidance that should apply across **every** agent in your workspace, use [**Settings → Agents → Agent behavior**](/clarion/learn/settings#agent-behavior) instead of duplicating it in each skill.
Good examples:
* How to start a war room.
* Organization-wide terminology, escalation hierarchy, and on-call conventions.
## What you can do
* **Create** skills from a template or from scratch.
* **Edit** skill content with full version history.
* **Embed tools** in a skill to give agents the actions they need.
* **Assign** skills to agents.
* **Fork** templates on customization, or **reset** back to the template default.
Every domain we ship skill templates for.
The actions a skill can give an agent.
How to write a skill agents pick at the right moment and follow well.
## Our skills
Clarion ships **131 skill templates** across **13 domains**. Every skill is a self-contained playbook: its description says when to apply it, and its body says how to investigate and what to do about it. Attach one to an agent and it stays synced with the template; edit it and it forks into your own copy.
Skills are grouped by domain so you can find the right playbook by the kind of problem, not by which vendor raised it. A skill can be shared by several agents — the counts below are of distinct skills.
| Domain | Skills | Coverage in one line |
| - | - | - |
| [Cloud](#cloud) | 40 | AWS, Azure, GCP, Cloudflare, Vercel, Replit, and Wiz control-plane and exposure response |
| [Identity & Access](#identity-access) | 26 | Sign-in anomalies, MFA and session attacks, OAuth abuse, privilege escalation, secret-manager misuse |
| [Endpoint & Device](#endpoint-device) | 16 | EDR triage and the full attack chain, from execution to ransomware, across four vendors |
| [SDLC](#sdlc) | 13 | Repository and CI/CD integrity, dependency findings, MCP-server governance, shift-left design review |
| [DNS & Infrastructure](#dns-infrastructure) | 10 | Record, subdomain, and email-auth changes; registrar hijack, tunneling, and takeover risk |
| [Operations](#operations) | 7 | Outage runbooks, detection tuning, knowledge upkeep, vendor review, questionnaire drafting |
| [Vulnerability](#vulnerability) | 6 | Dependency and bug-bounty findings, reachability validation, remediation evidence |
| [Security Incidents](#security-incidents) | 5 | Cross-product incident entry points and hunting pivots |
| [Network](#network) | 3 | Edge DDoS, WAF, and origin-exposure response |
| [Web3 & Blockchain](#web3-blockchain) | 2 | On-chain alert response and multisig signer monitoring |
| [Application](#application) | 1 | Client-side script and supply-chain integrity |
| [Email](#email) | 1 | Phishing and email-threat investigation |
| [Threat Intelligence](#threat-intelligence) | 1 | Advisory triage and applicability to your environment |
### Cloud
**40 skills.** The largest domain, and the one with the deepest per-provider coverage.
* **AWS (10)** — a general CloudTrail response procedure plus dedicated playbooks for root-account security, IAM privilege escalation and persistence, credential exposure and access-key compromise, console authentication abuse, compute compromise, network and infrastructure manipulation, data exfiltration and resource exposure, suspicious access activity, and defense evasion or log tampering.
* **Azure (10)** — security posture triage and Defender for Cloud alert response, then Entra ID identity compromise, RBAC privilege escalation and persistence, Storage and data exposure, Key Vault secret access, network exposure and lateral movement, compute compromise, defense evasion, and Secure Score misconfiguration remediation.
* **GCP (7)** — Cloud Monitoring incident triage and Security Command Center finding triage, then privilege escalation and anti-forensics, service-account key compromise, unauthorized compute, and SCC-specific IAM and exposure response.
* **Wiz (3)** — toxic combinations scored on whether their ANDed facets are simultaneously live, threat detections scored on actor and baseline, and resource and identity ownership context.
* **Cloudflare (2)** — origin and edge availability, certificate and Access lifecycle.
* **Vercel and Replit (6)** — exposure sweeps and single-site triage for each platform, plus Vercel deployment-failure triage and security and domain monitoring.
* **Microsoft Sentinel (1)** — Azure and cloud control-plane activity investigation.
* **Cross-provider (1)** — suspicious shell session.
### Identity & Access
**26 skills.** The broadest attack-pattern coverage of any domain, mirrored across identity providers.
* **Provider-neutral core (14)** — triage and a general response procedure, then impossible travel, brute force and credential attacks, MFA attacks and session hijacking, OAuth and API abuse, admin compromise and privilege escalation, federation and IdP abuse, email and communication exposure, data exfiltration and staging, mobile device and MDM security, security control and policy weakening, government-backed attack warnings, and phishing campaign response.
* **Microsoft (6)** — Defender XDR variants of impossible travel, MFA and session hijacking, OAuth abuse, and admin compromise; Sentinel identity-compromise investigation and UEBA anomaly investigation.
* **1Password (4)** — burst failed sign-ins, user suspension, vault item export, and the vault-access-then-export sequence.
* **Huntress ITDR (1)** and **Wiz entitlement review (1)** — identity findings from the detection and posture sides.
### Endpoint & Device
**16 skills.** Every vendor gets a triage entry point; the attack-chain playbooks sit behind it.
* **CrowdStrike (8)** — Falcon and OverWatch triage, then execution (scripts, LOLBins, process-ancestry anomalies), persistence, credential access, defense evasion and sensor tampering, lateral movement, command and control and exfiltration, and ransomware and destructive action.
* **SentinelOne (4)** — threat triage, investigation and scoping, gated containment and response, and false-positive handling with exclusions.
* **Microsoft (2)** — Defender endpoint host deep-dive and Sentinel ransomware and mass-impact scoping.
* **Huntress (2)** — incident investigation and escalation handoff.
### SDLC
**13 skills.** Repository integrity, pipeline integrity, and the governance of what developers connect their tooling to.
* **GitHub (7)** — tag spraying, CI/CD script injection via branch names, force push on a default branch, repository visibility change to public, branch-protection misconfiguration, org-owner addition, and a generic GitHub alert fallback.
* **Claude Code / MCP governance (3)** — server governance triage, inventory review sweep, and external account triage.
* **Apex (2)** — triage and remediation, plus a customizable Apex skill.
* **Shift-left (1)** — assessing new Jira epics for security risk before implementation starts.
### DNS & Infrastructure
**10 skills.** Change detection on the records that define who you are, plus takeover risk.
Record change, subdomain change, email-authentication (SPF/DKIM/DMARC) change, new subdomain discovery, DNS hijacking and registrar compromise, DNS tunneling and data exfiltration, DNS DDoS and amplification, Cloudflare DNS and zone integrity, and the dangling-subdomain sweep and triage pair.
### Operations
**7 skills.** The playbooks that keep the platform and the program healthy rather than responding to an attack.
Outage runbook, health-repair triage for Clarion's own integrations and monitors, signal-rule refinement, Brain maintenance, Vercel production rollback and recovery, review of newly discovered Vanta vendors, and drafting answers to vendor security questionnaires (DDQ / SIG / VSA).
### Vulnerability
**6 skills.** Findings that arrive as a queue rather than an incident, and the evidence trail behind closing them.
Dependabot vulnerability remediation and backlog processing, reachability and runtime validation with exposure scoring (shared by Apex and Dependabot), Wiz vulnerability and component exposure, Cantina bug-bounty finding triage, and SOC 2 evidence collection.
### Security Incidents
**5 skills.** Cross-product entry points that route to the scenario playbooks in other domains.
Microsoft Defender XDR and Microsoft Sentinel incident triage procedures, the Sentinel advanced-hunting pivot, Cloudflare Logpush incident handoff, and credential-harvesting triage.
### Network
**3 skills.** Cloudflare Logpush L7 DDoS detection triage, Logpush origin-exposure and DNS-bypass checks, and Cloudflare DDoS and WAF attack response.
### Web3 & Blockchain
**2 skills.** Smart contract and on-chain alert response — including emergency pause coordination — and multisig signer monitoring.
### Application
**1 skill.** Cloudflare client-side security response, covering injected JavaScript and browser-side supply-chain integrity.
### Email
**1 skill.** Microsoft Sentinel phishing and email-threat investigation.
### Threat Intelligence
**1 skill.** Threat intel advisory triage and applicability — deciding whether a published advisory, IOC set, or TTP actually touches your environment.
### Beyond the library
Skill templates are a starting point. The **[Community Library](https://clarion.cantina.xyz/community)** carries skills written and proven by other security teams running Clarion, alongside full agents. Take a single skill into an agent you already have, or an entire agent with its skills and scheduled jobs.
Skills and agents shared by teams running Clarion.
Every agent template and the skills it bundles.
## Authoring best practices
Skills are the backbone of our platform. Authoring good skills will make a huge difference in both the triage result, and also the duration.
These practices follow the skill templates we ship as part of Clarion. Open any of them from the [skill library](/clarion/learn/skills#our-skills) to see an example.
### What is a skill
A skill is a set of instructions written in natural language that belong to one or multiple agents. They are primarily used as part of the triage and remediation phases, thus authoring your own skills gives you control over how different alerts are being handled.
### How agents use skills
Every agent has access to its own skills plus any skills referenced by those. Also, it has access to any skills referenced in [agent behavior](/clarion/learn/settings#agent-behavior) or in the scheduled task prompt.
When starting, the agent gets the title and description of each of those skills. It will then decide which ones to follow, and read their full body. After that, it will proceed to follow the instructions in those skills it read.
We don't inject the full skill body in the agent context, to prevent bloat. That's why good titles and descriptions are essential to make sure the agent picks the right one.
### Title
A good title should name the category of this task, not the agent or author. As a reader scanning the catalog, we should know what the skill is for from the title alone.
| Good | Weak |
| - | - |
| Identity Entitlement Review | Wiz skill 2 |
| Vercel Exposure Sweep | Weekly check |
| Credential harvesting triage | Claude Code agent playbook |
Include the vendor when the skill only works against one vendor's data. Keep it generic if it's provider neutral
### Description
The description will be used by the Agent when to decide what skill to follow, so it must include two things:
* a short summary of what the skill does
* instructions of when to use this skill
Keep the description short, ideally 2 or 3 sentences. A long description bloats the context of every agent run
Good description examples:
* Investigates GCP service account key creation as potential credential compromise or attacker persistence. Use when a new service account key is created, especially outside expected workflows.
* Investigates failed-sign-in bursts on a 1Password user as brute force, credential stuffing, or targeted account takeover. Use when an alert fires for multiple failed 1Password sign-in attempts for the same user in a small period.
* Remediates Dependabot vulnerabilities end-to-end and escalates high/critical findings in place. Use when a Clarion alert fires for one or more Dependabot vulnerabilities in a repository.
Bad description examples:
* Handles Wiz findings.
* Investigates suspicious activity and takes the appropriate action.
* First fetch the issue, then query the audit logs for the last 24 hours, check the user in Okta, and post a summary to Slack.
### Body
The body represents the instructions for the agent to follow. Try authoring it like guidance from the most experienced person on the team, thus saying what matters, what to check, what the evidence means, and what to do about it.
Agents are smart so this doesn't need to be a very specific step-by-step list. Keep it generic when the flow is not clear, so the agent can follow its own reasoning
#### Common template
Most templates follow the same outline. Keep the sections your skill needs and drop the rest.
| Section | Purpose |
| - | - |
| Opening framing | One to three sentences on the goal and on what does and does not count as a finding |
| Ground rules | Rules that hold across every step, each with its reason |
| Workflow | Usually numbered steps, each naming what to check, and how/if the result changes the next step |
| Outcome | The evidence that decides the verdict and severity, then what to do once decided: escalate or set the status, and write what was learned to the Brain |
| Remediation | What the agent may fix itself and under which verdict (open a PR, revert a record, contain a host) and what it leaves to a human as a follow-up task |
#### What to put in the skill
1. Specify what the goal is and what isn't
> The goal is to find deployments open to the internet that were **not meant to be**: internal dashboards, admin panels, stale proofs-of-concept. Intentionally public marketing sites, blogs, and products that enforce their own login are not findings.
2. Give every rule its reason so the agent can generalise
> Do not escalate Dependabot issues that are related to dev-only packages. They create noise and unnecessary work for the team. The priority should be on actual packages used in the production deployment.
3. Mention the required evidence
Say what counts as actual proof and what does not. The correctness of the alert details cannot be guaranteed, that's why the agent needs to correlate with actual evidence by using the available tools.
4. Keep it concise and clear
Think whether or not this skill makes sense if read by a colleague. If not, probably won't make sense if read by an agent.
Split a skill when its triggers differ, or when the evidence that decides the verdict differs. Two skills that each do one job route better, and read better, than one skill with a branch at the top.
#### What not to put in the skill
1. Do not mention tools by name. They are internal and may change freely, thus your skills will be outdated. Instead specify what the agent should do, not how.
2. Do not mention tool categories. By default each agent has access to all tools connected in your workspace. You can configure this from the agent page if you want granular control.
3. Do not give instructions about where or when to post notifications. Configure both under **Settings → Agents → Escalation & notifications**: see [Notifications](/clarion/learn/notifications) and [Severities that escalate](/clarion/learn/settings#severities-that-escalate).
4. Do not give instructions regarding asking for approvals. Those are set up once under **Settings → Tool policies** and they apply to all agents.
5. Do not put inside skills general knowledge about your business, the systems you use or the clients you have. This knowledge belongs in the Clarion Brain not in skills.
6. Do not put inside skills instructions that apply across all agents. Those belong in [agent behavior](/clarion/learn/settings#agent-behavior). A good example of such a rule is always creating a Linear task before starting triage of an issue.
### References inside a skill
The skill editor turns references into pills. Each kind behaves differently at runtime, and two of them change what the agent is allowed to do.
| Pill | Editor trigger | What it does at runtime |
| - | - | - |
| Skill | `$` | Adds the referenced skill to the agent's catalog, even when that skill is not linked to the agent, so the agent can fetch it at the step that needs it. References are followed up to three levels deep. |
| Knowledge | `$` | Declares a Brain knowledge element the skill depends on. The agent is told to fetch its live content by id instead of searching for it. The `$` picker lists skills and knowledge together, and offers knowledge only in the skill editor. |
| Channel or person | `#`, `@` | Points the agent at a Slack or Teams channel or person. Although notification settings are set up once per workspace, this can be useful to point the agent at channels to read or people to coordinate with during the investigation. |
| Tool | `/` | DEPRECATED. Names the tool the step should use. It is no longer needed, as the agent can use every connected integration its agent settings allow. |
Edit the skill to change how an agent handles an issue. The agent's own settings decide which tool groups it may use and which model it runs on, so check those when an agent cannot take an action its skill asks for.
### Final recommendations
Always review the skills you write, even if written by an AI. Good skills are essential for a good Clarion experience.
Before saving them, ask Clarion to review them, it will provide actionable feedback.
# Tasks
Source: https://docs.cantina.security/clarion/learn/tasks
Track follow-up work, agent improvements, and operational actions across your team.
Tasks are work items that persist beyond a single issue. Use them to track follow-up actions, capture agent-suggested improvements, and assign operational work to your team.
## What a task contains
* **Identifier**: Auto-incrementing number (TASK-001, TASK-002).
* **Status**: `Open` or `Completed`.
* **Priority**: `Low`, `Medium`, `High`, or `Critical`.
* **Assignees**: One or more team members responsible.
* **Linked issues**: Optional context the task relates to.
* **Linked improvement chats**: When an agent proposes a change, the conversation thread is preserved with the task.
## Where tasks come from
* **Manually**: Create a task from an issue, or directly from the Tasks view.
* **From agent investigations**: Agents propose tasks when they spot work a human should do (e.g. "rotate this access key").
* **From assistant chats**: Conversations that result in a proposed change become improvement tasks.
## What you can do
* **Create** tasks with title, description, priority, and assignees.
* **Assign** to one or more team members.
* **Update status** as work progresses.
* **Link** related issues for context.
* **Complete** tasks as work finishes.
# Tools
Source: https://docs.cantina.security/clarion/learn/tools
The integrations agents use to take action: send messages, change DNS, file tickets, and more.
Tools are the actions agents can take. Where skills describe what to do, tools are how it gets done.
## What a tool is
A tool is a single integration call: post a Slack message, update a DNS record, open a Jira ticket, page on-call. Tools are configured inside skills, so the same skill can be reused across agents and the same tool can appear in multiple skills.
## Built-in tool types
Clarion ships with native tools across these categories:
* **Notifications**: Slack, Teams, Discord, SMS, email, PagerDuty, phone call.
* **Ticketing**: Jira, GitHub Issues.
* **DNS & infrastructure**: Route 53, Cloudflare DNS, generic DNS providers.
* **Cloud**: AWS (CloudTrail lookups, IAM queries), Vercel.
* **Endpoint**: Huntress, CrowdStrike.
* **On-chain response**: Pause actions for smart contracts.
* **Issue management**: Create or update Clarion issues from a skill.
* **Approval & clarification**: Request human input before continuing.
## Custom MCP tools
Bring your own tool over MCP. Any [Model Context Protocol](https://modelcontextprotocol.io/) server you point Clarion at becomes available as a tool inside skills. Use this to integrate internal systems without writing a custom connector.
## Approval and execution modes
You can configure how tools run under **Settings → Tool policies**. Two execution modes are available, and both can be set at the tool level or per individual action:
* **Automatic**: The agent executes the tool without asking.
* **Requires approval**: The agent pauses and waits for a human to approve before executing.
Some tools also expose an **execution level** that controls the blast radius of an action:
* **Local**: Narrow scope, typically limited to a single resource or account.
* **Protected**: Wider scope, gated more carefully and usually combined with approval.
* **No restriction**: Full access. Combine with approval gates for sensitive actions.
## What an execution looks like
When a tool runs during an agent investigation, Clarion records:
* **Input parameters** as resolved at the time of the call.
* **Output** returned by the integration.
* **External ID** linking back to the system of record (Jira issue key, Slack message link, and so on).
* **Status**: succeeded, failed, pending approval, or pending clarification.
* **Errors** if the call failed.
Sensitive tools like DNS changes, smart contract pauses, and IAM revokes are gated behind approval requests by default. The agent pauses, the right human is notified through their preferred channel, and execution resumes after they approve.
How agents reach you for approval and clarification.
Everything Clarion connects to, on cantina.security.
# Getting the most value
Source: https://docs.cantina.security/clarion/roi/getting-the-most-value
The setup choices that most increase the time and money Clarion saves you.
ROI is not automatic. It scales with how much of your stack Clarion can see and how much of your team's judgment it can execute. This checklist covers the changes with the biggest payoff, in order.
Correlation and deduplication only work across the tools Clarion can see. Each missing integration is a blind spot where duplicate alerts still reach your team and context is missing from investigations. Start with your noisiest sources: SIEM, EDR, and cloud audit logs typically produce the most volume.
Auto-resolution is the largest line in the ROI calculation, and it only happens where an [agent](/clarion/learn/agents) is watching. Use the built-in templates to cover common workflows first, then point agents at whichever issue sources dominate your Analytics volume.
An agent with generic knowledge triages. An agent with your [skills](/clarion/learn/skills) triages the way your best analyst would: it knows which systems are critical, which alerts are known-benign, and who to escalate to. Every playbook you capture also survives team turnover.
[Alert filters](/clarion/learn/issues) decide which raw signals become issues at all. A few well-placed rules for known-noisy patterns cut your false positive rate directly, which is pure recovered time.
[Monitors](/clarion/learn/agents#monitors) on DNS records, endpoints, and infrastructure catch problems before they become incidents. Prevented incidents are the cheapest incidents.
Agents pause on sensitive actions until a human approves. If [notifications](/clarion/learn/notifications) land in Slack or Teams where your team already works, approvals take seconds and investigations do not stall waiting on a human.
## How you know it is working
Watch the Analytics page month over month:
* **AI Auto Resolved** should rise as agents and skills cover more of your queue.
* **False Positive Rate** should fall as filters and correlation absorb noise.
* **Mean Time to Respond** should fall as more issues get an instant first response.
When a metric plateaus, revisit the step above that feeds it. Then put the numbers into the [Measuring your ROI](/clarion/roi/measuring-roi) formulas to see the result in hours and dollars.
# Measuring your ROI
Source: https://docs.cantina.security/clarion/roi/measuring-roi
Turn the numbers on your Analytics page into hours and dollars saved.
Everything on this page uses data Clarion already collects for your workspace. Open the **Analytics** page in the sidebar to follow along with your own numbers.
## The four value levers
Clarion returns value in four ways. Each one maps to a metric you can read straight off the Analytics page.
Every issue an agent auto-resolves is an investigation your team never had to run.
Deduplication and alert filters cut the false positives that eat analyst hours.
Agents respond at 3am without waking anyone up, replacing on-call escalations.
Agents triage an issue in 3.4 minutes on average, shrinking the window an attacker has to do damage.
## Where your numbers live
| Analytics metric | What it tells you |
| - | - |
| **Issues Auto-Resolved** | The count of issues fully triaged and closed by agents with no human time spent |
| **AI Auto Resolved** | The share of your issues resolved without human involvement |
| **Agent Runs** | Total investigations agents performed on your behalf |
| **False Positive Rate** | How much incoming noise Clarion is absorbing before it reaches your team |
| **Mean Time to Respond** | How quickly issues get a verdict, around the clock |
| **Issues by Severity** | Where agent effort is concentrated, and what would otherwise be your queue |
## Translating to hours
An auto-resolved issue never reaches an analyst, so the time saved is the full manual investigation it replaced. The 3.4 minutes an agent spends on average do not count against you: they run in parallel and cost your team nothing.
```text theme={null}
minutes saved = auto-resolved issues x manual triage minutes
hours saved = minutes saved / 60
```
If you have not measured your own manual triage time, 15 to 30 minutes per alert is a common starting range for a SOC investigation. Substitute the number your team actually experiences.
Issues that agents triage but still escalate carry a partial saving too, since analysts start from a finished report instead of a raw alert. The calculation above ignores that, so treat it as a conservative floor.
## Translating to dollars
```text theme={null}
dollar value = hours saved x analyst hourly cost
```
Use the fully loaded hourly cost: salary plus benefits, tooling, and overhead, not base pay. Many teams use a figure between \$75 and \$110 per hour; your finance team will have the real one.
### A worked example
The numbers below are illustrative. Replace them with your own from the Analytics page.
| Input | Example value |
| - | - |
| Issues Auto-Resolved (per month) | 1,500 |
| Minutes per manual triage | 20 |
| Fully loaded analyst cost | \$85/hour |
```text theme={null}
minutes saved = 1,500 x 20 = 30,000 minutes/month
hours saved = 30,000 / 60 = 500 hours/month
dollar value = 500 x $85 = $42,500/month
annualized = $42,500 x 12 = $510,000/year
```
That is the capacity of roughly three full-time analysts, recovered without hiring.
## Value that is harder to price, but real
* **After-hours response.** Count the issues resolved outside business hours. Each one is an avoided page, an avoided escalation, or an avoided morning backlog.
* **Faster containment.** Agents deliver a first verdict within minutes of an issue opening, instead of the alert waiting in a queue for the next free analyst. Every hour off your mean time to respond is an hour less of attacker dwell time, and shorter incidents are cheaper incidents.
* **Knowledge that stays.** Playbooks captured as [skills](/clarion/learn/skills) keep working when the analyst who wrote them moves on. Onboarding a new hire onto documented, executable skills is faster than tribal knowledge transfer.
Review these numbers monthly. The [Getting the most value](/clarion/roi/getting-the-most-value) checklist covers the setup changes that move them.
# How Cantina works: the loop
Source: https://docs.cantina.security/how-it-works
How Cantina runs security work as a single loop: find, prioritize, remediate, and prove every issue closed with evidence.
Cantina runs security work as a single loop, from the first signal to a verified fix on the record. Every product and service on the platform maps to one of these four stages.
## Find
Cantina connects to your code, cloud, identity, and the tools you already run, and surfaces real security issues. Apex analyzes your codebase and pull requests; Clarion ingests signals from across your stack. The goal is not more findings. It is the findings that matter.
## Prioritize
Cantina understands your environment: your owners, your exposure, and your regulatory context. It ranks issues by what they actually put at risk, so your team spends time on what matters and keeps its credibility with engineering.
## Remediate
Cantina does not hand off a ticket and disappear. It works the fix, generates the change, and routes it to the owner, with a human in the driver's seat deciding how much the agent does on its own.
## Prove
A fix is not done until it is verified. Cantina confirms the issue is actually closed, records the evidence, and keeps proof on the record for engineering and auditors alike.
The result: fewer, defensible findings, faster time to resolution, and every loop closed with proof.
# Welcome to Cantina
Source: https://docs.cantina.security/introduction
Cantina is an agentic security platform that finds the issues that matter, prioritizes them against real exposure, remediates them, and proves the loop is closed.
Cantina is an agentic security platform. It finds the security issues that matter in your environment, prioritizes them against your real exposure, remediates them correctly, and proves the loop is closed.
Discovery is no longer the bottleneck. AI has made finding issues cheap, and findings now arrive faster than any human triage process was built to handle. The hard part is closing the loop: prioritizing what actually matters, remediating it correctly, and proving the fix holds. That is the work Cantina does.
## Who Cantina is for
Security teams at engineering-led companies who are accountable for more risk than they can manage by hand, and the security researchers who help secure the world's most critical code.
## What's here
* **[Platform Overview](/platform/overview)**: how Cantina works, the loop, and the core concepts.
* **Products**: [Apex](/apex) for code security, and [Clarion](/clarion) for security operations and response.
* **For Security Teams**: getting started, security services, and building on the platform.
* **For Security Researchers**: how to participate, contribute, and earn.
# Platform overview
Source: https://docs.cantina.security/platform/overview
One agentic security platform with two products, Apex and Clarion, and a network of human expertise, all running the same loop.
Cantina is one agentic security platform with two products and a network of human expertise behind it. Everything on the platform runs the same loop: find, prioritize, remediate, prove.
## The platform
* **[Apex](/apex)** handles code security: white-box scanning of repositories and pull requests, findings you can defend, and fix verification.
* **[Clarion](/clarion)** handles security operations: it ingests signals from across your stack, correlates and triages them, and executes governed response.
* **Services** from the Cantina network (audits, competitions, bug bounty, pen testing, MDR, advisory) plug into the same platform.
## How it fits together
Apex finds issues in code and hands them off; Clarion consolidates signals and drives response; both feed the same loop and the same record of what was found, fixed, and verified. Your team works from one place instead of stitching point tools together.
## Principles
* **Agentic, not another AI-SOC.** Reasoning agents, not brittle playbooks.
* **Human in the driver's seat.** You set how much the agents do on their own.
* **Sits above your stack.** Keep the tools you have; Cantina closes the loop across them.
* **Fewer findings, all defensible.** Top of funnel is not the problem; closure is.
# Products at a glance
Source: https://docs.cantina.security/platform/products
Apex for code security and Clarion for security operations, two products sharing one platform, one loop, and one record.
Cantina has two products. They share one platform, one loop, and one record of what was found, fixed, and verified.
## Apex - code security
[Apex](/apex) is Cantina's code security product. It performs white-box analysis of repositories and pull requests, produces defensible findings with evidence and remediation guidance, and verifies fixes. You connect a GitHub or GitLab source, scope a scan, and run it from the app, the CLI, or the API. Apex is #1 on the HackerOne US corporate leaderboard.
Where it fits in the loop: find (code), remediate (fix instructions), prove (fix review).
## Clarion - security operations
[Clarion](/clarion) is Cantina's security operations product. It ingests signals from the tools you already run (SIEM, EDR, cloud, identity, ticketing, and more), correlates and triages them, and executes governed response with a human in the driver's seat. It sits above your stack rather than replacing it.
Where it fits in the loop: find (signals), prioritize (correlation and exposure), remediate (governed action), prove (verified closure).
## Together
Apex finds and fixes issues in code; Clarion consolidates and responds across the wider environment. Findings and fixes flow between them, so your team runs the whole loop from one platform.
# The security loop
Source: https://docs.cantina.security/platform/the-loop
The core model behind Cantina: how a security issue moves from first signal to verified closure across find, prioritize, remediate, and prove.
The loop is the core model behind Cantina. It describes how a security issue moves from first signal to verified closure, and it is the same whether the work starts in code, in the cloud, or in your identity provider.
## 1. Find
Signals come in from Apex (code and pull requests), Clarion integrations (SIEM, EDR, cloud, identity, and more), and the human network (audits, competitions, bounty). Cantina turns raw signal into a validated, contextualized finding.
## 2. Prioritize
Not every finding deserves the same attention. Cantina weighs each against your environment: is the affected service exposed, who owns it, does it carry regulatory weight, is it reachable in practice. The output is a short list your team can trust.
## 3. Remediate
Cantina works the fix to completion. It can generate the change, open a context-rich pull request or ticket, and route it to the right owner. Consequential actions can be gated behind human approval; the team controls the level of autonomy.
## 4. Prove
Closure is verified, not assumed. Cantina confirms the issue is actually resolved (the check passes, the exploit path closes), records the evidence, and keeps proof on the record.
## Why the loop matters
Time to exploit is going down. Time to remediate has been going up. Breaches happen in that gap. The loop is how Cantina closes it, and how a lean team gets the security capacity of a team many times its size.
# Trust, auditability, and human control
Source: https://docs.cantina.security/platform/trust
How Cantina keeps autonomous security work under the team's control and on the record with human approval, verified closure, and full audit trails.
Security teams will not grant write access to something they cannot govern or audit. Cantina is built so that even autonomous work stays under the team's control and on the record.
## Human in the driver's seat
Cantina is capable of running security work end to end. Whether it does is the team's choice. Read (investigation) actions are separated from state-changing actions, and consequential actions can be gated behind human approval. You set the level of autonomy, from approve-everything to auto-remediating well-defined classes of issue.
## Verified closure
A fix is not complete until it is proven. Cantina confirms the issue is actually resolved and records the evidence, so engineering trusts the result and auditors can stand behind it.
## On the record
Every action is logged and attributable. The audit trail is a first-class output, not an afterthought, which is what makes it safe to turn autonomy up over time.
This is how a lean team can trust the platform with real work: fewer, defensible findings, remediation done correctly, and proof the loop is closed.
# Referral Program
Source: https://docs.cantina.security/referrals
Earn rewards for growing the Cantina ecosystem
> Earn rewards for growing the Cantina ecosystem
**Earn for growing the Cantina ecosystem.**
Cantina's referral program rewards individuals who help bring new projects into our orbit. Whether you're introducing a project for a private engagement or a public bug bounty, we offer some of the best incentives in the industry.
***
## Client Referrals
Individuals that refer a client for any type of engagement outside of a bug bounty will receive **10% of Net Revenue** of the deal size.
## Bug Bounty Referrals
With Bug Bounty Referrals, individuals who provide referrals are compensated when the first payout is made as part of the bounty program on Cantina. For the first valid bug bounty finding, **10% of Cantina's Net Revenue** will be given to the individual who referred the client hosting the bounty.
## How to Submit a Referral
To qualify, make a warm introduction between your referral and one of the Cantina team members below:
* **Telegram:** @mleffer
* **Email:** [sales@spearbit.com](mailto:sales@spearbit.com)
* **Discord:** `@mikespearbit`
### Example Referral Message
> "Hi team, I wanted to introduce John Smith, the founder of SpaceSwap, an innovative DeFi primitive focused on non-custodial lending. They're interested in running a competition with Cantina, so I thought I'd warm up the introduction."
## Submission Conditions
To ensure your referral qualifies, it must meet the following criteria:
* You created the communication channel directly.
* The referral is a decision-maker at the project.
* An intro call is scheduled with Cantina.
# Competitions
Source: https://docs.cantina.security/researchers/competitions
Quick links for Cantina security competition participation, teams, and payments.
This page is a shortcut to competition docs. For full rules, judging, scoring, and FAQs, use the [Competition Guidelines](/researchers/participation/competitions).
## Quick links
* [**Competition participation**](/researchers/participation/competitions) — joining, teams, finding statuses, judging, escalation, and FAQs
* [**KYC and Payments**](/researchers/joining/kyc) — verify identity and wallet before payouts
* [**Payout schedule & payment statuses**](/researchers/joining/payout-schedule) — weekly cycle, blockers, and what each payment status means
* [**Submission guidelines**](/researchers/participation/submission-guidelines) — PoC requirements and report quality
# Joining Cantina
Source: https://docs.cantina.security/researchers/joining
Get started as a security researcher on Cantina
Welcome to Cantina! This page walks you through the essential steps for getting started as a researcher on our platform - creating your account and finding your first opportunities. For payments, see the dedicated pages linked below.
***
## Researcher Account Setup
Follow the steps below to create a new account.
1. Navigate to [https://www.cantina.security/](https://www.cantina.security/) and introduce your email and new password of choice.
2. Verify your email and select "I am a security researcher".
3. Choose the public username of your choice.
Your username will be displayed to all users (e.g., [cantina.xyz/u/noah](https://cantina.xyz/u/noah)). Profile visibility can be changed in profile settings.
Now you are all set to use the Cantina application!
***
## Finding Opportunities
To begin participating in the Cantina ecosystem and earn rewards for your security research, explore the active listings on the [Opportunities page](https://cantina.xyz/opportunities). This is the central hub for all ongoing security challenges, including both competitions and bug bounties.
### Navigating Opportunities
The page is organized into tabs:
* **Competitions**: Time-bound events where researchers compete to uncover vulnerabilities for a specific protocol. These often include structured scopes, bonus rewards, and leaderboard rankings.
* **Bounties**: Always-on programs that reward eligible findings submitted according to the protocol's vulnerability disclosure policy.
Each opportunity includes key information such as payout amounts, status, and start dates, making it easy to find challenges that match your skills and timeline.
### Staying Engaged
New opportunities are added regularly, so check back often to maximize your participation. Whether you're looking for competitive environments or open-ended bounty hunting, the Opportunities tab makes it easy to stay informed and get involved.
***
## Getting Paid
* [**KYC and Payments**](/researchers/joining/kyc) - Set up your payment information to receive rewards
* [**Payout Schedule & Process**](/researchers/joining/payout-schedule) - When and how you'll receive earnings
# KYC and Payments
Source: https://docs.cantina.security/researchers/joining/kyc
Set up your payment information to receive rewards
## Know Your Customer
To receive payments you must first undergo the Know Your Customer process. This process is conducted using [withpersona.com](https://withpersona.com/). Cantina does not store any personal user information.
After the identity verification process is complete, set up your payment address and verify it via the confirmation email before payouts can be processed.
## Add Payment Address
Follow the steps below to edit your payment settings and add your preferred **Ethereum mainnet address** to **receive USDC**.
> **Warning:** **Only Ethereum mainnet addresses are supported.** No other chain is currently supported.
>
> **Important:** Saving a wallet address is not enough. You must verify it from the email prompt (**Review change** → **Approve change**) or payouts will be blocked.
>
> **Important:** If you change your wallet address, you must verify the new address again before future payouts can be processed.
## Update or Change Your Wallet Address
To change your payout wallet address:
1. Go to **Payments**.
2. Click the **Settings** gear icon.
3. Update your wallet address.
4. Complete wallet verification for the new address by opening the email from `noreply@cantina.xyz`, then clicking **Review change** and **Approve change**.
Your payout can be delayed if your wallet address is missing or not verified.
If you are operating as a legal entity, it is possible to issue an invoice to Cantina for your own records. For when and how you'll receive payments (schedule, delays, troubleshooting), see [Payout Schedule & Process](/researchers/joining/payout-schedule).
> **Note:** All payments will be sent out through our [multisig](https://cantina.xyz/solutions/multisig-security).
>
> **cantina.eth**: `0x3dcb7cfbb431a11cabb6f7f2296e2354f488efc2`
# Payout Schedule & Process
Source: https://docs.cantina.security/researchers/joining/payout-schedule
Understand when and how you'll receive your earnings from competitions, security reviews, and bug bounty programs.
## Prerequisites
Before any payment can be processed, you must:
1. **Complete KYC** via [withpersona.com](https://withpersona.com/) — incomplete KYC is the most common reason for delayed or blocked payouts.
2. **Add a payment address** — an Ethereum mainnet wallet address to receive USDC, then verify it from the confirmation email. No other chain is supported.
If either of these is missing, your payment will be held until resolved. See [KYC and Payments](/researchers/joining/kyc) for setup instructions.
***
## Payout Schedule
Cantina processes payouts on a **weekly cycle**:
| Day | Action |
| - | - |
| **Tuesday** | Payment queue closes — all approved earnings queued for this cycle |
| **Wednesday** | Payments sent out via multisig |
**Cutoff rule:** If your earning is approved after the Tuesday cutoff, it rolls over to the **following Wednesday's** payout cycle.
***
## Withdrawing Your Balance
You can withdraw funds from your account balance on the Cantina platform, under your account settings.
Withdrawals follow the same weekly cycle as all payouts: after you click Withdraw, the payment shows **Scheduled** and is sent in the next **Wednesday** batch (Tuesday cutoff).
**Seeing "Scheduled"? That's normal — it is not an instant transfer.** Only mark a payment **Disputed** if something is actually wrong, e.g. you changed the wallet address on your profile or lost access to your wallet. Disputes are reviewed manually and will delay your payout.
If a payment is already **Scheduled**, changing your wallet afterward does not reroute that payment. To reroute, mark it **Disputed** and open a support ticket.
***
## Payment Statuses
Every payout on Cantina (competitions, bug bounties, reviews, balance withdrawals) moves through the same payment statuses on your account:
| Status | Description |
| - | - |
| `planned` | Payment is planned and must be scheduled by the Cantina team. Common blockers include incomplete KYC or a missing or unverified wallet. |
| `scheduled` | Payment is queued for the next weekly transaction batch (Tuesday cutoff, Wednesday send). |
| `submitted` | Payment is submitted and awaiting multisig signatures. |
| `executed` | Payment completed successfully on-chain. |
| `disputed` | Payment was disrupted during the planned or scheduled phase (for example, a wallet change that needs manual review). |
| `cancelled` | Payment was cancelled and will not be sent. |
***
## What Can Delay Your Payout
| Blocker | Details |
| - | - |
| Incomplete KYC | Must be fully verified before any payment is scheduled |
| Missing payment address | No wallet address on file = no payout |
| Sponsor hasn't paid Cantina | Cantina can only release funds after the client/sponsor has paid |
| Late approval | Findings approved after Tuesday queue closes roll to next week |
***
## Payment by Program Type
### Competitions
Payouts are planned and scheduled by the Cantina team after the competition ends and findings are judged. Your payout depends on your final score and prize pool allocation.
### Security Reviews (Cantina Code)
Payments are coordinated as part of the engagement terms set at the start of the review.
### Bug Bounties
Payouts are processed after a finding is marked **Confirmed** by the triage team and the sponsor. For program-specific timing and notes, see [Bug Bounty Payout](/researchers/participation/bug-bounty-payouts).
**Duplicate findings are not eligible for payment** in bug bounty programs.
***
## How Payments Are Sent
All payments are distributed in **USDC on Ethereum mainnet** through Cantina's multisig:
**cantina.eth** — `0x3dcb7cfbb431a11cabb6f7f2296e2354f488efc2`
You can verify any outgoing payment on-chain using this address.
***
## Invoicing (Legal Entities)
If you are operating as a registered legal entity (company, LLC, etc.), you may issue an invoice to Cantina for your own accounting records. Contact [support@cantina.xyz](mailto:support@cantina.xyz) for the relevant billing details.
***
## Still Waiting on a Payment?
If you believe your payout is overdue, check the following before reaching out:
Confirm your KYC status is fully verified on your Cantina profile.
Make sure an Ethereum mainnet address is saved under your payment settings.
Your finding or contribution must be marked as approved or confirmed.
At least one Tuesday–Wednesday cycle must have passed since your approval.
If all the above are confirmed, reach out to [support@cantina.xyz](mailto:support@cantina.xyz) with your Cantina username and the relevant competition or program name.
# Participation Guides
Source: https://docs.cantina.security/researchers/participation
Essential guidelines for participating in Cantina engagements
Welcome to the Participation Guides section. This page provides high-level overviews of the essential guidelines and processes involved in participating within the Cantina ecosystem as a researcher.
* [**Submission Guidelines**](/researchers/participation/submission-guidelines) - Learn the essential steps for submitting findings, including PoC requirements and best practices for writing high-quality, actionable reports.
* [**Finding Submission Examples**](/researchers/participation/examples) - See real examples of good and bad findings with Proof of Concept (PoC) code.
* [**Bug Bounty**](/researchers/participation/bounties) - Overview of bug bounty resources: finding statuses, payouts, deposits, and mediation.
* [**Bug Bounty Guidelines**](/researchers/participation/bug-bounty) - Rules, eligibility, mediation, and FAQs for bug bounty programs.
* [**Competition Guidelines**](/researchers/participation/competitions) - Rules and expectations for Cantina security competitions.
* [**Security Review Process**](/researchers/participation/security-review-process) - Explore the detailed steps involved in conducting security audits on Cantina.
# Bug Bounty
Source: https://docs.cantina.security/researchers/participation/bounties
Overview of Cantina bug bounty programs - getting started, statuses, payouts, deposits, and mediation
Use this section to find everything you need to participate in Cantina bug bounty programs: from getting started and understanding finding statuses to payouts, deposits, and mediation.
* [**Getting Started**](/researchers/participation/bug-bounty) - Guidelines for participating in bug bounty programs, including severity classification, scope, and eligibility.
* [**Finding Statuses**](/researchers/participation/bug-bounty-statuses) - How findings are categorized - New, In Review, Confirmed, Duplicate, Rejected, Spam, Withdrawn, and Disputed - and what each means for your submission.
* [**Bounty Severity Classification**](/standards/severity/bug-bounty) - Standardized framework for evaluating vulnerability impact and likelihood across bounty programs.
* [**Deposits for Bounty Submissions**](/researchers/participation/deposits) - When deposits are required, how to add balance, and how refunds and slashing work.
* [**Bug Bounty Payout**](/researchers/participation/bug-bounty-payouts) - Prerequisites for receiving payouts, payout schedule, and what to expect after your finding is confirmed.
* [**Mediation Process**](/researchers/participation/bug-bounty#mediation-process-for-bounties) - How to escalate a dispute and work with Cantina when you disagree with a client's decision.
# Bug Bounty Participation
Source: https://docs.cantina.security/researchers/participation/bug-bounty
Guidelines for participating in Cantina bug bounty programs
At Cantina, we prioritize the security and integrity of our ecosystem. Our Bug Bounty program aims to foster collaboration between researchers and clients to identify and resolve vulnerabilities before they can be exploited. See [Bounty Severity Classification](/standards/severity/bug-bounty) for how vulnerabilities are categorized and rewards are determined.
***
## Getting Started
To participate in bug bounty programs you must:
* Create a [Security Researcher Account](/researchers/joining#researcher-account-setup)
* Complete [KYC and Payments](/researchers/joining/kyc) before expecting a payout
* Browse active programs on [Opportunities](https://cantina.xyz/opportunities) or from the program page in Cantina
***
## Bounty Flow: From Submission to Payout
1. **Submit finding** — researcher submits through Cantina Code.
2. **Triage** — finding moves through statuses such as New and In Review (see [Finding Statuses](/researchers/participation/bug-bounty-statuses)).
3. **Client review** — client and triage confirm, reject, or mark duplicate.
4. **Confirmed** — only **Confirmed** findings are eligible for payout.
5. **Payment** — queued on the weekly cycle; see [Bug Bounty Payout](/researchers/participation/bug-bounty-payouts) and [Payout Schedule](/researchers/joining/payout-schedule).
***
## Testing Guidelines
To ensure responsible testing:
* Use **local forks** instead of public chains.
* Avoid actions that may disrupt **network integrity**.
* Do not access or modify data that does not belong to you.
* Provide detailed reports with **proof of concept** and **steps to reproduce**.
***
## Eligibility
To qualify for a bounty, submissions must meet the following criteria:
* Report a **previously unknown, non-public vulnerability** within the program's scope.
* Be the **first to disclose** the vulnerability.
* Provide **sufficient information** to reproduce and resolve the issue.
* **Avoid exploiting** the vulnerability or disclosing it publicly.
* **Comply with all program rules and guidelines**.
***
## Prohibited Actions
The following actions are prohibited:
* Testing on **public mainnet/testnet** deployments.
* **Public disclosure** of vulnerabilities without prior consent.
* **Exploitation** of vulnerabilities for personal gain.
* Engaging in illegal activities or coercive tactics.
***
## Discuss findings on Cantina
All discussion about a submitted finding must happen on Cantina. Contacting the program client or its employees about it through any other channel may result in the finding being rejected with no reward and a ban from the Cantina platform.
***
## Mediation Process for Bounties
To initiate mediation, you must set the finding's status to **Disputed** in Cantina Code. That status triggers the process so Cantina can step in and help resolve the disagreement.
> **Note:** Only findings in **Disputed** status are eligible for mediation. If you disagree with a Rejected or Duplicate decision, set the finding to Disputed to request mediation.
At Cantina, we foster a collaborative environment where researchers and clients can work together to resolve disputes in a fair and transparent manner.
### 1. Submission of Finding
* **Researcher**: Submits a finding.
* **Client**: Reviews the finding and provides feedback.
### 2. Disagreement
Disagreements may arise over:
* Severity assessment.
* Finding validity.
### 3. Escalation to Cantina
If a resolution cannot be reached, either party can escalate the finding to **Cantina** for mediation.
### 4. Triage and Solution Proposal
Cantina's triaging team will:
* Review the finding.
* Propose a fair solution based on the guidelines.
### 5. Final Decision
The **client** has the final say on the resolution.
***
## Client Rejection Policy
If a client rejects more than five findings in one year that we believe are valid, Cantina reserves the right to:
* Conduct a thorough review of the client's participation.
* Take necessary actions to ensure platform integrity.
***
## Communication Guidelines During Mediation
* **Direct Communication**: Cease direct communication between parties during mediation.
* **Reporting**: Communicate all concerns to Cantina.
* **Status Updates**: Researchers can request updates through the relevant bug report thread.
***
## FAQs
### When will I get paid after my finding is confirmed?
Bounty payouts follow the weekly **Tuesday cutoff / Wednesday batch**. See [Bug Bounty Payout](/researchers/participation/bug-bounty-payouts) and [Payout Schedule & Process](/researchers/joining/payout-schedule).
### Are duplicate findings paid in bug bounties?
No. **Duplicate findings are not eligible for payment** in bug bounty programs.
### Do I need a deposit for every bounty?
No. Only programs that show a deposit requirement on the bounty page. See [Deposits for Bounty Submissions](/researchers/participation/deposits).
***
By adhering to these guidelines and classifications, we ensure a fair and transparent process that benefits both researchers and clients, and fosters the growth of a secure and resilient ecosystem.
# Bug Bounty Payout
Source: https://docs.cantina.security/researchers/participation/bug-bounty-payouts
Prerequisites and schedule for receiving bug bounty payouts on Cantina
This page covers what you need in place to receive bounty payouts and when payouts are processed. For the full payout schedule, prerequisites, and troubleshooting across all program types, see [Payout Schedule & Process](/researchers/joining/payout-schedule).
## Prerequisites for Payouts
Before you can receive bounty payouts on Cantina, you must:
* **Complete KYC** - Your identity and payment details must be verified. See [KYC](/researchers/joining/kyc) for how to complete this.
* **Team payment preference** - Ensure your team payment settings are configured so that payouts can be sent to you (e.g., individual or team distribution as applicable).
Confirm both are set up in your account so that confirmed findings can be paid out without delay.
## Payout Schedule
Bounty payouts run on a weekly cycle:
* **Tuesday** - Findings that are confirmed and eligible for payout are queued for the week.
* **Wednesday** - Payouts are processed and sent to researchers based on that queue.
Timing can vary slightly depending on volume and payment provider. If you have questions about a specific payout, use the relevant report thread or contact [Cantina Support](https://support.cantina.xyz/).
For what each payment status means on your account (`planned`, `scheduled`, `executed`, and others), see [Payment Statuses](/researchers/joining/payout-schedule#payment-statuses).
## Notes
* Only **Confirmed** findings are eligible for payout. See [Bug Bounty Finding Statuses](/researchers/participation/bug-bounty-statuses) for how statuses affect your submission.
* If you disagree with a decision, you can set the finding to **Disputed** to request [mediation](/researchers/participation/bug-bounty#mediation-process-for-bounties). Payout for that finding may be delayed until the dispute is resolved.
# Bug Bounty Finding Statuses
Source: https://docs.cantina.security/researchers/participation/bug-bounty-statuses
Understanding finding statuses for bug bounty programs - from submission to resolution
Findings in bug bounty programs are assigned a status that reflects their current state in the review process. Below are the statuses used for Cantina bug bounty programs.
| Finding Status | Explanation |
| - | - |
| **New** | Once a finding is submitted by the security researcher, it is labelled as New by default. |
| **In Review** | The finding has been triaged and is now waiting on the client input. The outcome will appear on the finding when that review is complete. |
| **Rejected** | Upon review, if the finding does not meet the criteria or is deemed invalid, the triager or client will mark it as Rejected. |
| **Duplicate** | Marked when another researcher already reported the same underlying issue (same root cause and the same realistic attack path to the same impact). Duplicates are not rewarded in bug bounty programs. Every **Duplicate** decision includes a short comment describing the reason for the classification, so you can review the basis for the decision. |
| **Confirmed** | When the finding is valid, it is labelled as Confirmed. |
| **Spam** | Used for submissions that are irrelevant, low-quality, automated, AI-generated, or otherwise non-actionable, not for valid findings that are simply incorrect (those are usually **Rejected**). Spam can carry reputation and deposit consequences. |
| **Withdrawn** | The researcher has chosen to withdraw the finding. |
| **Disputed** | The researcher has set this status to challenge the initial decision and request mediation. |
> **Info:** **Duplicate or Rejected and you disagree?** You can set the finding's status to **Disputed** in Cantina Code to trigger mediation. Only findings in Disputed status are eligible for Cantina's mediation process. See the [Mediation Process for Bounties](/researchers/participation/bug-bounty#mediation-process-for-bounties) for how escalation works.
# Competition Participation
Source: https://docs.cantina.security/researchers/participation/competitions
Rules and guidelines for participating in Cantina competitions
In Cantina, security researchers can join competitions to showcase their skills and earn rewards. Here's everything you need to know to participate effectively:
## Joining as an Individual Researcher
To participate in competitions you must first:
* Create a [Security Researcher Account](/researchers/joining#researcher-account-setup)
* [Join a competition](https://cantina.xyz/competitions)
* [Join the discord server](https://discord.gg/Qe2var8zU6)
***
## Joining as a Team
At Cantina, researchers can form teams to participate in competitions. To register as a team, follow the steps below:
1. **Team Creation:**
* Head to the **team-submissions** chat in our Discord channel.
* Send your team submission request using the following format:
* **Team Name:**
* **Competition Name:**
* **Team Lead (Cantina Username):**
* **Other Team Members (Cantina Usernames):**
Once the Cantina core team processes your application, your team will appear at the top-right section of the competition repository.
1. **Team Payments**:
* Payments are disbursed to team leaders, who are responsible for distributing them fairly.
* Cantina is not liable for internal disputes between teammates.
2. **Important**:
* Team applications are valid only for the competition specified. If you want to participate in a different competition, submit a new application.
* **No findings** can be made before the team is created. Once a finding is submitted, the team cannot be updated.
***
## Discuss findings on Cantina
All discussion about a submitted finding must happen on Cantina. Contacting the program client or its employees about it through any other channel may result in the finding being rejected with no reward and a ban from the Cantina platform.
***
## Finding Statuses & Labels
During the competition, your findings will be labeled and tracked. Below are the different **finding statuses** and **labels**:
### Finding Statuses
* **New**: Assigned to newly submitted findings.
* **Rejected**: If a finding doesn't meet competition criteria, it will be rejected.
* **Duplicate**: Marked when another researcher already reported the same underlying issue (same root cause and the same realistic attack path to the same impact). Duplicates considered in competitions.
* **Confirmed**: Valid findings are marked as confirmed and are rewarded.
* **Spam**: Used for submissions that are irrelevant, low-quality, automated, AI-generated, or otherwise non-actionable, not for valid findings that are simply incorrect (those are usually **Rejected**). Spam can carry reputation and deposit consequences.
* **Withdrawn**: If you withdraw a finding, it will be marked as withdrawn.
For the full status list, see [Finding Labels and Status](/standards/severity/finding-categorization).
### Finding Labels
* **Escalated**: Applied when a researcher disagrees with a judge's decision and escalates the issue.
***
## Payment Process
### KYC & Payment Setup
To receive payments, you must complete **KYC (Know Your Customer)** and set a payment address, then verify that wallet via the email confirmation (**Review change** → **Approve change**). A saved but unverified wallet can block payouts. For detailed instructions, check out our [KYC and Payments Page](/researchers/joining/kyc).
For what each payment status means (`planned`, `scheduled`, `executed`, and others), see [Payment Statuses](/researchers/joining/payout-schedule#payment-statuses) on the Payout Schedule page.
***
## Scoring & Prize Distribution
The competition prize pool is distributed based on the severity of the findings.
* **High Severity**: 10 points
* **Medium Severity**: 3 points
* **Low Severity/Informational/Gas-Optimization**: These will be assessed on a separate pool, as announced in the competition's specific details.
### Duplicate Findings
When multiple researchers submit the same finding in a competition, points for each participant are scaled down based on the formula:
`Points = 0.9^(n-1)`
where *n* is the number of duplicate findings. For example, if there are 3 duplicates for a high-severity bug (10 points), each participant receives 2.7 points.
The competition rewards **unique findings** - the more original your submission, the greater your payout potential!
***
## Judging Process
Judges evaluate submissions based on a set of established rules, ensuring each finding is assessed fairly. They also handle **duplication** of findings, ensuring the competition remains competitive and equitable.
### Judge Responsibilities
* Verifying finding validity.
* Handling duplication of issues.
* Collaborating with sponsors for further evaluation.
* Overseeing the escalation process.
***
## Escalation Process
After the judging phase, if a researcher disagrees with the severity of their finding, they may request an escalation. During this phase:
* **Only the researcher who submitted the finding can escalate** it.
* **Invalid escalations** are penalized with a \$100 fine from future competition earnings.
* Cantina has the final say on escalations.
**Private Comments on Findings**
Researchers can add **private comments** on any finding. These comments are only visible to the judges and can help them make an informed decision during the review process. Please keep comments objective and focused on the findings.
***
## Competition Flow: From Submission to Payout
1. **Submit Finding**: Researchers submit their findings for evaluation.
2. **Judging**: Judges assess the findings for validity, severity, and relevance.
3. **Escalation** (if applicable): Researchers can escalate findings if they disagree with the judgment.
4. **Payment**: Once confirmed, researchers complete the KYC process and are scheduled for payment.
***
## FAQs
### Does it matter who submits the finding first?
No, every finding is scored the same regardless of when it was submitted during the competition. We encourage early, high-quality submissions to allow your teammates to leave feedback and plan fixes.
### Can I withdraw my finding?
Yes, you can withdraw findings through the finding's context menu.
### How are low-severity or informational findings judged?
Some competitions reserve a pool for these findings. This is explicitly mentioned in the competition details. High-quality findings (regardless of severity) may also earn rewards from this pool.
# Deposits for Bounty Submissions
Source: https://docs.cantina.security/researchers/participation/deposits
Learn about deposit requirements for bounty submissions on Cantina
## Overview
When submitting to a bounty that has this feature implemented, researchers must maintain a minimum wallet balance in their Cantina account.
> **Note:** Not all bounties require deposits. Check the bounty home page for deposit requirements (e.g., "Deposit required: \$10").
**TODO:** Deposit amount and mechanics may vary by program. Cantina will confirm and document any standard amounts or flows; in the meantime, use the bounty home page and account balance UI as the source of truth.
## Why Deposits May Be Required
Bounty programs may require deposits to:
* **Deter low-effort or AI-generated submissions**
* **Reduce spam and abuse from repeat offenders**
* **Encourage thoughtful, high-quality findings**
* **Discourage exaggerated severity classifications**
## Maintaining Your Balance
Ensure you have sufficient balance before submitting to bounties with deposit requirements. Your balance can be viewed and managed in your account settings.
## How to Add Balance
1. Navigate to [cantina.xyz/settings/account-balance](https://cantina.xyz/settings/account-balance)
2. When prompted to submit a deposit, set the deposit amount directly in the UI.
3. After confirming the amount, you will be redirected to Stripe Checkout.
4. Complete the payment on Stripe using your preferred supported wallet option.
5. Once payment is successful, you are redirected back to Cantina and your deposit is recorded automatically.
> **Warning:** Stripe is now the default and preferred method for deposits. Deposits completed via Stripe are automatically added to the wallet balance in your Cantina account
> **Warning:** **Deposits made outside the flow shown in the UI are not automatically credited** - this includes sending on the wrong network (e.g. Base instead of Ethereum mainnet), sending the wrong token, transferring directly from an exchange wallet, or sending to any address not shown during checkout. Recovering these funds requires manual intervention from the Cantina team and takes time. Always complete the deposit exactly as the UI instructs.
If a Stripe payment fails or stays pending, contact [Cantina Support](https://support.cantina.xyz/) before retrying.
## Slashing & Refunds
Deposits will only be slashed in specific cases. Regular rejected findings will **not** lose their deposit. For how submission outcomes map to finding statuses (e.g., Confirmed, Spam), see [Bug Bounty Finding Statuses](/researchers/participation/bug-bounty-statuses).
| Submission Outcome | Deposit Status |
| - | - |
| Valid submission | Deposit refunded |
| Legitimate invalid submission | Deposit refunded |
| Spam/low-effort/AI submission | Deposit slashed |
| Over-inflated severity claim | Deposit slashed |
| Repeat abusive behavior | Deposit slashed & possible account action |
## Example
If a bounty requires a \$100 deposit:
* You submit a finding and it's confirmed valid → Your \$100 is refunded
* You submit a finding and it's rejected as out of scope → Your \$100 is refunded
* You submit a low-effort or AI-generated finding → Your \$100 is slashed
## Legacy Deposit Addresses (Deprecated)
The previous deposit flow using static deposit addresses is deprecated.
New deposit addresses are no longer issued and previously issued deposit addresses no longer work.
### UI Behavior During Transition
If the Cantina UI still displays a deposit address, that flow will continue to work only while it is shown.
If you see a Stripe redirect instead of a deposit address, you must use Stripe to submit your deposit.
### What to Do Going Forward
Always follow the deposit method shown in the UI.
If Stripe is presented, do not attempt to send funds to old deposit addresses - those payments will not be recognized.
***
For support, contact [Cantina Support](https://support.cantina.xyz/).
# Finding Submission Examples
Source: https://docs.cantina.security/researchers/participation/examples
Real examples of good and bad security findings including Proof of Concept (PoC) code for smart contract audits.
Good writing skills are important to communicate complex ideas, ensuring that the reader fully understands the vulnerability's significance and urgency. Below we provide two examples to follow as a guideline when submitting findings.
## Good
A good finding report clearly explains:
1. What is the issue
2. How / Why it is happening
3. Where exactly the vulnerable code is located and which logic it connects to
4. How to reproduce it with a Proof of Concept (PoC)
5. How it can be remediated
In the image below you will find a finding submission by [cantina.xyz/u/cmichel](https://cantina.xyz/u/cmichel). Let's dissect why this is a good finding and why you should follow this standard.
![Detailed security finding with code and explanation.]()
![Smart contract code line highlight.]()
1. Clearly describes what the issue is.
> The `supply` and `withdraw` functions can increase the supply share price (`totalSupplyAssets / totalSupplyShares`). If a depositor uses the `shares` parameter in `supply` to specify how many assets they want to supply they can be tricked into supplying more assets than they wanted. It's easy to inflate the supply share price by 100x through a combination of a single supply of 100 assets and then withdrawing all shares without receiving any assets in return.
1. Clearly describes why it is happening.
> The reason is that in `withdraw` we compute the `assets` to be received as `assets = shares.toAssetsUp(market[id].totalSupplyAssets, market[id].totalSupplyShares);`. Note that `assets` can be zero and the `withdraw` essentially becomes a pure `burn` function.
1. Clearly points to the vulnerable line using the code-highlighting feature.
2. Provides a Proof Of Concept for anyone to reproduce and verify the vulnerability.
```solidity theme={null}
function testSupplyInflationAttack() public {
vm.startPrank(SUPPLIER);
loanToken.setBalance(SUPPLIER, 1 * 1e18);
// 100x the price. in the end we end up with 0 supply and totalAssets = assets supplied here
morpho.supply(marketParams, 99, 0, SUPPLIER, "");
uint256 withdrawals = 0;
for (;; withdrawals++) {
(uint256 totalSupplyAssets, uint256 totalSupplyShares,,) = morpho.expectedMarketBalances(marketParams);
uint256 shares = (totalSupplyShares + 1e6).mulDivUp(1, totalSupplyAssets + 1) - 1;
// burn all of our shares, then break
if (shares > totalSupplyShares) {
shares = totalSupplyShares;
}
if (shares == 0) {
break;
}
morpho.withdraw(marketParams, 0, shares, SUPPLIER, SUPPLIER);
}
(uint256 totalSupplyAssets, uint256 totalSupplyShares,,) = morpho.expectedMarketBalances(marketParams);
console2.log("withdrawals", withdrawals);
console2.log("totalSupplyAssets", totalSupplyAssets);
console2.log("final share price %sx", (totalSupplyAssets + 1) * 1e6 / (totalSupplyShares + 1e6));
// without inflation this should mint at initial share price of 1e6, i.e., 1 asset
(uint256 returnAssets,) = morpho.supply(marketParams, 0, 1 * 1e6, SUPPLIER, "");
console2.log("pulled in assets ", returnAssets);
}
```
1. Provides a remediation for the client.
> Suppliers should use the `assets` parameter instead of `shares` whenever possible. In the other cases where `shares` must be used, they need to make sure to only approve the max amount they want to spend. Alternatively, consider adding a slippage parameter `maxAssets` that is the max amount of assets that can be supplied and transferred from the user. This attack of inflating the supply share price is especially possible when there are only few shares minted, i.e., at market creation or when an attacker / contracts holds the majority of shares that can be redeemed.
### Competitions Finding Format
For Competitions, please use the Detailed template when submitting a finding.
![Vulnerability report template structure.]()
## Bad
The finding below is an example of a bad finding submission:
![Security issue report with severity indicators.]()
* The description is generic and nonsensical - it shows lack of understanding of the protocol and does not clearly state the exact problem or why it is happening
* It does not point to the lines of code affected
* It does not provide a Proof of Concept (PoC)
# Security Review Process
Source: https://docs.cantina.security/researchers/participation/security-review-process
Guide for researchers conducting security reviews on Cantina
A streamlined guide to help you navigate Cantina's security review process as a researcher - from accessing repos to communicating findings effectively.
## Accessing a Cantina Repo
Contact the Cantina core team to get access to the repository for your engagement.
## Commenting, Tagging & Communication
### Can clients see my comments and findings?
Yes - they have access. However, your comments might be hard to locate unless you ping `@project`. This ensures they receive a notification.
Always ping @project when commenting on findings or threads.
Replying to a comment notifies everyone involved in that thread.
### Can I ping fellow SRs?
Not at this time. Ping functionality is currently limited to the `@project` tag.
### Can I chat natively in the repo?
While real-time chat isn't supported, you can:
* Leave comments directly on the code or findings.
* Discuss via finding threads.
## Downloading the Repo
Yes, you can download the Cantina repository by:
* Toggling the sidebar and selecting download.
* You should also have access to the original scoped repo
***
## Review Lifecycle: What to Expect
Here's how Cantina's team structures a security review, from kickoff to final delivery:
### 1. Kickoff
We align with the client on goals, expectations, and deliverables. This includes scope confirmation and scheduling initial meetings.
### 2. Scoping & Information Gathering
You'll receive documentation and codebases to understand the system deeply. Expect technical specs, diagrams, and architectural overviews.
### 3. Security Review Period
This is your time to shine: Manual analysis, tool-assisted testing, and a deep dive into the codebase to identify vulnerabilities or logic flaws.
### 4. Communication Channels
Cantina facilitates structured touchpoints and async updates. Use repo comments, finding threads, or Discord (if set up).
### 5. Fix Period (Optional)
Clients may patch vulnerabilities. During this time, provide clarity and support where needed.
### 6. Close-Out Call
We walk through the findings and their resolutions. This helps solidify the client's understanding and closes the review loop.
### 7. Final Report
You'll contribute to a detailed report outlining vulnerabilities, severity, and remediation efforts - an important artifact for client security posture.
# Submission Guidelines
Source: https://docs.cantina.security/researchers/participation/submission-guidelines
Best practices for submitting high-quality findings, including PoC requirements, validity criteria, and competition submission rules.
When submitting a finding through Cantina in a competition, it's important to follow the outlined process and meet the requirements to ensure your submission is considered valid. This guide provides detailed information on the process, severity criteria, and mandatory submission rules to help you submit findings effectively.
## Finding Submission Process
You can initiate a finding submission in two ways:
1. By highlighting code during a code review
2. By clicking the "New Finding" button in the top right corner of the Findings section
To submit a finding, you must fill out the following required fields (optional fields are also available):
* **Severity**: The criticality of the issue, helping to determine its urgency. It is based on factors like Likelihood and Impact, ranging from Critical (severe consequences) to Low (minimal impact).
* **Likelihood** (optional): The probability of exploitation.
* **Impact** (optional): Potential consequences if exploited.
* **Title**: A concise description that clearly conveys the essence of the vulnerability.
* **Description**: A detailed explanation of the problem, including cause, effects, and any proof of concept (PoC) or supporting material (e.g., diagrams).
* **Select Template**: Choose a structured template to format your report.
You can add code to an existing finding if it doesn't already include a highlighted area.
***
## Finding Severity Criteria
The severity of a finding is determined by its impact and likelihood.
* **Impact** relates to the potential damage or consequences caused by the issue (e.g., loss of user funds, disruption of services).
* **Likelihood** indicates how likely the vulnerability is to be exploited (e.g., can it be triggered by any user, or does it require special conditions?).
### Severity Matrix
| Likelihood/Impact | High Impact | Medium Impact | Low Impact |
| - | - | - | - |
| High | High | Medium | Medium |
| Medium | High | Medium | Low |
| Low | Medium | Low | Informational |
### Impact Criteria
* **High**: Loss of user funds, breaks core functionality.
* **Medium**: Temporary disruptions, minor fund exposure, non-core functionality failures.
* **Low**: Issues without risk to assets or core functions.
### Likelihood Criteria
* **High**: Easily triggered by any user, likely exploitation.
* **Medium**: Issues requiring constraints or planning (e.g., capital or other users' actions).
* **Low**: Requires rare conditions or admin action.
***
## Exceptions to Severity Matrix
Some issues are capped in severity (unless explicitly stated otherwise):
### Low Severity
* Minimal loss due to rounding errors.
* Issues with "weird" ERC20 tokens.
* Errors in view functions not used in the protocol.
### Informational Severity
* Admin errors (wrong parameters in a function call).
* Malicious admin actions (unless explicitly covered in the scope).
* User errors that don't affect other users.
* Protocol design-related issues.
### Invalid Submissions
* Speculative Issues related to future code or integrations.
* Known Issues that have already been reported.
***
## Key Considerations
* **Protocol Behavior**: Always refer to the competition README for protocol behavior.
* **Mandatory PoC Rule**: All high and medium severity submissions must be accompanied by a Proof of Concept (PoC) unless the researcher's reputation score is above 80. Exceptions will be noted on the competition page.
* **Cantina Dedicated Researchers** are exempt from this rule and can submit PoCs upon request.
* **Escalation Process**: If there's a disagreement over severity or findings, there's a formal escalation process. Invalid escalations will incur penalties, so ensure your case is strong before submission.
***
## Proof of Concept (PoC) Requirements
### PoC Validity Criteria
PoC validity: Your Proof of Concept must compile and demonstrate the impact of the issue. Additional precautions that help reviewers:
* Mention which test file it's part of
* Ensure it's valid for the audit branch
* Note any additional requirements for the PoC to run
* Provide the PoC output
* Explain the PoC output vs. expected output
### When PoC Is Not Required
Exceptions when PoC is not required:
* Missing function(s)
Any other exceptions will be noted on the specific competition page.
***
## Duplication Rules
To consider a submission a potential duplicate:
* **Root Cause Identified**: The finding must identify the root cause of the issue.
* **Medium or Higher Severity**: The impact should be significant.
* **Valid Attack Path**: A clear, realistic path must link the root cause to the impact. This can be shown through a PoC or a detailed description of the code.
Invalid duplicates may result from:
* Failure to identify the root cause clearly.
* Insufficient impact analysis or unclear attack paths.
**Incomplete or Invalid Attack Path**: If the attack path from root cause to impact is poorly described or invalid, the finding may be downgraded or invalidated. This includes:
* **Incorrect POC**: The POC cannot be executed, does not demonstrate the stated impact, or relies on unrealistic assumptions or conditions.
* **Insufficient Description** (for issues without a coded POC): The description of how the root cause leads to the stated impact is incomplete, incorrect, or unclear.
***
## Additional Submission Quality Guidelines
* Ensure clarity and context in your findings so they can be properly evaluated.
* Judging time is limited, so ensure that your findings are clear, actionable, and well-supported for efficient review.
**Final Judgment**: While these guidelines serve as a reference, the final judgment on validity and severity rests with Cantina's appointed judges, who will evaluate each finding based on the full context.
***
## Cantina Assistant
Cantina Assistant is here to assist you in crafting more effective findings. With Cantina Assistant, you'll be able to analyze your submission to ensure it follows the template, includes a valid proof of concept, and meets all criteria for a positive judgment. This increases your chances of clear communication and successful outcomes.
For real-world examples of good and bad findings with PoC code, see [Finding Submission Examples](/researchers/participation/examples).
# Researcher Resources
Source: https://docs.cantina.security/researchers/resources
Resources for growing your career on Cantina
**Everything you need to grow, get recognized, and level up.**
This page covers the systems that power your journey through Cantina and Spearbit - designed to make expectations clear, reward great work, and unlock the next level of opportunity.
***
## Spearbit Promotion Process
This section outlines the advancement path through Spearbit's tiered researcher system. Understanding these tiers helps researchers plan their career growth and understand what's expected at each level.
### Researcher Tiers
#### Security Researcher (SR)
The entry point into the Spearbit network. SRs demonstrate solid security fundamentals and the ability to find meaningful vulnerabilities.
**What we look for:**
* Consistent track record of finding valid vulnerabilities
* Strong technical writing in findings
* Ability to work independently on codebases
#### Associate Security Researcher (ASR)
A stepping stone between SR and LSR. ASRs have demonstrated above-average performance and are building toward lead researcher capabilities.
**What we look for:**
* Sustained high performance in audits and competitions
* Broader technical scope and deeper protocol understanding
* Early signs of leadership and mentorship
#### Lead Security Researcher (LSR)
The highest tier in the network. LSRs are trusted to lead complex engagements and represent Spearbit's quality standard.
**What we look for:**
* Exceptional track record across multiple engagement types
* Ability to scope, lead, and deliver complex audits
* Mentorship of junior researchers
* Technical excellence and strong communication skills
### Advancement Criteria
Promotion decisions are based on:
1. **Performance data** – Findings quality, quantity, and consistency across engagements
2. **Technical breadth** – Ability to audit diverse protocol types and architectures
3. **Collaboration** – Working effectively with clients and other researchers
4. **Reliability** – Meeting deadlines and maintaining professionalism
### Benefits by Tier
Higher tiers unlock:
* Access to more prestigious and complex engagements
* Higher compensation rates
* Leadership opportunities on audits
* Influence on Spearbit's direction and methodology
* Recognition within the broader security community
### How to Progress
To maximize your chances of advancement:
* Deliver high-quality, well-written findings
* Take on a variety of protocol types and complexity levels
* Be responsive and professional in all communications
* Seek feedback and continuously improve your methodology
* Help mentor newer researchers when opportunities arise
For specific questions about your tier status or advancement path, reach out to the Spearbit team directly.
***
## Reputation System
At Cantina, our mission is to reward researchers who consistently demonstrate technical rigor and valuable impact. The Reputation Score system is central to that mission. It's a dynamic metric that reflects your reliability, quality of submissions, and track record over time - helping top performers stand out and projects assess findings faster. You can view your reputation score directly on your Cantina profile.
### Why Reputation Scores Matter
Researchers with a reputation score ≥ 80 are exempt from submitting POCs for medium and high severity findings in public competitions. This trust-based system significantly reduces friction for top contributors, while preserving the signal that POCs provide.
### How the Reputation Score Works
All researchers start at a baseline of 50 points. Your score moves up or down based on the severity and accuracy of your submissions, as well as the quality of your writeups. The score is capped between 0 and 100.
#### Positive Contributions
| Type | Base Points |
| - | - |
| Confirmed Critical/High | +5 |
| Confirmed Medium | +3 |
| Confirmed Low/Info/Gas | +1 |
| Accepted Escalations | TBD |
#### Negative Outcomes
| Type | Base Points |
| - | - |
| Spam Findings | –5 |
| Rejected Findings | –3 |
| Rejected Escalations | TBD |
#### Quality Multiplier
Each submission is evaluated and tagged with a quality score, which modifies the base points:
| Quality Level | Multiplier |
| - | - |
| Low (Level 1) | –10% |
| Medium (Level 2) | No change |
| High (Level 3) | +20% |
Spam findings are not eligible for quality multipliers - they always incur the full –5 penalty.
### Examples
**Example 1** - A high severity bug is confirmed with Level 3 quality.
* Base: +5
* Quality Bonus: +1 (20% of 5)
* Total: +6
* Final Score: 50 → 56
**Example 2** - A medium severity bug is rejected with Level 1 quality.
* Base: –3
* Quality Bonus: +0.3 (–10% of –3)
* Total: –2.7
* Final Score: 50 → 47.3
**Example 3** - You submit a spam finding.
* Base: –5
* Quality not applied
* Final Score: 50 → 45
### Earning Trust, One Submission at a Time
Reputation isn't just about climbing a leaderboard - it's a signal to Cantina, Spearbit, and our clients that you're a trusted operator. Your score affects access to private opportunities and administrative overhead (like the POC requirement).
# Cantina Tools
Source: https://docs.cantina.security/researchers/tools
Tools available to security researchers on Cantina
Cantina Code is designed to streamline your workflow and enhance your productivity as a security researcher. Whether you're submitting findings, collaborating with clients, or using the powerful communication features within the platform, Cantina Code is built with your needs in mind.
* [**Communication Features**](/researchers/tools/features) - Effective communication is a cornerstone of successful security research. Cantina Code offers integrated tools that allow you to stay connected with clients, team members, and other researchers.
* [**Cantina Code Usage**](/researchers/tools/cantina-code) - Cantina Code serves as the central hub for all your security research activities.
# Cantina Code Usage
Source: https://docs.cantina.security/researchers/tools/cantina-code
How to use Cantina Code for security research
Cantina Code provides security researchers with a robust platform to conduct their work, from submitting findings to interacting with code and other users. This page covers the key features and functionalities that will help you navigate and make the most of Cantina Code.
## 1. Download Content & Toggle Sidebar
Cantina Code allows you to download the content of a repository and manage the interface through the sidebar.
* **Download Content:** You can download the entire repository content by clicking the download button, which will provide you with a compressed `.zip` file containing the source code (excluding `.git` version control data).
* **Toggle Sidebar:** Easily toggle the sidebar to access repository details, file navigation, and additional tools.
***
## 2. Highlighting Code
The ability to highlight portions of code allows for efficient interaction during security reviews. Once highlighted, you have several options:
* **Copy Line:** Copies the contents of the highlighted area.
* **Copy Permalink:** Copies the URL pointing to the exact highlighted area.
* **Comment Line:** Opens a comment thread under the highlighted code for further discussion.
* **Link to Existing Finding:** Links the highlighted area to an already open finding.
* **Reference in New Finding:** Starts a new finding submission process by referencing the highlighted code.
***
## 3. Findings Submission Process
Submitting a finding is easy and can be done in two ways:
1. By highlighting code during a Code Review or,
2. By clicking the "New Finding" button in the Findings section.
**Required Fields:**
* **Severity:** How critical the vulnerability is (ranging from Critical to Low).
* **Likelihood:** The probability of the vulnerability being exploited (optional).
* **Impact:** The potential consequences of the exploit (optional).
* **Title:** A brief description of the vulnerability.
* **Description:** A detailed explanation of the issue, including proof of concept, tests, or diagrams.
**Optional:** You can also select a standard template to guide the writing process.
For high and medium severity findings, a **Proof of Concept (PoC)** is required. See [Submission Guidelines](/researchers/participation/submission-guidelines) for validity criteria and [Finding Submission Examples](/researchers/participation/examples) for real PoC examples.
Once submitted, findings will appear in the Findings section for further processing.
***
## 4. Findings Labels & Statuses
**Labels:** Labels are tags you can assign to your findings for better organization. The availability of custom labels depends on the repository and security review type.
**Statuses:** Each finding has a status that reflects its current state. Common statuses include:
* **New:** Default status when a finding is first submitted.
* **Confirmed:** When the finding is validated.
* **Acknowledged:** When the finding is confirmed by the sponsor or judge.
* **Fixed:** After the sponsor applies a fix to the vulnerability.
* **Withdrawn:** When a researcher withdraws their finding.
***
## 5. Add Code to Existing Finding
You can link new code areas to an existing finding. This allows you to further clarify or expand on your discovery without creating a new finding from scratch.
***
## 6. Better Findings with Cantina Assistant
Cantina's AI-powered **Cantina Assistant** helps you craft more effective findings by:
* Analyzing your findings for clarity.
* Ensuring your submission follows the correct format.
* Verifying that it includes the necessary proof of concept.
Using the Assistant significantly increases your chances of submitting higher-quality findings, which can result in more successful outcomes.
***
## 7. New Shortcuts
Cantina Code supports several keyboard shortcuts to enhance navigation:
* **CMD+P** (Ctrl+P on Windows/Linux): Opens the "jump to file" capability.
* **CMD+B** (Ctrl+B on Windows/Linux): Quickly hides the file explorer in the Code Review tab.
***
## 8. Diagrams & Formulas
Cantina Code allows you to include **Mermaid.js diagrams** and **MathJax formulas** within your comments and findings, making it easier to visualize and communicate complex ideas.
### Mermaid Diagrams
You can create sequence diagrams, flowcharts, and more using Mermaid.js syntax. For example:
```mermaid theme={null}
sequenceDiagram
participant Bank
participant Attacker
Attacker->>+Bank: Request withdrawal
Bank->>+Attacker: Transfer funds
Attacker->>+Bank: Request withdrawal (reentry)
Bank->>+Attacker: Transfer funds (reentry)
Bank-->>-Attacker: Insufficient balance
```
This will render as a visual diagram that illustrates a reentrancy attack on a smart contract.
### MathJax Formulas
Cantina also supports MathJax, allowing you to include mathematical formulas in your findings. For example:
$$
H_{f} = \frac {\sum Collateral_{i}\;in\;ETH \times Liquidation\;Threshold}{Total\;Collateral\;in\;ETH}
$$
This will render the formula in a readable format, helping you explain complex mathematical models clearly.
***
## 9. Finding Workflow Optimization
Cantina Code streamlines the process of managing and submitting findings with various tools and features:
* Linking existing code to a finding.
* Using custom labels to categorize findings in private reviews.
* Hidden comments for sensitive communications during escalations.
These features help you keep track of your work and ensure that findings are handled efficiently and professionally.
# Communication Features
Source: https://docs.cantina.security/researchers/tools/features
Communication tools for security researchers on Cantina Code
Effective communication is essential to successful security research, and Cantina Code offers a suite of features to help you collaborate with clients, teammates, and other researchers. Whether you're participating in a competition, bug bounty, or a regular security review, our communication tools ensure that your messages, feedback, and updates reach the right people at the right time.
## 1. Comments & Pings
### Comments
Cantina Code enables you to leave comments on specific lines of code during a security review. This feature helps you collaborate seamlessly, sharing your observations and thoughts with your team or clients.
**How to Use Comments:**
* When in Code Review mode, hover over a line of code to reveal a blue box at the right side of the line number.
* Clicking on this box will give you the option to either submit a comment or initiate a Findings Submission.
* Comments can be set to visible for everyone in the repository, your teammates, or only you, depending on the repository settings.
Visibility rules are determined by the repository administrator, so be sure to check with them if you're unsure about the settings.
**Enhanced Commenting:**
To make the most of your comments, you can:
* **Ping users** by tagging them, ensuring they receive a notification and can quickly navigate to your comment.
* **Copy the permalink** for the comment and share it with others.
* Comments also support **LaTeX formulas** and **Mermaid.js diagrams**, allowing you to include technical formulas and diagrams directly in your comments.
### Pings
Pings allow you to notify other users about important comments or updates.
**How to Ping:**
* To notify clients, use the **@project** tag to send an email notification and a dashboard alert.
* The user receiving the ping will be notified promptly, making it easier to ensure that the right people are paying attention to your findings and observations.
Like comments, pings are influenced by the type of security review and repository settings, so be mindful of these when using them.
***
## 2. Custom Labels in Private Reviews
Cantina Code gives you more control over your findings with the ability to create **custom labels** for your work in private reviews.
**Custom Labels:**
* You can now organize your findings according to your preferred classification system, giving you the flexibility to categorize and track them as you see fit.
* This feature streamlines the review process, making it easier to manage and prioritize your research.
***
## 3. Hidden Comments for Judging and Escalations
Cantina Code now supports **hidden comments** that can be made visible exclusively to judges and sponsors during escalations and evaluations.
**Benefits of Hidden Comments:**
* This feature helps you provide additional context, reasoning, and rationale for escalated findings without exposing your arguments to unnecessary public debate.
* It ensures smoother judging and escalation processes by keeping discussions focused and private, allowing for quicker decisions and reducing the chances of unproductive debates.
# Clarion Terms of Service
Source: https://docs.cantina.security/resources/clarion-terms
Terms governing use of Clarion.
Last updated: July 6, 2026
For Clarion's security posture, subprocessors, and compliance reports, see the [Cantina Trust Center](https://www.cantina.security/trust).
These Clarion Terms of Service ("Terms") govern access to and use of Clarion, a security alert monitoring, enrichment, triage, investigation, and response product operated by Spearbit Labs Inc. ("Cantina," "we," "us," or "our").
If you access or use Clarion on behalf of an organization, you represent that you have authority to bind that organization to these Terms. In that case, "you" refers to both you and that organization.
These Terms are Clarion-specific supplemental terms. They incorporate the [Cantina General Terms of Use](https://cantina.xyz/terms/general) by reference. By accessing Clarion, using Clarion, or checking an acceptance box for Clarion terms, you agree to these Terms and to the Cantina General Terms of Use.
## Relationship to Other Agreements
These Terms apply to Clarion unless you or your organization has entered into a separate written agreement with Cantina that expressly governs Clarion. If these Terms conflict with a written agreement, the written agreement controls for that conflict.
The Cantina General Terms of Use continue to apply to Clarion, including provisions and obligations relating to account security, authority to bind an organization, permitted use, third-party content, fees, Cantina rights, suspension or termination, user termination, license and intellectual property, use of marks, disclaimers, prohibited jurisdictions, limitation of liability, indemnification and release, changes to terms, severability, assignment, notices, and electronic acceptance. Some Cantina General Terms of Use provisions are specific to Cantina marketplace, security review, researcher, payment, KYC, tax, blockchain, or similar workflows and apply to Clarion only where relevant.
If these Terms conflict with the Cantina General Terms of Use for Clarion, these Terms control only for Clarion and only to the extent of the conflict. The Google Workspace API and Customer Data restrictions in these Terms and in the [Clarion Privacy & Legal Disclosures](/resources/legal) control over any broader data analytics, deliverable-use, or AI/ML training language in the Cantina General Terms of Use.
Clarion-specific privacy disclosures are available in the [Clarion Privacy & Legal Disclosures](/resources/legal). The full Clarion privacy policy is available at [clarion.cantina.xyz/about/privacy](https://clarion.cantina.xyz/about/privacy). Cantina's broader privacy policy is available at [cantina.security/privacy-policy](https://www.cantina.security/privacy-policy).
## Clarion Service
Clarion helps authorized users monitor, enrich, triage, investigate, and respond to security and operational alerts. Clarion may connect to third-party services, including Google Workspace, cloud providers, SIEMs, notification tools, ticketing tools, source control providers, and other systems you configure.
You are responsible for ensuring that you have the rights, permissions, and consents needed to connect third-party services to Clarion and to submit data to Clarion.
## Accounts and Workspaces
You are responsible for maintaining the confidentiality of your account credentials and for activity that occurs through your account or workspace. You must promptly notify Cantina of unauthorized access, credential compromise, or other security concerns.
Workspace administrators are responsible for managing authorized users, integrations, permissions, notification destinations, and workspace configuration.
Cantina may monitor, log, audit, and analyze use of Clarion to provide, secure, maintain, support, troubleshoot, and improve Clarion, subject to these Terms, the Clarion Privacy & Legal Disclosures, the Cantina General Terms of Use, and any applicable written agreement.
## Acceptable Use
You may not use Clarion to:
* violate applicable law or third-party rights;
* gain unauthorized access to systems, accounts, data, or networks;
* interfere with, disrupt, overload, or degrade Clarion or third-party services;
* submit malware, exploit code, or harmful content except as part of an authorized security workflow;
* reverse engineer, copy, or create derivative works of Clarion except where applicable law prohibits this restriction;
* bypass usage limits, security controls, or access controls;
* use Clarion for spam, phishing, fraud, harassment, or unlawful surveillance.
## Customer Data
"Customer Data" means data, content, configuration, credentials, alerts, logs, findings, messages, files, and other information submitted to or accessed by Clarion through your account, workspace, integrations, or authorized use of the service.
Cantina may process Customer Data to provide, secure, maintain, support, troubleshoot, analyze service performance, and improve Clarion; to comply with applicable law; and as agreed with the customer. Nothing in these Terms or in the Cantina General Terms of Use permits Cantina to use Google Workspace API data in a way that conflicts with the Google API Services User Data Policy or Clarion's Google API Limited Use Disclosure.
Clarion does not use Google Workspace API data to develop, improve, or train generalized AI or ML models. Where Clarion uses AI services, Google Workspace API data is used only to provide user-facing Clarion functionality requested by the user or workspace administrator.
## Third-Party Services and AI Providers
Clarion may interoperate with third-party services that you connect or authorize. Your use of those services remains subject to their own terms, policies, and permissions.
Clarion may use third-party service providers, including AI service providers, to provide Clarion functionality requested by users or workspace administrators. Cantina remains responsible for using those providers consistently with these Terms, the Clarion Privacy & Legal Disclosures, and applicable customer agreements.
## Trials, Fees, and Suspension
Some Clarion functionality may be provided through a trial, pilot, paid subscription, order form, statement of work, or other written agreement. Fees, payment terms, usage limits, and subscription terms are governed by the applicable agreement or ordering document.
If a trial workspace is not converted to a paid subscription within 60 days, Cantina may suspend or delete the workspace and associated data.
Cantina may suspend or restrict access to Clarion if we reasonably believe use of the service creates a security risk, violates these Terms, violates the Cantina General Terms of Use, violates applicable law, or could harm Clarion, Cantina, users, customers, or third parties.
You may terminate your use of Clarion by discontinuing use of the service or by contacting Cantina to request account deletion, subject to Cantina's need to retain information as required by law, to resolve disputes, to enforce rights, to maintain security, or as agreed with the customer.
## Security Workflows
Clarion can automate or assist with security workflows, investigations, and response actions. You are responsible for reviewing and configuring Clarion appropriately for your environment, permissions, risk tolerance, and internal policies.
Clarion is not a substitute for independent security judgment and does not guarantee that every alert, threat, vulnerability, misconfiguration, or incident will be detected, prevented, or resolved.
## Intellectual Property
Cantina owns Clarion and all related software, documentation, interfaces, designs, and technology, excluding Customer Data and third-party materials. Subject to these Terms and any applicable agreement, Cantina grants you a limited, non-exclusive, non-transferable right to access and use Clarion for your internal security operations.
You retain ownership of Customer Data. You grant Cantina the rights needed to process Customer Data to provide and support Clarion and as otherwise described in these Terms, the Clarion Privacy & Legal Disclosures, and any applicable customer agreement.
## Prohibited Jurisdictions and Compliance
You may not access or use Clarion from a jurisdiction where such access or use is prohibited by applicable law, sanctions, export controls, or the Cantina General Terms of Use. You may not misrepresent your location, identity, organization, authority, or eligibility to use Clarion.
## Disclaimers
Clarion is provided "as is" and "as available" except as expressly stated in a written agreement. To the maximum extent permitted by law, Cantina disclaims all warranties, including implied warranties of merchantability, fitness for a particular purpose, title, and non-infringement.
## Limitation of Liability
To the maximum extent permitted by law, Cantina will not be liable for indirect, incidental, special, consequential, exemplary, or punitive damages, or for lost profits, lost revenue, lost savings, lost business opportunity, loss of data, or service interruption arising from or related to Clarion.
If no separate written agreement sets a different liability limit, Cantina's total liability arising from or related to Clarion will not exceed the fees paid to Cantina for Clarion by you or your organization in the three months before the event giving rise to the claim.
## Indemnification
You agree to defend, indemnify, and hold harmless Cantina, its affiliates, service providers, and their respective officers, directors, employees, contractors, agents, successors, and assigns from claims, liabilities, damages, losses, costs, and expenses arising out of or relating to your violation of these Terms, your violation of the Cantina General Terms of Use, your use of Clarion, your Customer Data, your integrations, or access to Clarion through your account or workspace.
## Changes to These Terms
Cantina may update these Terms from time to time. Updates are effective when posted unless a later effective date is stated. If changes materially affect your rights or obligations, Cantina may provide additional notice through Clarion, email, or other reasonable means.
Your continued use of Clarion after updated Terms become effective means you accept the updated Terms.
## General Legal Terms
If any part of these Terms is held invalid or unenforceable, the remaining provisions remain in effect. Cantina may assign or delegate these Terms as permitted by the Cantina General Terms of Use. You may not assign or delegate your rights or obligations under these Terms without Cantina's prior written consent.
You consent to receive notices and communications electronically. By checking an acceptance box, clicking a similar acceptance control, accessing Clarion, or continuing to use Clarion, you agree that your action constitutes valid electronic acceptance of these Terms and any incorporated terms.
## Contact
Questions about these Terms can be sent to [support@cantina.security](mailto:support@cantina.security).
# FAQ
Source: https://docs.cantina.security/resources/faq
Frequently asked questions about Cantina security audits, competitions, bounties, and researcher programs.
> Frequently asked questions about Cantina security audits, competitions, bounties, and researcher programs.
## FAQ For Organizations
*Coming soon - questions from organizations about security services.*
***
## FAQ for Researchers
### Support FAQ
#### How do I open a Cantina support ticket?
Go to [support.cantina.xyz](https://support.cantina.xyz/) and submit the form with as much detail as you can. See [Support](/resources/support) for what to include in your message.
#### Do I need an account on the support portal?
No. [support.cantina.xyz](https://support.cantina.xyz/) does not offer researcher or client logins. Anyone can submit a ticket from the form; there is no portal account to create or sign into.
#### How do I follow up on an open ticket?
Reply to the confirmation email or any message from Cantina Support in your inbox. That reply updates the same ticket. You do not need to log into the portal to continue the conversation.
### Competitions FAQ
#### Where can I see my results card?
On the [competition page](https://cantina.xyz/competitions) you have participated on. If you don't see it yet, it will display soon as the feature is retroactively applied.
#### My issue is marked as a duplicate of another issue, but I disagree since my issue is misunderstood and not a duplicate, how do I fix this?
If your finding was marked as duplicate and you disagree, you can escalate it during the escalation phase.
#### Does it matter who submitted the finding first?
No, every finding is scored the same regardless of when it was submitted during the contest duration. We highly encourage you to spend time writing great findings. We also encourage submitting it as soon as you have a great write-up. This way, the team can often leave feedback on the finding and plan for fixes. We particularly want to discourage people who submit findings at the last moment.
#### Can I withdraw findings that I submitted?
Yes, you can withdraw findings by going to the finding context menu and clicking 'withdraw finding'.
#### How are low-severity / informational / gas-optimization scored and judged?
Some competitions may have a pool reserved for low-severity, informational and gas-optimization. This would be explicitly mentioned in the competition specific page, and these prizes are awarded for the top findings. Note: only quality of the findings are considered, not quantity. Excellent writeups for high and medium severity findings can also get awards from this separate pot.
***
### Security Audits FAQ
#### How to access cantina repo?
A core team member must set it up first, then share the link with you. Direct access to cantina repo from SR dashboard not yet supported. A workaround is to:
* Access it through notifications.
* Saving the link corresponding to the cantina repo audit.
* If it's related to Competitions:
* Click on your user profile on the top right side of the interface.
* Access it through the Security Researcher Dashboard
#### I am doing a security audit and not a competition. Can the client see my comments and findings?
Yes, but it may be hard to locate comments. When leaving comments, always ping `@project` so they receive a notification. Note that when a comment is a reply to another comment, all the users that left a comment in the thread will get a notification.
#### Can I ping fellow SRs?
No. It is not possible to ping the username of the security researchers in your team yet.
#### Can I communicate natively on a cantina repo?
Chat like functionality is not yet available. You can nevertheless:
* Communicate via comments.
* Communicate on the finding thread.
* Ask the core team to set up private discord communication channels.
#### Can I mark finding as FIXED or ACKNOWLEDGED?
Not yet. To finalize the status of a finding it will have to be done with a comment on that finding.
#### Can I download a cantina repository?
Yes. You can download repository content via the sidebar. You should nevertheless have access to the original repo with the code in scope (if you do not, reach out to core team).
## Clarion FAQ
> A collection of answers to frequently asked questions.
### Guides
* [**Getting started**](/clarion/getting-started) - Set up your workspace, connect your first integration, and activate your first agent.
### Looking for something else?
* [**Concepts**](/clarion/learn) - Understand how alerts, incidents, agents, skills, and tools fit together.
* [**Integrations**](/clarion/integrations/1password) - Setup instructions for every tool Clarion connects to.
# Clarion Privacy & Legal Disclosures
Source: https://docs.cantina.security/resources/legal
Clarion-specific privacy and legal disclosures.
> Clarion-specific privacy and legal disclosures.
## Clarion Privacy Disclosures
Clarion is operated by Spearbit Labs Inc. ("Cantina"). These disclosures describe Clarion-specific handling of Google Workspace API data and should be read together with the [Clarion Privacy Policy](https://clarion.cantina.xyz/about/privacy) and [Cantina's Privacy Policy](https://cantina.xyz/privacy-policy).
Clarion may access Google Workspace data only when a workspace administrator or authorized user connects a Google integration. Clarion uses that data to provide user-facing Clarion functionality, including alert enrichment, detection, triage, reporting, and related security workflows.
Clarion may process Google Workspace data with third-party service providers, including AI service providers, only to provide Clarion functionality requested by the user or workspace administrator.
Clarion retains Google Workspace data only as needed to provide the service, support security workflows, comply with legal obligations, or as agreed with the customer. Trial workspace data may be suspended or deleted if the trial is not converted to a paid subscription within 60 days.
Clarion protects Google Workspace data using administrative, technical, and physical safeguards appropriate to the sensitivity of the data.
## Google API Limited Use Disclosure
Clarion's use and transfer of raw or derived user data received from Google Workspace APIs adheres to the [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy), including the Limited Use requirements.
Clarion does not use, transfer, or sell Google Workspace API data to develop, improve, or train generalized AI or ML models. Where Clarion uses AI services, Google Workspace API data is used only to provide user-facing Clarion functionality requested by the user or workspace administrator.
Clarion does not use Google Workspace API data for advertising or to serve ads.
Clarion does not allow humans to read Google Workspace API data except with the user's explicit consent, where necessary for security purposes, where required to comply with applicable law, or where the data has been aggregated and anonymized for internal operations.
# Links
Source: https://docs.cantina.security/resources/links
Official Cantina and Spearbit resources
Stay connected with Cantina and Spearbit across all platforms for the latest updates and resources. Below are direct links to our official sites and social channels.
## Official Websites
* [**Cantina Website**](https://cantina.security/) – Learn more about our platform and services.
* [**Spearbit Website**](https://spearbit.com/) – Explore the leading network of security researchers.
## Social Media
Follow us on social media to stay updated on industry news, insights, and events.
* [**Twitter - Cantina**](https://twitter.com/cantinaxyz)
* [**Twitter - Spearbit**](https://twitter.com/spearbit)
* [**LinkedIn - Cantina**](https://www.linkedin.com/company/cantinasecurity/)
* [**LinkedIn - Spearbit**](https://www.linkedin.com/company/spearbit-labs/)
* [**Discord - Cantina**](https://discord.com/invite/SdXxD9yEkB)
* [**YouTube - Cantina**](https://www.youtube.com/@cantina-xyz) – Check out our educational videos and tutorials.
## Additional Resources
* **Blog - Cantina** – Stay informed with our latest thought leadership, case studies, and updates.
* **Blog - Spearbit** – Explore security research insights, researcher spotlights, and more.
# Public Reports
Source: https://docs.cantina.security/resources/public-reports
Browse published security reports from Cantina and Spearbit audits and competitions.
> Browse published security reports from Cantina and Spearbit audits and competitions.
Browse published security reports from Cantina and Spearbit engagements.
Visit [cantina.xyz/portfolio](https://cantina.xyz/portfolio) to view our full portfolio of public security reports.
# Support
Source: https://docs.cantina.security/resources/support
How to get help with Cantina and Clarion.
Need help with Cantina? This page covers how to reach us for the **Cantina** platform and for [Clarion](/clarion), our security operations product.
***
## Cantina Support
Use this for competitions, bug bounties, security reviews, payouts, KYC, deposits, organization settings, and other **Cantina** platform issues.
**Open a ticket:** [support.cantina.xyz](https://support.cantina.xyz/)
All Cantina support requests should go through the ticket portal.
### How tickets work
* Submit the form with as much detail as you can.
* You'll receive an automated email confirming we received your request.
* **There is no researcher or client login on the support portal.** Tickets are tracked by email, not by a portal account.
* Continue the conversation by **replying to that email thread**. Our replies go to your inbox; your replies update the same ticket.
* When we close the ticket, you'll receive an automated email that the request is resolved.
For common questions, see [Support FAQ](/resources/faq#support-faq) under FAQ for Researchers.
### Required information
* Your **Cantina username** or **organization name**
* If your issue is finding-related, include the **link to the finding**
***
## Clarion Support
Use this for Clarion workspace, agents, integrations, alerts, and other issues on [clarion.cantina.xyz](https://clarion.cantina.xyz).
**Email us:** [clarion@cantina.security](mailto:clarion@cantina.security)
### Required information
* Your **workspace name**
* If the issue is alert- or finding-related, include the **relevant link**
# Cantina Code for Companies
Source: https://docs.cantina.security/security-teams/cantina-code
See findings submitted in real time and collaborate with security researchers through Cantina Code.
Cantina Code makes it easy and convenient for companies to see findings submitted in real time and enable efficient communication by receiving comments and pings from Security Researchers.
> **Note:** Learn more about the Cantina Code interface and Security Researcher workflow by reading the Cantina Code for Security Researchers section.
Reviews are conducted on Cantina Code repositories set up by the core team. The details behind the set up are discussed during engagement confirmation.
* [**Managing Findings**](/security-teams/cantina-code/managing-findings) - Track, assign, and collaborate on findings; respond to researchers and @project pings until resolution.
* [**Working with Reports**](/security-teams/cantina-code/working-with-reports) - Report generation, team review, and accessing final reports.
# Managing Findings
Source: https://docs.cantina.security/security-teams/cantina-code/managing-findings
Efficiently manage and prioritize security findings
Efficiently managing security findings is crucial to ensuring that vulnerabilities are addressed promptly and thoroughly. Cantina Code provides several tools to help you track, assign, and collaborate on findings. Here's how you can make the most of these features.
## Responding to Findings
In the Findings section, you'll see a list of all submitted vulnerabilities. It's important to engage with researchers in the comment threads until a resolution is reached. This ensures that vulnerabilities are fully understood and addressed.
### How to Use:
1. **Access the Findings List**: Navigate to the Findings section on your dashboard to view the list of all vulnerabilities.
2. **Engage in the Conversation**: Click on a finding to open the conversation thread and provide feedback or ask follow-up questions to the researcher.
3. **Mark as Resolved**: Once the vulnerability is addressed, mark the finding as resolved or closed. This ensures that your team keeps track of which issues are still open and which are successfully mitigated.
***
## Integrated Findings
Cantina Code's newly redesigned code review interface makes collaboration smoother. Comments and findings are now seamlessly integrated alongside the source code, creating a more intuitive review process.
### How to Use:
1. **View Comments and Findings**: As you navigate the code, comments and findings will appear alongside the relevant lines of code. This allows for a more natural review process, as you can see both the code and feedback in one place.
2. **Collaborate in Context**: Respond to comments directly in the interface, providing real-time feedback and collaborating with researchers and other team members on specific lines of code.
***
## Assign Findings
The Assign Findings feature enables customers and repository owners to assign findings to internal team members for investigation and resolution. This feature is especially useful for competitions and collaborative reviews, ensuring that all findings are tracked and addressed by the right people.
### How to Use:
1. **Assign a Finding**: Click on a finding and use the Assign button to choose a team member who will handle the investigation or resolution of the issue.
2. **Track Assigned Findings**: Once a finding is assigned, you can monitor its progress through status updates and comments from the assigned team member.
***
## Findings List
The Findings list gives you a more organized and visible overview of each finding's status and labels. This change helps you prioritize vulnerabilities and track their progress more easily.
### How to Use:
1. **Navigate the Findings List**: The updated list displays findings with clear status indicators and labels, making it easier to prioritize and manage each vulnerability.
2. **Filter and Sort Findings**: Use filters and sorting options to organize findings by status, priority, or submission date. This helps you focus on the most critical issues first.
***
## Responding to Pings
When a Security Researcher pings you using the `@project` tag, a notification will be displayed on the company dashboard and also sent via email.
You are encouraged to regularly check for notifications in order to respond promptly to Security Researcher questions, which may lead to the discovery of a vulnerability.
Pings can be either unlimited or limited depending on the type of engagement.
This is a feature linked to the Cantina reputation mechanism to encourage Security Researchers to ask good questions and not waste your time. For example, pings are limited during competitions in order to shield you from low-quality pings.
If you find a question or comment useful, you can give the ping back to the Security Researcher by hovering over `@project`. On the other hand, during a Security Review pings are unlimited because the engagement is constrained to a small number of participants.
# Working with Reports
Source: https://docs.cantina.security/security-teams/cantina-code/working-with-reports
Understand and act on security reports
Once a security review engagement is completed, the Cantina team generates a comprehensive report that outlines all valid findings, their severity rankings, resolutions, and relevant comments. These reports serve as a key deliverable, helping organizations track vulnerabilities and understand the outcomes of the security review.
## Report Generation Process
The process of generating a comprehensive security report is as follows:
### 1. Compilation of Findings
The Cantina team gathers all findings from the engagement, including comments, resolution statuses, severity rankings, and other relevant data. This process includes reviewing the findings submitted by the Security Researchers and ensuring all information is captured accurately.
### 2. Draft Report
After compiling all relevant information, the Cantina team drafts the initial report. This report will include:
* A list of all findings with their respective severity rankings (Low, Medium, High)
* Resolution status for each finding (Resolved, Pending, Not Resolved)
* Comments and context from both Security Researchers and your team
* Any other relevant details that can help the organization understand each finding
The draft report is then shared with your team for review.
### 3. Team Review
Your team can review the draft report and provide feedback. This is an opportunity to clarify any findings, request further context, or adjust severity rankings and resolution statuses. The Cantina team will work with you to incorporate any changes or adjustments as needed.
### 4. Final Report
After incorporating feedback from your team, the Cantina team finalizes the report. The final version is delivered to your team, and it serves as the official document for the security review. The final report is a comprehensive record of the vulnerabilities found and the actions taken to address them.
***
## Accessing Reports
Once the report is finalized, you can access it anytime from the Reports section of your Cantina dashboard. Here, you will find a comprehensive list of past reports associated with completed engagements.
### How to Use:
1. **View Report**: Navigate to the Reports section and select the relevant engagement report.
2. **Download or Share Report**: Once opened, you can download the report or share it with your team or stakeholders.
To see examples of previous reports, check out [Public Reports](/resources/public-reports).
# Building agents on the platform
Source: https://docs.cantina.security/security-teams/community/building-agents
Build your own security agents and skills on top of the platform, within guardrails your team controls.
Cantina is an open substrate: your team can build its own security agents and skills on top of the platform, not just use the ones that ship by default.
## What you can build
* **Agents** that carry out security work in your environment, within guardrails your team controls.
* **Skills**: reusable, versioned playbooks that teach an agent how to handle a class of task to a known standard.
## How it works
Agents run against governed, human-readable playbooks. A skill declares exactly which actions an agent may take, so capability, permission, and audit live in one place. You decide the level of autonomy, and every action is logged.
## Why build your own
Out-of-the-box agents cover common work, but every environment has workflows specific to it. Building your own lets a lean team encode its expertise once and run it repeatedly, instead of doing the same work by hand.
Start from a template, customize its skills and the tools it can use, and put it into production when you are ready.
# Community guidelines
Source: https://docs.cantina.security/security-teams/community/guidelines
Contribution standards that keep shared agents and skills safe, clear, and useful for everyone.
Shared agents and skills are only useful if they are trustworthy. These guidelines keep contributions safe, clear, and useful for everyone.
## Contribution standards
* **Be clear about what it does.** Describe the agent or skill's purpose, the actions it can take, and the environment it expects.
* **Scope permissions tightly.** A skill should request only the actions it needs. Prefer read and investigation actions; gate state-changing ones.
* **Version your changes.** Publish updates as new versions so adopters can review what changed.
* **Keep it honest.** Document limitations and assumptions. Do not overstate what an agent can guarantee.
## Using community contributions
* Review a shared skill's declared actions and permissions before you run it.
* Start in a low-autonomy mode and raise it as you build trust.
* Report issues so the author and the community can improve the library.
# Sharing and reusing
Source: https://docs.cantina.security/security-teams/community/sharing
Publish agents and skills, and draw on what the community has already shared.
Agents and skills are meant to be shared. What one team builds, another can adopt, so the community's collective expertise becomes something every team can draw on.
## Share what you build
Publish an agent or skill so others can use it. Because a skill is versioned and declares its own permissions and actions, it can be adopted safely without re-architecting anything.
## Reuse what others have built
Start from community-contributed agents and skills instead of a blank page. Adapt them to your environment, keep the parts that fit, and contribute improvements back.
## The idea
Security teams tend to solve the same problems in isolation. An open, shared library means a lean team does not have to build everything itself, and capability compounds across the community.
# Getting Started with Cantina
Source: https://docs.cantina.security/security-teams/getting-started
Your guide to setting up and using Cantina as an organization
Welcome to Cantina - the platform built to help organizations connect with the best security researchers. Whether you're preparing for a launch, running a bug bounty, or in need of urgent incident response, this section will walk you through how to get started on the platform.
***
## Account Creation
To begin using Cantina, you'll need to create an **Organization Account**, which unlocks access to the platform's solutions and tools.
### Steps to create an account
1. Navigate to [https://www.cantina.security/](https://www.cantina.security/) to get started
2. Choose your account type from the welcome screen:
* Select "Organization" if you have security needs
* Select "Researcher" if you offer security solutions
3. Add your personal details: enter your full name (e.g., Jordan Patel), create a username (e.g., jordanpatel), and click "Continue" to proceed.
4. Add your company details: enter your Company Name, create a Company Username (this will be your organization's identifier), and click "Complete sign up".
5. Accept Terms of Use: review Cantina's Terms of Use and click "Accept" to agree to the terms and complete registration.
6. Access your dashboard: you'll be redirected to your organization dashboard. The main navigation includes: Dashboard, Repositories, Opportunities, Leaderboard, and Discover Cantina.
After creating your account: complete your profile with additional company information, invite team members via the "Invite team members" option in your dashboard, and explore the platform's resources and security solutions.
***
## Platform Navigation
Cantina is designed to streamline the experience of managing security engagements. Once you're logged in as part of an organization, here's what you'll find:
### Main Navigation
* **Dashboard**: Your organization's home base with welcome message, team management, and quick actions
* **Repositories**: GitHub integration and code repository management for your projects
* **Opportunities**: Browse available security engagements, competitions, and bounty programs with detailed filtering
* **Leaderboard**: View researcher rankings and performance metrics across the platform
* **Discover Cantina**: Explore platform features, resources, and educational content
### User Menu (accessed via profile dropdown)
* **Settings**: Account preferences and configuration
* **Support**: Help resources and contact information
* **Sign out**: Logout from your account
### Dashboard Overview
The main dashboard provides important information at a glance:
* **Organization Profile**: Display of your company name, username, and avatar
* **Team Management**: Quick access to invite team members to your organization
* **Researcher Showcase**: Visual display of top researchers available on the platform
* **Quick Actions**: Direct buttons for starting security engagements
### Opportunities Section
When you navigate to `cantina.xyz/opportunities`, you'll find:
* **Platform Statistics**: Live metrics including payouts available, total paid out, vulnerabilities found, and active researchers
* **Engagement Filters**: Browse by All, Competitions, Bounties, or Ended engagements
* **Search Functionality**: Find specific opportunities using the search bar
* **Live Programs**: Active bug bounties and competitions with payout amounts and start dates
### Notifications System
Access notifications through the inbox icon or directly via `cantina.xyz/notifications`:
* **Inbox**: Centralized message center for all platform communications
* **Filter Options**: Organize notifications by type (Pings & Assignments, New findings, Comments, Status changes, Payments, Badges, Spam)
* **Settings**: Configure notification preferences and delivery methods
### Settings
Navigate to Settings to manage your organization's configuration at `cantina.xyz/organization/settings/company`:
* **Personal profile**: Your individual account settings and preferences
* **Company profile**: Organization information visible to others on Cantina, including company name and username, logo/avatar upload (WebP, PNG, or JPEG up to 2 MB), website and company email, social media links (X/Twitter, GitHub), about section with rich text editing, and a link to view your public profile page
* **Manage users**: Team member access and permissions
* **Account security**: Security settings and authentication options
### Managing Team Members
To manage your organization's team members:
1. Go to Settings from your profile menu
2. Select "Manage users" from the left sidebar, or navigate directly to `cantina.xyz/organization/settings/members`
3. View all users who currently have access to the company
**Adding team members:** In the Manage users section, click the "+" button, enter the email address of the person you want to invite, and send the invitation (users will initially have "Pending" status).
**Managing existing users:** The Manage users page shows the user list (names, current roles, email addresses), role management via the "Role" dropdown (**Manager**: full access to organization settings and user management; **Member**: standard access to engagements and repositories), status tracking for pending invitations, and a "Disable user" button to remove access when needed.
**Setting user roles:** After a user accepts their invitation, locate them in your Manage users list, click their "Role" dropdown, and select either "Manager" or "Member". The role change takes effect immediately.
***
## Session Settings
Session settings apply to all company users and control how long user sessions remain active and how often they need to be refreshed.
**Where to configure:** Organization Settings → Session Settings
**Available settings:**
* **Refresh Time** - How often user sessions need to be refreshed.
* **Max Session Duration** - The maximum length of time a user session can remain active before the user must sign in again.
**To update:** Select a Refresh Time from the dropdown, select a Max Session Duration from the dropdown, then select Update Session Settings to apply the changes.
**Recommendations:**
* Set the refresh time to 8–12 hours for a good user experience.
* Set the max session duration to 1–7 days for security.
* The refresh time should always be less than the max session duration.
**Managing your own sessions:** Each user can view and manage their own active login sessions under User Profile → Settings → Account security. The Login sessions list shows every active session and device, including last activity, expiration date, and status. From here you can terminate a session (immediately sign out that device) or extend a session's expiration date.
***
## Going Further
* [**API Access**](/security-teams/getting-started/api-access) - Programmatic access to Cantina for client organizations
* [**SSO Configuration**](/security-teams/getting-started/sso) - Enforce Google SSO or configure Okta for your organization
* [**Security Solutions**](/security-teams/services) - Explore our full suite of security offerings
# API Access
Source: https://docs.cantina.security/security-teams/getting-started/api-access
Programmatic access to Cantina for client organizations
Cantina exposes a REST API that lets client organizations integrate Cantina data and workflows into their own tools. Use it to list repositories, retrieve findings, generate reports, manage company users, and react to events as they happen.
The endpoints available to clients are documented in the [Client API Reference](/api).
## Authentication
All API requests are authenticated with an API key issued through the API keys settings. The same key is used whether you're driving the API from Zapier or from your own scripts and services.
### Generating an API key
1. Sign in as a Company Manager and navigate to Settings → API keys.
2. Click Generate New API Key.
3. Set an expiration date (required).
4. Store the key in a secret manager - it is shown only once.
You can revoke API access at any time by deleting an API key from the same API keys settings page.
For the full step-by-step including connecting Zaps and mapping repository IDs, see the Cantina + Zapier Integration guide.
### Using the key
Pass the key as a bearer token on every request:
```bash theme={null}
curl https://cantina.xyz/api/v0/companies \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Permissions
API keys inherit the permissions of the Company Manager who generated them. An endpoint that requires `manage_users`, `manage_github`, or other scoped permissions will return `403` if the issuing user does not hold those permissions on the target company.
## Use with Claude or OpenAI
The client API surface is published as an OpenAPI 3.1 specification you can hand directly to an AI assistant.
The fastest way to get an assistant up to speed is to use the Copy Page as Markdown button at the top of this page - it copies the full page (endpoint URL, auth instructions, and a pointer to the OpenAPI spec) into your clipboard so you can paste it straight into Claude or ChatGPT.
If you'd rather have the assistant fetch the docs itself:
* This page: [https://docs.cantina.security/security-teams/getting-started/api-access](/security-teams/getting-started/api-access)
* OpenAPI spec: [https://docs.cantina.xyz/api-reference/openapi-client.yaml](https://docs.cantina.xyz/api-reference/openapi-client.yaml)
Example prompt:
> Fetch [https://docs.cantina.security/security-teams/getting-started/api-access](/security-teams/getting-started/api-access) for auth and endpoint details, then use the linked OpenAPI spec to list the findings in repository ``. Authenticate with `Authorization: Bearer `.
The spec only includes the endpoints documented in the Client API Reference.
## Rate limits and stability
The API surface documented under Client API Reference is the supported public surface for client organizations. Endpoints outside that section may change without notice.
# SSO Configuration
Source: https://docs.cantina.security/security-teams/getting-started/sso
Learn how to configure SSO enforcement for your Cantina organization
Cantina supports enforcing single sign-on for all users in your email domain, with two supported providers: Google SSO and Okta (OIDC). Both are configured from **Organization Settings → Single Sign-On**.
## Google SSO Enforcement
This section explains how to enforce Google OAuth/SSO authentication for users in the `your-company.com` email domain.
### Create SSO Enforcement Rule
1. Navigate to **Organization Settings → Single Sign-On**.
2. Select **Add SSO Enforcement Rule**.
3. In **Email Domain**, enter: `your-company.com`
4. Create rule
### Expected Behavior
Once enabled, all users with an email address ending in `@your-company.com` will be required to sign in using Google SSO.
Users will no longer be able to authenticate with password-based login methods for this domain.
***
## Okta Configuration
Cantina integrates directly with Okta for authentication. The setup process involves configuring an application in Okta's admin console and then connecting it through Cantina's SSO settings.
### Okta Settings
1. Navigate to the Okta Admin Console and select Applications.
2. Click Create App Integration and select OIDC - OpenID Connect, then click Next.
3. Select Web Application as the application type.
4. Configure your application:
* Name your application (e.g., "Cantina")
* Set the Sign-in redirect URI to: `https://cantina-prod.us.auth0.com/login/callback`
### Cantina Settings
1. Go to your organization's SSO settings at [https://cantina.xyz/organization/settings/sso](https://cantina.xyz/organization/settings/sso)
2. Click Add SSO Connection
3. Enter the following information from your Okta application:
| Field | Description |
| - | - |
| Okta Tenant URL | Your Okta domain URL. Remove "-admin" from your admin panel URL if present. |
| Client ID | Found in your Okta application settings (see below). |
| Client Secret | Found in your Okta application settings (see below). |
| Email Domain | The email domain for your organization. Contact Cantina support if you need to modify this. |
All users with this email domain will be automatically redirected to Okta when they log in to Cantina.
### Testing
After configuration, log out of Cantina and attempt to sign in using your email address. You should be automatically redirected to Okta's authentication system.
# Security solutions
Source: https://docs.cantina.security/security-teams/services
Human-delivered security services powered by the Spearbit network, each plugging into the same find, prioritize, remediate, and prove-closure loop.
Beyond the platform's automated products, Cantina offers human-delivered security services powered by the Spearbit network of elite researchers. Each service plugs into the same loop: find the issues that matter, prioritize them, remediate correctly, and prove closure.
## Services
* **Smart contract security audits**: in-depth reviews by Spearbit and Cantina researchers.
* **Application security audits**: infrastructure and application security assessments.
* **Competitions**: collaborative, time-boxed security reviews with expert validation.
* **Bug bounty**: managed programs for ongoing vulnerability discovery.
* **Penetration testing**: on-chain and off-chain infrastructure testing.
* **Managed Detection and Response (MDR)**: 24/7 monitoring and response.
* **Advisory**: strategic, executive-level security guidance.
* **Multisig security**: multi-signature wallet protection and key management.
## How services fit the platform
Findings from a service engagement land in the same place as everything else, so remediation and verified closure happen in one workflow instead of a static report that gets filed away.
See each service page for scope, process, and how to engage.
# Advisory
Source: https://docs.cantina.security/security-teams/services/advisory
Strategic security advisory and executive-level guidance
**Advisory** (formerly known as vCISO) provides on-demand security leadership, offering expert guidance tailored to the unique needs of onchain protocols. This service is designed for projects requiring high-level, strategic security expertise at various stages of development and operations, without the need for a full-time security hire.
## Service Process
The advisory process is consultative and can be adjusted to the specific requirements of your protocol. The engagement typically follows these steps:
### 1. Initial Assessment
* **Objective**: Understand the protocol's architecture, goals, and security posture.
* **Activities**: Audit technical specifications, identify key areas of concern, and establish security priorities.
* **Outcome**: A clear understanding of the current security landscape and a framework for addressing key risks.
### 2. Security Strategy Development
* **Objective**: Provide a security strategy that aligns with the protocol's goals and development roadmap.
* **Activities**: Develop a tailored security roadmap with short- and long-term security objectives.
* **Outcome**: A security strategy document that outlines actionable steps to mitigate risks and improve the protocol's security posture.
### 3. Technical Guidance and Recommendations
* **Objective**: Deliver actionable insights across various security domains.
* **Activities**:
* **Smart Contract Best Practices**: Audit and advise on secure development practices for smart contracts.
* **Architecture Audits**: Evaluate protocol architecture to identify systemic vulnerabilities and improve resilience.
* **Application Security Guidance**: Provide expertise on application security practices that can be integrated into onchain protocols, such as network security and threat modeling.
* **Development Framework Recommendations**: Recommend frameworks and tools that promote security throughout the development lifecycle.
* **Outcome**: Clear and concise recommendations for improving security and mitigating risks in the protocol's design and implementation.
### 4. Ongoing Consultations and Security Audits
* **Objective**: Provide continuous support and periodic audits to ensure security remains robust over time.
* **Activities**:
* Conduct periodic security audits to assess the protocol's evolving threat landscape.
* Address emerging vulnerabilities and adjust security practices as necessary.
* **Outcome**: Regular security updates and adjustments based on new threats, vulnerabilities, or changes in protocol functionality.
### 5. Managed Detection and Response & Post-Incident Analysis
* **Objective**: Offer support in case of security incidents to minimize damage and enhance future resilience.
* **Activities**:
* Provide technical expertise during and after an incident to help mitigate impact and identify root causes.
* Conduct post-incident analysis to improve future incident response protocols and reduce risk exposure.
* **Outcome**: A detailed incident report with lessons learned and recommendations for preventing similar issues in the future.
### 6. Documentation and Compliance
* **Objective**: Ensure the protocol is aligned with security best practices and compliant with relevant standards.
* **Activities**:
* Provide guidance on building and maintaining comprehensive security documentation.
* Assist in achieving compliance with regulatory standards, such as data privacy laws and security standards.
* **Outcome**: Security documentation that clearly articulates the protocol's security posture, decision-making processes, and compliance efforts.
## Contact Us
For more information or to scope a potential engagement, reach out via [cantina.security/contact](https://www.cantina.security/contact)
# Application Security Audits
Source: https://docs.cantina.security/security-teams/services/application-security-audits
Comprehensive application infrastructure and application security assessments
Cantina delivers comprehensive application security audits. This unified offering blends deep application-layer expertise with operational security (OpSec) assessments - identifying risks across everything from API integrations and authentication flows to device security and cloud configurations.
***
## What We Cover
We provide full-spectrum application security audits spanning:
### Application Logic & Code
* Authentication and session management
* Backend APIs and automation scripts
* Business logic flaws and insecure integrations
* Injection vectors (IDOR, SSRF, RCE)
* SaaS misconfigurations and data leakage
### Operational & Endpoint Security
* Employee and contributor account exposure
* Device hardening (MDM, EDR, VPN)
* Communication platforms (email, Discord, Slack)
* RBAC and secrets management
* Provisioning/offboarding workflows
### Infrastructure & Cloud
* Admin panels and multisig dashboards
* CI/CD pipeline security
* Cloud environment misconfigurations and key exposure
***
## Process Overview
Our Application Security audit process ensures thorough coverage across both application and operational layers:
### 1. Scoping and Information Gathering
We begin by aligning on your organization's unique risk profile:
* **Operational Assessment**: Inventory of internal systems, endpoints, devices, and communication platforms
* **Application Assessment**: Technical specifications, source code, architecture overviews
* **Documentation audit**: Existing OpSec policies, infrastructure setups, and security procedures
* **Stakeholder Interviews**: Understanding workflows, roles, and risk tolerances
### 2. Statement of Work (SOW)
The SOW includes:
* **Scope Definition**: Application codebases, APIs, devices, cloud assets, and more
* **Deliverables**: Security reports with actionable recommendations and remediation guidance
* **Timeline**: Audit duration and check-in cadence
* **Team Composition**: Assigned auditors with relevant expertise
* **Access Requirements**: Systems, code, documentation, and communication access
### 3. Kickoff
Following the SOW, we coordinate logistics and onboarding:
* **Kickoff Call**: Walkthrough of scope, timelines, and workflows
* **Access Provisioning**: Secure access to repos, devices, and systems
* **Channels Setup**: Real-time coordination paths, escalation protocols
* **Audit Synchronization**: Aligned scheduling across application and operational streams
### 4. Security Audit Period
Parallel assessments by specialized researchers:
**Operational Security Audit**
* Device and configuration analysis (e.g. MDM, EDR, VPN)
* Communication tool and endpoint security
* Policy audits and RBAC gap detection
* Contributor access controls
**Application Security Audit**
* Manual and automated code analysis
* API and integration risk evaluation
* Authentication flow testing
* Infrastructure and deployment attack surface audit
**Cross-Team Coordination**
* Regular syncs between application and OpSec auditors
* Shared threat modeling
* Identification of intersecting risks (e.g. cloud + SaaS + credentials)
### 5. Communication
Ongoing transparency throughout the engagement:
* **Daily Standups**: Internal auditor coordination
* **Weekly Client Updates**: Status reports and early signals
* **Urgent Escalations**: Immediate flagging of critical issues
* **Clarification Sessions**: Optional deep-dives with your engineering or ops teams
### 6. Fix Period
Hands-on remediation guidance:
* **Prioritization**: Joint evaluation of impact and exploitability
* **Implementation Support**: Recommendations on fixing both app and OpSec issues
* **Dependencies**: Help resolving cross-domain findings
* **Progress Tracking**: Dashboard of remediation status
### 7. Findings Call
Final walkthrough of results:
* **Joint Presentation**: Unified report with correlated risks
* **Strategic Takeaways**: Systemic issues and structural fixes
* **Interactive Discussion**: Technical questions, rationale, and guidance
### 8. Final Report Delivery
The engagement concludes with a comprehensive package:
* **Executive Summary**: High-level view of organizational posture
* **Technical Findings**: Deep dive into application and operational risks
* **Unified Risk Matrix**: Impact + likelihood evaluation
* **Remediation Roadmap**: Prioritized action items
* **Forward Strategy**: Recommendations for ongoing improvements
### 9. Closeout Call
Final audit and planning touchpoint:
* **Feedback**: Audit process and outcomes
* **Security Strategy**: Long-term recommendations and risk trends
* **Next Steps**: Retainer or follow-up support options
* **QBR Scheduling**: Optional quarterly security audit
***
## When to Engage
Application Security audits are especially valuable during:
**Pre-Launch Events**
* Token launches, governance activations, or frontend deployments
* Launching new SaaS dependencies or internal tools
**Scaling Moments**
* Contributor onboarding
* Organizational restructuring or jurisdictional expansion
**Post-Incident Recovery**
* Following phishing, credential leaks, or infrastructure breaches
* Remediation validation after implementing MDM/EDR/SaaS controls
**Compliance or Assurance**
* Fundraising diligence
* Regulatory or partner-driven security requirements
* Annual posture audits
***
## Target Organizations
This service is ideal for:
* **Protocols**: With off-chain systems tied to governance, oracles, or multisig operations
* **Foundations & DAOs**: Coordinating large teams with SaaS exposure
* **Exchanges & Custodians**: With endpoint-heavy operational models
* **Bridges & Rollups**: Relying on application infrastructure for cross-chain control
* **Developer Teams**: With modern CI/CD pipelines, APIs, and web frontends
***
## Contact Information
For full-scope application security audits, reach out via [cantina.security/contact](https://www.cantina.security/contact).
# Bug Bounty
Source: https://docs.cantina.security/security-teams/services/bug-bounty
Managed bug bounty programs for ongoing vulnerability discovery
Cantina's bug bounty programs connect protocols with vetted security researchers to identify real-world vulnerabilities in live code, featuring intelligent filtering and transparent reporting.
***
## Program Setup
This phase involves establishing your bug bounty program, from setting up the platform to configuring the security frameworks. The Cantina team will assist in ensuring all necessary settings are tailored for your organization's goals and security needs.
***
## Scope Definition
Defining the boundaries of your bug bounty program, including which systems, components, and protocols are in scope. A well-defined scope ensures high-quality submissions and efficient resource allocation for both researchers and your development team.
***
## Vulnerability Reporting
When a researcher discovers a vulnerability, they report it through the Cantina platform. The report includes steps to reproduce, severity level, and suggested remediation, ensuring a clear and actionable report for your team.
***
## Triage Process
All reported vulnerabilities go through a structured triage process. Our team evaluates the severity and impact, prioritizing issues based on risk. This process ensures that your team can focus on the most critical vulnerabilities first.
***
## Rewards and Payments
Once vulnerabilities are confirmed and validated, the reward payout process begins. Cantina ensures seamless and timely payments to researchers based on severity, ensuring a fair and transparent reward system.
***
## Disclosure Policy
Cantina's disclosure policy governs how vulnerabilities are handled and disclosed, including communication guidelines with the researcher and public disclosure protocols. We ensure that all disclosures are managed securely and transparently, protecting both the researcher and the organization.
# Competitions
Source: https://docs.cantina.security/security-teams/services/competitions
Collaborative security audit competitions with expert validation
Cantina Competitions offer organizations a structured, time-bound opportunity to have their codebase audited by top-tier security researchers. These events help identify and address potential vulnerabilities before your product is released, ensuring a stronger security posture and a safer user experience.
## Competition Planning
* **Booking a Competition**: To begin, fill out the competition request form. A member of the Cantina team will reach out to discuss the next steps and ensure the competition is tailored to your specific needs.
* **Defining Scope and Prizes**: Once the competition is booked, you'll complete a Competition Submission Template. This document will help outline the project scope, including target repositories, commit hashes, and prize distribution. Be sure to define the scope clearly, specifying which parts of the codebase should be audited and how prize pools will be allocated.
## Timeline and Structure
* **Competition Duration**: You can determine the duration of your competition based on your organization's needs. Typically, these competitions last from a few weeks to a couple of months, depending on the complexity of your codebase.
* **Competition Phases**: Our structured approach ensures comprehensive coverage and clear outcomes through the following phases:
* **Scoping and Information Gathering**: Define competition parameters, scope, and technical requirements
* **Statement of Work (SOW)**: Finalize competition agreement with scope, deliverables, and timelines
* **Kickoff**: Official launch with project introduction and competition rule walkthrough
* **Competition Period**: Researchers audit codebase and submit vulnerability findings
* **Communication Channels**: Ongoing support and clarification throughout the competition
* **Fix Period**: Address identified vulnerabilities with Cantina team support
* **Findings Call**: Final audit meeting discussing outcomes and recommendations
* **Final Report Delivery**: Comprehensive documentation of findings and security recommendations
* **Closeout Call**: Competition feedback and strategic security discussion
## Participants and Teams
* **Participant Roles**:
* **Security Researchers**: The experts who will analyze your codebase for vulnerabilities.
* **Judges**: Responsible for auditing and scoring the findings submitted by researchers.
* **Team Formation**: Researchers can participate individually or form teams. Collaboration is encouraged to leverage diverse expertise and maximize the effectiveness of the competition.
## Submission Process
* **Finding Submission**: Researchers submit identified vulnerabilities using a standardized format, ensuring clarity and consistency.
* **Proof of Concept (PoC)**: By default, all competitions have a mandatory POC rule: All high and medium severity submissions must be accompanied by a coded Proof of Concept **before** the competition ends. This applies only to researchers with a reputation score below 80.
## Judging Process
* **Severity Assessment**: Each finding is evaluated based on its impact and likelihood of exploitation. We follow the Finding Severity Criteria to ensure consistent and objective assessments.
* **Scoring**: Findings are scored according to their severity, with high-severity issues earning the most points. Researchers are awarded based on the points they accumulate through valid and impactful findings.
* **Escalation Process**: In the event of disagreements over the severity assessment, researchers can appeal the decision. We ensure a fair audit process, though invalid escalations may result in penalties.
## Escalation Process
After the judging phase, the escalation process starts. If a finding was judged and the security researcher that submitted the issue doesn't agree with the severity given, they can appeal for an escalation process and provide extra information justifying the appeal.
Each security researcher can only escalate issues submitted by themselves, and if invalid, will be penalized \$100 from their future credit of potential earnings from the competition.
## Awards Distribution
* **Prize Allocation**: Based on the scoring, participants receive their share of the prize pool.
## Results and Reporting
* **Final Report**: At the conclusion of the competition, we deliver a detailed report summarizing all findings, fixes made, and additional recommendations for improving your security posture.
* **Post-Competition Support**: After the competition, your team will receive recommendations for further strengthening your codebase based on the insights gained during the audit process.
***
Cantina Competitions provide an efficient and effective way for organizations to enhance the security of their codebase, leveraging the expertise of top researchers in a controlled and structured environment. Ready to secure your project with the best in the field? [Reach out today](https://cantina.xyz/contact) to start your next competition with Cantina.
# How Cantina Audits Work
Source: https://docs.cantina.security/security-teams/services/how-audits-work
Structured, expert-led reviews of your codebase conducted by vetted security researchers
**Cantina security audits** are structured, expert-led reviews of your codebase conducted by vetted security researchers.
## Audit Formats
| Format | Best For | How It Works |
| - | - | - |
| **Competitive Audit** | Maximum coverage | Multiple independent researchers audit simultaneously; findings ranked by severity and rewarded from a shared prize pool |
| **Private Audit** | Sensitive codebases, tight timelines | Dedicated team of matched researchers works exclusively on your code |
## The Audit Process
### Step 1 - Scoping
Define code in scope, nLoC, format, and timeline. [Start here](https://cantina.xyz/security-reviews).
### Step 2 - Researcher Matching
Cantina matches researchers to your stack (Solidity, Rust, Go, Python, application frameworks).
### Step 3 - Review Period
Researchers audit via Cantina Code, submitting findings with write-ups and PoCs.
### Step 4 - Judging
Findings are severity-classified, deduplicated, and researchers may escalate disputes.
### Step 5 - Remediation
Your team fixes findings and marks them Fixed, Acknowledged, or Disputed in Cantina Code.
### Step 6 - Final Report
You receive a signed report: executive summary, all findings by severity, and researcher attestations.
## Severity Levels
| Severity | Description | Example |
| - | - | - |
| **Critical** | Immediate risk of fund loss | Unchecked reentrancy |
| **High** | Significant impact with conditions | Access control bypass |
| **Medium** | Moderate impact | Incorrect accounting logic |
| **Low** | Minor / best-practice violations | Unlocked pragma |
| **Informational** | No security impact | Gas optimization |
## Frequently Asked Questions
### What is the difference between a competitive and private audit?
A competitive audit opens your codebase to multiple independent researchers simultaneously for maximum coverage. A private audit assigns a dedicated, curated team - better for sensitive code or tight confidentiality requirements.
### How long does a Cantina audit take?
Most competitive audits run 1–4 weeks. Private audits can be scoped shorter. Judging and report delivery add 1–2 weeks post-review.
### How much does a Cantina audit cost?
Pricing depends on codebase size, format, and timeline. [Contact Cantina](https://cantina.xyz/security-reviews) for a scoping estimate.
### What deliverables does my organization receive?
A final audit report with all findings by severity, recommended remediations, and researcher attestations.
### Can we request a re-review after fixing findings?
Yes, for private audit engagements. Reach out to [support@cantina.xyz](mailto:support@cantina.xyz).
## Ready to Start?
[**Request an Audit →**](https://cantina.xyz/security-reviews)
***
> **Maintained by the Cantina Security Team** · Last reviewed: March 2026 · [support@cantina.xyz](mailto:support@cantina.xyz)
# Managed Detection and Response
Source: https://docs.cantina.security/security-teams/services/managed-detection-and-response
24/7 incident response and security monitoring
Cantina's MDR solution equips protocol teams with the support they need to detect, respond to, and resolve active security threats. By combining 24/7 researcher coverage, hands-on remediation support, and real-world simulations, Cantina helps ensure your team is prepared for - and capable of quickly handling - live exploits.
## What We Provide
### 24/7 Coverage
Cantina leverages a globally distributed network of security researchers to provide around-the-clock incident coverage. When a potential incident occurs, this network activates to triage, assess, and respond quickly - minimizing time to containment and reducing the potential scope of damage.
### Active Resolution Support
Our approach goes beyond alerting. Cantina researchers actively investigate ongoing incidents, trace root causes, analyze impact, and support teams through remediation. We work directly with your developers to restore affected systems and ensure future risk is mitigated.
### Flexible Engagement Models
Cantina supports two approaches to engagement:
* **Fixed monthly retainer**: A dedicated group of researchers is always on-call for your protocol.
* **Incentive-based response**: A broader pool of researchers is activated per incident, with an SLA-based multiplier to incentivize quick response times.
Teams can select the model that aligns best with their internal workflows and risk appetite.
### Simulated Attack Scenarios
Proactive preparation is key. Cantina offers incident response simulations to help your team stress test existing playbooks. Led by a Cantina Advisor, these simulations replicate real-world attack conditions in a controlled environment, providing a safe opportunity to improve detection, coordination, and resolution processes.
## Engagement Overview
A typical Managed Detection and Response setup includes:
1. **Initial Setup & Integration**
* Define communication channels and points of contact
* Align on coverage scope and response expectations
* Choose engagement model (fixed or incentive-based)
2. **Ongoing Monitoring & Availability**
* Standby support 24/7 through Cantina's distributed researcher network
* Optional simulations and playbooks
3. **During an Incident**
* Researcher activation based on severity and scope
* Real-time investigation and coordination
* Support through remediation and system restoration
4. **Post-Incident Audit**
* Summary of findings
* Recommendations for architectural and operational improvements
* Update or refinement of security playbooks
## Interested in setting up MDR coverage?
Reach out to us via [https://cantina.xyz/solutions/incident-response](https://cantina.xyz/solutions/incident-response)
# Multisig Security
Source: https://docs.cantina.security/security-teams/services/multisig-security
Multi-signature wallet protection and key management solutions
Multisignature (multisig) security is a key mechanism in blockchain protocols designed to prevent single points of failure by requiring multiple signatories to authorize actions. It is particularly critical in securing assets, enabling governance, and managing key operations across decentralized systems.
Cantina's multisig security service focuses on ensuring your multisig implementation is secure, robust, and aligned with best practices, providing the protection your protocol needs while minimizing risk.
## What You Can Expect From Our Multisig Security Engagement
Our multisig security service is tailored to your project's unique needs. Here's a breakdown of the engagement process and what to expect:
### 1. Initial Assessment
We start by evaluating your current multisig setup or understanding your requirements for new multisig implementation. This includes:
* Auditing your protocol's architecture and determining how the multisig will interact with the overall system.
* Assessing your protocol's governance model and how multisig fits within it.
* Identifying potential risks or vulnerabilities in your current multisig configuration.
### 2. Multisig Design and Configuration
If you're implementing a new multisig solution, Cantina's team will work with you to:
* Advise on the optimal number of signatories and threshold configurations based on your protocol's governance structure.
* Define best practices for key management, ensuring security and redundancy.
* Design the multisig system to integrate seamlessly with other parts of your infrastructure.
### 3. Code Audit and Vulnerability Assessment
Cantina will perform a comprehensive security audit of your multisig smart contracts to identify any vulnerabilities or issues that could compromise the integrity of the multisig process.
Our audit will focus on:
* Verifying access control mechanisms and ensuring the correct implementation of the multisig logic.
* Checking for common security issues such as reentrancy attacks, improper signature validation, or logic flaws.
* Testing the contract to ensure that all operations perform as expected under different conditions.
### 4. Key Management and Security
Key management is a critical aspect of multisig security. Cantina will guide you through:
* Recommendations on securely managing the private keys involved in the multisig process.
* Advising on the use of hardware wallets, HSMs (Hardware Security Modules), and other secure storage options.
* Establishing key recovery processes to ensure the protocol remains operational in the event of key loss or compromise.
### 5. Testing and Validation
After the multisig implementation and key management practices are in place, Cantina will perform various tests to validate:
* The functional operation of your multisig contracts, ensuring that they work as expected in both normal and edge-case scenarios.
* Security testing, including simulated attacks and tests for misconfigurations.
* Performance testing to ensure multisig transactions can be processed efficiently.
## Contact Us
For more information or to scope a potential engagement, reach out via [https://cantina.xyz/solutions/multisig-security](https://cantina.xyz/solutions/multisig-security)
# Penetration Testing
Source: https://docs.cantina.security/security-teams/services/penetration-testing
Comprehensive penetration testing for on-chain and off-chain infrastructure
Cantina provides comprehensive penetration testing solution designed to identify vulnerabilities before they can be exploited. By simulating real-world attack scenarios, our testing surfaces weaknesses across your environment - providing clear, actionable remediation guidance to improve your overall security posture.
## Our Approach
Our penetration testing process includes the following key components:
### Proactive Vulnerability Identification
We perform a systematic assessment of your systems and codebase to uncover potential weaknesses that could be exploited by adversaries.
### Real-World Attack Simulation
We simulate attacker behavior based on current threat intelligence and historical exploit patterns to evaluate how your systems hold up under realistic attack conditions.
### Advanced Threat Modeling
Our team builds a threat model specific to your environment and architecture to ensure all high-risk pathways are evaluated and prioritized.
Each engagement is scoped and tailored to the specifics of your tech stack, infrastructure, and security concerns.
## The Scope
* **API Testing**
* **Network Layer Testing**
* **Mobile Applications**
* **Web Applications**
* **Cloud Architecture**
* **Onchain-Specific Network & Application Testing**
Whether you're securing traditional infrastructure or cutting-edge decentralized applications, our team tailors testing to your systems and stack.
## Researcher Expertise
Cantina works with experienced penetration testers who specialize in different domains, including cloud, network, mobile, web, and onchain. Our researchers conduct manual testing where automated tools fall short and provide detailed, technically rigorous findings.
## Deliverables and Process
Each penetration testing engagement includes:
* **Initial Scoping Call** – Define systems in scope, testing objectives, timelines, and access requirements.
* **Kickoff and Access Setup** – Establish secure credentials or test environments.
* **Testing Period** – Active testing performed over an agreed-upon period (usually 1–2 weeks).
* **Reporting** – Detailed vulnerability report including:
* Description of each finding
* Proof of concept (PoC)
* Severity rating
* Recommended remediation steps
* **Retesting (optional)** – Validation of fixes after remediation, if desired.
## Contact Us
If you're exploring penetration testing solutions or want to understand how we might tailor an engagement to your systems, reach out at [https://cantina.xyz/solutions/spearbit/penetration-testing](https://cantina.xyz/solutions/spearbit/penetration-testing). We're happy to walk through scoping, researcher selection, and timeline planning.
# Smart Contract Security Audits
Source: https://docs.cantina.security/security-teams/services/smart-contract-audits
Comprehensive security audits by Spearbit and Cantina
## Comprehensive Security Solutions by Spearbit and Cantina
Smart contract security audits are the cornerstone of secure onchain development. Whether you're building decentralized protocols, financial applications, or ecosystem infrastructure, our expert networks provide tailored security assessments to uncover vulnerabilities before they become exploits.
**Spearbit** delivers bespoke audits led by elite, hand-selected researchers who specialize in deep, manual security analysis. With 282 audits completed, 4500+ vulnerabilities found, and 119 projects secured, Spearbit focuses on high-end security audits with team sizes typically of 4-5 security researchers for complex, high-value deployments.
**Cantina** offers flexible smart contract security audits through modular teams of solo security researchers, competitive formats, and collaborative audits. Cantina provides scalable audit formats that match your workflow and risk profile, from individual expert audits to structured competitive assessments.
Both approaches ensure transparent, expert-led security audits that go beyond surface-level checks to uncover architectural weaknesses, specific edge cases, and logic flaws that typical audits miss.
## Process Overview
An overview of how our team conducts comprehensive security audits of your smart contracts. This process aims to uncover vulnerabilities, evaluate the security of your code, and provide actionable insights to strengthen your system's integrity.
### Scoping and Information Gathering
In this stage, we focus on understanding your project's unique needs. Our team will collect the necessary documentation, such as technical specifications, source code, and architecture details, to accurately scope the audit. This helps ensure that the audit addresses all critical areas of concern.
### Statement of Work (SOW)
The Statement of Work (SOW) outlines the scope, deliverables, timelines, and responsibilities associated with the security audit. It serves as a contract between your organization and our team, ensuring transparency and mutual understanding throughout the process.
### Kickoff
The kickoff phase happens after scoping, information gathering and signed SOW, where our team coordinates with your organization to finalize scope details and set expectations. During this phase, we'll schedule meetings, clarify project goals, and align on deliverables before the security audit begins. For engagements longer than one week, we'll also schedule a mid-audit sync to provide progress updates and address any emerging questions.
### Security Audit Period
Once the audit is kicked off, the security researchers dive deep into your smart contracts, conducting a detailed examination for vulnerabilities, bugs, and potential exploits. This phase includes manual analysis, automated testing, and in-depth exploration of the codebase.
### Communication Channels
Clear communication is essential throughout the audit process. We establish regular touchpoints of your preference with your organization, addressing questions, and providing status updates.
### Fix Period
After the initial audit, our team provides feedback on any vulnerabilities discovered. Your development team then has a set period to address and patch these issues. During this period, we offer guidance and clarification to ensure fixes are properly implemented.
### Findings Call
Once all issues have been addressed, we schedule a findings call. This session provides an opportunity for your team to discuss the audit findings, ask questions, and gain a deeper understanding of the identified vulnerabilities and how they were mitigated.
### Final Report Delivery
Following the findings call, our team delivers a comprehensive final report summarizing all findings, remediation actions taken, and security recommendations. This report is designed to be clear, actionable, and useful for your team's future security efforts.
### Closeout Call
After report delivery, we conduct a closeout call focused on engagement feedback and quarterly business audit (QBR). This session allows us to gather feedback on the overall engagement experience and discuss your organization's broader security strategy and future needs.
# Evaluations and Standards
Source: https://docs.cantina.security/standards
How we ensure fairness, clarity, and consistency
> How we ensure fairness, clarity, and consistency
**How we ensure fairness, clarity, and consistency.**
This section outlines the principles and processes that guide how we evaluate findings. Whether you're submitting a bug or auditing one, these standards ensure everyone's on the same page.
## [Severity Classifications](/standards/severity)
Our standardized severity framework helps ensure findings are consistently rated across competitions, based on real-world impact and exploitability.
## [Judging Processes](/standards/judging)
Submissions are audited by experienced judges using a rigorous, criteria-based approach to ensure objective, repeatable outcomes at scale.
# Judging Processes
Source: https://docs.cantina.security/standards/judging
How findings are evaluated, escalated, and scored
**How findings are evaluated, escalated, and scored across Cantina.**
Our judging system is designed to be transparent, consistent, and aligned with real-world risk - ensuring high-quality results for both researchers and clients.
## Scoring System
How competition points are calculated and prize pots are distributed.
Cantina competitions use a transparent, points-based scoring model to reward high-impact, high-quality submissions - encouraging depth, originality, and clarity.
### Prize Pot Distribution
All eligible participants who score points share in a public prize pot.
* **High severity finding**: 10 points
* **Medium severity finding**: 3 points
* **Low severity findings**: May be eligible for a separate prize pool, if specified.
### Duplicate Submission Scaling
When multiple researchers submit the same bug, each person's score is scaled down based on the total number of duplicates:
$\text{Points} = \frac{\text{Full Points}}{1 + 0.8 \times (n - 1)}$
Where `n` is the number of duplicate submissions.
* 2 duplicates: each receives **4.5 points** for a high severity finding
* 3 duplicates: each receives **2.7 points** for a high severity finding
This incentivizes originality - being the one to find the bug no one else saw results in a much larger reward.
### Submission Timing
Submissions are scored equally regardless of when they're submitted during the competition. However, early, well-written reports are encouraged to allow teams to provide feedback and begin implementing fixes.
### Withdrawing Findings
You can withdraw a submission at any time using the "withdraw finding" option in the finding menu.
### Low-Severity, Informational, and Gas Findings
Some competitions include a dedicated prize pool for these types of findings. These awards are based solely on **quality**, not quantity - and exceptional writeups in this category (or for high/medium findings) may be recognized here as well.
## Escalation Process
Appeal a judging decision with clarity and consequence.
Once the initial judging phase is complete, researchers have the opportunity to appeal a decision they believe was misjudged - by initiating an escalation.
### Who Can Escalate
* Only the **original submitter** of a finding can initiate an escalation.
* Escalations must include **additional context or justification** for why the severity should be reconsidered.
### Penalty for Invalid Escalations
* Invalid escalations will result in a **\$100 penalty**, deducted from any future competition earnings.
* This system is in place to prevent unnecessary or speculative appeals.
### Judging Authority
* All escalations are reviewed by Cantina.
* **Cantina's decision is final**.
### Private Comments
* You can add **private comments** to any finding - visible only to judges.
* These are useful both during initial judging and if you escalate.
* If commenting on others' findings, stay professional: keep your notes **objective and specific**.
## Judge Responsibilities
During the judging phase, judges are responsible for handling different operations for findings.
These are extended and not limited to managing thorough duplication of all raised issues, which helps in identifying and filtering out obvious low or invalid concerns.
They are tasked with evaluating issues based on established rules and may seek feedback from sponsors when necessary to make informed judgments. Furthermore, judges facilitate a system of escalation, allowing researchers to present additional information for reevaluation of their issues. In such scenarios, judges provide valuable feedback, incorporating the sponsor's perspective if needed.
Ultimately, while judges contribute significantly to the reassessment process, the final decision often resides with the Cantina internal team, ensuring that all judgments are well-considered and equitable.
### Key Responsibilities
* **Evaluate findings** based on established severity criteria
* **Handle duplication** by grouping related findings
* **Collaborate with sponsors** for clarification when needed
* **Process escalations** and provide feedback
* **Maintain consistency** across all submissions
# Severity Classifications
Source: https://docs.cantina.security/standards/severity
Standardized framework for vulnerability classification
> Standardized framework for vulnerability classification
We use a standardized classification system to bring consistency and clarity to how vulnerabilities are tracked and evaluated across our platform.
* [**Finding Status and Labels**](/standards/severity/finding-categorization) - Every submission is assigned a status and may be tagged with labels to aid in triage, filtering, and reporting.
* [**Competition Finding Severity**](/standards/severity/competition) - Severities are determined using criteria that evaluate potential impact, likelihood, and exploitability.
* [**Bug Bounty Severity**](/standards/severity/bug-bounty) - For bounty programs, we follow a framework to map severity levels to payout tiers.
# Bug Bounty Severity Classification
Source: https://docs.cantina.security/standards/severity/bug-bounty
Cantina's bug bounty severity classification for smart contract vulnerabilities. Learn what's in scope vs out of scope for vulnerability rewards.
> Cantina's bug bounty severity classification for smart contract vulnerabilities. Learn what's in scope vs out of scope for vulnerability rewards.
## Introduction
At [Cantina](https://cantina.xyz/solutions/bounties), we prioritize the security and integrity of our ecosystem. This **Severity Classification System** provides a standardized framework for evaluating and categorizing vulnerabilities based on their **impact** and **likelihood of exploitation**. This system is designed to ensure consistency and transparency in assessing risks across our programs.
> **Note:** This bounty severity classification serves as a general guide and may be customized based on individual client requirements. Some bug bounty programs may define their own severity criteria, so please review the respective program's home page carefully.
***
## Severity Levels
We classify vulnerabilities in **four distinct levels** based on their **impact** and **likelihood of exploitation**. The severity of a vulnerability is determined by combining these two factors using the **Risk Classification Matrix** below:
| **Severity Level** | **Impact: Critical** | **Impact: High** | **Impact: Medium** | **Impact: Low** |
| - | - | - | - | - |
| **Likelihood: High** | Critical | High | Medium | Low |
| **Likelihood: Medium** | High | High | Medium | Low |
| **Likelihood: Low** | Medium | Medium | Low | Informational |
***
## 1. Critical
* **Impact**: Catastrophic damage to the protocol or its users.
* Examples include severe loss of **assets**, permanent system disruption, or widespread compromise.
* **Likelihood**: High, with minimal or no user interaction required.
* Exploitation is very easy or highly incentivized.
* **Examples**:
* Permanent loss or freezing of **assets**.
* Network-wide shutdown or inability to confirm transactions.
* Unintended permanent chain splits requiring a hard fork.
* Protocol insolvency or governance manipulation leading to direct financial harm.
* **Application**: Account takeover with significant impact (e.g., admin account compromise).
***
## 2. High
* **Impact**: Significant damage to the protocol or its users, but not catastrophic.
* Examples include notable financial loss or significant harm to user trust.
* **Likelihood**: Medium to high, with some user interaction or specific conditions required.
* Exploitation is possible under certain conditions.
* **Examples**:
* Temporary freezing of **assets** or transactions.
* Unintended chain splits (network partitions).
* Theft of unclaimed yield or royalties.
* Exploits requiring elevated privileges but with high impact.
* **Application**: Account takeover with moderate impact (e.g., user account compromise).
***
## 3. Medium
* **Impact**: Moderate damage, often limited to specific users or conditions.
* Examples include limited financial damage or moderate system impact.
* **Likelihood**: Medium, requiring specific conditions or user interaction.
* Exploitation is possible but not trivial.
* **Examples**:
* Increased resource consumption or temporary disruption of network nodes.
* Theft of gas or griefing attacks with no direct profit motive.
* Bugs causing unintended smart contract behavior without direct financial risk.
* **Application**: Non-sensitive data disclosure, open redirects, or reflected HTML injection.
***
## 4. Low
* **Impact**: Minor damage, often limited to non-critical functionality.
* Examples include minimal direct risk or areas for improvement.
* **Likelihood**: Low, requiring significant user interaction or unlikely conditions.
* Exploitation is difficult or requires highly specific conditions.
* **Examples**:
* Shutdown of a small percentage of network nodes without network-wide impact.
* Modification of transaction fees outside design parameters.
* Non-critical UI/UX issues or minor information disclosure.
* **Application**: Minor UI/UX issues or non-critical functionality disruptions.
***
## Scope and Considerations
### Blockchain
* **Critical**: Network-wide issues, permanent **asset** loss, or hard fork requirements.
* **High**: Temporary network disruptions or unintended chain splits.
* **Medium**: Resource consumption spikes or localized node shutdowns.
* **Low**: Minor node disruptions or fee modifications.
### Smart Contracts
* **Critical**: Direct theft, permanent freezing of **assets**, or governance manipulation.
* **High**: Theft of unclaimed yield, temporary freezing of **assets**, or unauthorized minting.
* **Medium**: Griefing, gas theft, or unbounded gas consumption.
* **Low**: Non-critical contract behavior or minor functionality issues.
### Websites and Apps
* **Critical**: Remote code execution, unauthorized access to sensitive data, or significant financial harm.
* **High**: Sensitive data disclosure, subdomain takeovers (case-by-case basis), or unauthorized actions.
* **Medium**: Non-sensitive data disclosure, open redirects, or reflected HTML injection.
* **Low**: Minor UI/UX issues or non-critical functionality disruptions.
***
## Out of Scope
The following are considered out of scope for our vulnerability classification system:
### Onchain and Protocol-Specific
* **Weird ERC20 tokens** - Issues related to non-compliant or non-standard ERC20 token implementations.
* **Centralization-related risks** - General concerns about protocol centralization.
* **Admin errors** - Issues based on admin mistakes (e.g., calling a function with wrong parameters, admin actions on integrated protocols). *Note: Issues based on wrong implementation of admin functions will have severity defined by the severity matrix.*
* **Malicious admin** - Issues based on a malicious or compromised admin, unless explicitly included in the contest scope.
* **User errors** - Issues based on user error without significant impact on other users.
* **Design philosophy of the protocol** - Issues related to trade-offs made on permissionless protocols.
* **Speculation on future code or integrations** - Issues based on future changes, integrations, or upgrades, unless the finding directly relates to current code and behavior.
* **Known issues by the team** - Vulnerabilities already identified by the program sponsor.
### General Security
* **Theoretical vulnerabilities** without proof of concept.
* **Social engineering attacks** or phishing.
* **Issues requiring physical access** to a user's device or local network.
* **Best practice recommendations** or feature requests.
* **Third-party integrations** or dependencies not under our control.
* **Denial of Service (DoS) attacks** without demonstrated impact.
* **Self-XSS** or non-exploitable UI/UX issues.
* **Clickjacking** on pages with no sensitive actions.
* **Server Information & Status Pages** (e.g., stack traces, descriptive error messages).
* **SSL/TLS best practices** (e.g., missing SSL Pinning, insecure configurations).
* **Optional email security features** (e.g., SPF/DKIM/DMARC configurations).
* **Most issues related to rate limiting**.
* **Content-Security-Policy configuration opinions**.
* **Verbose error messages** without proof of exploitability.
* **Attacks requiring MITM or physical access** to a user's device.
* **Reports from automated tools or scans**.
* **Missing HTTP Only flags on non-sensitive cookies**.
* **Content spoofing, text injection**.
* **Issues without clearly identified security impact**.
* **Self-exploitation** (e.g., self-XSS, self-DoS, cookie reuse).
* **Tabnabbing**.
* **Brute forcing account credentials**.
* **Known vulnerable libraries** without a working Proof of Concept.
* **Open access to publicly-exposed resources** (e.g., Google Sheets) without demonstration of vulnerability exploitation.
***
## Testing Guidelines
To ensure safe and responsible testing:
* Use **local forks** for testing instead of public chains.
* Avoid actions that could disrupt network availability or integrity.
* Do not attempt to access, modify, or destroy data that does not belong to you.
* Submit detailed reports with **proof of concept** and steps to reproduce the vulnerability.
***
## Eligibility
To qualify for consideration:
* Report a **previously unknown, non-public vulnerability** within the program's scope.
* Be the **first to disclose** the vulnerability.
* Provide sufficient information for our team to reproduce and resolve the issue.
* Avoid exploiting the vulnerability or making it public.
* Comply with all program rules and guidelines.
***
## Prohibited Actions
The following actions are strictly prohibited:
* Testing on **public mainnet or testnet deployments**.
* Public disclosure of vulnerabilities without prior consent.
* Engaging in **illegal activities** or coercive tactics.
* Exploiting vulnerabilities for personal gain.
# Competition Finding Severity Criteria
Source: https://docs.cantina.security/standards/severity/competition
Competition finding severity criteria including the mandatory PoC rule. Learn when Proof of Concept is required for high and medium severity submissions.
> Competition finding severity criteria including the mandatory PoC rule. Learn when Proof of Concept is required for high and medium severity submissions.
## Severity Matrix
The severity matrix serves as the baseline for assigning a severity to a bug.
It's often easier to think about the *impact* and the *likelihood* of the occurrence of an issue in two different categories.
* A High impact situation would be one where funds can be lost.
* A High likelihood situation would be one in which any participant can trigger such a bug in the protocol.
| Severity | Impact: High | Impact: Medium | Impact: Low |
| - | - | - | - |
| **Likelihood: High** | High | High | Medium |
| **Likelihood: Medium** | High | Medium | Low |
| **Likelihood: Low** | Medium | Low | Informational |
However, this is just the first step in assigning severity and has a lot of subjectivity in practice. **When in doubt, consider what would happen to the protocol when such a bug is not fixed**. If it leads to a catastrophic scenario that can be triggered by anyone or occur naturally, then it is very likely to be a High severity bug.
If the protocol can function without the bug getting fixed, it's likely to be a low severity bug.
The last consideration to make is to put yourself in the shoes of the protocol designer. The best way to do this would be to think about how to mitigate the bug.
We highly recommend everyone to submit a recommended mitigation for every finding. Doing this exercise can help you understand the tradeoffs that protocol designers have to make.
For example, building a permissionless protocol often means making tradeoffs on certain properties -- the Uniswap protocol allows anyone to deploy a pool and in most cases, these are perfectly legitimate pools, but, pools can be setup with malicious tokens to act in certain ways.
There are two ways to mitigate such issues, adding a whitelist of all 'genuine' pools or alternatively rely on off-chain trust on what are the legitimate pools.
If your suggested fix goes against the design philosophy of the protocol, it's very likely to be at most an informational issue.
## Mandatory PoC Rule
By default, all competitions have a **mandatory PoC rule**:
* All **high** and **medium** severity submissions must be accompanied by a coded **Proof of Concept (PoC)** before the competition ends. This applies to researchers with a reputation score below 80.
* Exceptions will be noted on the specific competition page.
* **Cantina Dedicated Researchers** in a competition are exempt and can provide PoC upon request when needed.
To be considered valid, **the PoC must compile and demonstrate the impact of the issue**. See [Submission Guidelines](/researchers/participation/submission-guidelines#proof-of-concept-poc-requirements) for PoC validity criteria and [Finding Submission Examples](/researchers/participation/examples) for real examples.
*Exceptions when PoC is not required:* Missing function(s), or when the researcher's reputation score is ≥ 80.
***
## Important Considerations
* Issues that are ultimately user errors and can be easily managed in the front-end should at most be informational.
* Issues that require admin access (or equivalent) to perform should at most be low severity, unless the protocol was designed to be resilient against such actions in the first place.
* AI generated findings: submitting AI generated findings without validating them can lead to *disqualifications* or worse, a *permanent ban*.
* The goal of getting a security review is for protocols to make meaningful changes to the protocols to improve its security. Make sure the findings you submit contribute to this cause.
* In case of public competitions, a judge will act as an independent arbiter for any disagreements. After judging is done, there will be an escalation phase where people can contest some judgements. Anyone can currently contest a judgement, but there will be a penalty for escalations that were invalid.
* Be mindful of the judges' and the protocol-team's time.
## Protocol Behavior
The competition README must be used as the main reference for protocol behavior and not other sources.
## Tips
* Approval race conditions for ERC20 tokens will be considered invalid.
* Assume by default that a protocol will be using only standard ERC20 tokens. Any findings that rely on [weird token](https://github.com/d-xo/weird-erc20) properties should at most be a low severity finding.
* Losing dust amounts, say, due to rounding is at most a low severity finding.
* Any finding that has been acknowledged in a previous report will be considered invalid.
# Finding Labels and Status
Source: https://docs.cantina.security/standards/severity/finding-categorization
Understanding finding statuses and labels
> Understanding finding statuses and labels
## Finding Labels
Labels are **user-made tags** which can be assigned to a finding. Each Cantina Code repository can have its own custom tags, and whether a user can create or modify a tag depends on the engagement and security review type.
Common labels include:
* **Potentially Duplicate**: Used when a finding may match another submission and still needs confirmation.
* **Escalated**: Used in competitions when a researcher disagrees with a judge's decision and escalates the finding.
## Finding Status
Below is the list of finding statuses used on Cantina.
Bug bounty programs use a focused subset with bounty-specific payout rules. See [Bug Bounty Finding Statuses](/researchers/participation/bug-bounty-statuses).
| Status | Description |
| - | - |
| **New** | Once a finding is submitted by the security researcher, it will be labelled as new by default. |
| **In Review** | The finding has been triaged and is now waiting on the client input. The outcome will appear on the finding when that review is complete. |
| **Disputed** | On the occasion where the competition client disagrees with the judging decision of a finding, they would change the status of the finding to disputed while providing reasoning to the change. |
| **Rejected** | Upon review, if the finding does not fit the criteria within the competitive scoring schema, the judge will list the finding as rejected. |
| **Duplicate** | Marked when another researcher already reported the same underlying issue. In competitions, duplicates are rewarded; in bug bounties they are not (see [Bug Bounty Finding Statuses](/researchers/participation/bug-bounty-statuses)). |
| **Confirmed** | When the finding is valid, it will be labelled as confirmed and be awarded based on the competition prize pool. |
| **Acknowledged** | After a finding is confirmed by the judge, the competition sponsor will have to acknowledge and double confirm the issue. |
| **Fixed** | After a finding is acknowledged, the sponsor marks it Fixed once the issue has been remediated. This status tracks findings that have already been fixed. |
| **Spam** | When a finding is marked as spam, it typically refers to the issue reported being irrelevant, low-quality, automated and inappropriate. Both the judge and the sponsor can mark this status for findings. |
| **Withdrawn** | If the researcher submits an issue and decides to withdraw it for any reason, the finding will be labelled as "Withdrawn". |
# Vision and approach
Source: https://docs.cantina.security/vision-and-approach
Cantina's approach to security: machine intelligence paired with world-class human expertise, with the human always in the driver's seat.
## Our approach
Cantina is built by security researchers, for security teams. We pair machine intelligence with world-class human expertise, and we keep the human in the driver's seat: the platform is capable of running security work end to end, and each team decides how much autonomy to grant based on its own risk and compliance posture.
We sit above your existing stack rather than replacing it. Your detection tools keep doing detection; Cantina is the reasoning, memory, and action layer that closes the resolution loop across all of them.
## Our roots
Cantina grew out of the Spearbit network of elite security researchers, which has secured more than \$100B in value and is trusted by teams like Coinbase, Uniswap, Aave, and SAP. That network still powers our audits, competitions, and bug bounty programs, and it is the human expertise the platform builds on.
## Where we're headed
Security built for a world where attackers move at machine speed, and defenders finally can too. We are working toward security that runs as a background function for every team, whatever its size.