From b9a9f722247467668f80d745bbc9822f0081bcad Mon Sep 17 00:00:00 2001 From: Kamilo Amir Date: Wed, 14 Oct 2026 15:47:11 -0400 Subject: [PATCH] Add Cribl Detect plugin to Published Plugins Introduces a read-only Microsoft Security Copilot plugin for Cribl Detect. The plugin exposes nine skills covering detection rules, alerts, notable events, ingest data sources, and routing pipelines, backed by an OpenAPI 3.0.1 spec with Bearer-token auth and per-tenant base URL. Co-Authored-By: Claude Opus 4.7 --- .../CriblDetect/CHANGELOG.md | 15 + .../CriblDetect/CriblDetect_OpenAPI.yaml | 677 ++++++++++++++++++ .../CriblDetect/CriblDetect_manifest.yaml | 59 ++ .../CriblDetect/SamplePrompts.md | 36 + .../Published Plugins/CriblDetect/readme.md | 164 +++++ 5 files changed, 951 insertions(+) create mode 100644 Plugins/Published Plugins/CriblDetect/CHANGELOG.md create mode 100644 Plugins/Published Plugins/CriblDetect/CriblDetect_OpenAPI.yaml create mode 100644 Plugins/Published Plugins/CriblDetect/CriblDetect_manifest.yaml create mode 100644 Plugins/Published Plugins/CriblDetect/SamplePrompts.md create mode 100644 Plugins/Published Plugins/CriblDetect/readme.md diff --git a/Plugins/Published Plugins/CriblDetect/CHANGELOG.md b/Plugins/Published Plugins/CriblDetect/CHANGELOG.md new file mode 100644 index 00000000..b7e8e25f --- /dev/null +++ b/Plugins/Published Plugins/CriblDetect/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +All notable changes to this plugin are documented here. This project +follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses +[Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2026-10-14 + +### Added +- Initial release of the Cribl Detect plugin for Microsoft Security Copilot. +- Nine skills covering detections, alerts, notables, data sources, and pipelines. +- OpenAPI 3.0.1 spec (`CriblDetect-OpenAPI.yaml`) with Bearer-token auth. +- Card formats for Detection, Alert, Notable, and DataSource responses. +- `README.md` with install and troubleshooting instructions. +- `SamplePrompts.md` with triage, coverage, and chained-skill prompts. diff --git a/Plugins/Published Plugins/CriblDetect/CriblDetect_OpenAPI.yaml b/Plugins/Published Plugins/CriblDetect/CriblDetect_OpenAPI.yaml new file mode 100644 index 00000000..b5d21135 --- /dev/null +++ b/Plugins/Published Plugins/CriblDetect/CriblDetect_OpenAPI.yaml @@ -0,0 +1,677 @@ +openapi: 3.0.1 +info: + title: Cribl Detect API (Security Copilot plugin surface) + description: >- + Read-only slice of the Cribl Detect REST API exposed to Microsoft Security + Copilot. Covers detection rules, alerts/findings, notable events, ingest + data sources, and routing pipelines. All operations require a Bearer token + with read scope on the corresponding Cribl resources. The server URL is + supplied by the plugin setting "CriblBaseUrl" via the manifest field + EndpointUrlSettingName. + version: 1.0.0 + contact: + name: Cribl Support + url: https://docs.cribl.io +servers: + - url: https://default.main.example-org.cribl.cloud + description: >- + Placeholder base URL. The actual base URL is injected by Microsoft + Security Copilot from the "CriblBaseUrl" plugin setting at install time. +security: + - BearerAuth: [] +tags: + - name: Detections + description: Detection rule inventory + - name: Alerts + description: Findings produced by detection rules + - name: Notables + description: Correlated incidents / notable events + - name: DataSources + description: Ingest sources and routing pipelines + +paths: + /api/v1/m/{workerGroup}/detect/detections: + get: + tags: [Detections] + operationId: listDetections + summary: List detection rules + description: >- + List detection rules configured in Cribl Detect for a worker group. + Filter by severity, enabled state, MITRE ATT&CK technique, data source, + or free-text match on name and description. Returns rule id, name, + severity, MITRE mapping, data sources, and lastUpdated. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: severity + in: query + description: Filter by one or more severities. + required: false + schema: + type: array + items: + type: string + enum: [informational, low, medium, high, critical] + style: form + explode: true + - name: enabled + in: query + description: If true, return only enabled rules. + required: false + schema: + type: boolean + - name: mitreTechnique + in: query + description: MITRE ATT&CK technique id (e.g. T1059.001). + required: false + schema: + type: string + pattern: '^T\d{4}(\.\d{3})?$' + - name: dataSource + in: query + description: Filter rules that reference the given data source id. + required: false + schema: + type: string + - name: q + in: query + description: Free-text match on rule name or description. + required: false + schema: + type: string + maxLength: 200 + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Offset' + responses: + '200': + description: Detection rule page. + content: + application/json: + schema: + $ref: '#/components/schemas/DetectionPage' + '401': { $ref: '#/components/responses/Unauthorized' } + '403': { $ref: '#/components/responses/Forbidden' } + '429': { $ref: '#/components/responses/RateLimited' } + + /api/v1/m/{workerGroup}/detect/detections/{detectionId}: + get: + tags: [Detections] + operationId: getDetection + summary: Get a detection rule + description: >- + Return the full definition of a single Cribl detection rule by id, + including the detection logic (Cribl Search / KQL / SPL), schedule, + suppression settings, enrichment lookups, and version history. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: detectionId + in: path + required: true + schema: + type: string + description: Detection rule id (ULID). + responses: + '200': + description: Full detection rule definition. + content: + application/json: + schema: + $ref: '#/components/schemas/Detection' + '401': { $ref: '#/components/responses/Unauthorized' } + '404': { $ref: '#/components/responses/NotFound' } + + /api/v1/m/{workerGroup}/detect/alerts: + get: + tags: [Alerts] + operationId: listAlerts + summary: Query alerts and findings + description: >- + Return alerts produced by Cribl Detect rules. Supports filtering by + time window (start/end ISO-8601), severity, status + (new / acknowledged / in_progress / closed / suppressed), assignee, + source rule id, and entity (host, user, ip, hash). Defaults to the + last 24 hours if no time window is supplied. Prefer small page sizes + for interactive triage. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: startTime + in: query + description: Inclusive lower bound (ISO-8601 UTC). + required: false + schema: + type: string + format: date-time + - name: endTime + in: query + description: Exclusive upper bound (ISO-8601 UTC). + required: false + schema: + type: string + format: date-time + - name: severity + in: query + required: false + schema: + type: array + items: + type: string + enum: [informational, low, medium, high, critical] + style: form + explode: true + - name: status + in: query + required: false + schema: + type: array + items: + type: string + enum: [new, acknowledged, in_progress, closed, suppressed] + style: form + explode: true + - name: assignee + in: query + description: UPN or email of alert owner. + required: false + schema: + type: string + - name: ruleId + in: query + description: Return only alerts raised by the given detection rule. + required: false + schema: + type: string + - name: entity + in: query + description: >- + Filter by any observed entity. Pass as `type:value`, for example + `user:alice@contoso.com` or `ip:10.1.2.3`. + required: false + schema: + type: string + pattern: '^(host|user|ip|hash|url|domain|file):.+$' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Offset' + responses: + '200': + description: Alert page. + content: + application/json: + schema: + $ref: '#/components/schemas/AlertPage' + '401': { $ref: '#/components/responses/Unauthorized' } + '429': { $ref: '#/components/responses/RateLimited' } + + /api/v1/m/{workerGroup}/detect/alerts/{alertId}: + get: + tags: [Alerts] + operationId: getAlert + summary: Get one alert + description: >- + Retrieve a single alert by id including the full matched event sample, + enrichment fields, risk score, MITRE mapping, and links back to the + originating detection rule and notable event (if correlated). + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: alertId + in: path + required: true + schema: + type: string + responses: + '200': + description: Full alert record. + content: + application/json: + schema: + $ref: '#/components/schemas/Alert' + '404': { $ref: '#/components/responses/NotFound' } + + /api/v1/m/{workerGroup}/detect/notables: + get: + tags: [Notables] + operationId: listNotables + summary: List notable events + description: >- + List notable events (correlated incidents) from Cribl Detect. Filter by + time window, severity, status, assignee, risk score threshold, or + entity. Each notable may link to multiple underlying alerts. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: startTime + in: query + required: false + schema: { type: string, format: date-time } + - name: endTime + in: query + required: false + schema: { type: string, format: date-time } + - name: severity + in: query + required: false + schema: + type: array + items: + type: string + enum: [informational, low, medium, high, critical] + style: form + explode: true + - name: status + in: query + required: false + schema: + type: array + items: + type: string + enum: [new, acknowledged, in_progress, closed] + style: form + explode: true + - name: assignee + in: query + required: false + schema: { type: string } + - name: minRiskScore + in: query + description: Return only notables with risk score >= this value (0-100). + required: false + schema: + type: integer + minimum: 0 + maximum: 100 + - name: entity + in: query + required: false + schema: + type: string + pattern: '^(host|user|ip|hash|url|domain|file):.+$' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Offset' + responses: + '200': + description: Notable event page. + content: + application/json: + schema: + $ref: '#/components/schemas/NotablePage' + + /api/v1/m/{workerGroup}/detect/notables/{notableId}: + get: + tags: [Notables] + operationId: getNotable + summary: Get one notable event + description: >- + Retrieve a single notable event by id with its contributing alert ids, + risk timeline, affected entities, and investigation notes. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: notableId + in: path + required: true + schema: { type: string } + responses: + '200': + description: Notable detail with contributing alerts. + content: + application/json: + schema: + $ref: '#/components/schemas/Notable' + '404': { $ref: '#/components/responses/NotFound' } + + /api/v1/m/{workerGroup}/system/sources: + get: + tags: [DataSources] + operationId: listDataSources + summary: List ingest data sources + description: >- + Enumerate ingest data sources known to Cribl (Stream Sources and Edge + collectors feeding Cribl Detect). Returns name, type (syslog, http, + kafka, s3, azure_blob, splunk_hec, ...), worker group, pipeline, + status, and recent EPS / throughput metrics. Use this to confirm + coverage before trusting a "no results" answer from an alert query. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: type + in: query + required: false + description: Filter by source type (syslog, http, kafka, s3, azure_blob, splunk_hec, ...) + schema: { type: string } + - name: status + in: query + required: false + schema: + type: string + enum: [healthy, degraded, down, disabled] + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Offset' + responses: + '200': + description: Data source page. + content: + application/json: + schema: + $ref: '#/components/schemas/DataSourcePage' + + /api/v1/m/{workerGroup}/system/sources/{sourceId}: + get: + tags: [DataSources] + operationId: getDataSource + summary: Get one data source + description: >- + Return configuration and recent health metrics for a single Cribl data + source by id, including last-ingested timestamp, dropped events, and + backpressure state. + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - name: sourceId + in: path + required: true + schema: { type: string } + responses: + '200': + description: Data source config and recent health. + content: + application/json: + schema: + $ref: '#/components/schemas/DataSource' + '404': { $ref: '#/components/responses/NotFound' } + + /api/v1/m/{workerGroup}/pipelines: + get: + tags: [DataSources] + operationId: listPipelines + summary: List routing pipelines + description: >- + List Cribl routing pipelines for a worker group. Returns pipeline id, + description, number of functions, and the detection rules and + destinations that depend on it. Useful for coverage questions ("does + this detection see firewall data?"). + parameters: + - $ref: '#/components/parameters/WorkerGroup' + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Offset' + responses: + '200': + description: Pipeline page. + content: + application/json: + schema: + $ref: '#/components/schemas/PipelinePage' + +components: + securitySchemes: + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + + parameters: + WorkerGroup: + name: workerGroup + in: path + required: true + description: >- + Cribl worker group (e.g. "default_search"). The model should pass the + value configured in the "CriblWorkerGroup" plugin setting when no + explicit group is requested by the user. + schema: + type: string + default: default_search + Limit: + name: limit + in: query + description: Max number of items to return (1-100). + required: false + schema: + type: integer + minimum: 1 + maximum: 100 + default: 25 + Offset: + name: offset + in: query + description: Zero-based pagination offset. + required: false + schema: + type: integer + minimum: 0 + default: 0 + + responses: + Unauthorized: + description: Missing or invalid bearer token. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + Forbidden: + description: Token lacks required scope. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + NotFound: + description: Resource not found. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + RateLimited: + description: Too many requests; retry after the duration in Retry-After. + headers: + Retry-After: + schema: { type: integer } + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + schemas: + Error: + type: object + properties: + timestamp: { type: integer, format: int64 } + errorMessage: { type: string } + correlationId: { type: string } + + MitreMapping: + type: object + properties: + tactics: + type: array + items: { type: string } + techniques: + type: array + items: { type: string } + + Detection: + type: object + required: [id, name, severity, enabled] + properties: + id: { type: string } + name: { type: string } + description: { type: string } + severity: + type: string + enum: [informational, low, medium, high, critical] + enabled: { type: boolean } + schedule: + type: object + properties: + type: { type: string, enum: [realtime, cron, interval] } + cron: { type: string } + intervalSeconds: { type: integer } + search: + type: object + description: Detection logic + properties: + language: { type: string, enum: [cribl_search, kql, spl] } + query: { type: string } + mitre: { $ref: '#/components/schemas/MitreMapping' } + dataSources: + type: array + items: { type: string } + suppression: + type: object + properties: + windowSeconds: { type: integer } + keyFields: + type: array + items: { type: string } + lastUpdated: { type: string, format: date-time } + createdBy: { type: string } + version: { type: integer } + consoleUrl: { type: string, format: uri } + + DetectionPage: + type: object + properties: + items: + type: array + items: { $ref: '#/components/schemas/Detection' } + total: { type: integer } + limit: { type: integer } + offset: { type: integer } + + Alert: + type: object + required: [id, title, severity, status, createdAt] + properties: + id: { type: string } + title: { type: string } + description: { type: string } + severity: + type: string + enum: [informational, low, medium, high, critical] + status: + type: string + enum: [new, acknowledged, in_progress, closed, suppressed] + createdAt: { type: string, format: date-time } + updatedAt: { type: string, format: date-time } + assignee: { type: string } + riskScore: { type: integer, minimum: 0, maximum: 100 } + ruleId: { type: string } + ruleName: { type: string } + notableId: + type: string + nullable: true + description: Correlated notable event id (if any). + entities: + type: array + items: + type: object + properties: + type: { type: string, enum: [host, user, ip, hash, url, domain, file] } + value: { type: string } + matchedEvent: + type: object + additionalProperties: true + description: Representative raw event fields that triggered the rule. + mitre: { $ref: '#/components/schemas/MitreMapping' } + consoleUrl: { type: string, format: uri } + + AlertPage: + type: object + properties: + items: + type: array + items: { $ref: '#/components/schemas/Alert' } + total: { type: integer } + limit: { type: integer } + offset: { type: integer } + + Notable: + type: object + required: [id, title, severity, status, createdAt] + properties: + id: { type: string } + title: { type: string } + summary: { type: string } + severity: + type: string + enum: [informational, low, medium, high, critical] + status: + type: string + enum: [new, acknowledged, in_progress, closed] + createdAt: { type: string, format: date-time } + assignee: { type: string } + riskScore: { type: integer, minimum: 0, maximum: 100 } + contributingAlertIds: + type: array + items: { type: string } + entities: + type: array + items: + type: object + properties: + type: { type: string } + value: { type: string } + timeline: + type: array + items: + type: object + properties: + at: { type: string, format: date-time } + event: { type: string } + detail: { type: string } + consoleUrl: { type: string, format: uri } + + NotablePage: + type: object + properties: + items: + type: array + items: { $ref: '#/components/schemas/Notable' } + total: { type: integer } + limit: { type: integer } + offset: { type: integer } + + DataSource: + type: object + required: [id, name, type, status] + properties: + id: { type: string } + name: { type: string } + type: { type: string, description: "e.g. syslog, http, kafka, s3, azure_blob, splunk_hec" } + status: { type: string, enum: [healthy, degraded, down, disabled] } + group: { type: string } + pipeline: { type: string } + lastEventAt: { type: string, format: date-time } + metrics: + type: object + properties: + eventsPerSecond: { type: number } + bytesPerSecond: { type: number } + droppedLastHour: { type: integer } + backpressure: { type: boolean } + consoleUrl: { type: string, format: uri } + + DataSourcePage: + type: object + properties: + items: + type: array + items: { $ref: '#/components/schemas/DataSource' } + total: { type: integer } + limit: { type: integer } + offset: { type: integer } + + Pipeline: + type: object + properties: + id: { type: string } + description: { type: string } + functionCount: { type: integer } + inputSources: + type: array + items: { type: string } + outputDestinations: + type: array + items: { type: string } + linkedDetections: + type: array + items: { type: string } + consoleUrl: { type: string, format: uri } + + PipelinePage: + type: object + properties: + items: + type: array + items: { $ref: '#/components/schemas/Pipeline' } + total: { type: integer } + limit: { type: integer } + offset: { type: integer } diff --git a/Plugins/Published Plugins/CriblDetect/CriblDetect_manifest.yaml b/Plugins/Published Plugins/CriblDetect/CriblDetect_manifest.yaml new file mode 100644 index 00000000..599fdced --- /dev/null +++ b/Plugins/Published Plugins/CriblDetect/CriblDetect_manifest.yaml @@ -0,0 +1,59 @@ +Descriptor: + Name: Cribl Detect + DisplayName: Cribl Detect + DescriptionDisplay: >- + Query Cribl Detect for detection rules, alerts, notable events, and ingest + health from inside Microsoft Security Copilot. + Description: |- + Use this plugin to interact with the Cribl Detect platform. The plugin is + read-only and lets Microsoft Security Copilot: + + - List and look up detection rules by id, severity, status, data source, or + MITRE ATT&CK technique. + - Query alerts and findings with filters for time window, severity, status, + assignee, source rule, and entity (host / user / ip / hash). + - Retrieve notable events (correlated incidents) with ownership, risk + score, and contributing alert ids. + - Inspect ingest data sources, worker groups, and routing pipelines to + confirm detection coverage and spot broken telemetry. + + Prefer narrow time windows (last 24 hours by default) and small page sizes + unless the user asks for more. Identifiers returned by one skill + (ruleId, alertId, notableId, sourceId) can be passed to any other skill in + this plugin. + + Published by Microsoft and Cribl. + Category: Other + Icon: https://cdn.cribl.io/dl/logos/cribl-logo-128.png + Settings: + - Name: CriblBaseUrl + Label: Cribl Base URL + Description: >- + Base URL of your Cribl deployment, without a trailing slash and without + /api/v1. For Cribl.Cloud this is + https://.main..cribl.cloud; for self-hosted Cribl use + the leader address, for example https://cribl.example.corp:9000. + HintText: https://default.main.example-org.cribl.cloud + SettingType: String + Required: true + - Name: CriblWorkerGroup + Label: Worker Group + Description: >- + Default Cribl worker group to query (e.g. "default" or + "default_search"). Used when a skill does not receive an explicit + workerGroup argument from the model. + HintText: default_search + SettingType: String + Required: false + SupportedAuthTypes: + - APIKey + Authorization: + Type: APIKey + Key: Authorization + Location: Header + AuthScheme: Bearer +SkillGroups: + - Format: API + Settings: + OpenApiSpecURL: https://raw.githubusercontent.com/Azure/Security-Copilot/main/Plugins/Published%20Plugins/CriblDetect/CriblDetect_OpenAPI.yaml + EndpointUrlSettingName: CriblBaseUrl diff --git a/Plugins/Published Plugins/CriblDetect/SamplePrompts.md b/Plugins/Published Plugins/CriblDetect/SamplePrompts.md new file mode 100644 index 00000000..ef656df3 --- /dev/null +++ b/Plugins/Published Plugins/CriblDetect/SamplePrompts.md @@ -0,0 +1,36 @@ +# Sample Copilot prompts for the Cribl Detect plugin + +These prompts are tuned to the skill descriptions in +`CriblDetect-Plugin.yaml`. Copy any of them into Microsoft Security +Copilot once the plugin is installed and the Cribl settings are filled +in. + +## Rule inventory & coverage + +- `Using Cribl Detect, list the detection rules mapped to MITRE T1078 (Valid Accounts) and tell me which are disabled.` +- `Which Cribl detections depend on firewall logs? Group by vendor and show rule severity.` +- `Show me every Cribl detection changed in the last 7 days — include who edited it and the current version number.` + +## Alert triage + +- `Give me a prioritized list of Cribl alerts from the last 24 hours: critical or high, status new, assigned to no one.` +- `Pull the Cribl alert with id alt_01HK3EXAMPLE and summarize the matched event, the rule that fired, and any correlated notable.` +- `Any Cribl alerts in the last 4 hours involving user alice@contoso.com or host web-prod-07?` + +## Notable / incident review + +- `List Cribl notables with risk score >= 70 from the past 48 hours and tell me who owns them.` +- `Open the notable not_01HK9EXAMPLE, show its timeline, and list every contributing alert id.` + +## Ingest health (coverage sanity checks) + +- `Are any Cribl data sources currently degraded or down? Include lastEventAt and dropped-events-in-last-hour.` +- `Which pipelines in the default_search worker group route Windows Security logs, and which detections depend on them?` +- `I'm asked why no Cribl alerts fired for lateral-movement last night — check if the authentication-log sources were healthy during that window.` + +## Cross-skill investigations (chaining) + +Copilot will chain multiple skills from a single prompt. Try: + +- `Investigate user alice@contoso.com: list Cribl alerts for her from the last 72 hours, open the highest-severity one, and tell me which detection rule fired and whether its source pipelines were healthy at the time.` +- `For every critical Cribl detection enabled today, confirm the ingest sources feeding it are healthy and report any gaps.` diff --git a/Plugins/Published Plugins/CriblDetect/readme.md b/Plugins/Published Plugins/CriblDetect/readme.md new file mode 100644 index 00000000..56907e7b --- /dev/null +++ b/Plugins/Published Plugins/CriblDetect/readme.md @@ -0,0 +1,164 @@ +# Cribl Detect + +The **Cribl Detect** plugin lets Microsoft Security Copilot read detection +rules, alerts, notable events, and ingest-pipeline health from a Cribl +deployment (Cribl.Cloud or self-hosted). It helps analysts enrich +investigations with detection context, confirm telemetry coverage, and +reason about data quality — all without leaving Copilot. + +Key insights the plugin exposes: + +- Detection rule inventory with severity, MITRE ATT&CK mapping, data-source + dependencies, and version history. +- Alerts and findings with time-window, severity, status, assignee, source + rule, and entity filters. +- Correlated notable events (incidents) with risk score, timeline, and + contributing alert ids. +- Ingest data sources and routing pipelines, including status, EPS, and + dropped-event counters. + +The plugin is read-only — none of its skills create, modify, or delete +Cribl resources. Learn more at . + +## Pre-requisites + +1. **Enable Cribl Detect** on your Cribl deployment. For Cribl.Cloud, + open the Cribl Cloud portal, select your organization, and confirm + that the Cribl Detect capability is enabled on at least one worker + group (for example `default_search`). Note the **Base URL** of your + deployment — it looks like `https://.main..cribl.cloud` + for Cribl.Cloud or `https://:9000` for self-hosted. + +2. **Create a Cribl API bearer token** for a dedicated service account. + The account must have read permission on **Detections**, **Alerts**, + **Notables**, **Sources**, and **Pipelines**. In Cribl.Cloud go to + **Settings → Access Management → Users** and generate an API key for + the service account. See + [Cribl API docs](https://docs.cribl.io/stream/api-tutorials/) for + details. + +3. **Enable the plugin in Microsoft Security Copilot**. In the Copilot + session, open the **Sources** panel (plug icon) and locate the + **Cribl Detect** plugin under custom plugins. Toggle it on. + +4. **Configure the plugin**. When Copilot shows the configuration + dialog, fill in: + - **Cribl Base URL** — e.g. `https://default.main.your-org.cribl.cloud` + (no trailing slash, no `/api/v1`). + - **Cribl API Bearer Token** — the token from step 2. The plugin + stores it encrypted (marked `IsSecret`) and never surfaces it to + the model. + - **Worker Group** _(optional)_ — defaults to `default_search`. + + Click **Save**. The plugin's skills now appear in the Copilot skill + palette under `Cribl Detect`. + +## Invoking the Plugin and Skills + +Once the plugin is enabled and configured, users can invoke Cribl Detect in +two ways: + +1. **Natural language** — type a question that references Cribl Detect in a + Copilot prompt. Copilot picks the right skill. Example: + `List enabled Cribl detections tagged with MITRE T1059.001 in the last 30 days.` +2. **Direct skill invocation** — type `/` in the prompt and pick the + skill explicitly, e.g. `/ListAlerts` or `/GetNotable`. + +## Skills & Prompts + +1. **ListDetections** — Enumerate detection rules; filter by severity, + enabled state, MITRE technique, data source, or free-text match. + - **Example Prompt(s):** + - `List enabled Cribl detections mapped to MITRE [T1078] and tell me which depend on firewall logs.` + - `Which Cribl detections changed in the last 7 days? Include who edited them.` + - **Inputs:** `severity`, `enabled`, `mitreTechnique`, `dataSource`, + `q` (free-text), `limit`, `offset`. + +2. **GetDetection** — Return the full definition of a single rule. + - **Example Prompt(s):** + - `Open Cribl detection [det_01HK3EXAMPLE] and summarize the logic, schedule, and MITRE mapping.` + - **Inputs:** `detectionId`. + +3. **ListAlerts** — Query alerts and findings produced by Cribl Detect rules. + Defaults to the last 24 hours when no time window is supplied. + - **Example Prompt(s):** + - `Pull the top 20 Cribl alerts from the last 24 hours — critical or high, status new, unassigned.` + - `Any Cribl alerts in the last 4 hours involving user [alice@contoso.com] or host [web-prod-07]?` + - **Inputs:** `startTime`, `endTime`, `severity`, `status`, `assignee`, + `ruleId`, `entity` (`type:value`), `limit`, `offset`. + +4. **GetAlert** — Full alert context: matched event, enrichments, risk, + linked notable. + - **Example Prompt(s):** + - `Open Cribl alert [alt_01HK3EXAMPLE] and summarize the matched event and the rule that fired.` + - **Inputs:** `alertId`. + +5. **ListNotables** — List correlated incidents, filter by risk score, status, + assignee, time window, and entity. + - **Example Prompt(s):** + - `List Cribl notables with risk score >= [70] from the past 48 hours and tell me who owns them.` + - **Inputs:** `startTime`, `endTime`, `severity`, `status`, `assignee`, + `minRiskScore`, `entity`, `limit`, `offset`. + +6. **GetNotable** — Notable timeline plus contributing alert ids and + investigation notes. + - **Example Prompt(s):** + - `Open Cribl notable [not_01HK9EXAMPLE], show its timeline and list every contributing alert id.` + - **Inputs:** `notableId`. + +7. **ListDataSources** — Confirm ingest coverage: source type, status, EPS, + pipeline. + - **Example Prompt(s):** + - `Are any Cribl data sources currently degraded or down? Include lastEventAt and dropped events.` + - **Inputs:** `type`, `status`, `limit`, `offset`. + +8. **GetDataSource** — Deep-dive on a single source (lastEventAt, + dropped events, backpressure). + - **Example Prompt(s):** + - `Show me the recent health of Cribl source [src_01HK...] — is it dropping events?` + - **Inputs:** `sourceId`. + +9. **ListPipelines** — Routing pipelines and the detections that depend + on them. + - **Example Prompt(s):** + - `Which pipelines in worker group [default_search] route Windows Security logs, and which detections depend on them?` + - **Inputs:** `limit`, `offset`. + +### Cross-skill investigations + +Copilot will chain skills from a single prompt. Try: + +- `Investigate user [alice@contoso.com]: list Cribl alerts for her from the last 72 hours, open the highest-severity one, and tell me which detection rule fired and whether its source pipelines were healthy at the time.` +- `For every critical Cribl detection enabled today, confirm the ingest sources feeding it are healthy and report any gaps.` + +## Frequently Asked Questions (FAQ) + +1. **I keep getting `401 Access denied` on every call.** + The bearer token is invalid, revoked, or belongs to a different + tenant. Reissue the token in Cribl **Access Management**, update the + **Cribl API Bearer Token** field in the plugin configuration, and + save. + +2. **Detections work but `/alerts` returns `403`.** + The service account is missing the Detect-reader role bundle. In + Cribl, grant the service account read permission on **Alerts**, + **Notables**, and **Detections**, then retry. + +3. **I get `404` on a specific source or detection id.** + The id belongs to a different worker group. Set the **Worker Group** + plugin setting to match (for example `default_search`), or ask the + skill to use that group explicitly. + +4. **Copilot replies "I can't query Cribl right now".** + The configured **Cribl Base URL** has a trailing slash or includes + `/api/v1`. Set it to the host only — e.g. + `https://default.main.your-org.cribl.cloud`. + +5. **Rate-limit (`429`) during large queries.** + Narrow the time window or ask for a smaller page size (`limit=25`). + The plugin surfaces the `Retry-After` header so Copilot can back off. + +6. **Important:** The plugin is **read-only**. It does not create, + modify, or delete Cribl resources. Use a dedicated service account + with the minimum read-only role bundle on the four resource families + above and rotate the token on your normal cadence.