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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(community): add the connector template and the detection translation drive (#658)
Beenu Arora0d48e9d7d1ef
diff --git a/.github/ISSUE_TEMPLATE/connector_proposal.yml b/.github/ISSUE_TEMPLATE/connector_proposal.ymlnew file mode 100644index 000000000..8c1a9a37a--- /dev/null+++ b/.github/ISSUE_TEMPLATE/connector_proposal.yml@@ -0,0 +1,109 @@+name: Connector proposal+description: Propose a new data connector, or claim one from the wishlist.+title: "[connector] <vendor / product>"+labels: ["enhancement", "connector", "needs-triage"]+body:+ - type: markdown+ attributes:+ value: |+ A connector is one of the three single-file contribution surfaces in+ this repo, and CI validates every one of them. The walkthrough is at+ [`apps/docs/docs/connectors/`](../tree/main/apps/docs/docs/connectors);+ the shape you are implementing is `BaseConnector` in+ [`services/connectors/app/connectors/`](../tree/main/services/connectors/app/connectors).++ Open this before writing code so nobody duplicates your work — the+ [connector wishlist](../issues/356) is the running list of what people+ have asked for.++ - type: input+ id: vendor+ attributes:+ label: Vendor and product+ description: The exact product name, and a link to its API docs.+ placeholder: "Acme XDR — https://developer.acme.example/api"+ validations:+ required: true++ - type: dropdown+ id: category+ attributes:+ label: Category+ description: Determines where it lands in the marketplace catalogue.+ options:+ - edr+ - siem+ - cloud+ - iam+ - saas+ - vcs+ - network+ validations:+ required: true++ - type: dropdown+ id: auth+ attributes:+ label: Authentication+ description: |+ Secret-bearing fields must be declared `secret=True` in `schema()` so+ the credential vault encrypts them. A conformance test checks this.+ options:+ - API key / token+ - Basic auth+ - OAuth2 client credentials+ - OAuth2 authorization code+ - Cloud IAM role+ - mTLS / client certificate+ - Other (describe below)+ validations:+ required: true++ - type: textarea+ id: severity-ladder+ attributes:+ label: Vendor severity values, and how they map+ description: |+ AiSOC's ladder is exactly five tiers: `info | low | medium | high | critical`.+ If the vendor publishes a distinct critical tier it must map to+ `critical` and must not be collapsed into `high` — that has been a+ recurring source of under-triaged alerts.+ placeholder: |+ Acme: informational -> info, low -> low, medium -> medium,+ high -> high, severe -> critical+ validations:+ required: true++ - type: textarea+ id: sample+ attributes:+ label: Sample alert payload+ description: |+ A redacted example response from the vendor's alert endpoint. This+ becomes the normalisation fixture. **Remove every credential, real+ hostname, internal IP and customer identifier first.**+ render: json+ validations:+ required: true++ - type: checkboxes+ id: scope+ attributes:+ label: What you are signing up for+ description: Each item has a CI gate, so none of them are optional.+ options:+ - label: A `schema()` classmethod declaring the config fields, with secrets marked+ - label: An async `test_connection()` implementation+ - label: A `fetch_alerts()` implementation that paginates and handles HTTP errors without crashing the poller+ - label: A `normalize()` mapping to OCSF, preserving all five severity tiers+ - label: Registration in `_CONNECTOR_CLASSES`+ - label: A `plugins/<id>/plugin.yaml` marketplace manifest+ - label: A docs page under `apps/docs/docs/connectors/`++ - type: checkboxes+ id: claiming+ attributes:+ label: Are you implementing this?+ options:+ - label: I intend to open the PR myself+ - label: I am proposing it for someone else to pick updiff --git a/docs/contributing/detection-translation-drive.md b/docs/contributing/detection-translation-drive.mdnew file mode 100644index 000000000..3cafe5669--- /dev/null+++ b/docs/contributing/detection-translation-drive.md@@ -0,0 +1,71 @@+# Detection translation drive++This is the most parallelisable contribution surface in the project, and the+one where a first-time contributor can land something measurable in an hour.++## The gap, in the project's own numbers++From [`docs/detections/truth-table.md`](../detections/truth-table.md), which is+generated by `scripts/detection_truth_table.py` and CI-gated so it cannot+drift:++| tier | on disk | executable |+|------|--------:|-----------:|+| native | 869 | 869 |+| sigma (imported) | 3132 | 77 |+| splunk (imported) | 2005 | 0 |+| chronicle (imported) | 877 | 0 |+| car (imported) | 99 | 0 |++**947 of 6,983 rules fire today.** The other 6,036 are on disk for provenance+and ATT&CK coverage mapping, quarantined because their body is an upstream+query language the engine does not execute.++The project is deliberately honest about this — the README quotes the+executable figure, not the on-disk one. The way to improve the number is to+translate rules, not to relabel them.++## Start with Sigma++Of the five tiers, the imported Sigma pool is by far the best target:++- **3,055 quarantined Sigma rules**, against 77 already translated — so there+ are worked examples in-tree to copy from.+- Sigma's `selection` / `condition` model maps closely onto the native+ `match_when` DSL. It is mechanical, not a rewrite.+- SPL, YARA-L and CAR pseudocode need semantic reinterpretation and are a much+ poorer first task. Leave those.++## What a translation looks like++1. Pick a rule under `detections/_quarantine/` in the sigma tier. Check no open+ PR already claims it.+2. Translate the body into the native condition DSL. The 869 rules under+ `detections/<category>/` are your reference, and the 77 already-translated+ Sigma imports are the closest analogues.+3. Write **both** fixtures under `detections/fixtures/` — one event the rule+ must fire on, one it must stay quiet on. This is not optional paperwork: the+ gate replays both and a rule that fires on its negative fixture is rejected.+4. Move the rule out of `_quarantine/` into its category directory.+5. Open a PR. `validate-detections.yml` replays every fixture and+ `detection_truth_table.py --check` updates the counts.++## Why the negative fixture is the important one++A detection that fires on everything has perfect recall and no value. The+negative fixture is what stops the corpus filling with rules that would drown+an analyst, and it is the reason this drive can accept contributions from+people who have never seen the codebase: **the gate is objective**. Either the+rule fires on the positive and stays quiet on the negative, or CI says no.++## Scope one PR sensibly++One to five related rules. A 200-rule PR cannot be reviewed meaningfully and+will sit. A handful of rules covering one technique is a good unit, and it is+fine for that to be your whole contribution.++## If you want something smaller first++- Add a negative fixture to an existing native rule that has only a positive one.+- Fix a false positive someone has already reported against a firing rule.+- Pick up an issue labelled [good first issue](../../issues?q=is%3Aopen+label%3A%22good+first+issue%22).