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.

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.yml
new file mode 100644
index 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 up
diff --git a/docs/contributing/detection-translation-drive.md b/docs/contributing/detection-translation-drive.md
new file mode 100644
index 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).