Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

The Attack Graph had no route, and the catalog proxy never authenticated (#830)

Beenu Aroraba0c6429ce14
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a4d3b2e23..1a12343e9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -370,6 +370,34 @@ jobs:
run: |
python3 -m pip install --quiet pytest
python3 -m pytest tests/test_connector_types_generated.py -q
+ # The registry is also what the API image's *fallback* catalog is a copy
+ # of, and that copy had 26 entries against a registry of 84. It was
+ # served on every request — the proxy sent no credential, so the
+ # connectors service (default-deny) answered 401 and the fallback was
+ # never a fallback — and because `connector_type` is validated against
+ # it, the 58 connectors it had never heard of were rejected as "unknown".
+ #
+ # The copy is now generated rather than hand-refreshed, and this gate
+ # compares three independent readings of connector identity in both
+ # directions: what the source declares, what reaches the runtime
+ # registry, and what each `schema()` advertises. The third is the one
+ # nothing looked at — `list_connector_schemas()` walks the registry but
+ # takes each entry's id from the schema, so a class registered as
+ # `tenable_io` whose schema said `tenable` would be offered under a name
+ # `get_connector_class()` cannot resolve.
+ #
+ # Self-test first, on the same tree: it drops a connector, renames one,
+ # deletes the artefact, unhooks the consumer and empties every input,
+ # and requires each to be caught.
+ - name: Connector catalog fallback — self-test
+ # Same import closure as the connector docs gate below: the catalog is
+ # each connector's real schema(), read at runtime, so the gate needs
+ # what those modules import at module scope.
+ run: |
+ python -m pip install --quiet httpx pydantic structlog "cryptography>=46,<51"
+ python3 scripts/generate_connector_catalog_fallback.py --self-test
+ - name: Verify the bundled connector catalog matches the registry
+ run: python3 scripts/generate_connector_catalog_fallback.py --check
# The count says how many connectors exist; this says whether the name
# each one is registered under still reaches a normalization profile.
# The connectors service declares `crowdstrike` and `okta` while the
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 093a38a46..4b9c7c49a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -77,6 +77,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **`GET /api/v1/graph` exists.** The console's Attack Graph view has always
+ called it and always got a 404, while `/graph/neighbors/…` and
+ `/graph/mitre-coverage` returned 200 from the same Neo4j instance holding
+ real graph-at-ingest data — the data and the scoping were sound and only
+ the overview endpoint was missing.
+
+ It returns the caller's own entity graph in the shape the Cytoscape canvas
+ consumes, bounded to 400 nodes and 900 edges per render with `truncated`
+ set when the cut was applied. `depth` (1–6) bounds the walk; `entity`
+ narrows the seed set to one named host, user or indicator.
+
+ Scoping follows the rule the other graph reads had to learn the hard way:
+ **every node of every traversed path** must satisfy the tenant predicate,
+ not only the node the walk starts from, and `tenant_id IS NULL` is never
+ readable — an untagged node that were readable would bridge two tenants
+ through any entity they share. Edges are returned only between nodes that
+ first pass that filter, so an edge cannot reintroduce a node the node query
+ refused. Global MITRE labels stay exempt, but cannot seed a traversal.
+
+ Two failure modes are kept distinguishable. An empty graph is `200` with no
+ nodes; an unreachable graph is `503`. It deliberately does not degrade to an
+ empty graph the way `/graph/mitre-coverage` does, because "no attack
+ relationships exist in your estate" is a security claim, and making it on
+ evidence nobody retrieved is the shape of defect this codebase keeps
+ rediscovering. The console's error state — which names the endpoint and the
+ status rather than inventing topology — is unchanged, and a test now asserts
+ the view holds no graph at **first paint**, so a future `fallbackData` (which
+ disables revalidation, making a mock permanent rather than provisional)
+ fails the build.
+
- **Every test file in the tree is now executed by a workflow, and a gate
holds it that way in both directions.** 63 were executed by nothing at all:
56 of the 82 under `services/agents`, because that invocation was a
@@ -1537,6 +1567,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
+- **The connector catalog proxy never authenticated, and served a stale list
+ on every request because of it.** `_fetch_catalog()` issued a bare
+ `client.get(url)` with no `Authorization` header at a connectors service
+ that is default-deny on every route, so it was answered `401` on every
+ single call and fell through to the catalog bundled in the API image *every
+ time*. The bundle had **26 entries against a live registry of 84**. Nothing
+ failed: the wizard rendered a confidently wrong list, and because
+ `connector_type` is validated against that same list, the 58 connectors it
+ had never heard of were rejected as "unknown connector_type".
+
+ The proxy now presents the service credential and the tenant it is acting
+ for, mirroring the fusion gateway. Every call site passes the tenant
+ explicitly — it is a required parameter, not a defaulted one, because a
+ defaulted parameter is one call sites forget.
+
+ The fallback is kept, and given a stated job: **keep the console usable when
+ the connectors service is not deployed or not answering.** For that to be
+ defensible it has to be distinguishable from the real thing, so
+ `/connectors/catalog` now returns `source` (`live` / `bundled`), `degraded`
+ and `reason`. A deployment with no connectors service is `bundled` but not
+ degraded — there the bundle *is* the source of truth, and flagging it would
+ train operators to ignore the flag.
+
+ While degraded, an unrecognised `connector_type` returns **503 rather than
+ 422**: a connectors service rolled ahead of the API image legitimately knows
+ types that image does not, and "unknown connector_type" sends an operator to
+ debug a connector that is fine.
+
+- **The bundled catalog is generated, not refreshed by hand.**
+ `scripts/generate_connector_catalog_fallback.py` builds it from the
+ connector registry and `--check` fails the build on drift, so the artefact
+ cannot fall behind the registry it copies. The gate compares **three**
+ independent readings of connector identity, in both directions: what
+ `_CONNECTOR_CLASSES` declares (read through the AST by
+ `generate_connector_types.parse_registry`, so there is one definition of
+ "the registry" rather than two), what reaches `CONNECTOR_REGISTRY` at
+ runtime, and what each `cls.schema()` **advertises**.
+
+ The third is the reading nothing looked at. `list_connector_schemas()`
+ iterates the registry but takes each entry's `connector_id` from the schema,
+ so a class registered as `tenable_io` whose `schema()` said `tenable` would
+ be offered in the wizard under a name `get_connector_class()` cannot
+ resolve — 84 independent opportunities for two declarations to disagree.
+ Identity is read off the class, never the filename: `jira_connector.py`
+ declares `jira` and `tenable.py` declares `tenable_io`, and `--self-test`
+ asserts that property rather than trusting a comment. The self-test runs
+ before the gate in CI and injects nine defects — a dropped connector, a
+ renamed one, a class that never registers, a deleted artefact, an unhooked
+ consumer, an empty corpus — requiring each to be caught.
+
- **Two more gates were exempt from the empty-corpus rule only by accident.**
`check_route_auth.py` and `check_tenant_query_predicates.py` did not exit 0
over an empty tree, but neither had a corpus floor: each happened to fail
diff --git a/apps/docs/docs/api/rest.md b/apps/docs/docs/api/rest.md
index 34f0eee09..be7bf2216 100644
--- a/apps/docs/docs/api/rest.md
+++ b/apps/docs/docs/api/rest.md
@@ -131,6 +131,50 @@ Time-decayed risk scores per entity, computed by the fusion service.
| `GET` | `/entity-risk` | Top entities by risk score (descending) |
| `GET` | `/entity-risk/{entity}` | Risk detail for a specific entity |
+### Entity Graph
+
+The Neo4j entity graph written at ingest time. Every read is scoped to the
+calling tenant on **every node of every traversed path**, not only on the node
+the walk starts from, and a node carrying no `tenant_id` is not readable —
+otherwise any entity two tenants happen to share would bridge between them.
+Global MITRE reference labels (`Technique`, `Tactic`, `Mitigation`) are the
+narrow exemption, because they belong to no tenant.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/graph` | Tenant-level overview: nodes, edges, `generatedAt` |
+| `GET` | `/graph/neighbors/{entity_type}/{entity_id}` | Immediate neighbours of one entity |
+| `GET` | `/graph/blast-radius/{entity_type}/{entity_id}` | Entities reachable within N hops |
+| `GET` | `/graph/attack-path/{case_id}` | Case → alerts → hosts/users → IOCs → techniques |
+| `GET` | `/graph/incident-context/{alert_id}` | Identity, asset, cloud, business and threat context |
+| `GET` | `/graph/mitre-coverage` | Technique coverage aggregated from tenant alerts |
+
+`GET /graph` backs the console's Attack Graph view. Two query parameters:
+`depth` (1–6, default 3) bounds how far the traversal walks out from the
+tenant's own nodes, and `entity` narrows the seed set to one named host, user
+or indicator.
+
+One response is bounded to at most 400 nodes and 900 edges — past that a
+force-directed canvas is unreadable — and sets `truncated: true` when the cut
+was applied, so a partial picture is never mistaken for the whole estate.
+
+Its two failure modes are deliberately distinguishable:
+
+- **`200` with an empty `nodes` array** means the tenant genuinely has no
+ graph yet.
+- **`503`** means the graph backend could not be reached. This endpoint does
+ *not* degrade to an empty graph, because "no attack relationships exist in
+ your estate" is a security claim and making it on evidence nobody retrieved
+ is worse than saying nothing. The console surfaces the status and the path.
+
+:::note Shared infrastructure fails closed
+The ingest graph writer merges nodes on `natural_key` with `tenant_id` as a
+property, so a genuinely shared entity such as a public IP is last-writer-wins.
+The strict read filter therefore drops those nodes rather than showing them
+under the wrong tenant: safe, never leaking, at some cost in completeness.
+Re-keying on `(tenant_id, natural_key)` is the proper fix and needs a migration.
+:::
+
### Cases & Response
| Method | Path | Description |
diff --git a/apps/docs/docs/connectors/index.md b/apps/docs/docs/connectors/index.md
index fae3f3466..e0a0456ff 100644
--- a/apps/docs/docs/connectors/index.md
+++ b/apps/docs/docs/connectors/index.md
@@ -122,6 +122,36 @@ The catalog ships with **84 connectors** out of the box, registered in [`service
4. Click **Test connection**. The pre-save test is stateless — credentials are sent once over TLS, the target API is called, and **nothing is persisted** unless the test passes and you click **Save**.
5. On save, the credentials are encrypted in the vault, the instance is stored with `is_enabled=true`, and the scheduler picks it up on the next reload (within 30 seconds).
+### Where the catalog grid comes from
+
+The wizard's grid is `GET /api/v1/connectors/catalog`, which the API service
+proxies to `services/connectors` when `CONNECTORS_SERVICE_URL` is set. That is
+the live registry, so a connector added to the connectors service appears in
+the wizard with no API redeploy.
+
+The API image also bundles a copy of the catalog, and the response says which
+one you got:
+
+| Field | Meaning |
+|---|---|
+| `source` | `live` — the connectors service answered. `bundled` — the copy in the API image was used. |
+| `degraded` | `true` only when the connectors service was configured and could not be reached. A deployment with no connectors service at all is `bundled` but not degraded: there, the bundle *is* the source of truth. |
+| `reason` | Why the bundle was used, when it was. |
+
+The bundle exists so a single-tenant or demo deployment — and a deployment
+whose connectors service is briefly down — still renders the wizard. It is
+**generated** from the connector registry by
+`scripts/generate_connector_catalog_fallback.py` and verified by `--check` in
+CI, so it cannot fall behind the registry it copies. It previously was
+hand-refreshed, drifted to 26 entries against a registry of 84, and was served
+on every request because the proxy authenticated with nothing and the
+connectors service (default-deny) answered `401`.
+
+While `degraded` is true, saving a connector whose type the bundle does not
+list returns **503**, not 422. A connectors service rolled ahead of the API
+image legitimately knows types that image does not, and reporting "unknown
+connector_type" would send you to debug a connector that is fine.
+
## How polling works
Each enabled connector instance becomes one job in an in-process [`APScheduler`](https://apscheduler.readthedocs.io/) running inside `services/connectors`:
diff --git a/apps/web/src/components/graph/AttackGraphView.test.tsx b/apps/web/src/components/graph/AttackGraphView.test.tsx
new file mode 100644
index 000000000..38d6fa4f6
--- /dev/null
+++ b/apps/web/src/components/graph/AttackGraphView.test.tsx
@@ -0,0 +1,159 @@
+/**
+ * The Attack Graph must not invent a graph, and must say so when it cannot
+ * load one.
+ *
+ * `GET /api/v1/graph` did not exist — the console called it, got 404, and
+ * rendered its error state. The error state was the *correct* behaviour and
+ * the temptation on fixing the route is to soften it; these tests pin the two
+ * halves that make it correct.
+ *
+ * Asserted at **first paint**, not only on the error branch. SWR v2 disables
+ * `revalidateOnMount` whenever `fallbackData` is supplied, so a component
+ * handed a mock there may never fetch at all: the sample data is not a
+ * placeholder that a real response replaces, it is what the view shows for
+ * good. A test that only drives the error branch passes happily against a
+ * component that renders a fabricated graph forever and never errors,
+ * because the error never happens.
+ *
+ * The header's "Generated …" timestamp is the signal, because it renders if
+ * and only if `graphState.data` is already populated. Present on the very
+ * first render means data arrived without a fetch.
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { SWRConfig } from 'swr';
+
+const getOverview = vi.hoisted(() => vi.fn());
+const getMitreCoverage = vi.hoisted(() => vi.fn());
+const canUseDemoData = vi.hoisted(() => vi.fn());
+
+vi.mock('@/lib/api', () => ({
+ __esModule: true,
+ graphApi: { getOverview, getMitreCoverage },
+}));
+
+vi.mock('@/lib/demoFallback', () => ({
+ __esModule: true,
+ canUseDemoData,
+}));
+
+vi.mock('next/navigation', () => ({
+ __esModule: true,
+ useSearchParams: () => new URLSearchParams(''),
+}));
+
+// cytoscape renders onto a real canvas, which jsdom does not provide. The
+// stub keeps `GraphCanvas` mountable so "did the view decide it has a graph
+// to draw?" stays observable; node labels are painted, not DOM, so the
+// assertions below key on the surrounding chrome instead.
+vi.mock('cytoscape', () => {
+ const cy = () => ({ on: vi.fn(), destroy: vi.fn() });
+ cy.use = vi.fn();
+ return { __esModule: true, default: cy };
+});
+vi.mock('cytoscape-fcose', () => ({ __esModule: true, default: {} }));
+
+import { AttackGraphView } from './AttackGraphView';
+
+/** The message shape `request()` throws: status and path, never a guess. */
+class ApiError extends Error {
+ constructor(
+ message: string,
+ public status: number,
+ ) {
+ super(message);
+ this.name = 'ApiError';
+ }
+}
+
+function renderView() {
+ return render(
+ <SWRConfig value={{ provider: () => new Map(), dedupingInterval: 0 }}>
+ <AttackGraphView />
+ </SWRConfig>,
+ );
+}
+
+const GENERATED = /Generated /;
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ canUseDemoData.mockReturnValue(false);
+ getMitreCoverage.mockResolvedValue({ tactics: [], cells: [], generatedAt: '' });
+});
+
+afterEach(cleanup);
+
+describe('AttackGraphView, demo mode off', () => {
+ it('holds no graph at first paint — it has not fetched one yet', () => {
+ getOverview.mockImplementation(() => new Promise(() => {}));
+ renderView();
+ // If `fallbackData` were ever supplied, `graphState.data` would be
+ // populated on the first render and this timestamp would be present.
+ expect(screen.queryByText(GENERATED)).toBeNull();
+ });
+
+ it('names the endpoint and the status rather than inventing a graph', async () => {
+ getOverview.mockRejectedValue(
+ new ApiError('API 503 Service Unavailable — /api/v1/graph', 503),
+ );
+ renderView();
+
+ expect(screen.queryByText(GENERATED)).toBeNull();
+
+ await waitFor(() => {
+ expect(screen.getByText("Couldn't load graph")).toBeInTheDocument();
+ });
+ expect(
+ screen.getByText('API 503 Service Unavailable — /api/v1/graph'),
+ ).toBeInTheDocument();
+ // Still nothing fabricated standing in for the estate.
+ expect(screen.queryByText(GENERATED)).toBeNull();
+ });
+
+ it('reads a tenant with no graph as empty, not as broken', async () => {
+ getOverview.mockResolvedValue({
+ nodes: [],
+ edges: [],
+ generatedAt: '2026-09-24T12:00:00Z',
+ });
+ renderView();
+
+ await waitFor(() => {
+ expect(screen.getByText('No graph yet')).toBeInTheDocument();
+ });
+ expect(screen.queryByText("Couldn't load graph")).toBeNull();
+ });
+
+ it('draws the graph the backend returned', async () => {
+ getOverview.mockResolvedValue({
+ nodes: [{ id: 'host:WIN-DB01', label: 'WIN-DB01', kind: 'host', riskScore: 92 }],
+ edges: [],
+ generatedAt: '2026-09-24T12:00:00Z',
+ });
+ renderView();
+
+ await waitFor(() => {
+ expect(screen.queryByText('No graph yet')).toBeNull();
+ });
+ expect(screen.queryByText("Couldn't load graph")).toBeNull();
+ expect(getOverview).toHaveBeenCalledWith({ depth: 3 });
+ });
+});
+
+describe('AttackGraphView, hosted demo', () => {
+ it('substitutes sample topology only when demo mode allows it', async () => {
+ // The same failure as the second test above, with the gate open. If this
+ // rendered the error state too, the gate would be dead code; if the test
+ // above rendered a graph, the gate would not be a gate.
+ canUseDemoData.mockReturnValue(true);
+ getOverview.mockRejectedValue(new ApiError('API 503 — /api/v1/graph', 503));
+ renderView();
+
+ await waitFor(() => {
+ expect(screen.queryByText(GENERATED)).not.toBeNull();
+ });
+ expect(screen.queryByText("Couldn't load graph")).toBeNull();
+ });
+});
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index cc973a847..c0ce21211 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -3957,6 +3957,63 @@ paths:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
+ /api/v1/graph:
+ get:
+ tags:
+ - graph
+ summary: Tenant-level entity graph for the Attack Graph console
+ description: "The caller's own entity graph, bounded for one canvas render.\n\
+ \nScoping is the whole of this endpoint's security surface. Every node of\n\
+ every traversed path must satisfy the tenant predicate — not just the\nnode\
+ \ the walk started from — and a node with no ``tenant_id`` is not\nreadable,\
+ \ because an untagged node that *were* readable would bridge two\ntenants\
+ \ through any entity they happen to share. The narrow exemption is\nthe global\
+ \ MITRE labels, which belong to no tenant by design.\n\nTwo failure modes\
+ \ that must not look alike:\n\n``empty``\n 200 with no nodes. The tenant\
+ \ really has no graph yet — nothing has\n been ingested, or nothing ingested\
+ \ produced entities. The console\n renders its empty state.\n``unavailable``\n\
+ \ 503. The graph backend could not be reached, so we do not know what\n\
+ \ the tenant has. This deliberately does *not* degrade to an empty\n \
+ \ graph the way ``/graph/mitre-coverage`` does: an empty attack graph\n \
+ \ reads as \"no attack relationships exist in your estate\", which is a\n\
+ \ security claim, and making it on evidence we never retrieved is the\n\
+ \ failure this codebase keeps finding. The console's error state names\n\
+ \ the endpoint and the status, which is the honest answer."
+ operationId: get_graph_overview_api_v1_graph_get
+ security:
+ - HTTPBearer: []
+ parameters:
+ - name: depth
+ in: query
+ required: false
+ schema:
+ type: integer
+ maximum: 6
+ minimum: 1
+ default: 3
+ title: Depth
+ - name: entity
+ in: query
+ required: false
+ schema:
+ anyOf:
+ - type: string
+ maxLength: 256
+ - type: 'null'
+ title: Entity
+ responses:
+ '200':
+ description: Successful Response
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/GraphOverviewResponse'
+ '422':
+ description: Validation Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/HTTPValidationError'
/api/v1/graph/attack-path/{case_id}:
get:
tags:
@@ -20502,6 +20559,41 @@ components:
- id
- label
title: GraphNode
+ GraphOverviewResponse:
+ properties:
+ nodes:
+ items:
+ $ref: '#/components/schemas/OverviewNode'
+ type: array
+ title: Nodes
+ edges:
+ items:
+ $ref: '#/components/schemas/OverviewEdge'
+ type: array
+ title: Edges
+ generatedAt:
+ type: string
+ title: Generatedat
+ truncated:
+ type: boolean
+ title: Truncated
+ default: false
+ type: object
+ required:
+ - nodes
+ - edges
+ - generatedAt
+ title: GraphOverviewResponse
+ description: 'The tenant''s entity graph, bounded for one canvas render.
+
+
+ ``truncated`` is part of the contract rather than a diagnostic. A graph
+
+ cut at the node ceiling and a graph that is genuinely this size render
+
+ identically, and a viewer who cannot tell them apart reads a partial
+
+ picture as the whole estate.'
HTTPValidationError:
properties:
detail:
@@ -23440,6 +23532,62 @@ components:
- benign_corrections
- escalate_corrections
title: OverrideSummaryResponse
+ OverviewEdge:
+ properties:
+ id:
+ type: string
+ title: Id
+ source:
+ type: string
+ title: Source
+ target:
+ type: string
+ title: Target
+ label:
+ type: string
+ title: Label
+ attributes:
+ additionalProperties: true
+ type: object
+ title: Attributes
+ type: object
+ required:
+ - id
+ - source
+ - target
+ - label
+ title: OverviewEdge
+ OverviewNode:
+ properties:
+ id:
+ type: string
+ title: Id
+ label:
+ type: string
+ title: Label
+ kind:
+ type: string
+ title: Kind
+ riskScore:
+ anyOf:
+ - type: number
+ - type: 'null'
+ title: Riskscore
+ severity:
+ anyOf:
+ - type: string
+ - type: 'null'
+ title: Severity
+ attributes:
+ additionalProperties: true
+ type: object
+ title: Attributes
+ type: object
+ required:
+ - id
+ - label
+ - kind
+ title: OverviewNode
PackAssignmentCreate:
properties:
child_tenant_id:
diff --git a/scripts/competitor_names.toml b/scripts/competitor_names.toml
index cb1dea6d7..ba2949953 100644
--- a/scripts/competitor_names.toml
+++ b/scripts/competitor_names.toml
@@ -135,6 +135,11 @@ paths = ["packages/types/src/generated/connector-types.ts", "packages/types/src/
names = ["Torq", "Tines", "Wazuh"]
reason = "The console's connector_type vocabulary, generated from the connector registry by scripts/generate_connector_types.py. Each name here is a connector id the platform ingests under; removing one would make the type reject events from a connector that ships."
+[[allow]]
+paths = ["services/api/app/data/connector_catalog_fallback.json"]
+names = ["Torq", "Tines", "Wazuh"]
+reason = "The connector catalog bundled into the API image, generated from the connector registry by scripts/generate_connector_catalog_fallback.py. It is each connector's own schema() verbatim — the vendor name, the field labels and the setup help text the wizard renders — so these are the same first-party integration references the connector modules carry. This file previously held a hand-refreshed 26-connector subset that happened to exclude them."
+
[[allow]]
paths = ["apps/docs/sidebars.ts"]
names = ["Torq", "Tines", "Wazuh"]
diff --git a/scripts/generate_connector_catalog_fallback.py b/scripts/generate_connector_catalog_fallback.py
new file mode 100644
index 000000000..fe967ba38
--- /dev/null
+++ b/scripts/generate_connector_catalog_fallback.py
@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""Generate the connector catalog the API image falls back to.
+
+Why this exists
+---------------
+``services/api`` proxies ``GET /api/v1/connectors/catalog`` to the connectors
+service and keeps a copy of the catalog bundled in its own image for when that
+service is not deployed or not answering. The proxy sent no credential, so the
+connectors service — default-deny on every route — answered 401 every time and
+the proxy fell through to the bundle on *every single request*. The bundle had
+26 entries. The registry had 84.
+
+Nothing failed. The wizard rendered a confident list of connectors that was
+missing 58 of them, and because the API also validates ``connector_type``
+against that list, the 58 it had never heard of were rejected with 422 as
+"unknown connector_type" — the type existed, the copy of the list did not
+know about it.
+
+The authentication is fixed in the proxy. This exists so the second half
+cannot come back: the bundle is now *generated* from the registry rather than
+refreshed by hand, and ``--check`` fails the build when the committed artefact
+is not what generation produces. A hand-refresh is a step somebody has to
+remember, and the evidence that nobody remembered is the 58.
+
+What it credits as correct
+--------------------------
+The question worth asking about a gate is not what it flags but what it lets
+through. This one compares **three independent readings of connector
+identity**, in both directions, because two of them are separate declarations
+that can silently disagree:
+
+``declared``
+ ``_CONNECTOR_CLASSES`` in ``services/connectors/app/connectors/__init__.py``
+ resolved to each class's ``connector_id``, read through the AST by
+ ``generate_connector_types.parse_registry``. Imported from there rather
+ than re-implemented: two scanners drift the first time either learns
+ something the other has not.
+``registered``
+ ``CONNECTOR_REGISTRY`` keys at runtime. Differs from ``declared`` if a
+ connector module fails to import, or if registration is skipped.
+``advertised``
+ The ``connector_id`` field of each catalog entry — which comes from
+ ``cls.schema()``, **not** from the registry key. That is the blind spot.
+ ``list_connector_schemas()`` iterates the registry but takes each entry's
+ identity from the schema, so a class registered as ``tenable_io`` whose
+ ``schema()`` says ``tenable`` would be advertised under a name the service
+ cannot resolve: the wizard offers it, the operator picks it, and
+ ``get_connector_class()`` returns None. No check in this tree looked at
+ that, and the two are 84 independent opportunities to disagree.
+
+Identity is read off the class, never the filename. ``jira_connector.py``
+declares ``jira`` and ``tenable.py`` declares ``tenable_io``, so a filename
+slug would misname both — the defect that had
+``scripts/generate_connector_docs.py`` emitting duplicate pages while its
+coverage gate reported 100%. ``--self-test`` asserts that property holds
+rather than trusting the comment.
+
+Nothing here is positional
+--------------------------
+Entries are sorted by ``connector_id``, so reordering ``_CONNECTOR_CLASSES``
+cannot change a byte of the output and no lock file is needed. (Contrast
+``generate_detections.py``, which assigned ids by position and therefore did.)
+
+Usage
+-----
+ python3 scripts/generate_connector_catalog_fallback.py # write
+ python3 scripts/generate_connector_catalog_fallback.py --check # gate
+ python3 scripts/generate_connector_catalog_fallback.py --json
+ python3 scripts/generate_connector_catalog_fallback.py --self-test
+
+``--repo-root`` overrides the tree under inspection. The resolved root comes
+from ``git rev-parse``, every file read is printed before the verdict, and an
+empty read is a hard error rather than a quiet zero: a bundle generated from a
+registry nobody opened is the failure this replaces, one level up.
+
+Exit codes: 0 clean, 1 findings, 2 the scan itself could not run.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+# `scripts/` is on sys.path when this file is run as a program, but not when a
+# test loads it by path with importlib. Its siblings sit beside it either way.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from gate_toolkit import repo_root, self_test_main # noqa: E402
+from generate_connector_types import GateError, parse_registry # noqa: E402
+
+CONNECTORS_REL = Path("services/connectors")
+REGISTRY_REL = Path("services/connectors/app/connectors/__init__.py")
+OUT_REL = Path("services/api/app/data/connector_catalog_fallback.json")
+CONSUMER_REL = Path("services/api/app/api/v1/endpoints/connectors.py")
+
+
+def load_runtime_catalog(root: Path) -> tuple[list[dict[str, Any]], set[str]]:
+ """``(catalog entries, registry keys)`` from the connectors package.
+
+ The directory is checked before the import is attempted, on purpose. In a
+ tree with no ``services/`` the refusal must be "the corpus is not here",
+ not ``ModuleNotFoundError``, so that a genuinely missing third-party
+ dependency stays distinguishable from an empty tree.
+ """
+ package_root = root / CONNECTORS_REL
+ if not (root / REGISTRY_REL).exists():
+ raise GateError(f"expected input does not exist: {root / REGISTRY_REL}")
+
+ sys.path.insert(0, str(package_root))
+ try:
+ from app.connectors import CONNECTOR_REGISTRY, list_connector_schemas
+ except ImportError as exc:
+ raise GateError(
+ f"could not import the connector registry from {package_root}: {exc}. "
+ "The gate reads every connector's schema() at runtime, so it needs what those "
+ "modules import at module scope (httpx, pydantic, structlog, cryptography)."
+ ) from exc
+
+ entries = list_connector_schemas()
+ registered = set(CONNECTOR_REGISTRY)
+ if not entries:
+ raise GateError("the connector registry produced zero schemas — refusing to generate from an empty read")
+ if not registered:
+ raise GateError("CONNECTOR_REGISTRY is empty — refusing to generate from an empty read")
+ return entries, registered
+
+
+def render(entries: list[dict[str, Any]]) -> str:
+ """The canonical on-disk form: sorted by id, stable key order, one file."""
+ ordered = sorted(entries, key=lambda e: str(e.get("connector_id", "")))
+ return json.dumps(ordered, indent=2, sort_keys=True) + "\n"
+
+
+def evaluate(
+ declared: set[str],
+ registered: set[str],
+ entries: list[dict[str, Any]],
+ on_disk: str | None,
+ consumer: str | None,
+) -> list[tuple[str, str]]:
+ """Every finding, each named by a code the self-test can require."""
+ failures: list[tuple[str, str]] = []
+ advertised = {str(e.get("connector_id", "")) for e in entries if e.get("connector_id")}
+
+ # An empty set here would make every comparison below vacuously clean.
+ for name, values in (("declared", declared), ("registered", registered), ("advertised", advertised)):
+ if not values:
+ failures.append(("empty-corpus", f"the {name} connector-id set is empty; every comparison below would pass vacuously"))
+ if failures:
+ return failures
+
+ # Both directions for each pair. The dominant failure shape in this tree
+ # is a gate that compares A against B and never B against A, so drift in
+ # the direction things actually change slips through while it prints OK.
+ pairs = (
+ ("declared", declared, "registered", registered),
+ ("registered", registered, "advertised", advertised),
+ )
+ for left_name, left, right_name, right in pairs:
+ for missing in sorted(left - right):
+ failures.append(
+ (
+ f"{right_name}-missing",
+ f"{missing!r} is {left_name} but not {right_name}"
+ + (
+ "; the wizard cannot offer a connector the build ships"
+ if right_name == "advertised"
+ else "; the class does not reach the registry"
+ ),
+ )
+ )
+ for extra in sorted(right - left):
+ failures.append(
+ (
+ f"{right_name}-unknown",
+ f"{extra!r} is {right_name} but not {left_name}"
+ + (
+ "; the wizard would offer a type get_connector_class() cannot resolve"
+ if right_name == "advertised"
+ else "; the registry holds a class the source does not declare"
+ ),
+ )
+ )
+
+ expected = render(entries)
+ if on_disk is None:
+ failures.append(("output-missing", f"{OUT_REL} does not exist; run the generator"))
+ elif on_disk != expected:
+ failures.append(
+ (
+ "output-drifted",
+ f"{OUT_REL} is not what generation produces; run the generator and commit the result",
+ )
+ )
+
+ # A generated artefact nobody reads is current and useless. This is the
+ # same rule generate_connector_types.py applies to its consumer.
+ if consumer is None:
+ failures.append(("consumer-missing", f"{CONSUMER_REL} does not exist"))
+ elif OUT_REL.name not in consumer:
+ failures.append(
+ (
+ "consumer-not-reading",
+ f"{CONSUMER_REL} no longer names {OUT_REL.name}; the generated catalog would sit in the tree unread",
+ )
+ )
+ return failures
+
+
+def load(root: Path) -> dict[str, Any]:
+ entries, registered = load_runtime_catalog(root)
+ return {
+ "declared": set(parse_registry(root)),
+ "registered": registered,
+ "entries": entries,
+ }
+
+
+def _read(path: Path) -> str | None:
+ return path.read_text(encoding="utf-8") if path.exists() else None
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--repo-root", type=Path, default=repo_root())
+ parser.add_argument("--check", action="store_true", help="fail (exit 1) on drift instead of rewriting the output")
+ parser.add_argument("--json", action="store_true")
+ parser.add_argument("--self-test", action="store_true", help="prove the gate detects injected drift in each direction")
+ args = parser.parse_args(argv)
+
+ root = args.repo_root.resolve()
+ if args.self_test:
+ return self_test(root)
+
+ try:
+ inputs = load(root)
+ except GateError as exc:
+ print(f"generate_connector_catalog_fallback: FAILED to read the tree: {exc}", file=sys.stderr)
+ return 2
+
+ out_path = root / OUT_REL
+ # Written only after the read is known to be non-empty, so a broken read
+ # can never overwrite a good artefact with nothing.
+ if not args.check:
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+ out_path.write_text(render(inputs["entries"]), encoding="utf-8")
+
+ failures = evaluate(
+ inputs["declared"],
+ inputs["registered"],
+ inputs["entries"],
+ _read(out_path),
+ _read(root / CONSUMER_REL),
+ )
+
+ if args.json:
+ print(
+ json.dumps(
+ {
+ "repo_root": str(root),
+ "declared": sorted(inputs["declared"]),
+ "registered": sorted(inputs["registered"]),
+ "advertised": sorted(str(e.get("connector_id", "")) for e in inputs["entries"]),
+ "failures": [{"code": c, "detail": d} for c, d in failures],
+ },
+ indent=2,
+ sort_keys=True,
+ )
+ )
+ return 1 if failures else 0
+
+ print(f"repo root {root}")
+ print(f"registry {REGISTRY_REL} ({len(inputs['declared'])} declared connector ids)")
+ print(f"runtime app.connectors from {CONNECTORS_REL} ({len(inputs['registered'])} registered)")
+ print(f"output {OUT_REL} ({len(inputs['entries'])} catalog entries)")
+ print(f"consumer {CONSUMER_REL}")
+ print()
+ print(
+ f"identity declared {len(inputs['declared'])} = registered {len(inputs['registered'])} = advertised "
+ f"{len({str(e.get('connector_id', '')) for e in inputs['entries']})}, compared in both directions"
+ )
+ print()
+
+ if failures:
+ print(f"FAIL — {len(failures)} finding(s):")
+ for code, detail in failures:
+ print(f" [{code}] {detail}")
+ return 1
+ print("OK — the bundled catalog is what the connector registry generates, and every")
+ print(" connector_id it advertises is one the connectors service can resolve.")
+ return 0
+
+
+# --------------------------------------------------------------------------
+# Self-test
+# --------------------------------------------------------------------------
+def self_test(root: Path) -> int:
+ """Inject drift in each direction and require the gate to catch each one."""
+ try:
+ inputs = load(root)
+ except GateError as exc:
+ print(f"self-test: cannot read the tree: {exc}", file=sys.stderr)
+ return 2
+
+ declared: set[str] = inputs["declared"]
+ registered: set[str] = inputs["registered"]
+ entries: list[dict[str, Any]] = inputs["entries"]
+ good = render(entries)
+ consumer = _read(root / CONSUMER_REL) or ""
+
+ clean = evaluate(declared, registered, entries, good, consumer)
+ if clean:
+ print("self-test: the unmodified tree already fails; fix that first", file=sys.stderr)
+ for code, detail in clean:
+ print(f" [{code}] {detail}", file=sys.stderr)
+ return 1
+
+ a_connector = sorted(declared)[0]
+ dropped = [e for e in entries if e.get("connector_id") != a_connector]
+ renamed = [dict(e, connector_id="not_a_registered_id") if e.get("connector_id") == a_connector else e for e in entries]
+
+ cases: list[tuple[str, str, tuple]] = [
+ (
+ "the bundled catalog is short a connector the registry ships (the 26-vs-84 defect)",
+ "advertised-missing",
+ (declared, registered, dropped, render(dropped), consumer),
+ ),
+ (
+ "the bundled catalog offers a type the registry does not declare",
+ "advertised-unknown",
+ (declared, registered, renamed, render(renamed), consumer),
+ ),
+ (
+ "a class declares one connector_id and its schema() advertises another",
+ "advertised-unknown",
+ (declared, registered, renamed, render(renamed), consumer),
+ ),
+ (
+ "a declared class never reaches the runtime registry",
+ "registered-missing",
+ (declared, registered - {a_connector}, entries, good, consumer),
+ ),
+ (
+ "the registry holds a class the source does not declare",
+ "registered-unknown",
+ (declared - {a_connector}, registered, entries, good, consumer),
+ ),
+ (
+ "a hand edit changes the committed artefact",
+ "output-drifted",
+ (declared, registered, entries, good.replace('"category"', '"catagory"', 1), consumer),
+ ),
+ (
+ "the committed artefact is deleted",
+ "output-missing",
+ (declared, registered, entries, None, consumer),
+ ),
+ (
+ "the API stops reading the generated catalog",
+ "consumer-not-reading",
+ (declared, registered, entries, good, consumer.replace(OUT_REL.name, "some_other_file.json")),
+ ),
+ (
+ "every input is empty, so each comparison would pass vacuously",
+ "empty-corpus",
+ (set(), set(), [], "[]\n", consumer),
+ ),
+ ]
+
+ print(f"self-test against {root}")
+ print(f"clean tree: {len(entries)} catalog entries, 0 failures (the baseline every case below perturbs)")
+ print(f" a declared id is {a_connector!r}\n")
+ extra: list[tuple[str, bool]] = []
+ for description, expected, call in cases:
+ codes = {code for code, _ in evaluate(*call)}
+ caught = expected in codes
+ extra.append((f"{description} [{expected}]", caught))
+
+ # Identity must come off the class: two connectors in this tree are
+ # registered under an id their filename does not spell, so a filename slug
+ # would misname them and every comparison above would be against the wrong
+ # names. Asserted, not commented.
+ registry = parse_registry(root)
+ mismatched = sorted(cid for cid, info in registry.items() if info["module"][:-3] != cid)
+ extra.append(
+ (
+ f"IDENTITY: connector_id comes from the class, not the filename "
+ f"({len(mismatched)} would be misnamed by a filename slug: {', '.join(mismatched) or 'none'})",
+ bool(mismatched),
+ )
+ )
+
+ # Every advertised id must resolve through the same lookup the connectors
+ # service uses when the wizard posts the type back.
+ sys.path.insert(0, str(root / CONNECTORS_REL))
+ from app.connectors import get_connector_class
+
+ unresolvable = sorted(cid for cid in {str(e.get("connector_id", "")) for e in entries} if get_connector_class(cid) is None)
+ extra.append(
+ (
+ f"RESOLVABLE: every advertised connector_id resolves through get_connector_class() "
+ f"({len(unresolvable)} unresolvable: {', '.join(unresolvable) or 'none'})",
+ not unresolvable,
+ )
+ )
+
+ return self_test_main(Path(__file__).name, ["--check"], extra=extra)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/services/api/app/api/v1/endpoints/agents.py b/services/api/app/api/v1/endpoints/agents.py
index 8df84b970..d50d8135d 100644
--- a/services/api/app/api/v1/endpoints/agents.py
+++ b/services/api/app/api/v1/endpoints/agents.py
@@ -261,9 +261,9 @@ async def list_agent_tools(
# 2. Catalog lookup, once. We index by connector_id (the catalog's
# notion of "type slug", not a UUID) so we can answer per-instance
# questions without N round-trips to the connectors service.
- catalog = await _fetch_catalog()
+ catalog = await _fetch_catalog(current_user.tenant_id)
catalog_by_type: dict[str, dict[str, Any]] = {
- entry["connector_id"]: entry for entry in catalog if isinstance(entry, dict) and isinstance(entry.get("connector_id"), str)
+ entry["connector_id"]: entry for entry in catalog.entries if isinstance(entry, dict) and isinstance(entry.get("connector_id"), str)
}
tools: list[AgentToolDescriptor] = []
diff --git a/services/api/app/api/v1/endpoints/connectors.py b/services/api/app/api/v1/endpoints/connectors.py
index 32612faa2..75eaf02b2 100644
--- a/services/api/app/api/v1/endpoints/connectors.py
+++ b/services/api/app/api/v1/endpoints/connectors.py
@@ -35,8 +35,10 @@ from __future__ import annotations
import json
import logging
+import os
import re
import uuid
+from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Annotated, Any
@@ -319,15 +321,85 @@ def _connectors_service_url(path: str) -> str:
return f"{base}/api/v1{suffix}"
-# Fallback catalog shipped with the API image. Generated from the connectors
-# microservice's registry and committed alongside the API source. Used when
-# the connectors microservice is not deployed (single-tenant / demo) or
-# temporarily unreachable so the AddConnector wizard still renders. Refresh:
-#
-# cd services/connectors && python -c "import json; \\
-# from app.connectors import list_connector_schemas as l; \\
-# print(json.dumps(l(), indent=2))" \\
-# > ../api/app/data/connector_catalog_fallback.json
+# Header the connectors service reads to learn which tenant a trusted service
+# is acting for. Must match ``TENANT_HEADER`` in
+# services/connectors/app/security/tenant_scope.py.
+_TENANT_HEADER = "X-AiSOC-Tenant-ID"
+
+
+def _service_token() -> str:
+ """The shared secret this service presents to the connectors service."""
+ specific = (os.getenv("AISOC_CONNECTORS_SERVICE_TOKEN") or "").strip()
+ return specific or (os.getenv("AISOC_SERVICE_TOKEN") or "").strip()
+
+
+def _catalog_headers(tenant_id: uuid.UUID | str | None) -> dict[str, str]:
+ """Credential + tenant assertion for a proxied connectors-service call.
+
+ Every route on the connectors service sits behind
+ ``require_console_or_service_auth``: a bearer credential is mandatory, and
+ a *service* token must additionally declare the tenant it acts for,
+ because an absent scope there is an empty scope rather than every scope.
+ This proxy sent neither, so it was answered with 401 on every single call
+ and fell through to the bundled catalog every time — which is how a
+ 26-entry list stood in for an 84-connector registry while every check
+ passed. Mirrors ``_upstream_headers`` in the fusion gateway.
+ """
+ headers: dict[str, str] = {}
+ token = _service_token()
+ if token:
+ headers["Authorization"] = f"Bearer {token}"
+ if tenant_id is not None:
+ headers[_TENANT_HEADER] = str(tenant_id)
+ return headers
+
+
+#: Where a catalog came from. The distinction is load-bearing: see
+#: :class:`CatalogResult`.
+CATALOG_LIVE = "live"
+CATALOG_BUNDLED = "bundled"
+
+
+@dataclass(frozen=True)
+class CatalogResult:
+ """A connector catalog and an honest account of where it came from.
+
+ The bundled catalog exists for exactly one situation: **the connectors
+ service is not deployed, or is not answering, and the console still has
+ to render the AddConnector wizard.** That is worth having. What is not
+ worth having is a fallback that cannot be told apart from the live
+ registry, because then a wrong catalog is served with the same confidence
+ as a right one — and this one was wrong, by 58 connectors, for as long as
+ nobody happened to compare the two by hand.
+
+ So provenance travels with the payload:
+
+ ``source``
+ ``live`` when the connectors service answered, ``bundled`` when the
+ catalog came out of the image.
+ ``degraded``
+ True only when we *wanted* live and could not get it. A deployment
+ with no connectors service at all is ``bundled`` but not degraded —
+ the bundle is that deployment's source of truth, and flagging it
+ would train operators to ignore the flag.
+ ``reason``
+ Why, in one token, for the log line and the API response.
+
+ ``degraded`` is what stops :func:`_validate_connector_type` from claiming
+ a connector type is unknown when it simply could not look it up.
+ """
+
+ entries: list[dict[str, Any]]
+ source: str
+ degraded: bool = False
+ reason: str = ""
+
+
+# Catalog bundled into the API image, generated from the connectors registry
+# by `scripts/generate_connector_catalog_fallback.py` and kept in sync by
+# `--check` in CI. Generated rather than hand-refreshed because a hand-refresh
+# is a step someone has to remember: this file sat 58 connectors behind the
+# registry it is a copy of, and nothing failed.
_FALLBACK_CATALOG_PATH = Path(__file__).resolve().parents[3] / "data" / "connector_catalog_fallback.json"
@@ -346,35 +418,51 @@ def _load_fallback_catalog() -> list[dict[str, Any]]:
return data if isinstance(data, list) else []
-async def _fetch_catalog() -> list[dict[str, Any]]:
- """Pull the connector catalog from the connectors microservice, with fallback.
+async def _fetch_catalog(tenant_id: uuid.UUID | str | None) -> CatalogResult:
+ """Pull the connector catalog from the connectors service, with fallback.
+
+ ``tenant_id`` is the tenant this call is being made on behalf of, and is
+ required rather than defaulted: the connectors service will refuse a
+ service token that does not declare one, and a parameter that defaults to
+ ``None`` is a parameter call sites forget. Pass ``None`` explicitly for
+ the few callers that genuinely act outside a tenant.
Resolution order:
- 1. If ``CONNECTORS_SERVICE_URL`` is set and reachable, use it (live source
- of truth — supports newly-added connectors without an API redeploy).
- 2. Otherwise, fall back to the catalog bundled with the API image. This
- is what keeps demo / single-tenant deploys functional even when the
- dedicated connectors microservice is not deployed.
+ 1. ``CONNECTORS_SERVICE_URL`` set and answering — the live registry, so
+ a newly added connector works without an API redeploy.
+ 2. The catalog bundled in the image, tagged with why it was used.
"""
base_url = (getattr(settings, "CONNECTORS_SERVICE_URL", "") or "").strip()
if not base_url:
- logger.info("connectors_service.catalog.using_fallback reason=no_url_configured")
- return _load_fallback_catalog()
+ # Not degraded: no connectors service is deployed, so the bundle is
+ # this deployment's source of truth rather than a stand-in for one.
+ logger.info("connectors_service.catalog.using_bundled reason=no_url_configured")
+ return CatalogResult(entries=_load_fallback_catalog(), source=CATALOG_BUNDLED, reason="no_url_configured")
url = _connectors_service_url("/connectors/schemas")
try:
async with httpx.AsyncClient(timeout=_CATALOG_TIMEOUT) as client:
- resp = await client.get(url)
+ resp = await client.get(url, headers=_catalog_headers(tenant_id))
resp.raise_for_status()
except httpx.HTTPError as exc:
+ # Logged at warning with the status when there was one: a 401 here
+ # means this proxy's credential is wrong, which is a configuration
+ # fault that previously presented as "the service is down".
+ upstream_status = getattr(getattr(exc, "response", None), "status_code", None)
logger.warning(
- "connectors_service.catalog.unreachable url=%s error_type=%s falling_back=true",
- url,
+ "connectors_service.catalog.unreachable url=%s error_type=%s status=%s falling_back=true",
+ _safe_log_val(url),
type(exc).__name__,
+ upstream_status,
)
fallback = _load_fallback_catalog()
if fallback:
- return fallback
+ return CatalogResult(
+ entries=fallback,
+ source=CATALOG_BUNDLED,
+ degraded=True,
+ reason=f"connectors_service_unreachable:{type(exc).__name__}",
+ )
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
detail="connectors service is unavailable; cannot list connector catalog",
@@ -387,22 +475,40 @@ async def _fetch_catalog() -> list[dict[str, Any]]:
status_code=status.HTTP_502_BAD_GATEWAY,
detail="connectors service returned a malformed catalog",
)
- return schemas
-
-
-async def _validate_connector_type(connector_type: str) -> dict[str, Any]:
- """Return the catalog entry for ``connector_type`` or raise 422.
-
- Validating against the live catalog (rather than a hand-maintained
- enum) means a freshly-added connector is automatically usable as soon
- as the connectors microservice picks it up — no API-side allowlist to
- keep in sync.
+ return CatalogResult(entries=schemas, source=CATALOG_LIVE)
+
+
+async def _validate_connector_type(connector_type: str, tenant_id: uuid.UUID | str | None) -> dict[str, Any]:
+ """Return the catalog entry for ``connector_type``, or refuse.
+
+ Two different refusals, because "this connector does not exist" and "I
+ could not find out whether it exists" are different facts:
+
+ 422
+ The catalog we consulted is authoritative for this deployment and
+ does not list the type.
+ 503
+ The connectors service was configured but unreachable, so the bundled
+ catalog stood in. It is generated from the registry at image-build
+ time, so it is not stale — but a connectors service rolled forward
+ ahead of this image legitimately knows types this image does not, and
+ telling an operator their brand-new connector is "unknown" sends them
+ to debug the wrong thing. This is the failure mode the stale bundle
+ used to produce on every single request.
"""
- catalog = await _fetch_catalog()
- for entry in catalog:
+ catalog = await _fetch_catalog(tenant_id)
+ for entry in catalog.entries:
if entry.get("connector_id") == connector_type:
return entry
- known = sorted(e.get("connector_id", "?") for e in catalog)
+ if catalog.degraded:
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail=(
+ f"cannot validate connector_type '{_safe_connector_type(connector_type)}': the connectors "
+ f"service is unreachable ({catalog.reason}) and the bundled catalog may lag it"
+ ),
+ )
+ known = sorted(e.get("connector_id", "?") for e in catalog.entries)
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail=f"unknown connector_type '{connector_type}'. Known types: {', '.join(known) or '(none)'}",
@@ -495,8 +601,15 @@ async def list_catalog(
— every tenant in this build sees the same catalog — but still gated
behind authentication.
"""
- schemas = await _fetch_catalog()
- return {"connectors": schemas}
+ catalog = await _fetch_catalog(current_user.tenant_id)
+ return {
+ "connectors": catalog.entries,
+ # Provenance ships with the list so the wizard can say "this may lag
+ # the live registry" instead of presenting a stand-in as the real one.
+ "source": catalog.source,
+ "degraded": catalog.degraded,
+ "reason": catalog.reason,
+ }
# ------------------------------------------------------------------ health summary
@@ -579,7 +692,7 @@ async def test_connection(
connectors microservice's stateless test endpoint. **Nothing is
persisted** — these credentials never touch Postgres or the vault.
"""
- await _validate_connector_type(request.connector_type)
+ await _validate_connector_type(request.connector_type, current_user.tenant_id)
return await _proxy_test_connection(
request.connector_type,
request.auth_config,
@@ -615,7 +728,7 @@ async def create_connector(
``auth_config`` is encrypted with the credential vault before it
touches Postgres.
"""
- catalog_entry = await _validate_connector_type(request.connector_type)
+ catalog_entry = await _validate_connector_type(request.connector_type, current_user.tenant_id)
category = request.category or catalog_entry.get("category") or "uncategorized"
try:
@@ -758,7 +871,7 @@ async def update_connector_capabilities(
# declared set. We pull from the live catalog (rather than a hard-coded
# enum on the API side) so newly-added capabilities are usable as soon
# as the connectors microservice rolls them out, with no API redeploy.
- catalog_entry = await _validate_connector_type(connector.connector_type)
+ catalog_entry = await _validate_connector_type(connector.connector_type, current_user.tenant_id)
declared_caps_raw = catalog_entry.get("capabilities") or []
declared_caps = {str(c) for c in declared_caps_raw}
requested_caps = {str(c) for c in request.allowed_capabilities}
diff --git a/services/api/app/api/v1/endpoints/graph.py b/services/api/app/api/v1/endpoints/graph.py
index ed99e67c8..e6bfe0496 100644
--- a/services/api/app/api/v1/endpoints/graph.py
+++ b/services/api/app/api/v1/endpoints/graph.py
@@ -7,6 +7,7 @@ from __future__ import annotations
import logging
import uuid
+from datetime import UTC, datetime
from typing import Annotated, Any
from fastapi import APIRouter, Depends, HTTPException, Query, status
@@ -123,6 +124,150 @@ class MitreCoverageResponse(BaseModel):
generatedAt: str
+# ── Tenant-level overview payload ───────────────────────────────────────────
+# Matches `AttackGraph` in apps/web/src/lib/api.ts. `graphApi.getOverview()`
+# hands the body straight to the Cytoscape canvas with no key remapping, so
+# these field names are camelCase on purpose — the same reason
+# `MitreCoverageResponse` above is.
+
+
+class OverviewNode(BaseModel):
+ id: str
+ label: str
+ kind: str
+ riskScore: float | None = None
+ severity: str | None = None
+ attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class OverviewEdge(BaseModel):
+ id: str
+ source: str
+ target: str
+ label: str
+ attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+class GraphOverviewResponse(BaseModel):
+ """The tenant's entity graph, bounded for one canvas render.
+
+ ``truncated`` is part of the contract rather than a diagnostic. A graph
+ cut at the node ceiling and a graph that is genuinely this size render
+ identically, and a viewer who cannot tell them apart reads a partial
+ picture as the whole estate.
+ """
+
+ nodes: list[OverviewNode]
+ edges: list[OverviewEdge]
+ generatedAt: str
+ truncated: bool = False
+
+
+#: Neo4j label → the node kind the console has a colour and a glyph for.
+#:
+#: The console's `GraphNodeKind` union is ten members wide and the graph
+#: schema declares 29 labels, so this is a projection, not a rename. What it
+#: must not do is *lose* the distinction: every node carries its real labels
+#: in ``attributes.labels``, so a label that projects onto the generic
+#: ``asset`` glyph is still identifiable in the payload.
+_LABEL_KIND: dict[str, str] = {
+ "Host": "host",
+ "Endpoint": "host",
+ "User": "user",
+ "Identity": "user",
+ "ServiceAccount": "user",
+ "Employee": "user",
+ "Process": "process",
+ "Container": "process",
+ "Alert": "alert",
+ "Technique": "technique",
+ "Tactic": "tactic",
+}
+
+#: IOC nodes carry their own type, so they resolve more precisely than their
+#: label alone allows. Keys are matched against a lowercased ``ioc_type``.
+_IOC_KIND: dict[str, str] = {
+ "ip": "ip",
+ "ipv4": "ip",
+ "ipv6": "ip",
+ "ip_address": "ip",
+ "domain": "domain",
+ "fqdn": "domain",
+ "hostname": "domain",
+ "url": "domain",
+ "md5": "hash",
+ "sha1": "hash",
+ "sha256": "hash",
+ "hash": "hash",
+ "file_hash": "hash",
+}
+
+#: The five-tier ladder, and the only values allowed onto `severity`. A
+#: vendor-specific string is dropped rather than coerced: the console shades
+#: by severity, and guessing one would shade a node by a fact nobody
+#: established.
+_SEVERITY_TIERS = frozenset({"info", "low", "medium", "high", "critical"})
+
+#: Properties that can carry a human-readable name, most specific first.
+_LABEL_PROPS = ("hostname", "username", "name", "title", "value", "technique_id", "email", "natural_key", "id")
+
+
+def _node_kind(labels: list[str], properties: dict[str, Any]) -> str:
+ """Project a node's Neo4j labels onto a kind the canvas can draw."""
+ if "IOC" in labels:
+ ioc_type = str(properties.get("ioc_type") or "").strip().lower()
+ return _IOC_KIND.get(ioc_type, "asset")
+ for label in labels:
+ kind = _LABEL_KIND.get(label)
+ if kind:
+ return kind
+ return "asset"
+
+
+def _node_label(node_id: str, properties: dict[str, Any]) -> str:
+ """The name to draw on the node, falling back to its identifier."""
+ for prop in _LABEL_PROPS:
+ value = properties.get(prop)
+ if isinstance(value, str) and value.strip():
+ return value.strip()
+ return node_id
+
+
+def _risk_score(properties: dict[str, Any]) -> float | None:
+ """``risk_score`` when the node carries a usable number, else None.
+
+ None and 0.0 are different claims — "not scored" against "scored zero" —
+ and the console renders the first as an em dash.
+ """
+ raw = properties.get("risk_score")
+ if isinstance(raw, bool) or not isinstance(raw, int | float):
+ return None
+ return round(max(0.0, min(100.0, float(raw))), 1)
+
+
+def _to_overview_node(record: dict[str, Any]) -> OverviewNode | None:
+ """Project one graph record onto the console's node shape.
+
+ Returns None for a node with no resolvable identifier: the canvas keys
+ elements by id, and a blank one would collapse every such node into a
+ single element that claims to be all of them.
+ """
+ node_id = record.get("id")
+ if not isinstance(node_id, str) or not node_id.strip():
+ return None
+ labels = [str(label) for label in (record.get("labels") or [])]
+ properties = dict(record.get("properties") or {})
+ severity = str(properties.get("severity") or "").strip().lower()
+ return OverviewNode(
+ id=node_id,
+ label=_node_label(node_id, properties),
+ kind=_node_kind(labels, properties),
+ riskScore=_risk_score(properties),
+ severity=severity if severity in _SEVERITY_TIERS else None,
+ attributes={"labels": labels},
+ )
+
+
class UpsertHostRequest(BaseModel):
host_id: str
hostname: str
@@ -248,6 +393,92 @@ async def _attack_path_from_relational(
}
+ "",
+ response_model=GraphOverviewResponse,
+ summary="Tenant-level entity graph for the Attack Graph console",
+)
+async def get_graph_overview(
+ depth: Annotated[int, Query(ge=1, le=6)] = 3,
+ entity: Annotated[str | None, Query(max_length=256)] = None,
+ current_user: CurrentUser = Depends(get_current_user),
+) -> GraphOverviewResponse:
+ """The caller's own entity graph, bounded for one canvas render.
+
+ Scoping is the whole of this endpoint's security surface. Every node of
+ every traversed path must satisfy the tenant predicate — not just the
+ node the walk started from — and a node with no ``tenant_id`` is not
+ readable, because an untagged node that *were* readable would bridge two
+ tenants through any entity they happen to share. The narrow exemption is
+ the global MITRE labels, which belong to no tenant by design.
+
+ Two failure modes that must not look alike:
+
+ ``empty``
+ 200 with no nodes. The tenant really has no graph yet — nothing has
+ been ingested, or nothing ingested produced entities. The console
+ renders its empty state.
+ ``unavailable``
+ 503. The graph backend could not be reached, so we do not know what
+ the tenant has. This deliberately does *not* degrade to an empty
+ graph the way ``/graph/mitre-coverage`` does: an empty attack graph
+ reads as "no attack relationships exist in your estate", which is a
+ security claim, and making it on evidence we never retrieved is the
+ failure this codebase keeps finding. The console's error state names
+ the endpoint and the status, which is the honest answer.
+ """
+ try:
+ data = await graph_service.get_graph_overview(
+ tenant_id=str(current_user.tenant_id),
+ depth=depth,
+ entity=entity,
+ )
+ except Exception as exc:
+ logger.warning(
+ "graph overview: backend unavailable (%s: %s)",
+ type(exc).__name__,
+ str(exc).replace("\r", "").replace("\n", " ")[:200],
+ )
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail=f"graph backend unavailable: {type(exc).__name__}",
+ ) from exc
+
+ nodes = [n for n in (_to_overview_node(r) for r in data["nodes"]) if n is not None]
+ known_ids = {n.id for n in nodes}
+ ref_to_id = {r["ref"]: r["id"] for r in data["nodes"] if isinstance(r.get("id"), str)}
+
+ edges: list[OverviewEdge] = []
+ seen_edges: set[str] = set()
+ for record in data["edges"]:
+ source = ref_to_id.get(record["source"])
+ target = ref_to_id.get(record["target"])
+ # An edge to a node that was dropped (no identifier, or past the node
+ # ceiling) would render as a line into nothing.
+ if source not in known_ids or target not in known_ids:
+ continue
+ edge_id = f"{source}|{record['type']}|{target}"
+ if edge_id in seen_edges:
+ continue
+ seen_edges.add(edge_id)
+ edges.append(
+ OverviewEdge(
+ id=edge_id,
+ source=str(source),
+ target=str(target),
+ label=str(record["type"]),
+ attributes={},
+ )
+ )
+
+ return GraphOverviewResponse(
+ nodes=nodes,
+ edges=edges,
+ generatedAt=datetime.now(UTC).isoformat(),
+ truncated=bool(data.get("truncated")),
+ )
+
+
@router.get(
"/attack-path/{case_id}",
response_model=AttackPathResponse,
@@ -562,9 +793,6 @@ async def get_mitre_coverage_compat(
``/graph/mitre-coverage`` and degrade gracefully (empty set) when the
knowledge graph is offline, mirroring that endpoint's behaviour.
"""
- from datetime import UTC as _UTC
- from datetime import datetime as _dt
-
try:
records = await graph_service.get_mitre_coverage(
tenant_id=str(current_user.tenant_id),
@@ -578,7 +806,7 @@ async def get_mitre_coverage_compat(
return MitreCoverageResponse(
tactics=[],
cells=[],
- generatedAt=_dt.now(_UTC).isoformat(),
+ generatedAt=datetime.now(UTC).isoformat(),
)
raise HTTPException(
status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
@@ -617,7 +845,7 @@ async def get_mitre_coverage_compat(
return MitreCoverageResponse(
tactics=sorted(tactics),
cells=cells,
- generatedAt=_dt.now(_UTC).isoformat(),
+ generatedAt=datetime.now(UTC).isoformat(),
)
diff --git a/services/api/app/api/v1/endpoints/oauth.py b/services/api/app/api/v1/endpoints/oauth.py
index 87836adae..04f2f919a 100644
--- a/services/api/app/api/v1/endpoints/oauth.py
+++ b/services/api/app/api/v1/endpoints/oauth.py
@@ -241,15 +241,18 @@ def _safe_connector_type(value: str) -> str:
return value
-async def _fetch_catalog_entry(connector_type: str) -> dict[str, Any]:
- """Resolve the connector's catalog entry (with OAuthHints) or 422.
+async def _fetch_catalog_entry(connector_type: str, tenant_id: uuid.UUID | str | None) -> dict[str, Any]:
+ """Resolve the connector's catalog entry (with OAuthHints) or refuse.
Reuses :func:`_validate_connector_type` so we share one source of
truth with the wizard's POST flow — the catalog ships the
``category`` we'll use on insert + the ``oauth`` hints (authorize
URL, token URL, scopes) we need for the redirect dance.
+
+ ``tenant_id`` is the tenant this OAuth flow belongs to; the connectors
+ service requires a service caller to declare it.
"""
- return await _validate_connector_type(connector_type)
+ return await _validate_connector_type(connector_type, tenant_id)
def _hints_from_catalog(catalog_entry: dict[str, Any]) -> dict[str, Any]:
@@ -633,7 +636,7 @@ async def oauth_start(
# Validate against the live catalog (defense in depth — same gate
# the POST /connectors path uses) and pull OAuth hints in one shot.
- catalog_entry = await _fetch_catalog_entry(safe_type)
+ catalog_entry = await _fetch_catalog_entry(safe_type, current_user.tenant_id)
hints = _hints_from_catalog(catalog_entry)
# Schema is the source of truth for whether hosted OAuth is wired
@@ -881,7 +884,7 @@ async def oauth_callback(
# hints for the token exchange and (b) recover the connector category
# to stamp on the new row — same gate as POST /connectors.
try:
- catalog_entry = await _fetch_catalog_entry(state_row.connector_type)
+ catalog_entry = await _fetch_catalog_entry(state_row.connector_type, state_row.tenant_id)
except HTTPException:
# Connector class disappeared from the catalog between start and
# callback (deployment in flight). Bail with a clear error.
diff --git a/services/api/app/data/connector_catalog_fallback.json b/services/api/app/data/connector_catalog_fallback.json
index 72e2cf54a..382dab4b8 100644
--- a/services/api/app/data/connector_catalog_fallback.json
+++ b/services/api/app/data/connector_catalog_fallback.json
@@ -1,852 +1,3565 @@
[
{
- "connector_id": "aws_security_hub",
- "connector_name": "AWS Security Hub",
+ "capabilities": [
+ "pull_alerts",
+ "pivot_user",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "abnormal_security",
+ "connector_name": "Abnormal Security",
+ "description": "Abnormal Security behavioural-AI email threat events. Polls /v1/threats and /v1/cases for BEC, credential phishing, account takeover, and invoice-fraud detections.",
+ "docs_url": "/docs/connectors/abnormal_security",
+ "fields": [
+ {
+ "default": "https://api.abnormalplatform.com",
+ "label": "API base URL",
+ "name": "base_url",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Abnormal Console \u2192 Settings \u2192 Integrations \u2192 API \u2192 Generate token.",
+ "label": "API token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit"
+ ],
+ "category": "ai",
+ "connector_id": "ai_gateway",
+ "connector_name": "AI Gateway / MCP Runtime",
+ "description": "Pull request logs from an LLM gateway or MCP server (LiteLLM, Portkey, Helicone, or an in-house proxy) to see which agents call which tools and models, on whose behalf. Covers every app behind the gateway without instrumenting each one. For apps you control, the aisoc-ai-sdk push path is lower friction.",
+ "docs_url": "/docs/connectors/ai_gateway",
+ "fields": [
+ {
+ "label": "Gateway base URL",
+ "name": "base_url",
+ "placeholder": "https://llm-gateway.internal",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Gateway API key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Any model outside this list raises an unapproved_model finding. Leave blank to disable the check rather than flag everything.",
+ "label": "Approved models (comma-separated)",
+ "name": "approved_models",
+ "placeholder": "gpt-4o, claude-sonnet-4, llama-3.3-70b",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": true,
+ "help_text": "Disable only for an internal gateway using a private CA.",
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts"
+ ],
+ "category": "edr",
+ "connector_id": "auditd",
+ "connector_name": "Linux Auditd",
+ "description": "Linux Audit (``auditd``) log connector. Tails ``/var/log/audit/audit.log`` forward from a saved byte cursor, reassembles multi-record events (SYSCALL + EXECVE + PATH + \u2026) into flat documents, and feeds the same execve / file-watch / kernel-module primitives that detections/endpoint/linux-*.yaml rules pivot on. Ship the AiSOC ``audit.rules`` profile (profiles/auditd/aisoc.rules) for full coverage; rules with ``aisoc_*`` keys auto-bucket into AiSOC's severity tiers.",
+ "docs_url": "/docs/connectors/auditd",
+ "fields": [
+ {
+ "help_text": "Human-readable label for the host being monitored. Surfaced on every normalised event so detections and investigations can filter to a single fleet member without relying on the kernel's reported hostname.",
+ "label": "Host label",
+ "name": "host_label",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "default": "/var/log/audit/audit.log",
+ "help_text": "Absolute path to ``audit.log`` inside the AiSOC connector pod. Mount the host's ``/var/log/audit`` directory read-only into the pod, or run the connector on the same host as the auditd daemon.",
+ "label": "Audit log path",
+ "name": "audit_log_path",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Optional override for where AiSOC stores its byte-position cursor. Defaults to ``<audit_log_path>.aisoc-cursor``. Use a writeable path \u2014 the connector pod needs to update this on every successful poll.",
+ "label": "Cursor file path",
+ "name": "cursor_path",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pivot_user",
+ "read_audit_trail"
+ ],
+ "category": "iam",
+ "connector_id": "auth0",
+ "connector_name": "Auth0",
+ "description": "Auth0 tenant logs. Pulls login events, MFA events, and admin actions via the Management API.",
+ "docs_url": "/docs/connectors/auth0",
+ "fields": [
+ {
+ "label": "Auth0 Domain",
+ "name": "domain",
+ "placeholder": "yourcorp.us.auth0.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "M2M Client ID",
+ "name": "client_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "M2M Client Secret",
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://AUTH0_DOMAIN/authorize",
+ "scopes": [
+ "read:logs",
+ "read:logs_users"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://AUTH0_DOMAIN/oauth/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
"category": "cloud",
- "description": "AWS Security Hub findings (GuardDuty, Inspector, Macie, third-party).",
+ "connector_id": "aws_cloudtrail",
+ "connector_name": "AWS CloudTrail",
+ "description": "AWS CloudTrail audit events. Polls a curated allow-list of high-signal management events (IAM grants, trail tampering, public-S3 changes, KMS key destruction, cross-account sharing) so detections fire without drowning in read-only noise.",
+ "docs_url": "/docs/connectors/aws-cloudtrail",
"fields": [
{
- "name": "region",
- "type": "string",
+ "default": "us-east-1",
"label": "AWS Region",
+ "name": "region",
"required": true,
- "default": "us-east-1"
+ "type": "string"
},
{
+ "help_text": "Leave blank to use the runtime IAM role / instance profile.",
+ "label": "Access Key ID",
"name": "access_key",
- "type": "string",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Required only when supplying a static access key above.",
+ "label": "Secret Access Key",
+ "name": "secret_key",
+ "required": false,
+ "type": "secret"
+ },
+ {
+ "default": "",
+ "help_text": "Override the default curated event list. Leave blank to use AiSOC's curated list, or set to '*' to pull every CloudTrail event in the window (high volume \u2014 not recommended).",
+ "label": "Event allow-list (comma-separated)",
+ "name": "event_names",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "cloud",
+ "connector_id": "aws_guardduty",
+ "connector_name": "AWS GuardDuty",
+ "description": "AWS GuardDuty findings. Pulls native GuardDuty alerts (threat detection across VPC flow logs, DNS logs, CloudTrail, EKS, S3, RDS, Lambda) directly without requiring Security Hub aggregation.",
+ "docs_url": "/docs/connectors/aws-guardduty",
+ "fields": [
+ {
+ "default": "us-east-1",
+ "label": "AWS Region",
+ "name": "region",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Leave blank to use the runtime IAM role / instance profile.",
"label": "Access Key ID",
+ "name": "access_key",
"required": false,
- "help_text": "Leave blank to use the runtime IAM role / instance profile."
+ "type": "string"
},
{
+ "help_text": "Required only when supplying a static access key above.",
+ "label": "Secret Access Key",
"name": "secret_key",
- "type": "secret",
+ "required": false,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "block_ip",
+ "allow_ip"
+ ],
+ "category": "cloud",
+ "connector_id": "aws_security_hub",
+ "connector_name": "AWS Security Hub",
+ "description": "AWS Security Hub findings (GuardDuty, Inspector, Macie, third-party).",
+ "docs_url": "/docs/connectors/aws-security-hub",
+ "fields": [
+ {
+ "default": "us-east-1",
+ "label": "AWS Region",
+ "name": "region",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Leave blank to use the runtime IAM role / instance profile.",
+ "label": "Access Key ID",
+ "name": "access_key",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Required only when supplying a static access key above.",
"label": "Secret Access Key",
+ "name": "secret_key",
"required": false,
- "help_text": "Required only when supplying a static access key above."
+ "type": "secret"
}
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_logs",
+ "pull_alerts"
],
- "docs_url": "/docs/connectors/aws-security-hub"
+ "category": "cloud",
+ "connector_id": "aws_vpc_flow",
+ "connector_name": "AWS VPC Flow Logs",
+ "description": "AWS VPC Flow Logs streamed from CloudWatch Logs. Defaults to surfacing rejected flows only so the ingest pipeline gets the actionable network-deny signal without drowning in steady-state ACCEPT noise.",
+ "docs_url": "/docs/connectors/aws-vpc-flow",
+ "fields": [
+ {
+ "default": "us-east-1",
+ "label": "AWS Region",
+ "name": "region",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "The CloudWatch Logs log group your VPC Flow Logs publish to (e.g. ``/aws/vpc/flowlogs``). Configure flow logs to publish to CloudWatch Logs in the VPC console first if you haven't.",
+ "label": "CloudWatch Logs log group",
+ "name": "log_group_name",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "default": "?REJECT",
+ "help_text": "CloudWatch Logs filter pattern applied server-side. Default ``?REJECT`` surfaces blocked flows only. Set to empty string to ingest every flow record (high volume warning).",
+ "label": "CloudWatch Logs filter pattern",
+ "name": "filter_pattern",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": "v2",
+ "help_text": "AiSOC parses v2 (the AWS default 14-field layout) natively. For v5 custom layouts the raw record passes through on raw_event so detection content can match on the JSON.",
+ "label": "Flow log version (v2 or v5)",
+ "name": "flow_log_version",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Leave blank to use the runtime IAM role / instance profile.",
+ "label": "Access Key ID",
+ "name": "access_key",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Required only when supplying a static access key above.",
+ "label": "Secret Access Key",
+ "name": "secret_key",
+ "required": false,
+ "type": "secret"
+ }
+ ]
},
{
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "cloud",
"connector_id": "azure_activity",
"connector_name": "Azure Activity Logs",
- "category": "cloud",
"description": "Azure subscription Activity Log \u2014 every control-plane operation (resource CRUD, RBAC changes, policy changes). Requires Reader role on the subscription.",
+ "docs_url": "/docs/connectors/azure-activity",
"fields": [
{
- "name": "tenant_id",
- "type": "string",
"label": "Tenant ID",
- "required": true
+ "name": "tenant_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "client_id",
- "type": "string",
"label": "Application (Client) ID",
- "required": true
+ "name": "client_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "client_secret",
- "type": "secret",
"label": "Client Secret",
- "required": true
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
},
{
- "name": "subscription_id",
- "type": "string",
"label": "Subscription ID",
+ "name": "subscription_id",
+ "placeholder": "00000000-0000-0000-0000-000000000000",
"required": true,
- "placeholder": "00000000-0000-0000-0000-000000000000"
+ "type": "string"
}
],
- "docs_url": "/docs/connectors/azure-activity",
"oauth": {
- "supported_in_hosted": true,
"authorize_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
- "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"scopes": [
"https://management.azure.com/user_impersonation"
- ]
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token"
}
},
{
+ "capabilities": [
+ "pull_alerts",
+ "isolate_host",
+ "unisolate_host",
+ "block_ioc",
+ "run_av_scan"
+ ],
+ "category": "edr",
"connector_id": "azure_defender",
"connector_name": "Microsoft Defender",
- "category": "edr",
"description": "Microsoft 365 Defender unified alerts feed (Defender for Cloud, Endpoint, Identity, Office 365, Cloud Apps) via Microsoft Graph. Requires SecurityAlert.Read.All.",
+ "docs_url": "/docs/connectors/azure-defender",
"fields": [
{
- "name": "tenant_id",
- "type": "string",
"label": "Tenant ID",
- "required": true
+ "name": "tenant_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "client_id",
- "type": "string",
"label": "Application (Client) ID",
- "required": true
+ "name": "client_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "client_secret",
- "type": "secret",
"label": "Client Secret",
- "required": true
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
}
],
- "docs_url": "/docs/connectors/azure-defender",
"oauth": {
- "supported_in_hosted": true,
"authorize_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
- "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"scopes": [
"https://graph.microsoft.com/SecurityAlert.Read.All"
- ]
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token"
}
},
{
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts"
+ ],
+ "category": "iam",
"connector_id": "azure_entra",
"connector_name": "Microsoft Entra ID",
- "category": "iam",
"description": "Microsoft Entra ID (Azure AD) directory audits and risky sign-ins via Microsoft Graph. Requires AuditLog.Read.All and Directory.Read.All application permissions.",
+ "docs_url": "/docs/connectors/azure-entra",
"fields": [
{
- "name": "tenant_id",
- "type": "string",
"label": "Tenant ID",
+ "name": "tenant_id",
+ "placeholder": "00000000-0000-0000-0000-000000000000",
"required": true,
- "placeholder": "00000000-0000-0000-0000-000000000000"
+ "type": "string"
},
{
- "name": "client_id",
- "type": "string",
"label": "Application (Client) ID",
- "required": true
+ "name": "client_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "client_secret",
- "type": "secret",
"label": "Client Secret",
- "required": true
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
}
],
- "docs_url": "/docs/connectors/azure-entra",
"oauth": {
- "supported_in_hosted": true,
"authorize_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
- "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
"scopes": [
"https://graph.microsoft.com/AuditLog.Read.All",
"https://graph.microsoft.com/Directory.Read.All"
- ]
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token"
}
},
{
- "connector_id": "cloudflare",
- "connector_name": "Cloudflare",
+ "capabilities": [
+ "pull_audit",
+ "pivot_user",
+ "read_audit_trail"
+ ],
"category": "saas",
- "description": "Cloudflare account audit logs (zone changes, API token grants, member adds, WAF/firewall edits) via the v4 API. Requires an API token scoped to Account: Audit Logs: Read.",
+ "connector_id": "box",
+ "connector_name": "Box",
+ "description": "Box admin audit events: file shares / downloads / deletes, collaborator changes, login activity, policy edits, and Shield anomaly alerts.",
+ "docs_url": "/docs/connectors/box",
"fields": [
{
- "name": "account_id",
- "type": "string",
- "label": "Account ID",
- "required": true,
- "placeholder": "abc123def456...",
- "help_text": "Found in the Cloudflare dashboard under any zone's Overview, lower-right pane (\"Account ID\")."
- },
- {
- "name": "api_token",
- "type": "secret",
- "label": "API Token",
+ "help_text": "OAuth 2.0 access token from a Box JWT app with the 'Manage enterprise properties' scope. Refresh externally; this connector does not mint new tokens.",
+ "label": "Box access token",
+ "name": "access_token",
"required": true,
- "help_text": "Account-scoped API token with the Audit Logs: Read permission. Avoid using the legacy Global API Key."
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/cloudflare",
- "oauth": {
- "supported_in_hosted": false
- }
+ ]
},
{
- "connector_id": "cortex_xdr",
- "connector_name": "Cortex XDR",
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit",
+ "pivot_host",
+ "isolate_host",
+ "quarantine_file",
+ "block_hash"
+ ],
"category": "edr",
- "description": "Palo Alto Cortex XDR incidents via the public REST API.",
+ "connector_id": "carbon_black",
+ "connector_name": "VMware Carbon Black Cloud",
+ "description": "VMware Carbon Black Cloud (formerly Carbon Black Defense). Pulls alerts and audit log entries via API key authentication. Supports host isolation and hash banning via agent capabilities.",
+ "docs_url": "/docs/connectors/carbon-black",
"fields": [
{
- "name": "api_key_id",
- "type": "string",
- "label": "API Key ID",
- "required": true
+ "help_text": "CBC region your tenant is hosted in. The wrong region returns 401 rather than 404, so this can't be auto-detected.",
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "US East (defense.conferdeploy.net)",
+ "value": "us_east"
+ },
+ {
+ "label": "US West",
+ "value": "us_west"
+ },
+ {
+ "label": "Europe (defense-eu)",
+ "value": "eu"
+ },
+ {
+ "label": "United Kingdom (defense-uk)",
+ "value": "uk"
+ },
+ {
+ "label": "Australia (defense-au)",
+ "value": "au"
+ },
+ {
+ "label": "APAC (defense-apjp)",
+ "value": "apac"
+ }
+ ],
+ "required": true,
+ "type": "select"
},
{
- "name": "api_key",
- "type": "secret",
- "label": "API Key",
- "required": true
+ "help_text": "Found in CBC console under Settings \u2192 API Access \u2192 API Keys (the column labeled 'Org Key').",
+ "label": "Org Key",
+ "name": "org_key",
+ "placeholder": "ABCD1234",
+ "required": true,
+ "type": "string"
},
{
- "name": "fqdn",
- "type": "string",
- "label": "FQDN",
+ "help_text": "The 'API ID' half of the credential pair.",
+ "label": "API ID",
+ "name": "api_id",
"required": true,
- "placeholder": "api-example.xdr.us.paloaltonetworks.com",
- "help_text": "Fully qualified domain name of your Cortex XDR tenant."
+ "type": "string"
+ },
+ {
+ "help_text": "The long secret half of the credential pair.",
+ "label": "API Secret Key",
+ "name": "api_secret",
+ "required": true,
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/cortex-xdr"
+ ]
},
{
- "connector_id": "crowdstrike",
- "connector_name": "CrowdStrike Falcon",
- "category": "edr",
- "description": "CrowdStrike Falcon detections via the Falcon REST API.",
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_user",
+ "pivot_ip"
+ ],
+ "category": "siem",
+ "connector_id": "chronicle",
+ "connector_name": "Google Chronicle",
+ "description": "Google Chronicle SecOps SIEM. Pulls detections and supports UDM searches. Auth is via a Google Cloud service account JSON key with chronicle.* roles.",
+ "docs_url": "/docs/connectors/chronicle",
"fields": [
{
- "name": "client_id",
- "type": "string",
- "label": "Client ID",
- "required": true
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "United States (us)",
+ "value": "us"
+ },
+ {
+ "label": "Europe (europe)",
+ "value": "europe"
+ },
+ {
+ "label": "Asia Southeast 1 (asia-southeast1)",
+ "value": "asia-southeast1"
+ },
+ {
+ "label": "Asia Northeast 1 (asia-northeast1)",
+ "value": "asia-northeast1"
+ },
+ {
+ "label": "Australia Southeast 1",
+ "value": "australia-southeast1"
+ }
+ ],
+ "required": true,
+ "type": "select"
},
{
- "name": "client_secret",
- "type": "secret",
- "label": "Client Secret",
- "required": true
+ "label": "GCP Project ID",
+ "name": "project_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "base_url",
- "type": "string",
- "label": "Base URL",
- "required": false,
- "default": "https://api.crowdstrike.com",
- "help_text": "Override only if your tenant lives in a non-US cloud (e.g. api.eu-1.crowdstrike.com)."
+ "help_text": "UUID of your Chronicle tenant.",
+ "label": "Chronicle Customer ID",
+ "name": "customer_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Paste the entire service-account JSON key.",
+ "label": "Service Account JSON",
+ "name": "service_account_json",
+ "required": true,
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/crowdstrike"
+ ]
},
{
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_domain",
+ "pivot_ip",
+ "enrich_domain"
+ ],
+ "category": "network",
+ "connector_id": "cisco_umbrella",
+ "connector_name": "Cisco Umbrella",
+ "description": "Cisco Umbrella DNS + secure web gateway activity. Surfaces blocked domains, malware verdicts, and proxy events.",
+ "docs_url": "/docs/connectors/cisco_umbrella",
+ "fields": [
+ {
+ "label": "Umbrella Management API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "Umbrella Management API Secret",
+ "name": "api_secret",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Optional. If omitted, the token's default org is used.",
+ "label": "Organization ID",
+ "name": "org_id",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "saas",
+ "connector_id": "cloudflare",
+ "connector_name": "Cloudflare",
+ "description": "Cloudflare account audit logs (zone changes, API token grants, member adds, WAF/firewall edits) via the v4 API. Requires an API token scoped to Account: Audit Logs: Read.",
+ "docs_url": "/docs/connectors/cloudflare",
+ "fields": [
+ {
+ "help_text": "Found in the Cloudflare dashboard under any zone's Overview, lower-right pane (\"Account ID\").",
+ "label": "Account ID",
+ "name": "account_id",
+ "placeholder": "abc123def456...",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Account-scoped API token with the Audit Logs: Read permission. Avoid using the legacy Global API Key.",
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "supported_in_hosted": false
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit",
+ "read_audit_trail"
+ ],
+ "category": "network",
+ "connector_id": "cloudflare_zt",
+ "connector_name": "Cloudflare WAF + Zero Trust",
+ "description": "Cloudflare data-plane events: WAF / firewall decisions (per-zone) and Zero Trust Access audit log (per-account). Auth is an account-scoped API token with Zone:Firewall Services:Read and Account:Access Audit Logs:Read.",
+ "docs_url": "/docs/connectors/cloudflare_zt",
+ "fields": [
+ {
+ "help_text": "Pick which stream this instance pulls. Run two instances side-by-side for full coverage.",
+ "label": "Event stream",
+ "name": "mode",
+ "options": [
+ {
+ "label": "WAF / firewall events",
+ "value": "waf"
+ },
+ {
+ "label": "Zero Trust Access audit",
+ "value": "access"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "help_text": "Cloudflare account ID, found in the dashboard right pane.",
+ "label": "Account ID",
+ "name": "account_id",
+ "placeholder": "abc123def456",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Required when mode=waf. Leave empty for Access mode.",
+ "label": "Zone ID (WAF mode only)",
+ "name": "zone_id",
+ "placeholder": "zone-uuid",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Account-scoped token with Zone:Firewall Services:Read (WAF) AND Account:Access Audit Logs:Read (Zero Trust).",
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "confluence_audit",
+ "connector_name": "Confluence Audit",
+ "description": "Atlassian Confluence audit trail. Pulls page, space, and permission audit events via the Confluence Cloud REST API. Requires an Atlassian Cloud API token; the calling user needs site-admin access to read the full audit log.",
+ "docs_url": "/docs/connectors/confluence-audit",
+ "fields": [
+ {
+ "label": "Confluence site URL",
+ "name": "site_url",
+ "placeholder": "https://yourorg.atlassian.net",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Account email",
+ "name": "email",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Generate at https://id.atlassian.com/manage-profile/security/api-tokens",
+ "label": "API token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://auth.atlassian.com/authorize",
+ "scopes": [
+ "read:audit-log:confluence",
+ "read:user:confluence",
+ "offline_access"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://auth.atlassian.com/oauth/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "isolate_host",
+ "unisolate_host"
+ ],
+ "category": "edr",
+ "connector_id": "cortex_xdr",
+ "connector_name": "Cortex XDR",
+ "description": "Palo Alto Cortex XDR incidents via the public REST API.",
+ "docs_url": "/docs/connectors/cortex-xdr",
+ "fields": [
+ {
+ "label": "API Key ID",
+ "name": "api_key_id",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Fully qualified domain name of your Cortex XDR tenant.",
+ "label": "FQDN",
+ "name": "fqdn",
+ "placeholder": "api-example.xdr.us.paloaltonetworks.com",
+ "required": true,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_user",
+ "isolate_host"
+ ],
+ "category": "siem",
+ "connector_id": "cortex_xsiam",
+ "connector_name": "Cortex XSIAM",
+ "description": "Palo Alto Networks Cortex XSIAM \u2014 pulls correlated incidents and supports XQL queries over the platform's data lake. Endpoint isolation is exposed as an agent action.",
+ "docs_url": "/docs/connectors/cortex-xsiam",
+ "fields": [
+ {
+ "help_text": "Found in the XSIAM console under Settings \u2192 API Keys.",
+ "label": "Tenant FQDN",
+ "name": "tenant_fqdn",
+ "placeholder": "api-yourtenant.xdr.us.paloaltonetworks.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Key ID",
+ "name": "api_key_id",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "isolate_host",
+ "unisolate_host",
+ "kill_process",
+ "quarantine_file",
+ "run_script"
+ ],
+ "category": "edr",
+ "connector_id": "crowdstrike",
+ "connector_name": "CrowdStrike Falcon",
+ "description": "CrowdStrike Falcon detections via the Falcon REST API.",
+ "docs_url": "/docs/connectors/crowdstrike",
+ "fields": [
+ {
+ "label": "Client ID",
+ "name": "client_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Client Secret",
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "https://api.crowdstrike.com",
+ "help_text": "Override only if your tenant lives in a non-US cloud (e.g. api.eu-1.crowdstrike.com).",
+ "label": "Base URL",
+ "name": "base_url",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pivot_host",
+ "pivot_ip"
+ ],
+ "category": "ndr",
+ "connector_id": "darktrace",
+ "connector_name": "Darktrace",
+ "description": "Darktrace NDR model breaches as alerts (Threat Visualizer API).",
+ "docs_url": "/docs/connectors/darktrace",
+ "fields": [
+ {
+ "label": "Appliance URL",
+ "name": "base_url",
+ "placeholder": "https://darktrace.example.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Public Token",
+ "name": "public_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "Private Token",
+ "name": "private_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "help_text": "Disable only for self-signed certificates on a private appliance.",
+ "label": "Verify SSL certificate",
+ "name": "ssl_verify",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_logs",
+ "pull_alerts",
+ "query_logs",
+ "pivot_host"
+ ],
+ "category": "siem",
+ "connector_id": "datadog",
+ "connector_name": "Datadog (Logs + APM)",
+ "description": "Datadog observability events: log search across the logs platform AND APM monitor / event-stream entries. For Cloud SIEM Security Signals use the ``datadog_cloud_siem`` connector.",
+ "docs_url": "/docs/connectors/datadog",
+ "fields": [
+ {
+ "label": "Datadog site",
+ "name": "site",
+ "options": [
+ {
+ "label": "US1 (datadoghq.com)",
+ "value": "us1"
+ },
+ {
+ "label": "US3 (us3.datadoghq.com)",
+ "value": "us3"
+ },
+ {
+ "label": "US5 (us5.datadoghq.com)",
+ "value": "us5"
+ },
+ {
+ "label": "EU1 (datadoghq.eu)",
+ "value": "eu1"
+ },
+ {
+ "label": "AP1 (ap1.datadoghq.com)",
+ "value": "ap1"
+ },
+ {
+ "label": "US1-FED (ddog-gov.com)",
+ "value": "us1-fed"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "label": "Stream",
+ "name": "mode",
+ "options": [
+ {
+ "label": "Logs Search API",
+ "value": "logs"
+ },
+ {
+ "label": "Events / APM monitors",
+ "value": "events"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "default": "status:error OR status:critical",
+ "help_text": "Logs Search query (logs mode) or tag filter (events mode, e.g. 'priority:all').",
+ "label": "Filter query",
+ "name": "query",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "Application Key",
+ "name": "application_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_user",
+ "pivot_ip"
+ ],
+ "category": "siem",
+ "connector_id": "datadog_cloud_siem",
+ "connector_name": "Datadog Cloud SIEM",
+ "description": "Datadog Cloud SIEM. Pulls Security Signals and supports log search across the Datadog logs platform.",
+ "docs_url": "/docs/connectors/datadog-cloud-siem",
+ "fields": [
+ {
+ "label": "Datadog site",
+ "name": "site",
+ "options": [
+ {
+ "label": "US1 (datadoghq.com)",
+ "value": "us1"
+ },
+ {
+ "label": "US3 (us3.datadoghq.com)",
+ "value": "us3"
+ },
+ {
+ "label": "US5 (us5.datadoghq.com)",
+ "value": "us5"
+ },
+ {
+ "label": "EU1 (datadoghq.eu)",
+ "value": "eu1"
+ },
+ {
+ "label": "AP1 (ap1.datadoghq.com)",
+ "value": "ap1"
+ },
+ {
+ "label": "US1-FED (ddog-gov.com)",
+ "value": "us1-fed"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "Application Key",
+ "name": "application_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs"
+ ],
+ "category": "siem",
+ "connector_id": "devo",
+ "connector_name": "Devo",
+ "description": "Pull triggered alerts from the Devo Alerting API. Devo alert severity (1-5 or named) maps to the five-tier ladder. Auth is a Devo standalone API token.",
+ "docs_url": "/docs/connectors/devo",
+ "fields": [
+ {
+ "label": "Alerting API URL",
+ "name": "api_url",
+ "placeholder": "https://api-us.devo.com/alerts",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Standalone API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pivot_user",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "dropbox",
+ "connector_name": "Dropbox Business",
+ "description": "Dropbox Business team event log: sharing, sign-in, member role changes, OAuth-app authorisations, policy edits.",
+ "docs_url": "/docs/connectors/dropbox",
+ "fields": [
+ {
+ "help_text": "OAuth 2.0 token for a Dropbox Business app with the ``team_data.governance.read`` and ``events.read`` scopes.",
+ "label": "Team admin token",
+ "name": "team_admin_token",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "iam",
"connector_id": "duo_security",
"connector_name": "Duo Security",
- "category": "iam",
"description": "Duo Security authentication logs via the Admin API (HMAC-SHA1 signed).",
+ "docs_url": "/docs/connectors/duo-security",
"fields": [
{
- "name": "integration_key",
- "type": "string",
"label": "Integration Key",
- "required": true
+ "name": "integration_key",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Secret Key",
+ "name": "secret_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "API Hostname",
+ "name": "api_hostname",
+ "placeholder": "api-XXXXXXXX.duosecurity.com",
+ "required": true,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "search_siem",
+ "sync_detection_rule",
+ "update_watcher"
+ ],
+ "category": "siem",
+ "connector_id": "elastic",
+ "connector_name": "Elastic SIEM",
+ "description": "Elastic Security via the ES|QL search API. Federated-search ready.",
+ "docs_url": "/docs/connectors/elastic",
+ "fields": [
+ {
+ "help_text": "Cluster endpoint, not Kibana.",
+ "label": "Elasticsearch URL",
+ "name": "base_url",
+ "placeholder": "https://elastic.example.com:9200",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": false,
+ "type": "secret"
+ },
+ {
+ "label": "Username",
+ "name": "username",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "label": "Password",
+ "name": "password",
+ "required": false,
+ "type": "secret"
+ },
+ {
+ "default": "logs-*",
+ "label": "Default Index Pattern",
+ "name": "index",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": true,
+ "help_text": "Disable only for self-signed certificates in private deployments.",
+ "label": "Verify SSL certificate",
+ "name": "ssl_verify",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "saas",
+ "connector_id": "email_inbox",
+ "connector_name": "Email Inbox (IMAP)",
+ "description": "Poll a mailbox over IMAP and ingest each forwarded alert email as an event. Pairs with the /v1/inbox/email webhook for environments that cannot push directly.",
+ "docs_url": "/docs/connectors/email-inbox",
+ "fields": [
+ {
+ "label": "IMAP host",
+ "name": "host",
+ "placeholder": "imap.gmail.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "default": 993,
+ "help_text": "Defaults to 993 (IMAPS).",
+ "label": "IMAP port",
+ "name": "port",
+ "required": false,
+ "type": "number"
+ },
+ {
+ "label": "Username",
+ "name": "username",
+ "placeholder": "[email protected]",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Use an app-specific password for Gmail / Outlook. Never your primary account password.",
+ "label": "Password / App Password",
+ "name": "password",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "INBOX",
+ "label": "Mailbox / folder",
+ "name": "mailbox",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": 50,
+ "help_text": "Cap how many unread messages we pull per poll. Older unread messages will still arrive \u2014 they'll just take more polls to drain.",
+ "label": "Max messages per poll",
+ "name": "max_messages",
+ "required": false,
+ "type": "number"
+ },
+ {
+ "default": true,
+ "label": "Use SSL (IMAPS)",
+ "name": "use_ssl",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pivot_user"
+ ],
+ "category": "siem",
+ "connector_id": "exabeam",
+ "connector_name": "Exabeam",
+ "description": "Pull notable, risk-scored user sessions from Exabeam Advanced Analytics / Fusion SIEM. Session riskScore maps to the five-tier severity ladder. Auth is an API key + secret.",
+ "docs_url": "/docs/connectors/exabeam",
+ "fields": [
+ {
+ "label": "Cluster URL",
+ "name": "base_url",
+ "placeholder": "https://cluster.exabeam.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Key ID",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "API Secret",
+ "name": "api_secret",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_logs"
+ ],
+ "category": "siem",
+ "connector_id": "falco",
+ "connector_name": "Falco",
+ "description": "Falco runtime security events for Linux and Kubernetes. Receives JSON rule hits over HTTP, either from falcosidekick or from Falco's built-in HTTP output plugin. Optionally validates a shared-secret header on each delivery.",
+ "docs_url": "/docs/connectors/falco",
+ "fields": [
+ {
+ "default": "/v1/webhooks/falco",
+ "help_text": "Path on the AiSOC ingest service where Falco / falcosidekick should POST events.",
+ "label": "Webhook path",
+ "name": "webhook_path",
+ "placeholder": "/v1/webhooks/falco",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "If set, each incoming request must include the matching value in the X-Falco-Secret header.",
+ "label": "Shared secret (optional)",
+ "name": "shared_secret",
+ "required": false,
+ "type": "secret"
+ },
+ {
+ "default": "DEBUG",
+ "help_text": "Drop events whose Falco priority is below this threshold. Defaults to DEBUG so nothing is filtered server-side.",
+ "label": "Minimum priority",
+ "name": "minimum_priority",
+ "options": [
+ {
+ "label": "DEBUG (everything)",
+ "value": "DEBUG"
+ },
+ {
+ "label": "INFORMATIONAL",
+ "value": "INFORMATIONAL"
+ },
+ {
+ "label": "NOTICE",
+ "value": "NOTICE"
+ },
+ {
+ "label": "WARNING",
+ "value": "WARNING"
+ },
+ {
+ "label": "ERROR",
+ "value": "ERROR"
+ },
+ {
+ "label": "CRITICAL",
+ "value": "CRITICAL"
+ },
+ {
+ "label": "ALERT",
+ "value": "ALERT"
+ },
+ {
+ "label": "EMERGENCY",
+ "value": "EMERGENCY"
+ }
+ ],
+ "required": false,
+ "type": "select"
+ }
+ ],
+ "oauth": {
+ "supported_in_hosted": false
+ }
+ },
+ {
+ "capabilities": [
+ "pull_logs",
+ "query_logs",
+ "query_processes",
+ "pivot_host"
+ ],
+ "category": "edr",
+ "connector_id": "fleetdm",
+ "connector_name": "FleetDM",
+ "description": "FleetDM \u2014 osquery fleet manager. Pulls host posture and saved-query results from the Fleet REST API.",
+ "docs_url": "/docs/connectors/fleetdm",
+ "fields": [
+ {
+ "help_text": "Base URL of the Fleet server (no trailing slash). The /api prefix is added automatically.",
+ "label": "Fleet Server URL",
+ "name": "base_url",
+ "placeholder": "https://fleet.example.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Long-lived token issued from the Fleet UI under Settings -> Users -> [user] -> Get API token.",
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Optional Fleet Team ID to scope queries to. Leave empty to span all teams.",
+ "label": "Team ID",
+ "name": "team_id",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS Certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "cloud",
+ "connector_id": "gcp_cloud_audit",
+ "connector_name": "GCP Cloud Audit Logs",
+ "description": "Google Cloud Audit Logs (Admin Activity, Data Access, System Event) via Cloud Logging. Requires a service account with roles/logging.viewer (and roles/logging.privateLogViewer for Data Access logs).",
+ "docs_url": "/docs/connectors/gcp-cloud-audit",
+ "fields": [
+ {
+ "help_text": "The GCP project to read audit logs from. Use a log-sink aggregator project if you've consolidated.",
+ "label": "Project ID",
+ "name": "project_id",
+ "placeholder": "my-prod-project",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Paste the full JSON key file. It will be encrypted at rest by the credential vault.",
+ "label": "Service account JSON key",
+ "name": "service_account_json",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "scopes": [
+ "https://www.googleapis.com/auth/logging.read"
+ ],
+ "supported_in_hosted": false,
+ "token_url": "https://oauth2.googleapis.com/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "cloud",
+ "connector_id": "gcp_scc",
+ "connector_name": "GCP Security Command Center",
+ "description": "Google Cloud Security Command Center findings. Requires a service account with roles/securitycenter.findingsViewer at the organization or folder level.",
+ "docs_url": "/docs/connectors/gcp-scc",
+ "fields": [
+ {
+ "help_text": "Numeric GCP organization ID. SCC is org-scoped; the service account must have findingsViewer at this level (or on a parent folder/source).",
+ "label": "Organization ID",
+ "name": "organization_id",
+ "placeholder": "1234567890",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Paste the full JSON key file. It will be encrypted at rest by the credential vault.",
+ "label": "Service account JSON key",
+ "name": "service_account_json",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "scopes": [
+ "https://www.googleapis.com/auth/cloud-platform"
+ ],
+ "supported_in_hosted": false,
+ "token_url": "https://oauth2.googleapis.com/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts"
+ ],
+ "category": "vcs",
+ "connector_id": "github",
+ "connector_name": "GitHub",
+ "description": "GitHub organization audit log and Code Scanning alerts. Requires a token with read:audit_log and security_events scopes (fine-grained PAT or GitHub App installation token).",
+ "docs_url": "/docs/connectors/github",
+ "fields": [
+ {
+ "label": "Organization slug",
+ "name": "organization",
+ "placeholder": "my-org",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Fine-grained PAT recommended. Required scopes: read:audit_log, security_events. For GitHub App auth, paste a fresh installation token.",
+ "label": "Personal Access Token or App Installation Token",
+ "name": "token",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://github.com/login/oauth/authorize",
+ "scopes": [
+ "read:audit_log",
+ "security_events",
+ "repo"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://github.com/login/oauth/access_token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts"
+ ],
+ "category": "vcs",
+ "connector_id": "gitlab",
+ "connector_name": "GitLab",
+ "description": "GitLab group audit events and security vulnerability findings. Requires a Personal Access Token with the 'api' scope; the authenticating user must own the group. Self-managed GitLab works too \u2014 set gitlab_url to your instance base URL.",
+ "docs_url": "/docs/connectors/gitlab",
+ "fields": [
+ {
+ "help_text": "Leave default for gitlab.com. For self-managed installations, paste the URL operators use to reach the web UI (no trailing slash).",
+ "label": "GitLab base URL",
+ "name": "gitlab_url",
+ "placeholder": "https://gitlab.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Group path or numeric ID",
+ "name": "group",
+ "placeholder": "my-org or 1234567",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "PAT with the 'api' scope. The authenticating user must be a group Owner to read audit events. Security findings require Ultimate.",
+ "label": "Personal Access Token (scope: api)",
+ "name": "token",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://gitlab.com/oauth/authorize",
+ "scopes": [
+ "api",
+ "read_api"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://gitlab.com/oauth/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "saas",
+ "connector_id": "google_workspace",
+ "connector_name": "Google Workspace",
+ "description": "Google Workspace audit logs (login, admin, drive, token, mobile) via the Admin SDK Reports API. Requires a service account with domain-wide delegation and an admin email to impersonate.",
+ "docs_url": "/docs/connectors/google-workspace",
+ "fields": [
+ {
+ "help_text": "The Google Workspace super-admin to impersonate via domain-wide delegation. The service account's client_id must be authorized in the Admin Console with the admin.reports.audit.readonly scope.",
+ "label": "Super-admin email",
+ "name": "admin_email",
+ "placeholder": "[email protected]",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Paste the full JSON key file. Encrypted at rest by the credential vault.",
+ "label": "Service account JSON key",
+ "name": "service_account_json",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "scopes": [
+ "https://www.googleapis.com/auth/admin.reports.audit.readonly"
+ ],
+ "supported_in_hosted": false,
+ "token_url": "https://oauth2.googleapis.com/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "enrich_ioc"
+ ],
+ "category": "saas",
+ "connector_id": "greynoise",
+ "connector_name": "GreyNoise",
+ "description": "GreyNoise threat intelligence \u2014 malicious IP observations (GNQL) as alerts.",
+ "docs_url": "/docs/connectors/greynoise",
+ "fields": [
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "classification:malicious last_seen:1d",
+ "help_text": "GreyNoise Query Language filter used to pull observations.",
+ "label": "GNQL query",
+ "name": "query",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pivot_ip",
+ "block_ip"
+ ],
+ "category": "network",
+ "connector_id": "imperva",
+ "connector_name": "Imperva Cloud WAF",
+ "description": "Imperva Cloud WAF (Incapsula) security events / blocked attacks as alerts.",
+ "docs_url": "/docs/connectors/imperva",
+ "fields": [
+ {
+ "label": "API ID",
+ "name": "api_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Optional. Limit to one protected site.",
+ "label": "Site ID",
+ "name": "site_id",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "push_case",
+ "push_status"
+ ],
+ "category": "saas",
+ "connector_id": "jira",
+ "connector_name": "Jira",
+ "description": "Jira Cloud issues via the REST API v3.",
+ "docs_url": "/docs/connectors/jira",
+ "fields": [
+ {
+ "label": "Jira Base URL",
+ "name": "base_url",
+ "placeholder": "https://yourorg.atlassian.net",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Email",
+ "name": "email",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://auth.atlassian.com/authorize",
+ "scopes": [
+ "read:jira-work",
+ "read:jira-user",
+ "write:jira-work",
+ "manage:jira-webhook",
+ "offline_access"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://auth.atlassian.com/oauth/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pivot_user"
+ ],
+ "category": "iam",
+ "connector_id": "jumpcloud",
+ "connector_name": "JumpCloud",
+ "description": "JumpCloud Directory Insights \u2014 authentication and admin events as alerts.",
+ "docs_url": "/docs/connectors/jumpcloud",
+ "fields": [
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts"
+ ],
+ "category": "cloud",
+ "connector_id": "kubernetes_audit",
+ "connector_name": "Kubernetes Audit Logs",
+ "description": "Kubernetes apiserver audit logs. Supports two delivery modes: webhook (apiserver pushes events to AiSOC's inbox) and file_tail (AiSOC tails a local audit log file forward from a byte cursor). Powers cluster-level detections under detections/cloud/kubernetes-*.yaml.",
+ "docs_url": "/docs/connectors/kubernetes-audit",
+ "fields": [
+ {
+ "default": "webhook",
+ "help_text": "Webhook is the right choice for managed clusters (EKS/GKE/AKS). File tail is the right choice for self-hosted clusters where you can mount the audit log path into the AiSOC connector pod.",
+ "label": "Delivery mode",
+ "name": "mode",
+ "options": [
+ {
+ "label": "Webhook (apiserver pushes)",
+ "value": "webhook"
+ },
+ {
+ "label": "File tail (read local audit log)",
+ "value": "file_tail"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "help_text": "Human-readable cluster name. Surfaced on every normalised event so detections and investigations can filter to a single cluster.",
+ "label": "Cluster name",
+ "name": "cluster_name",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Bound inbox token created with the ``k8s-audit`` template attached. Configure your apiserver AuditSink / --audit-webhook-config-file to POST to ``/v1/inbox/<this-token>``.",
+ "label": "Inbox token (webhook mode only)",
+ "name": "inbox_token",
+ "required": false,
+ "type": "secret"
+ },
+ {
+ "default": "/var/log/kubernetes/audit/audit.log",
+ "help_text": "Absolute path to the apiserver audit log file inside the connector pod. Mount it read-only from the host or from a persistent volume the apiserver writes to.",
+ "label": "Audit log path (file_tail mode only)",
+ "name": "audit_log_path",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Optional override for where AiSOC stores its byte-position cursor. Defaults to ``<audit_log_path>.aisoc-cursor``. Use a writeable path \u2014 the connector pod needs to update this on every successful poll.",
+ "label": "Cursor file path (file_tail mode only)",
+ "name": "cursor_path",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_ip",
+ "enrich_vuln"
+ ],
+ "category": "cloud",
+ "connector_id": "lacework",
+ "connector_name": "Lacework",
+ "description": "Lacework cloud security platform. Pulls alerts (events) and supports compliance / configuration query.",
+ "docs_url": "/docs/connectors/lacework",
+ "fields": [
+ {
+ "help_text": "First label of your Lacework console URL: https://<account>.lacework.net",
+ "label": "Account subdomain",
+ "name": "account",
+ "placeholder": "yourcorp",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Subaccount (optional)",
+ "name": "subaccount",
+ "placeholder": "prod",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "label": "Access Key ID",
+ "name": "key_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Secret Key",
+ "name": "secret",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "llm_usage",
+ "connector_name": "AI / LLM Usage Audit",
+ "description": "Pull organization audit logs from OpenAI or Anthropic \u2014 API key creation, role grants, logging/MFA changes, project deletes. Pairs with the llm-* detection rules. Auth is an admin/audit-scoped API key.",
+ "docs_url": "/docs/connectors/llm_usage",
+ "fields": [
+ {
+ "label": "Provider",
+ "name": "provider",
+ "options": [
+ {
+ "label": "OpenAI",
+ "value": "openai"
+ },
+ {
+ "label": "Anthropic",
+ "value": "anthropic"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "label": "Admin / Audit API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "saas",
+ "connector_id": "m365_audit",
+ "connector_name": "Microsoft 365 Audit",
+ "description": "Microsoft 365 unified audit log (Azure AD, Exchange, SharePoint/OneDrive, Teams, Power BI) via the Office 365 Management Activity API. Requires ActivityFeed.Read on an Azure AD app registration.",
+ "docs_url": "/docs/connectors/m365-audit",
+ "fields": [
+ {
+ "label": "Tenant ID",
+ "name": "tenant_id",
+ "placeholder": "00000000-0000-0000-0000-000000000000",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Application (Client) ID",
+ "name": "client_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Client Secret",
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+ "scopes": [
+ "https://manage.office.com/ActivityFeed.Read"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs"
+ ],
+ "category": "siem",
+ "connector_id": "microsoft_sentinel",
+ "connector_name": "Microsoft Sentinel",
+ "description": "Microsoft Sentinel incidents via the Azure Security Insights REST API.",
+ "docs_url": "/docs/connectors/microsoft-sentinel",
+ "fields": [
+ {
+ "label": "Tenant ID",
+ "name": "tenant_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Client ID",
+ "name": "client_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Client Secret",
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "Subscription ID",
+ "name": "subscription_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Resource Group",
+ "name": "resource_group",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Workspace Name",
+ "name": "workspace",
+ "required": true,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit",
+ "pivot_user",
+ "enrich_domain"
+ ],
+ "category": "saas",
+ "connector_id": "mimecast",
+ "connector_name": "Mimecast",
+ "description": "Mimecast Email Security 2.0 API. Pulls held messages, SIEM events, and URL protect verdicts as alerts.",
+ "docs_url": "/docs/connectors/mimecast",
+ "fields": [
+ {
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "United States",
+ "value": "us"
+ },
+ {
+ "label": "Europe",
+ "value": "eu"
+ },
+ {
+ "label": "Germany",
+ "value": "de"
+ },
+ {
+ "label": "Australia",
+ "value": "au"
+ },
+ {
+ "label": "South Africa",
+ "value": "za"
+ },
+ {
+ "label": "United Kingdom",
+ "value": "uk"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "label": "Client ID",
+ "name": "client_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Client Secret",
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pivot_user",
+ "pivot_ip"
+ ],
+ "category": "network",
+ "connector_id": "netskope",
+ "connector_name": "Netskope",
+ "description": "Pull DLP / malware / anomaly / policy alerts from the Netskope REST API v2. Alert severity maps to the five-tier ladder; malware and DLP alerts are floored at high. Auth is a Netskope API v2 token.",
+ "docs_url": "/docs/connectors/netskope",
+ "fields": [
+ {
+ "label": "Tenant URL",
+ "name": "tenant_url",
+ "placeholder": "https://tenant.goskope.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API v2 Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "read_audit_trail",
+ "pivot_user"
+ ],
+ "category": "cloud",
+ "connector_id": "oci",
+ "connector_name": "Oracle Cloud Infrastructure",
+ "description": "Oracle Cloud Infrastructure audit events. Polls the OCI audit service per region using request-signed API calls (tenancy + user OCID + RSA key).",
+ "docs_url": "/docs/connectors/oci",
+ "fields": [
+ {
+ "label": "Tenancy OCID",
+ "name": "tenancy_ocid",
+ "placeholder": "ocid1.tenancy.oc1..",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "User OCID",
+ "name": "user_ocid",
+ "placeholder": "ocid1.user.oc1..",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Root compartment OCID",
+ "name": "compartment_ocid",
+ "placeholder": "ocid1.compartment.oc1..",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API key fingerprint",
+ "name": "fingerprint",
+ "placeholder": "aa:bb:cc:..",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "PEM-encoded RSA private key paired with the fingerprint above.",
+ "label": "API private key (PEM)",
+ "name": "private_key_pem",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "US East (Ashburn)",
+ "value": "us-ashburn-1"
+ },
+ {
+ "label": "US West (Phoenix)",
+ "value": "us-phoenix-1"
+ },
+ {
+ "label": "Germany Central (Frankfurt)",
+ "value": "eu-frankfurt-1"
+ },
+ {
+ "label": "Netherlands NW (Amsterdam)",
+ "value": "eu-amsterdam-1"
+ },
+ {
+ "label": "UK South (London)",
+ "value": "uk-london-1"
+ },
+ {
+ "label": "Japan East (Tokyo)",
+ "value": "ap-tokyo-1"
+ },
+ {
+ "label": "India West (Mumbai)",
+ "value": "ap-mumbai-1"
+ },
+ {
+ "label": "Australia East (Sydney)",
+ "value": "ap-sydney-1"
+ },
+ {
+ "label": "Canada Southeast (Toronto)",
+ "value": "ca-toronto-1"
+ },
+ {
+ "label": "Saudi Arabia West (Jeddah)",
+ "value": "me-jeddah-1"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "disable_user",
+ "reset_password",
+ "suspend_session",
+ "force_mfa",
+ "revoke_session"
+ ],
+ "category": "iam",
+ "connector_id": "okta",
+ "connector_name": "Okta Identity",
+ "description": "Okta system log events (auth, MFA, account locks, blocked requests).",
+ "docs_url": "/docs/connectors/okta",
+ "fields": [
+ {
+ "label": "Okta Domain",
+ "name": "domain",
+ "placeholder": "https://yourorg.okta.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "{domain}/oauth2/v1/authorize",
+ "scopes": [
+ "okta.logs.read",
+ "okta.users.read",
+ "okta.groups.read",
+ "offline_access"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "{domain}/oauth2/v1/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "iam",
+ "connector_id": "onepassword",
+ "connector_name": "1Password Events",
+ "description": "1Password sign-in attempts via the Events Reporting API.",
+ "docs_url": "/docs/connectors/onepassword",
+ "fields": [
+ {
+ "label": "API Token (Bearer)",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "https://events.1password.com",
+ "help_text": "Override only for 1Password Business accounts on a non-default region.",
+ "label": "Events API Base URL",
+ "name": "base_url",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "opsgenie",
+ "connector_name": "Opsgenie",
+ "description": "Opsgenie on-call platform. Pulls alerts and tenant audit log events (API key issuance, role changes, integration edits) via the REST API. Choose the region matching your Opsgenie account.",
+ "docs_url": "/docs/connectors/opsgenie",
+ "fields": [
+ {
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "us",
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "US (api.opsgenie.com)",
+ "value": "us"
+ },
+ {
+ "label": "EU (api.eu.opsgenie.com)",
+ "value": "eu"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ }
+ ],
+ "oauth": {
+ "supported_in_hosted": false
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "cloud",
+ "connector_id": "orca",
+ "connector_name": "Orca Security",
+ "description": "Orca Security CNAPP. Pulls open alerts across workload, container, cloud configuration, identity, and data risk surfaces from the unified /api/alerts REST endpoint.",
+ "docs_url": "/docs/connectors/orca",
+ "fields": [
+ {
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "https://api.orcasecurity.io",
+ "help_text": "Override only if your tenant lives on a region-specific Orca endpoint. The default works for the standard commercial cloud.",
+ "label": "API URL",
+ "name": "api_url",
+ "placeholder": "https://api.orcasecurity.io",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_logs",
+ "query_logs",
+ "query_processes",
+ "pivot_host"
+ ],
+ "category": "edr",
+ "connector_id": "osctrl",
+ "connector_name": "osctrl",
+ "description": "osctrl \u2014 open-source osquery fleet manager. Pulls query results and node telemetry from the osctrl admin API.",
+ "docs_url": "/docs/connectors/osctrl",
+ "fields": [
+ {
+ "help_text": "Base URL of the osctrl admin server (no trailing slash). Use https in production.",
+ "label": "osctrl Admin URL",
+ "name": "base_url",
+ "placeholder": "https://osctrl.example.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "Long-lived admin token issued from the osctrl UI under Manage Users -> generate token.",
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "prod",
+ "help_text": "osctrl environment to scope queries to (e.g. 'prod', 'corp'). Required for distributed queries.",
+ "label": "Environment Name",
+ "name": "environment",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS Certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "pagerduty",
+ "connector_name": "PagerDuty",
+ "description": "PagerDuty on-call platform. Pulls incident lifecycle events and tenant audit records (role changes, integration edits, API key issuance) via the REST API. Requires a read-only REST API key.",
+ "docs_url": "/docs/connectors/pagerduty",
+ "fields": [
+ {
+ "help_text": "Generate under Integrations \u2192 API Access Keys. Read-only access is sufficient.",
+ "label": "REST API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Your acme.pagerduty.com subdomain. Used to build clickable links in normalised events; not required for ingestion.",
+ "label": "Subdomain (optional)",
+ "name": "subdomain",
+ "placeholder": "acme",
+ "required": false,
+ "type": "string"
+ }
+ ],
+ "oauth": {
+ "authorize_url": "https://app.pagerduty.com/oauth/authorize",
+ "scopes": [
+ "read"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://identity.pagerduty.com/oauth/token"
+ }
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "cloud",
+ "connector_id": "prisma_cloud",
+ "connector_name": "Prisma Cloud",
+ "description": "Prisma Cloud cloud security platform. Pulls open alerts across CSPM, CWPP, CIEM, and DSPM surfaces via the v1 REST API.",
+ "docs_url": "/docs/connectors/prisma-cloud",
+ "fields": [
+ {
+ "help_text": "Region-specific base URL of the Prisma Cloud REST API. See Prisma Cloud \u2192 System \u2192 API Endpoints for the value for your tenant (e.g. ``api2.eu``, ``api.gov``).",
+ "label": "API URL",
+ "name": "api_url",
+ "placeholder": "https://api.prismacloud.io",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Access Key ID",
+ "name": "access_key_id",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Secret Key",
+ "name": "secret_key",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "help_text": "Tenant-specific Compute (Twistlock) API base URL. Leave blank \u2014 v7.1.0 only consumes the unified ``/alert`` endpoint.",
+ "label": "Compute API URL (optional)",
+ "name": "compute_url",
+ "placeholder": "https://us-east1.cloud.twistlock.com/<tenant-id>",
+ "required": false,
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "saas",
+ "connector_id": "proofpoint",
+ "connector_name": "Proofpoint TAP",
+ "description": "Proofpoint Targeted Attack Protection \u2014 blocked messages via the SIEM API.",
+ "docs_url": "/docs/connectors/proofpoint",
+ "fields": [
+ {
+ "label": "Service Principal",
+ "name": "service_principal",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Service Secret",
+ "name": "service_secret",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs"
+ ],
+ "category": "siem",
+ "connector_id": "qradar",
+ "connector_name": "IBM QRadar",
+ "description": "Pull open offenses from IBM QRadar via the REST API (/api/siem/offenses). Offense magnitude (1-10) maps to the five-tier severity ladder. Auth is a QRadar SEC token.",
+ "docs_url": "/docs/connectors/qradar",
+ "fields": [
+ {
+ "label": "Console URL",
+ "name": "console_url",
+ "placeholder": "https://qradar.example.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "help_text": "QRadar authorized-service SEC token.",
+ "label": "SEC Token",
+ "name": "sec_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "help_text": "Disable only for consoles using an internal/self-signed CA.",
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "enrich_vuln",
+ "enrich_asset"
+ ],
+ "category": "cloud",
+ "connector_id": "qualys",
+ "connector_name": "Qualys VMDR",
+ "description": "Qualys Vulnerability Management (VMDR) host detections as alerts.",
+ "docs_url": "/docs/connectors/qualys",
+ "fields": [
+ {
+ "label": "API URL",
+ "name": "base_url",
+ "placeholder": "https://qualysapi.qg2.apps.qualys.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Username",
+ "name": "username",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "API Password",
+ "name": "password",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_user"
+ ],
+ "category": "siem",
+ "connector_id": "rapid7_insightidr",
+ "connector_name": "Rapid7 InsightIDR",
+ "description": "Rapid7 InsightIDR cloud SIEM/XDR. Pulls investigations and supports log search across collected sources.",
+ "docs_url": "/docs/connectors/rapid7-insightidr",
+ "fields": [
+ {
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "United States (us)",
+ "value": "us"
+ },
+ {
+ "label": "United States 2 (us2)",
+ "value": "us2"
+ },
+ {
+ "label": "United States 3 (us3)",
+ "value": "us3"
+ },
+ {
+ "label": "Europe (eu)",
+ "value": "eu"
+ },
+ {
+ "label": "Canada (ca)",
+ "value": "ca"
+ },
+ {
+ "label": "Australia (au)",
+ "value": "au"
+ },
+ {
+ "label": "Asia Pacific (ap)",
+ "value": "ap"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "label": "Insight API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "query_logs",
+ "pivot_user",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "salesforce",
+ "connector_name": "Salesforce",
+ "description": "Salesforce Event Monitoring + Setup Audit Trail. Pulls EventLogFile entries (logins, API usage, report exports) and SetupAuditTrail (admin config changes).",
+ "docs_url": "/docs/connectors/salesforce",
+ "fields": [
+ {
+ "label": "My Domain URL",
+ "name": "instance_url",
+ "placeholder": "https://yourcorp.my.salesforce.com",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Connected App Consumer Key",
+ "name": "client_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "secret_key",
- "type": "secret",
- "label": "Secret Key",
- "required": true
+ "label": "Connected App Consumer Secret",
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
},
{
- "name": "api_hostname",
- "type": "string",
- "label": "API Hostname",
- "required": true,
- "placeholder": "api-XXXXXXXX.duosecurity.com"
+ "help_text": "Provided automatically when you connect via OAuth.",
+ "label": "Refresh Token",
+ "name": "refresh_token",
+ "required": false,
+ "type": "secret"
}
],
- "docs_url": "/docs/connectors/duo-security"
+ "oauth": {
+ "authorize_url": "https://login.salesforce.com/services/oauth2/authorize",
+ "scopes": [
+ "api",
+ "refresh_token",
+ "offline_access"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://login.salesforce.com/services/oauth2/token"
+ }
},
{
- "connector_id": "elastic",
- "connector_name": "Elastic SIEM",
+ "capabilities": [
+ "pull_alerts",
+ "pivot_user"
+ ],
"category": "siem",
- "description": "Elastic Security via the ES|QL search API. Federated-search ready.",
+ "connector_id": "securonix",
+ "connector_name": "Securonix",
+ "description": "Pull incidents from Securonix Next-Gen SIEM / UEBA. Incident priority (Low/Medium/High/Critical) maps directly to the five-tier severity ladder. Auth is a tenant API token.",
+ "docs_url": "/docs/connectors/securonix",
"fields": [
{
- "name": "base_url",
- "type": "string",
- "label": "Elasticsearch URL",
+ "label": "Tenant URL",
+ "name": "tenant_url",
+ "placeholder": "https://tenant.securonix.net/Snypr",
"required": true,
- "placeholder": "https://elastic.example.com:9200",
- "help_text": "Cluster endpoint, not Kibana."
+ "type": "string"
},
{
- "name": "api_key",
- "type": "secret",
- "label": "API Key",
- "required": false
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
},
{
- "name": "username",
- "type": "string",
- "label": "Username",
- "required": false
- },
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "isolate_host",
+ "unisolate_host",
+ "quarantine_file"
+ ],
+ "category": "edr",
+ "connector_id": "sentinelone",
+ "connector_name": "SentinelOne",
+ "description": "SentinelOne threat detections via the Management Console API.",
+ "docs_url": "/docs/connectors/sentinelone",
+ "fields": [
{
- "name": "password",
- "type": "secret",
- "label": "Password",
- "required": false
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
},
{
- "name": "index",
- "type": "string",
- "label": "Default Index Pattern",
- "required": false,
- "default": "logs-*"
+ "label": "Base URL",
+ "name": "base_url",
+ "placeholder": "https://usea1-partners.sentinelone.net",
+ "required": true,
+ "type": "string"
},
{
- "name": "ssl_verify",
- "type": "boolean",
- "label": "Verify SSL certificate",
+ "help_text": "Optional. Limits results to a single site.",
+ "label": "Site ID",
+ "name": "site_id",
"required": false,
- "default": true,
- "help_text": "Disable only for self-signed certificates in private deployments."
+ "type": "string"
}
- ],
- "docs_url": "/docs/connectors/elastic"
+ ]
},
{
- "connector_id": "gcp_cloud_audit",
- "connector_name": "GCP Cloud Audit Logs",
- "category": "cloud",
- "description": "Google Cloud Audit Logs (Admin Activity, Data Access, System Event) via Cloud Logging. Requires a service account with roles/logging.viewer (and roles/logging.privateLogViewer for Data Access logs).",
+ "capabilities": [
+ "pull_alerts",
+ "push_case",
+ "push_status"
+ ],
+ "category": "saas",
+ "connector_id": "servicenow",
+ "connector_name": "ServiceNow",
+ "description": "ServiceNow incidents via the Table API.",
+ "docs_url": "/docs/connectors/servicenow",
"fields": [
{
- "name": "project_id",
- "type": "string",
- "label": "Project ID",
+ "label": "Instance URL",
+ "name": "instance_url",
+ "placeholder": "https://yourinstance.service-now.com",
"required": true,
- "placeholder": "my-prod-project",
- "help_text": "The GCP project to read audit logs from. Use a log-sink aggregator project if you've consolidated."
+ "type": "string"
},
{
- "name": "service_account_json",
- "type": "secret",
- "label": "Service account JSON key",
+ "label": "Username",
+ "name": "username",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Password",
+ "name": "password",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_audit",
+ "pivot_user",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "slack_audit",
+ "connector_name": "Slack Audit Logs",
+ "description": "Slack Enterprise Grid Audit Logs. Pulls workspace and org-level audit events (logins, channel changes, file shares, app installs). Requires the auditlogs:read scope on an Org-level Slack app.",
+ "docs_url": "/docs/connectors/slack-audit",
+ "fields": [
+ {
+ "help_text": "OrgLevel OAuth bot token with the auditlogs:read scope, issued from a Slack Enterprise Grid app.",
+ "label": "Org-level access token",
+ "name": "access_token",
"required": true,
- "help_text": "Paste the full JSON key file. It will be encrypted at rest by the credential vault."
+ "type": "secret"
}
],
- "docs_url": "/docs/connectors/gcp-cloud-audit",
"oauth": {
- "supported_in_hosted": false,
- "token_url": "https://oauth2.googleapis.com/token",
+ "authorize_url": "https://slack.com/oauth/v2/authorize",
"scopes": [
- "https://www.googleapis.com/auth/logging.read"
- ]
+ "auditlogs:read"
+ ],
+ "supported_in_hosted": true,
+ "token_url": "https://slack.com/api/oauth.v2.access"
}
},
{
- "connector_id": "gcp_scc",
- "connector_name": "GCP Security Command Center",
- "category": "cloud",
- "description": "Google Cloud Security Command Center findings. Requires a service account with roles/securitycenter.findingsViewer at the organization or folder level.",
+ "capabilities": [
+ "pull_audit",
+ "query_logs",
+ "read_audit_trail",
+ "pivot_user"
+ ],
+ "category": "saas",
+ "connector_id": "snowflake",
+ "connector_name": "Snowflake Audit",
+ "description": "Snowflake account_usage audit. Polls login_history and query_history for authentication failures, role grants, and data-exfil-shaped query patterns via the SQL API with key-pair JWT authentication.",
+ "docs_url": "/docs/connectors/snowflake",
"fields": [
{
- "name": "organization_id",
- "type": "string",
- "label": "Organization ID",
+ "help_text": "Account locator from your Snowflake URL.",
+ "label": "Account locator",
+ "name": "account",
+ "placeholder": "abc12345.us-east-1",
"required": true,
- "placeholder": "1234567890",
- "help_text": "Numeric GCP organization ID. SCC is org-scoped; the service account must have findingsViewer at this level (or on a parent folder/source)."
+ "type": "string"
},
{
- "name": "service_account_json",
- "type": "secret",
- "label": "Service account JSON key",
+ "help_text": "Snowflake user the JWT identifies.",
+ "label": "Service user",
+ "name": "user",
+ "placeholder": "AISOC_SVC",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Role",
+ "name": "role",
+ "placeholder": "ACCOUNTADMIN",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "label": "Warehouse",
+ "name": "warehouse",
+ "placeholder": "AUDIT_WH",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "PKCS#8 PEM-encoded RSA private key paired with the public key registered on the service user. Encrypted at rest by CredentialVault.",
+ "label": "RSA private key (PKCS#8 PEM)",
+ "name": "private_key_pem",
"required": true,
- "help_text": "Paste the full JSON key file. It will be encrypted at rest by the credential vault."
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/gcp-scc",
- "oauth": {
- "supported_in_hosted": false,
- "token_url": "https://oauth2.googleapis.com/token",
- "scopes": [
- "https://www.googleapis.com/auth/cloud-platform"
- ]
- }
+ ]
},
{
- "connector_id": "github",
- "connector_name": "GitHub",
+ "capabilities": [
+ "pull_alerts"
+ ],
"category": "vcs",
- "description": "GitHub organization audit log and Code Scanning alerts. Requires a token with read:audit_log and security_events scopes (fine-grained PAT or GitHub App installation token).",
+ "connector_id": "snyk",
+ "connector_name": "Snyk",
+ "description": "Snyk vulnerability issues via the REST API.",
+ "docs_url": "/docs/connectors/snyk",
"fields": [
{
- "name": "organization",
- "type": "string",
- "label": "Organization slug",
+ "label": "API Token",
+ "name": "api_token",
"required": true,
- "placeholder": "my-org"
+ "type": "secret"
},
{
- "name": "token",
- "type": "secret",
- "label": "Personal Access Token or App Installation Token",
+ "help_text": "Snyk organization UUID (Settings \u2192 General \u2192 Organization ID).",
+ "label": "Organization ID",
+ "name": "org_id",
"required": true,
- "help_text": "Fine-grained PAT recommended. Required scopes: read:audit_log, security_events. For GitHub App auth, paste a fresh installation token."
+ "type": "string"
+ },
+ {
+ "default": "https://api.snyk.io",
+ "help_text": "Override for Snyk Enterprise on-prem or EU tenants.",
+ "label": "Base URL",
+ "name": "base_url",
+ "required": false,
+ "type": "string"
}
- ],
- "docs_url": "/docs/connectors/github",
- "oauth": {
- "supported_in_hosted": false,
- "authorize_url": "https://github.com/login/oauth/authorize",
- "token_url": "https://github.com/login/oauth/access_token",
- "scopes": [
- "read:audit_log",
- "security_events"
- ]
- }
+ ]
},
{
- "connector_id": "google_workspace",
- "connector_name": "Google Workspace",
- "category": "saas",
- "description": "Google Workspace audit logs (login, admin, drive, token, mobile) via the Admin SDK Reports API. Requires a service account with domain-wide delegation and an admin email to impersonate.",
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "search_siem",
+ "create_notable_event"
+ ],
+ "category": "siem",
+ "connector_id": "splunk",
+ "connector_name": "Splunk SIEM",
+ "description": "Splunk Enterprise / Cloud notable events via the REST API.",
+ "docs_url": "/docs/connectors/splunk",
"fields": [
{
- "name": "admin_email",
- "type": "string",
- "label": "Super-admin email",
+ "help_text": "Management port (default 8089), not the web UI port.",
+ "label": "Splunk URL",
+ "name": "base_url",
+ "placeholder": "https://splunk.example.com:8089",
"required": true,
- "placeholder": "[email protected]",
- "help_text": "The Google Workspace super-admin to impersonate via domain-wide delegation. The service account's client_id must be authorized in the Admin Console with the admin.reports.audit.readonly scope."
+ "type": "string"
},
{
- "name": "service_account_json",
- "type": "secret",
- "label": "Service account JSON key",
+ "label": "HEC / API Token",
+ "name": "token",
"required": true,
- "help_text": "Paste the full JSON key file. Encrypted at rest by the credential vault."
+ "type": "secret"
+ },
+ {
+ "default": "AiSOC_Alerts",
+ "help_text": "Dispatched via the saved-search endpoint. Leave blank to search index=notable.",
+ "label": "Saved Search Name",
+ "name": "saved_search",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "default": 500,
+ "help_text": "Number of results fetched per page. Polling pages through all results \u2014 there is no 100-event cap.",
+ "label": "Results page size",
+ "name": "page_size",
+ "required": false,
+ "type": "number"
+ },
+ {
+ "default": true,
+ "help_text": "Disable only for self-signed certificates in private deployments.",
+ "label": "Verify SSL certificate",
+ "name": "ssl_verify",
+ "required": false,
+ "type": "boolean"
}
- ],
- "docs_url": "/docs/connectors/google-workspace",
- "oauth": {
- "supported_in_hosted": false,
- "token_url": "https://oauth2.googleapis.com/token",
- "scopes": [
- "https://www.googleapis.com/auth/admin.reports.audit.readonly"
- ]
- }
+ ]
},
{
- "connector_id": "jira",
- "connector_name": "Jira",
+ "capabilities": [
+ "pull_alerts",
+ "pivot_user",
+ "quarantine_file"
+ ],
"category": "saas",
- "description": "Jira Cloud issues via the REST API v3.",
+ "connector_id": "sublime_security",
+ "connector_name": "Sublime Security",
+ "description": "Sublime Security inbound-email detections. Polls /v1/messages for malicious + suspicious verdicts and links them to the originating mailbox + sender.",
+ "docs_url": "/docs/connectors/sublime_security",
"fields": [
{
+ "default": "https://api.platform.sublimesecurity.com",
+ "help_text": "Override only for self-hosted / regional Sublime tenants.",
+ "label": "API base URL",
"name": "base_url",
- "type": "string",
- "label": "Jira Base URL",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "help_text": "Sublime \u2192 Settings \u2192 API \u2192 Create token.",
+ "label": "API key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_user"
+ ],
+ "category": "siem",
+ "connector_id": "sumo_logic",
+ "connector_name": "Sumo Logic Cloud SIEM",
+ "description": "Sumo Logic Cloud SIEM Enterprise (CSE). Pulls insights and signals, and supports log search jobs across the platform.",
+ "docs_url": "/docs/connectors/sumo-logic",
+ "fields": [
+ {
+ "label": "Deployment",
+ "name": "deployment",
+ "options": [
+ {
+ "label": "United States (us1)",
+ "value": "us1"
+ },
+ {
+ "label": "United States 2 (us2)",
+ "value": "us2"
+ },
+ {
+ "label": "Europe (eu)",
+ "value": "eu"
+ },
+ {
+ "label": "Australia (au)",
+ "value": "au"
+ },
+ {
+ "label": "Germany (de)",
+ "value": "de"
+ },
+ {
+ "label": "Japan (jp)",
+ "value": "jp"
+ },
+ {
+ "label": "Canada (ca)",
+ "value": "ca"
+ },
+ {
+ "label": "India (in)",
+ "value": "in"
+ },
+ {
+ "label": "Sumo Logic FedRAMP (fed)",
+ "value": "fed"
+ }
+ ],
"required": true,
- "placeholder": "https://yourorg.atlassian.net"
+ "type": "select"
},
{
- "name": "email",
- "type": "string",
- "label": "Email",
- "required": true
+ "label": "Access ID",
+ "name": "access_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "api_token",
- "type": "secret",
+ "label": "Access Key",
+ "name": "access_key",
+ "required": true,
+ "type": "secret"
+ }
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_logs",
+ "pivot_host",
+ "read_audit_trail"
+ ],
+ "category": "siem",
+ "connector_id": "sysdig",
+ "connector_name": "Sysdig Secure",
+ "description": "Sysdig Secure runtime / cloud detection events. Polls the Secure Events API for Falco-style policy hits across Kubernetes workloads and cloud accounts.",
+ "docs_url": "/docs/connectors/sysdig",
+ "fields": [
+ {
+ "label": "Sysdig region",
+ "name": "region",
+ "options": [
+ {
+ "label": "US-East (secure.sysdig.com)",
+ "value": "us1"
+ },
+ {
+ "label": "US-West (us2.app.sysdig.com)",
+ "value": "us2"
+ },
+ {
+ "label": "US3 (app.us3.sysdig.com)",
+ "value": "us3"
+ },
+ {
+ "label": "US4 (app.us4.sysdig.com)",
+ "value": "us4"
+ },
+ {
+ "label": "EU-Frankfurt (eu1.app.sysdig.com)",
+ "value": "eu1"
+ },
+ {
+ "label": "Australia (app.au1.sysdig.com)",
+ "value": "au1"
+ },
+ {
+ "label": "Middle East (app.me2.sysdig.com)",
+ "value": "me2"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "help_text": "Sysdig Secure API token. Settings \u2192 API \u2192 Tokens. Needs read access to Secure Events.",
"label": "API Token",
- "required": true
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
}
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pull_logs"
],
- "docs_url": "/docs/connectors/jira"
+ "category": "network",
+ "connector_id": "syslog_cef",
+ "connector_name": "Syslog / CEF",
+ "description": "Generic listener for appliances that speak syslog + ArcSight CEF. A syslog receiver writes messages to a spool endpoint; this connector parses the CEF header + extension and maps CEF severity (0-10) to the five-tier ladder. Non-CEF lines are ingested at info.",
+ "docs_url": "/docs/connectors/syslog_cef",
+ "fields": [
+ {
+ "label": "Spool URL",
+ "name": "spool_url",
+ "placeholder": "https://syslog-receiver.internal/spool",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Spool token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
},
{
- "connector_id": "m365_audit",
- "connector_name": "Microsoft 365 Audit",
- "category": "saas",
- "description": "Microsoft 365 unified audit log (Azure AD, Exchange, SharePoint/OneDrive, Teams, Power BI) via the Office 365 Management Activity API. Requires ActivityFeed.Read on an Azure AD app registration.",
+ "capabilities": [
+ "pull_audit"
+ ],
+ "category": "network",
+ "connector_id": "tailscale",
+ "connector_name": "Tailscale",
+ "description": "Tailscale zero-trust network audit logs. Captures every ACL change, device approval / removal, key rotation, user role change, and admin configuration mutation in your tailnet.",
+ "docs_url": "/docs/connectors/tailscale",
"fields": [
{
- "name": "tenant_id",
- "type": "string",
- "label": "Tenant ID",
+ "help_text": "Your tailnet name (the organisation slug shown in the Tailscale admin console, e.g. 'example.com'). Use '-' to use the default tailnet associated with the API key / OAuth token.",
+ "label": "Tailnet",
+ "name": "tailnet",
+ "placeholder": "example.com or -",
"required": true,
- "placeholder": "00000000-0000-0000-0000-000000000000"
+ "type": "string"
+ },
+ {
+ "help_text": "Tailscale API key (starts with 'tskey-api-'). Use either this *or* the OAuth client credentials below \u2014 not both.",
+ "label": "API Key (optional if using OAuth)",
+ "name": "api_key",
+ "required": false,
+ "type": "secret"
},
{
+ "help_text": "OAuth 2.0 client ID from the Tailscale admin console. Required scope: 'audit:read'.",
+ "label": "OAuth Client ID (optional)",
"name": "client_id",
- "type": "string",
- "label": "Application (Client) ID",
- "required": true
+ "required": false,
+ "type": "string"
},
{
+ "help_text": "OAuth 2.0 client secret. Only needed when using client-credential flow instead of an API key.",
+ "label": "OAuth Client Secret (optional)",
"name": "client_secret",
- "type": "secret",
- "label": "Client Secret",
- "required": true
+ "required": false,
+ "type": "secret"
}
],
- "docs_url": "/docs/connectors/m365-audit",
"oauth": {
- "supported_in_hosted": true,
- "authorize_url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
- "token_url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+ "authorize_url": "https://login.tailscale.com/admin/settings/oauth",
"scopes": [
- "https://manage.office.com/ActivityFeed.Read"
- ]
+ "audit:read"
+ ],
+ "supported_in_hosted": false,
+ "token_url": "https://api.tailscale.com/api/v2/oauth/token"
}
},
{
- "connector_id": "microsoft_sentinel",
- "connector_name": "Microsoft Sentinel",
- "category": "siem",
- "description": "Microsoft Sentinel incidents via the Azure Security Insights REST API.",
+ "capabilities": [
+ "pull_alerts",
+ "pivot_host",
+ "pivot_ip",
+ "enrich_vuln",
+ "enrich_asset"
+ ],
+ "category": "cloud",
+ "connector_id": "tenable_io",
+ "connector_name": "Tenable.io",
+ "description": "Tenable.io / Tenable Vulnerability Management. Pulls vulnerability findings as alerts and exposes asset and vulnerability enrichment for the agent.",
+ "docs_url": "/docs/connectors/tenable-io",
"fields": [
{
- "name": "tenant_id",
- "type": "string",
- "label": "Tenant ID",
- "required": true
- },
- {
- "name": "client_id",
- "type": "string",
- "label": "Client ID",
- "required": true
- },
- {
- "name": "client_secret",
- "type": "secret",
- "label": "Client Secret",
- "required": true
- },
- {
- "name": "subscription_id",
- "type": "string",
- "label": "Subscription ID",
- "required": true
- },
- {
- "name": "resource_group",
- "type": "string",
- "label": "Resource Group",
- "required": true
+ "label": "Access Key",
+ "name": "access_key",
+ "required": true,
+ "type": "string"
},
{
- "name": "workspace",
- "type": "string",
- "label": "Workspace Name",
- "required": true
+ "label": "Secret Key",
+ "name": "secret_key",
+ "required": true,
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/microsoft-sentinel"
+ ]
},
{
- "connector_id": "okta",
- "connector_name": "Okta Identity",
- "category": "iam",
- "description": "Okta system log events (auth, MFA, account locks, blocked requests).",
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts",
+ "read_audit_trail"
+ ],
+ "category": "saas",
+ "connector_id": "tines",
+ "connector_name": "Tines",
+ "description": "Tines automation platform. Pulls story / agent audit events and case lifecycle events via the Tines REST API. Requires a personal access token with at least read-only scope on the target tenant.",
+ "docs_url": "/docs/connectors/tines",
"fields": [
{
- "name": "domain",
- "type": "string",
- "label": "Okta Domain",
+ "help_text": "Your Tines tenant URL, including scheme. For self-hosted deployments use the full HTTPS URL of the Rails app.",
+ "label": "Tines tenant URL",
+ "name": "base_url",
+ "placeholder": "https://acme.tines.com",
"required": true,
- "placeholder": "https://yourorg.okta.com"
+ "type": "string"
},
{
+ "help_text": "Generate under Profile \u2192 Personal Access Tokens. Read-only scope is sufficient; the connector never writes back to Tines.",
+ "label": "Personal Access Token",
"name": "api_token",
- "type": "secret",
- "label": "API Token",
- "required": true
- }
- ],
- "docs_url": "/docs/connectors/okta"
- },
- {
- "connector_id": "onepassword",
- "connector_name": "1Password Events",
- "category": "iam",
- "description": "1Password sign-in attempts via the Events Reporting API.",
- "fields": [
- {
- "name": "api_token",
- "type": "secret",
- "label": "API Token (Bearer)",
- "required": true
+ "required": true,
+ "type": "secret"
},
{
- "name": "base_url",
- "type": "string",
- "label": "Events API Base URL",
+ "help_text": "Scope event ingestion to a single Team. Leave blank to ingest across all teams the token can see.",
+ "label": "Team ID (optional)",
+ "name": "team_id",
"required": false,
- "default": "https://events.1password.com",
- "help_text": "Override only for 1Password Business accounts on a non-default region."
+ "type": "string"
}
],
- "docs_url": "/docs/connectors/onepassword"
+ "oauth": {
+ "supported_in_hosted": false
+ }
},
{
- "connector_id": "proofpoint",
- "connector_name": "Proofpoint TAP",
+ "capabilities": [
+ "pull_audit",
+ "pull_alerts",
+ "read_audit_trail"
+ ],
"category": "saas",
- "description": "Proofpoint Targeted Attack Protection \u2014 blocked messages via the SIEM API.",
+ "connector_id": "torq",
+ "connector_name": "Torq",
+ "description": "Torq automation platform. Streams workflow execution outcomes and tenant audit events (workflow edits, credential changes, role assignments). Requires an API key pair (key_id + secret) issued under Settings \u2192 API Keys.",
+ "docs_url": "/docs/connectors/torq",
"fields": [
{
- "name": "service_principal",
- "type": "string",
- "label": "Service Principal",
- "required": true
+ "label": "API Key ID",
+ "name": "key_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "service_secret",
- "type": "secret",
- "label": "Service Secret",
- "required": true
+ "label": "API Key Secret",
+ "name": "key_secret",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "https://api.torq.io/public/v1",
+ "help_text": "Override only for regional or self-hosted Torq deployments. Leave blank for the SaaS default.",
+ "label": "API Base URL (advanced)",
+ "name": "base_url",
+ "placeholder": "https://api.torq.io/public/v1",
+ "required": false,
+ "type": "string"
}
],
- "docs_url": "/docs/connectors/proofpoint"
+ "oauth": {
+ "supported_in_hosted": false
+ }
},
{
- "connector_id": "sentinelone",
- "connector_name": "SentinelOne",
- "category": "edr",
- "description": "SentinelOne threat detections via the Management Console API.",
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "pivot_host",
+ "pivot_user"
+ ],
+ "category": "siem",
+ "connector_id": "trellix_helix",
+ "connector_name": "Trellix Helix",
+ "description": "Trellix Helix (formerly FireEye Helix) XDR \u2014 alerts feed plus MQL search over raw events. Customer ID is the slug shown in your Helix console URL after /helix/id/.",
+ "docs_url": "/docs/connectors/trellix-helix",
"fields": [
{
- "name": "api_token",
- "type": "secret",
- "label": "API Token",
- "required": true
+ "default": "https://apps.fireeye.com",
+ "help_text": "Most tenants use the default. EU customers may use a regional FQDN.",
+ "label": "Helix base URL",
+ "name": "base_url",
+ "placeholder": "https://apps.fireeye.com",
+ "required": true,
+ "type": "string"
},
{
- "name": "base_url",
- "type": "string",
- "label": "Base URL",
+ "help_text": "The slug between '/helix/id/' and '/' in your Helix console URL. Lowercase alphanumeric.",
+ "label": "Customer ID",
+ "name": "customer_id",
+ "placeholder": "abcd1234",
"required": true,
- "placeholder": "https://usea1-partners.sentinelone.net"
+ "type": "string"
},
{
- "name": "site_id",
- "type": "string",
- "label": "Site ID",
- "required": false,
- "help_text": "Optional. Limits results to a single site."
+ "help_text": "Generated under Configure \u2192 Authentication \u2192 API Keys.",
+ "label": "API Key",
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/sentinelone"
+ ]
},
{
- "connector_id": "servicenow",
- "connector_name": "ServiceNow",
- "category": "saas",
- "description": "ServiceNow incidents via the Table API.",
+ "capabilities": [
+ "pull_alerts",
+ "pull_audit",
+ "pivot_host",
+ "isolate_host",
+ "unisolate_host"
+ ],
+ "category": "edr",
+ "connector_id": "trend_vision_one",
+ "connector_name": "Trend Vision One",
+ "description": "Trend Micro Vision One XDR. Pulls Workbench alerts and OAT (Observed Attack Technique) detections. Supports endpoint isolation as an agent capability.",
+ "docs_url": "/docs/connectors/trend-vision-one",
"fields": [
{
- "name": "instance_url",
- "type": "string",
- "label": "Instance URL",
+ "help_text": "Vision One has region-specific hostnames; using the wrong one returns 401.",
+ "label": "Region",
+ "name": "region",
+ "options": [
+ {
+ "label": "United States",
+ "value": "us"
+ },
+ {
+ "label": "Europe",
+ "value": "eu"
+ },
+ {
+ "label": "India",
+ "value": "in"
+ },
+ {
+ "label": "Japan",
+ "value": "jp"
+ },
+ {
+ "label": "Singapore",
+ "value": "sg"
+ },
+ {
+ "label": "Australia",
+ "value": "au"
+ }
+ ],
"required": true,
- "placeholder": "https://yourinstance.service-now.com"
- },
- {
- "name": "username",
- "type": "string",
- "label": "Username",
- "required": true
+ "type": "select"
},
{
- "name": "password",
- "type": "secret",
- "label": "Password",
- "required": true
+ "help_text": "Bearer token issued from Vision One console: Administration \u2192 API Keys.",
+ "label": "API Token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/servicenow"
+ ]
},
{
- "connector_id": "snyk",
- "connector_name": "Snyk",
- "category": "vcs",
- "description": "Snyk vulnerability issues via the REST API.",
+ "capabilities": [
+ "pull_audit",
+ "read_audit_trail"
+ ],
+ "category": "iam",
+ "connector_id": "vault",
+ "connector_name": "HashiCorp Vault Audit",
+ "description": "HashiCorp Vault audit-device events. Vault audit logs are pushed by a sidecar tailing the file/socket device into the connectors service buffer; this connector drains the buffer per poll. test_connection verifies the cluster health and token policy via the Vault REST API.",
+ "docs_url": "/docs/connectors/vault",
"fields": [
{
- "name": "api_token",
- "type": "secret",
- "label": "API Token",
- "required": true
+ "help_text": "Cluster URL used by test_connection. Can be left blank to skip the live probe.",
+ "label": "Vault address",
+ "name": "vault_addr",
+ "placeholder": "https://vault.example.com:8200",
+ "required": false,
+ "type": "string"
},
{
- "name": "org_id",
- "type": "string",
- "label": "Organization ID",
- "required": true,
- "help_text": "Snyk organization UUID (Settings \u2192 General \u2192 Organization ID)."
+ "help_text": "Token with sys/audit list / sys/health read. Used only by test_connection \u2014 events flow via the audit-device sidecar, not through this token.",
+ "label": "Vault token (audit-list policy)",
+ "name": "vault_token",
+ "required": false,
+ "type": "secret"
},
{
- "name": "base_url",
- "type": "string",
- "label": "Base URL",
+ "help_text": "Optional. Sent as X-Vault-Namespace.",
+ "label": "Vault Enterprise namespace",
+ "name": "namespace",
"required": false,
- "default": "https://api.snyk.io",
- "help_text": "Override for Snyk Enterprise on-prem or EU tenants."
+ "type": "string"
+ },
+ {
+ "default": "5000",
+ "label": "Max buffered audit lines",
+ "name": "buffer_size",
+ "required": false,
+ "type": "string"
}
- ],
- "docs_url": "/docs/connectors/snyk"
+ ]
},
{
- "connector_id": "splunk",
- "connector_name": "Splunk SIEM",
+ "capabilities": [
+ "pull_alerts",
+ "query_logs",
+ "search_siem",
+ "pivot_host"
+ ],
"category": "siem",
- "description": "Splunk Enterprise / Cloud notable events via the REST API.",
+ "connector_id": "wazuh",
+ "connector_name": "Wazuh",
+ "description": "Wazuh \u2014 open-source XDR/SIEM. Pulls alerts from the Wazuh indexer (OpenSearch-compatible) and maps the 0-15 rule level onto the AiSOC severity ladder.",
+ "docs_url": "/docs/connectors/wazuh",
"fields": [
{
- "name": "base_url",
- "type": "string",
- "label": "Splunk URL",
+ "help_text": "Base URL of the Wazuh indexer (NOT the dashboard or manager). Default port is 9200.",
+ "label": "Wazuh Indexer URL",
+ "name": "indexer_url",
+ "placeholder": "https://wazuh.example.com:9200",
"required": true,
- "placeholder": "https://splunk.example.com:8089",
- "help_text": "Management port (default 8089), not the web UI port."
+ "type": "string"
},
{
- "name": "token",
- "type": "secret",
- "label": "HEC / API Token",
- "required": true
+ "help_text": "Indexer user with read access to wazuh-alerts-*. Create a dedicated read-only role in production.",
+ "label": "Indexer Username",
+ "name": "username",
+ "required": true,
+ "type": "string"
},
{
- "name": "saved_search",
- "type": "string",
- "label": "Saved Search Name",
+ "label": "Indexer Password",
+ "name": "password",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": "wazuh-alerts-*",
+ "help_text": "Override only if you have re-templated the default Wazuh index naming.",
+ "label": "Alert Index Pattern",
+ "name": "index_pattern",
"required": false,
- "default": "AiSOC_Alerts"
+ "type": "string"
},
{
- "name": "ssl_verify",
- "type": "boolean",
- "label": "Verify SSL certificate",
+ "default": 7,
+ "help_text": "Drop alerts with rule.level below this value at ingest. Default 7 keeps low-signal noise out of the lake; lower to 3 for full audit coverage.",
+ "label": "Minimum Rule Level",
+ "name": "min_rule_level",
"required": false,
+ "type": "number"
+ },
+ {
"default": true,
- "help_text": "Disable only for self-signed certificates in private deployments."
+ "help_text": "Disable only for self-signed lab clusters. Production deployments must install the CA chain.",
+ "label": "Verify TLS Certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
}
- ],
- "docs_url": "/docs/connectors/splunk"
+ ]
},
{
- "connector_id": "tailscale",
- "connector_name": "Tailscale",
- "category": "network",
- "description": "Tailscale zero-trust network audit logs. Captures every ACL change, device approval / removal, key rotation, user role change, and admin configuration mutation in your tailnet.",
+ "capabilities": [
+ "pull_alerts",
+ "pull_logs",
+ "pivot_host"
+ ],
+ "category": "edr",
+ "connector_id": "windows_event",
+ "connector_name": "Windows Event / Sysmon",
+ "description": "Pull Windows Security + Sysmon events from a Windows Event Forwarding (WEF) collector's JSON spool endpoint. Severity is derived from channel + Event ID (log clears, service installs, process injection floored appropriately).",
+ "docs_url": "/docs/connectors/windows_event",
"fields": [
{
- "name": "tailnet",
- "type": "string",
- "label": "Tailnet",
+ "label": "Collector spool URL",
+ "name": "collector_url",
+ "placeholder": "https://wef-collector.internal/spool",
"required": true,
- "placeholder": "example.com or -",
- "help_text": "Your tailnet name (the organisation slug shown in the Tailscale admin console, e.g. 'example.com'). Use '-' to use the default tailnet associated with the API key / OAuth token."
+ "type": "string"
},
{
- "name": "api_key",
- "type": "secret",
- "label": "API Key (optional if using OAuth)",
- "required": false,
- "help_text": "Tailscale API key (starts with 'tskey-api-'). Use either this *or* the OAuth client credentials below \u2014 not both."
- },
- {
- "name": "client_id",
- "type": "string",
- "label": "OAuth Client ID (optional)",
- "required": false,
- "help_text": "OAuth 2.0 client ID from the Tailscale admin console. Required scope: 'audit:read'."
+ "label": "Spool token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
},
{
- "name": "client_secret",
- "type": "secret",
- "label": "OAuth Client Secret (optional)",
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
"required": false,
- "help_text": "OAuth 2.0 client secret. Only needed when using client-credential flow instead of an API key."
+ "type": "boolean"
}
- ],
- "docs_url": "/docs/connectors/tailscale",
- "oauth": {
- "supported_in_hosted": false,
- "authorize_url": "https://login.tailscale.com/admin/settings/oauth",
- "token_url": "https://api.tailscale.com/api/v2/oauth/token",
- "scopes": [
- "audit:read"
- ]
- }
+ ]
},
{
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "cloud",
"connector_id": "wiz",
"connector_name": "Wiz",
- "category": "cloud",
"description": "Wiz cloud security issues via the GraphQL API.",
+ "docs_url": "/docs/connectors/wiz",
"fields": [
{
- "name": "client_id",
- "type": "string",
"label": "Client ID",
- "required": true
+ "name": "client_id",
+ "required": true,
+ "type": "string"
},
{
- "name": "client_secret",
- "type": "secret",
"label": "Client Secret",
- "required": true
+ "name": "client_secret",
+ "required": true,
+ "type": "secret"
},
{
- "name": "api_endpoint_url",
- "type": "string",
+ "help_text": "Your tenant's GraphQL API endpoint.",
"label": "API Endpoint URL",
- "required": true,
+ "name": "api_endpoint_url",
"placeholder": "https://api.us20.app.wiz.io/graphql",
- "help_text": "Your tenant's GraphQL API endpoint."
+ "required": true,
+ "type": "string"
},
{
- "name": "auth_url",
- "type": "string",
+ "default": "https://auth.app.wiz.io/oauth/token",
+ "help_text": "OAuth2 token endpoint. Override only for gov-cloud tenants.",
"label": "Auth URL",
+ "name": "auth_url",
"required": false,
- "default": "https://auth.app.wiz.io/oauth/token",
- "help_text": "OAuth2 token endpoint. Override only for gov-cloud tenants."
+ "type": "string"
}
+ ]
+ },
+ {
+ "capabilities": [
+ "pull_alerts",
+ "pivot_ip"
],
- "docs_url": "/docs/connectors/wiz"
+ "category": "ndr",
+ "connector_id": "zeek_suricata",
+ "connector_name": "Zeek / Suricata NDR",
+ "description": "Pull network-detection events from a Zeek (notice.log) or Suricata (eve.json alert) sensor's JSON spool. Suricata alert severity (1=highest) and Zeek notice types map to the five-tier ladder.",
+ "docs_url": "/docs/connectors/zeek_suricata",
+ "fields": [
+ {
+ "label": "Sensor engine",
+ "name": "engine",
+ "options": [
+ {
+ "label": "Suricata (eve.json)",
+ "value": "suricata"
+ },
+ {
+ "label": "Zeek (notice.log)",
+ "value": "zeek"
+ }
+ ],
+ "required": true,
+ "type": "select"
+ },
+ {
+ "label": "Spool URL",
+ "name": "spool_url",
+ "placeholder": "https://ndr-sensor.internal/spool",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "label": "Spool token",
+ "name": "api_token",
+ "required": true,
+ "type": "secret"
+ },
+ {
+ "default": true,
+ "label": "Verify TLS certificate",
+ "name": "verify_tls",
+ "required": false,
+ "type": "boolean"
+ }
+ ]
},
{
+ "capabilities": [
+ "pull_alerts"
+ ],
+ "category": "network",
"connector_id": "zscaler",
"connector_name": "Zscaler Internet Access",
- "category": "network",
"description": "Zscaler Internet Access web security logs via the ZIA API.",
+ "docs_url": "/docs/connectors/zscaler",
"fields": [
{
- "name": "api_key",
- "type": "secret",
"label": "API Key",
- "required": true
+ "name": "api_key",
+ "required": true,
+ "type": "secret"
},
{
- "name": "cloud",
- "type": "string",
+ "default": "zscloud.net",
+ "help_text": "ZIA cloud domain (e.g. zscloud.net, zscaler.net).",
"label": "ZIA Cloud",
+ "name": "cloud",
"required": false,
- "default": "zscloud.net",
- "help_text": "ZIA cloud domain (e.g. zscloud.net, zscaler.net)."
+ "type": "string"
},
{
- "name": "username",
- "type": "string",
"label": "Admin Username",
- "required": true
+ "name": "username",
+ "required": true,
+ "type": "string"
},
{
- "name": "password",
- "type": "secret",
"label": "Admin Password",
- "required": true
+ "name": "password",
+ "required": true,
+ "type": "secret"
}
- ],
- "docs_url": "/docs/connectors/zscaler"
+ ]
}
-]
\ No newline at end of file
+]
diff --git a/services/api/app/services/graph_service.py b/services/api/app/services/graph_service.py
index a52c3b68e..711250966 100644
--- a/services/api/app/services/graph_service.py
+++ b/services/api/app/services/graph_service.py
@@ -355,6 +355,11 @@ def _scoped(var: str) -> str:
return _TENANT_SCOPED.format(var=var)
+def _is_global(var: str) -> str:
+ """Predicate: this node is shared reference data, not tenant estate."""
+ return f"any(l IN labels({var}) WHERE l IN $global_labels)"
+
+
async def get_blast_radius(entity_id: str, entity_type: str, tenant_id: str, hops: int = 3) -> dict[str, Any]:
"""
Compute blast radius: all entities reachable from an IOC/Host/User within N hops.
@@ -532,6 +537,144 @@ async def get_entity_neighbors(
}
+#: Bounds on one overview response.
+#:
+#: The console renders this as a force-directed canvas. Past a few hundred
+#: nodes the layout pass blocks the browser's main thread and the picture
+#: stops being readable, so these are the point at which more data makes the
+#: view worse — not a guess about what Neo4j can serve.
+OVERVIEW_SEED_LIMIT = 120
+OVERVIEW_NODE_LIMIT = 400
+OVERVIEW_EDGE_LIMIT = 900
+
+#: Properties that can carry the name an analyst would type into ``?entity=``.
+#: Ordered by how specific they are; the first non-null wins.
+_ENTITY_MATCH_PROPS = ("natural_key", "id", "hostname", "username", "name", "value", "technique_id")
+
+
+def _overview_id_expr(var: str) -> str:
+ """The business identifier for a node, whichever writer created it.
+
+ The Go ingest writer keys on ``natural_key``; ``graph_service``'s own
+ upserts key on ``id``; IOCs key on ``value`` and techniques on
+ ``technique_id``. A single coalesce covers all four rather than the
+ overview having to know which writer produced a given node.
+ """
+ return f"coalesce({', '.join(f'{var}.{p}' for p in ('natural_key', 'id', 'value', 'technique_id'))})"
+
+
+async def get_graph_overview(
+ tenant_id: str,
+ depth: int = 3,
+ entity: str | None = None,
+) -> dict[str, Any]:
+ """The tenant's entity graph, bounded, for the Attack Graph canvas.
+
+ Two statements rather than one, because the second depends on the first
+ having *already* proven every node it returns is in scope:
+
+ 1. Seed on the tenant's own nodes, expand up to ``depth`` hops, and keep
+ a path only when **every node on it** satisfies the tenant predicate.
+ Filtering the start node alone is what let a previous blast-radius
+ traversal walk out through a shared entity — a public IP two tenants
+ both saw — and enumerate the other tenant's estate. A node with no
+ ``tenant_id`` is not readable either: ``_scoped`` does not accept
+ null, so an untagged node cannot bridge between two tenants.
+ 2. Return relationships **only between nodes already in that set**. There
+ is no second tenant predicate here and there does not need to be: both
+ endpoints were resolved by step 1, so an edge can only exist in the
+ answer if both of its ends were independently proven in scope.
+
+ Seeds exclude the global MITRE labels. They are shared by every tenant,
+ so seeding on them would start every overview from the same reference
+ vocabulary; they remain reachable as neighbours, which is the point of
+ the exemption.
+
+ The Go writer ``MERGE``s on ``natural_key`` alone with ``tenant_id`` as a
+ property, so a shared entity such as a public IP is last-writer-wins. The
+ strict predicate therefore **fails closed** on those nodes — they drop out
+ of the overview rather than appearing under the wrong tenant. That is the
+ intended trade: completeness on shared infrastructure for never leaking.
+ Re-keying on ``(tenant_id, natural_key)`` is the proper fix and needs a
+ migration.
+
+ Returns ``{"nodes": [...], "edges": [...], "truncated": bool}``. An empty
+ node list means the tenant genuinely has no graph — callers must not
+ conflate it with a failed lookup, which raises instead.
+ """
+ # Interpolated because Cypher does not accept a parameter as a
+ # variable-length bound. Coerced and clamped here so the query string can
+ # only ever contain an integer, whatever the caller passed.
+ hops = max(0, min(int(depth), 6))
+
+ entity_clause = ""
+ if entity:
+ matches = " OR ".join(f"toLower(toString(seed.{prop})) = toLower($entity)" for prop in _ENTITY_MATCH_PROPS)
+ entity_clause = f"AND ({matches})"
+
+ nodes_cypher = f"""
+ MATCH (seed)
+ WHERE {_scoped("seed")} AND NOT {_is_global("seed")} {entity_clause}
+ WITH seed
+ ORDER BY coalesce(seed.risk_score, 0) DESC, elementId(seed)
+ LIMIT $seed_limit
+ MATCH path = (seed)-[*0..{hops}]-(n)
+ WHERE all(pn IN nodes(path) WHERE {_scoped("pn")})
+ WITH n, min(length(path)) AS hop
+ ORDER BY hop ASC, coalesce(n.risk_score, 0) DESC, elementId(n)
+ LIMIT $node_limit
+ RETURN collect({{
+ ref: elementId(n),
+ id: {_overview_id_expr("n")},
+ labels: labels(n),
+ properties: properties(n)
+ }}) AS nodes
+ """
+
+ # Both endpoints are constrained to `$refs`, which step 1 already proved
+ # tenant-scoped. Re-deriving the predicate here would be a second place
+ # for it to be got wrong.
+ edges_cypher = """
+ MATCH (a)-[r]->(b)
+ WHERE elementId(a) IN $refs AND elementId(b) IN $refs
+ RETURN
+ elementId(r) AS ref,
+ elementId(a) AS source,
+ elementId(b) AS target,
+ type(r) AS type,
+ properties(r) AS properties
+ ORDER BY ref
+ LIMIT $edge_limit
+ """
+
+ async with get_session() as s:
+ node_result = await s.run(
+ nodes_cypher,
+ tenant_id=tenant_id,
+ entity=entity,
+ global_labels=list(_GLOBAL_LABELS),
+ seed_limit=OVERVIEW_SEED_LIMIT,
+ node_limit=OVERVIEW_NODE_LIMIT,
+ )
+ node_record = await node_result.single()
+ nodes = list(node_record["nodes"]) if node_record else []
+
+ edges: list[dict[str, Any]] = []
+ if nodes:
+ edge_result = await s.run(
+ edges_cypher,
+ refs=[n["ref"] for n in nodes],
+ edge_limit=OVERVIEW_EDGE_LIMIT,
+ )
+ edges = [dict(record) async for record in edge_result]
+
+ return {
+ "nodes": nodes,
+ "edges": edges,
+ "truncated": len(nodes) >= OVERVIEW_NODE_LIMIT or len(edges) >= OVERVIEW_EDGE_LIMIT,
+ }
+
+
async def get_mitre_coverage(tenant_id: str) -> list[dict[str, Any]]:
"""Return MITRE ATT&CK technique coverage: alert counts per technique."""
cypher = """
diff --git a/services/api/app/workers/oauth_refresh.py b/services/api/app/workers/oauth_refresh.py
index 9965e27fb..03d5afad3 100644
--- a/services/api/app/workers/oauth_refresh.py
+++ b/services/api/app/workers/oauth_refresh.py
@@ -31,6 +31,7 @@ from __future__ import annotations
import asyncio
import logging
+import uuid
from collections.abc import Mapping
from datetime import UTC, datetime, timedelta
from typing import Any
@@ -65,17 +66,21 @@ class _CatalogResolver:
"""
@staticmethod
- async def hints_for(connector_type: str) -> dict[str, Any]:
+ async def hints_for(connector_type: str, tenant_id: uuid.UUID | str | None) -> dict[str, Any]:
"""Return the ``oauth`` hints block for ``connector_type``.
Empty dict when the catalog is unreachable or the entry doesn't
ship hints — the caller falls back to the per-tenant
``OAuthAppCredential.token_url`` override.
+
+ ``tenant_id`` is the tenant whose credential is being refreshed. The
+ connectors service requires a service caller to declare one, and the
+ worker always has it: it walks connectors tenant by tenant.
"""
from app.api.v1.endpoints.connectors import _fetch_catalog
try:
- catalog = await _fetch_catalog()
+ catalog = await _fetch_catalog(tenant_id)
except Exception as exc: # pragma: no cover - logged + bubbled to fallback
logger.warning(
"oauth_refresh.catalog_unreachable connector_type=%s err=%s",
@@ -83,7 +88,7 @@ class _CatalogResolver:
type(exc).__name__,
)
return {}
- for entry in catalog:
+ for entry in catalog.entries:
if not isinstance(entry, dict):
continue
if entry.get("name") == connector_type:
@@ -262,7 +267,7 @@ async def _refresh_one(
return False
# 3. Resolve token_url from the per-tenant override or catalog hints.
- hints = await _CatalogResolver.hints_for(connector_type)
+ hints = await _CatalogResolver.hints_for(connector_type, tenant_id)
token_url = _resolve_token_url(app_credential, hints)
if not token_url:
logger.warning(
diff --git a/services/api/tests/test_connectors_endpoint.py b/services/api/tests/test_connectors_endpoint.py
index ee25add6a..94c9364db 100644
--- a/services/api/tests/test_connectors_endpoint.py
+++ b/services/api/tests/test_connectors_endpoint.py
@@ -19,18 +19,26 @@ We mock ``httpx.AsyncClient`` directly because:
from __future__ import annotations
+import uuid
from typing import Any
from unittest.mock import AsyncMock, MagicMock, patch
import httpx
import pytest
from app.api.v1.endpoints.connectors import (
+ _catalog_headers,
_fetch_catalog,
+ _load_fallback_catalog,
_proxy_test_connection,
_validate_connector_type,
+ settings,
)
from fastapi import HTTPException
+#: The tenant every proxied call is made on behalf of. The connectors
+#: service refuses a service token that does not declare one.
+_TENANT = uuid.UUID("11111111-1111-1111-1111-111111111111")
+
def _mock_response(status_code: int, json_body: Any) -> MagicMock:
"""Build a MagicMock that quacks like an httpx.Response."""
@@ -68,8 +76,10 @@ async def test_fetch_catalog_returns_schemas() -> None:
]
resp = _mock_response(200, {"schemas": fake_schemas})
with _patched_client(get_resp=resp):
- result = await _fetch_catalog()
- assert result == fake_schemas
+ result = await _fetch_catalog(_TENANT)
+ assert result.entries == fake_schemas
+ assert result.source == "live"
+ assert result.degraded is False
@pytest.mark.asyncio
@@ -88,13 +98,18 @@ async def test_fetch_catalog_falls_back_when_service_unreachable() -> None:
"app.api.v1.endpoints.connectors.httpx.AsyncClient",
return_value=client_cm,
):
- result = await _fetch_catalog()
+ result = await _fetch_catalog(_TENANT)
# The bundled catalog ships with at least one connector schema; we
# don't pin a specific count because that's churned by the marketplace
# sync. The contract is "non-empty list of schemas" — that's enough
# for the API surface to keep serving.
- assert isinstance(result, list)
- assert result, "expected bundled fallback catalog to be non-empty"
+ assert isinstance(result.entries, list)
+ assert result.entries, "expected bundled fallback catalog to be non-empty"
+ # Provenance is the point: a stand-in must be distinguishable from
+ # the live registry, because this one stood in silently for 58 connectors.
+ assert result.source == "bundled"
+ assert result.degraded is True
+ assert "unreachable" in result.reason
@pytest.mark.asyncio
@@ -119,7 +134,7 @@ async def test_fetch_catalog_raises_503_when_unreachable_and_no_fallback() -> No
),
):
with pytest.raises(HTTPException) as exc_info:
- await _fetch_catalog()
+ await _fetch_catalog(_TENANT)
assert exc_info.value.status_code == 503
@@ -129,7 +144,7 @@ async def test_fetch_catalog_raises_502_for_malformed_body() -> None:
resp = _mock_response(200, {"schemas": "not-a-list"})
with _patched_client(get_resp=resp):
with pytest.raises(HTTPException) as exc_info:
- await _fetch_catalog()
+ await _fetch_catalog(_TENANT)
assert exc_info.value.status_code == 502
@@ -141,7 +156,7 @@ async def test_validate_connector_type_accepts_known() -> None:
fake_schemas = [{"connector_id": "splunk", "category": "siem", "name": "Splunk"}]
resp = _mock_response(200, {"schemas": fake_schemas})
with _patched_client(get_resp=resp):
- entry = await _validate_connector_type("splunk")
+ entry = await _validate_connector_type("splunk", _TENANT)
assert entry["connector_id"] == "splunk"
assert entry["category"] == "siem"
@@ -153,11 +168,130 @@ async def test_validate_connector_type_rejects_unknown() -> None:
resp = _mock_response(200, {"schemas": fake_schemas})
with _patched_client(get_resp=resp):
with pytest.raises(HTTPException) as exc_info:
- await _validate_connector_type("not_a_real_connector")
+ await _validate_connector_type("not_a_real_connector", _TENANT)
+ assert exc_info.value.status_code == 422
+ assert "splunk" in exc_info.value.detail
+
+
+# ------------------------------------------- catalog authentication (the defect)
+
+
+async def test_catalog_request_carries_the_service_credential(monkeypatch: pytest.MonkeyPatch) -> None:
+ """The proxy must authenticate. This is the whole of the original defect.
+
+ Every route on the connectors service sits behind
+ ``require_console_or_service_auth``, which needs a bearer credential and —
+ for a service token — the tenant the caller is acting for. The proxy sent
+ neither, so it was answered 401 on every call and served the bundled
+ catalog *every time*, with 26 entries against a registry of 84. Nothing
+ failed; the wizard just showed a confidently wrong list.
+
+ Asserting on the outgoing request rather than the return value is
+ deliberate: a test that only checks "we got a catalog back" passes just as
+ happily when the catalog came from the fallback.
+ """
+ monkeypatch.setenv("AISOC_SERVICE_TOKEN", "test-service-token")
+ monkeypatch.delenv("AISOC_CONNECTORS_SERVICE_TOKEN", raising=False)
+
+ fake_schemas = [{"connector_id": "splunk", "category": "siem", "fields": []}]
+ client_instance = MagicMock()
+ client_instance.get = AsyncMock(return_value=_mock_response(200, {"schemas": fake_schemas}))
+ client_cm = MagicMock()
+ client_cm.__aenter__ = AsyncMock(return_value=client_instance)
+ client_cm.__aexit__ = AsyncMock(return_value=None)
+
+ with patch("app.api.v1.endpoints.connectors.httpx.AsyncClient", return_value=client_cm):
+ result = await _fetch_catalog(_TENANT)
+
+ assert result.source == "live"
+ headers = client_instance.get.await_args.kwargs["headers"]
+ assert headers["Authorization"] == "Bearer test-service-token"
+ assert headers["X-AiSOC-Tenant-ID"] == str(_TENANT)
+
+
+def test_catalog_headers_prefer_the_connectors_specific_token(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Per-service override wins over the shared platform token."""
+ monkeypatch.setenv("AISOC_SERVICE_TOKEN", "shared")
+ monkeypatch.setenv("AISOC_CONNECTORS_SERVICE_TOKEN", "specific")
+ assert _catalog_headers(_TENANT)["Authorization"] == "Bearer specific"
+
+
+def test_catalog_headers_still_assert_the_tenant_without_a_token(monkeypatch: pytest.MonkeyPatch) -> None:
+ """No token configured: send the tenant anyway, never a blank credential.
+
+ A dev-mode connectors service accepts the call; a production one fails
+ closed, which is the correct outcome for a deployment that never
+ configured a service token. Sending ``Bearer `` would be neither.
+ """
+ monkeypatch.delenv("AISOC_SERVICE_TOKEN", raising=False)
+ monkeypatch.delenv("AISOC_CONNECTORS_SERVICE_TOKEN", raising=False)
+ headers = _catalog_headers(_TENANT)
+ assert "Authorization" not in headers
+ assert headers["X-AiSOC-Tenant-ID"] == str(_TENANT)
+
+
+async def test_unknown_type_is_503_not_422_when_the_catalog_is_degraded() -> None:
+ """ "I could not look it up" must not be reported as "it does not exist".
+
+ A connectors service rolled forward ahead of this API image legitimately
+ knows connector types the bundled catalog does not. Answering 422
+ "unknown connector_type" sends the operator to debug a connector that is
+ fine — which is exactly what the stale bundle did, on every request, for
+ 58 connectors.
+ """
+ client_instance = MagicMock()
+ client_instance.get = AsyncMock(side_effect=httpx.ConnectError("connection refused"))
+ client_cm = MagicMock()
+ client_cm.__aenter__ = AsyncMock(return_value=client_instance)
+ client_cm.__aexit__ = AsyncMock(return_value=None)
+ with (
+ patch("app.api.v1.endpoints.connectors.httpx.AsyncClient", return_value=client_cm),
+ patch(
+ "app.api.v1.endpoints.connectors._load_fallback_catalog",
+ return_value=[{"connector_id": "splunk", "category": "siem"}],
+ ),
+ ):
+ with pytest.raises(HTTPException) as exc_info:
+ await _validate_connector_type("a_newer_connector", _TENANT)
+ assert exc_info.value.status_code == 503
+ assert "unreachable" in exc_info.value.detail
+
+
+async def test_unknown_type_is_422_when_the_bundle_is_authoritative(monkeypatch: pytest.MonkeyPatch) -> None:
+ """With no connectors service deployed, the bundle *is* the source of truth.
+
+ That deployment is not degraded and 422 is the honest answer, so the
+ 503 above must not swallow the real rejection.
+ """
+ monkeypatch.setattr(settings, "CONNECTORS_SERVICE_URL", "", raising=False)
+ with patch(
+ "app.api.v1.endpoints.connectors._load_fallback_catalog",
+ return_value=[{"connector_id": "splunk", "category": "siem"}],
+ ):
+ with pytest.raises(HTTPException) as exc_info:
+ await _validate_connector_type("not_a_real_connector", _TENANT)
assert exc_info.value.status_code == 422
assert "splunk" in exc_info.value.detail
+def test_bundled_catalog_is_well_formed_and_covers_more_than_a_sample() -> None:
+ """The artefact the image ships is a real catalog, not a stub.
+
+ Deliberately a floor rather than an exact count — the exact number is the
+ generator's business, gated by
+ ``scripts/generate_connector_catalog_fallback.py --check``. What this
+ catches is the artefact silently becoming a placeholder again, which is
+ the shape it was in: a 26-entry subset that looked like a catalog.
+ """
+ bundled = _load_fallback_catalog()
+ assert len(bundled) >= 80, f"bundled catalog has only {len(bundled)} entries; regenerate it"
+ assert all(isinstance(e.get("connector_id"), str) and e["connector_id"] for e in bundled)
+ assert len({e["connector_id"] for e in bundled}) == len(bundled), "duplicate connector_id in the bundled catalog"
+
+
# ------------------------------------------------------------ test proxy
diff --git a/services/api/tests/test_graph_overview.py b/services/api/tests/test_graph_overview.py
new file mode 100644
index 000000000..6f0df954c
--- /dev/null
+++ b/services/api/tests/test_graph_overview.py
@@ -0,0 +1,235 @@
+"""``GET /api/v1/graph`` — the Attack Graph console's only data source.
+
+The route did not exist. The console called it, got 404, and rendered its
+error state, while ``/graph/neighbors/...`` and ``/graph/mitre-coverage``
+returned 200 from the same Neo4j instance holding real graph-at-ingest data.
+
+Tenant scoping for the traversal lives in ``test_graph_tenant_isolation.py``
+with the other graph reads, because that is the property all of them share.
+What is asserted here is the contract the console consumes, and in particular
+the distinction the endpoint exists to preserve:
+
+ an empty graph and an unreachable graph must not look the same.
+
+"No attack relationships exist in your estate" is a security claim. Making it
+because a database was down is the failure this codebase keeps rediscovering —
+``IncidentContextResponse`` carries ``partial``/``errors`` for exactly this
+reason, and ``evidence_fingerprint`` reported a flat zero for a whole release
+because nothing distinguished "found none" from "never looked".
+"""
+
+from __future__ import annotations
+
+import contextlib
+from typing import Any
+
+import pytest
+
+pytest.importorskip("neo4j", reason="neo4j driver not installed")
+
+from app.api.v1.endpoints import graph as graph_endpoint # noqa: E402
+from app.services import graph_service # noqa: E402
+from fastapi import HTTPException # noqa: E402
+
+TENANT = "11111111-1111-1111-1111-111111111111"
+
+
+class _User:
+ tenant_id = TENANT
+
+
+class _Result:
+ def __init__(self, record: Any = None, rows: list[dict[str, Any]] | None = None) -> None:
+ self._record = record
+ self._rows = rows or []
+
+ async def single(self) -> Any:
+ return self._record
+
+ def __aiter__(self):
+ async def _gen():
+ for row in self._rows:
+ yield row
+
+ return _gen()
+
+
+class _Session:
+ """Answers the node statement then the edge statement, in that order."""
+
+ def __init__(self, nodes: list[dict[str, Any]], edges: list[dict[str, Any]]) -> None:
+ self._nodes = nodes
+ self._edges = edges
+ self.calls: list[str] = []
+
+ async def run(self, cypher: str, **_params: Any) -> _Result:
+ self.calls.append(cypher)
+ if "collect({" in cypher and "ref: elementId(n)" in cypher:
+ return _Result(record={"nodes": self._nodes})
+ return _Result(rows=self._edges)
+
+
+def _install(monkeypatch: pytest.MonkeyPatch, nodes: list[dict], edges: list[dict]) -> _Session:
+ session = _Session(nodes, edges)
+
+ @contextlib.asynccontextmanager
+ async def _get_session():
+ yield session
+
+ monkeypatch.setattr(graph_service, "get_session", _get_session)
+ return session
+
+
+def _node(ref: str, node_id: str, labels: list[str], **properties: Any) -> dict[str, Any]:
+ return {"ref": ref, "id": node_id, "labels": labels, "properties": properties}
+
+
+# ── empty is not broken, and broken is not empty ──────────────────────────
+
+
+async def test_a_tenant_with_no_graph_gets_an_honest_empty_answer(monkeypatch: pytest.MonkeyPatch):
+ """200 and no nodes. The console renders "No graph yet", not an error."""
+ _install(monkeypatch, nodes=[], edges=[])
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert response.nodes == []
+ assert response.edges == []
+ assert response.truncated is False
+ assert response.generatedAt
+
+
+async def test_an_unreachable_graph_is_503_and_never_an_empty_graph(monkeypatch: pytest.MonkeyPatch):
+ """The distinction this endpoint exists to keep.
+
+ Degrading to ``{"nodes": []}`` here would tell an analyst their estate has
+ no attack relationships, on evidence nobody retrieved.
+ """
+
+ @contextlib.asynccontextmanager
+ async def _boom():
+ raise RuntimeError("Neo4j driver not initialized")
+ yield # pragma: no cover
+
+ monkeypatch.setattr(graph_service, "get_session", _boom)
+ with pytest.raises(HTTPException) as exc_info:
+ await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert exc_info.value.status_code == 503
+ assert "unavailable" in exc_info.value.detail
+
+
+# ── the shape the console consumes ────────────────────────────────────────
+
+
+async def test_nodes_and_edges_render_in_the_console_contract(monkeypatch: pytest.MonkeyPatch):
+ _install(
+ monkeypatch,
+ nodes=[
+ _node("n1", "host-1", ["Host"], hostname="WIN-DB01", risk_score=92),
+ _node("n2", "alert-1", ["Alert"], title="Credential dump", severity="critical"),
+ ],
+ edges=[{"ref": "r1", "source": "n2", "target": "n1", "type": "OBSERVED_ON", "properties": {}}],
+ )
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+
+ by_id = {n.id: n for n in response.nodes}
+ assert by_id["host-1"].kind == "host"
+ assert by_id["host-1"].label == "WIN-DB01"
+ assert by_id["host-1"].riskScore == 92.0
+ assert by_id["alert-1"].kind == "alert"
+ assert by_id["alert-1"].severity == "critical"
+
+ assert len(response.edges) == 1
+ assert (response.edges[0].source, response.edges[0].target) == ("alert-1", "host-1")
+ assert response.edges[0].label == "OBSERVED_ON"
+
+
+async def test_an_edge_to_a_dropped_node_is_dropped_too(monkeypatch: pytest.MonkeyPatch):
+ """An edge whose endpoint did not survive would draw a line into nothing."""
+ _install(
+ monkeypatch,
+ nodes=[_node("n1", "host-1", ["Host"], hostname="WIN-DB01")],
+ edges=[{"ref": "r1", "source": "n1", "target": "n-unknown", "type": "PEER_OF", "properties": {}}],
+ )
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert response.edges == []
+
+
+async def test_a_node_with_no_identifier_is_dropped_rather_than_collapsed(monkeypatch: pytest.MonkeyPatch):
+ """Cytoscape keys elements by id; a blank one merges every such node into
+ a single element claiming to be all of them."""
+ _install(
+ monkeypatch,
+ nodes=[_node("n1", "host-1", ["Host"]), {"ref": "n2", "id": None, "labels": ["Host"], "properties": {}}],
+ edges=[],
+ )
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert [n.id for n in response.nodes] == ["host-1"]
+
+
+async def test_a_vendor_severity_is_dropped_rather_than_guessed(monkeypatch: pytest.MonkeyPatch):
+ """The console shades by severity. Coercing an unrecognised vendor string
+ onto the five-tier ladder would shade a node by a fact nobody established."""
+ _install(
+ monkeypatch,
+ nodes=[_node("n1", "alert-1", ["Alert"], title="x", severity="SEV-2")],
+ edges=[],
+ )
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert response.nodes[0].severity is None
+
+
+async def test_an_unscored_node_is_not_reported_as_scoring_zero(monkeypatch: pytest.MonkeyPatch):
+ _install(monkeypatch, nodes=[_node("n1", "host-1", ["Host"], hostname="h")], edges=[])
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert response.nodes[0].riskScore is None
+
+
+async def test_labels_outside_the_console_union_keep_their_real_identity(monkeypatch: pytest.MonkeyPatch):
+ """The console knows ten kinds; the graph schema declares 29 labels.
+
+ Projecting the remainder onto the generic ``asset`` glyph is fine as long
+ as the projection does not *lose* the label, so the real one travels in
+ ``attributes``.
+ """
+ _install(monkeypatch, nodes=[_node("n1", "fin7", ["ThreatActor"], name="FIN7")], edges=[])
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert response.nodes[0].kind == "asset"
+ assert response.nodes[0].attributes["labels"] == ["ThreatActor"]
+
+
+async def test_iocs_resolve_by_their_own_type(monkeypatch: pytest.MonkeyPatch):
+ _install(
+ monkeypatch,
+ nodes=[
+ _node("n1", "1.2.3.4", ["IOC"], value="1.2.3.4", ioc_type="ipv4"),
+ _node("n2", "evil.test", ["IOC"], value="evil.test", ioc_type="domain"),
+ _node("n3", "deadbeef", ["IOC"], value="deadbeef", ioc_type="sha256"),
+ _node("n4", "mystery", ["IOC"], value="mystery", ioc_type="something_new"),
+ ],
+ edges=[],
+ )
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert [n.kind for n in response.nodes] == ["ip", "domain", "hash", "asset"]
+
+
+async def test_a_duplicated_relationship_yields_one_edge(monkeypatch: pytest.MonkeyPatch):
+ """Two writers can MERGE the same relationship shape between one pair."""
+ _install(
+ monkeypatch,
+ nodes=[_node("n1", "a", ["Host"], hostname="a"), _node("n2", "b", ["Host"], hostname="b")],
+ edges=[
+ {"ref": "r1", "source": "n1", "target": "n2", "type": "PEER_OF", "properties": {}},
+ {"ref": "r2", "source": "n1", "target": "n2", "type": "PEER_OF", "properties": {}},
+ ],
+ )
+ response = await graph_endpoint.get_graph_overview(depth=3, entity=None, current_user=_User())
+ assert len(response.edges) == 1
diff --git a/services/api/tests/test_graph_tenant_isolation.py b/services/api/tests/test_graph_tenant_isolation.py
index 472ceda04..e46434856 100644
--- a/services/api/tests/test_graph_tenant_isolation.py
+++ b/services/api/tests/test_graph_tenant_isolation.py
@@ -62,7 +62,7 @@ class _FakeSession:
@pytest.fixture
def session(monkeypatch: pytest.MonkeyPatch) -> _FakeSession:
- fake = _FakeSession(record={"source": None, "neighbors": [], "all_nodes": [], "affected": []})
+ fake = _FakeSession(record={"source": None, "neighbors": [], "all_nodes": [], "affected": [], "nodes": []})
@contextlib.asynccontextmanager
async def _get_session():
@@ -135,6 +135,74 @@ async def test_the_apoc_free_fallback_is_scoped_too(session: _FakeSession):
assert "tenant_id IS NULL" not in cypher
+# ── tenant overview (GET /api/v1/graph) ───────────────────────────────────
+#
+# The newest read path, and the one with the widest reach: it does not name an
+# entity, it walks outward from whatever the tenant owns. Every property the
+# two traversals above had to learn the hard way applies here from the start,
+# so they are asserted here rather than assumed.
+
+
+async def test_overview_scopes_every_node_of_every_path(session: _FakeSession):
+ await graph_service.get_graph_overview(tenant_id=TENANT, depth=3)
+ cypher, params = session.calls[0]
+ _assert_scoped(cypher, params, ["seed", "pn"])
+ assert "all(pn IN nodes(path)" in cypher, "path nodes are not checked collectively"
+
+
+async def test_overview_does_not_accept_an_untagged_node(session: _FakeSession):
+ """An untagged node readable by everyone is a bridge between tenants."""
+ await graph_service.get_graph_overview(tenant_id=TENANT, depth=3)
+ cypher, _ = session.calls[0]
+ assert "tenant_id IS NULL" not in cypher
+
+
+async def test_overview_does_not_seed_on_global_reference_labels(session: _FakeSession):
+ """Techniques are shared, so seeding on them would start every tenant's
+ overview from the same vocabulary. They stay reachable as neighbours."""
+ await graph_service.get_graph_overview(tenant_id=TENANT, depth=3)
+ cypher, _ = session.calls[0]
+ assert f"NOT {graph_service._is_global('seed')}" in cypher
+
+
+async def test_overview_depth_never_reaches_the_query_as_text(session: _FakeSession):
+ """Cypher cannot parameterise a variable-length bound, so `depth` is
+ interpolated. It must therefore be impossible for anything but an integer
+ to land in the string."""
+ await graph_service.get_graph_overview(tenant_id=TENANT, depth=99)
+ cypher, _ = session.calls[0]
+ # Clamped, not passed through.
+ assert "[*0..6]" in cypher
+ assert "99" not in cypher
+
+
+async def test_overview_entity_filter_is_a_bound_parameter(session: _FakeSession):
+ """The entity name comes from a query string, so it is bound rather than
+ interpolated — it must not be able to add a clause to the statement."""
+ await graph_service.get_graph_overview(tenant_id=TENANT, depth=2, entity="host-1' OR 1=1 //")
+ cypher, params = session.calls[0]
+ assert params["entity"] == "host-1' OR 1=1 //"
+ assert "OR 1=1" not in cypher
+
+
+async def test_overview_asks_for_no_edges_when_the_tenant_has_no_nodes(session: _FakeSession):
+ """An empty node set means there is nothing an edge could legally join.
+
+ Skipping the second statement is not an optimisation: `$refs` would be
+ empty, and a future edit that dropped the `IN $refs` predicate would then
+ return every relationship in the database.
+ """
+ result = await graph_service.get_graph_overview(tenant_id=TENANT, depth=3)
+ assert result == {"nodes": [], "edges": [], "truncated": False}
+ assert len(session.calls) == 1
+
+
# ── global reference data ─────────────────────────────────────────────────