Developer Preview · build a connector
You ship a security tool, a SaaS product, or infrastructure that customers wire into their stack. CyberCLI ingests events, takes governed action, and audits everything. A connector is the bridge between your tool and that engine — about an afternoon of work, declarative-first, no embedded SDK to maintain. You write a YAML manifest + a Vector remap parser. CI validates. We feature you. Customers find your tile on /connectors.
Status: Developer Preview. The spec is locked. CI is live. The public repo at cybercli-co/cybercli-connectors opens at v1 launch (~1 week). Spec, reference connectors, and lint CLI are available today for early-access partners — email partners@cybercli.com.
# 1. Fork the connectors repo
git clone https://github.com/<you>/cybercli-connectors.git
cd cybercli-connectors
# 2. Copy a reference as your starting point
cp -r examples/adguard contrib/my-connector
cd contrib/my-connector
# 3. Edit manifest.yaml — change `name`, `vendor`, `version`
$EDITOR manifest.yaml
# 4. Adapt vector.vrl to parse your tool's events
$EDITOR vector.vrl
# 5. Add a fixture pair
mkdir -p fixtures
cat > fixtures/basic.json <<'EOF'
<your tool's raw event>
EOF
cat > fixtures/basic.expected.json <<'EOF'
<expected CanonicalEvent shape>
EOF
# 6. Validate locally
python3 ../../tools/cybercli-connector-lint .
# 7. Submit
git checkout -b add-my-connector
git push origin add-my-connector
# Open a PR — CI posts results within 60 secondsmanifest.yaml Required Declarative contract — identity, ingest paths (api_poll · webhook · syslog · agent_stream), auth, OCSF + ATT&CK mapping, write actions (with risk_lock_ceiling), data locality, onboarding playbook for the guided wizard. The single source of truth — the engine, the dashboard, the AI digest layer, and the marketing catalog all read this.
vector.vrl Required for log-based Your normalizer. Vector Remap Language — small statically-typed transform. Reads vendor events, emits CanonicalEvent shape. ~60 lines for AdGuard, ~150 for nginx, ~250 for complex multi-class sources like Zeek.
fixtures/ Required (≥2 pairs) Golden tests. fixtures/basic.json (raw input) + fixtures/basic.expected.json (CanonicalEvent your VRL should produce). CI parses every input through your VRL and diffs against expected. Bumps prevent silent regressions.
callback.py Optional · Verified Partner only Bidirectional write-back to your vendor API — acknowledge an alert in your dashboard when CyberCLI closes the case, sync_disposition, etc. NOT accepted from community submissions (no sandboxing in v1). Verified Partners pass a manual security review; details with partners@cybercli.com.
README.md Optional but encouraged Vendor-facing notes, screenshots, links to your product docs. Surfaced on the per-connector landing page after merge.
Submitted via GitHub PR Fork → branch → push → open PR against cybercli-co/cybercli-connectors. CI runs cybercli-connector-lint within ~60s and posts the report as a comment. Auto-merge for already-Verified vendors making patch updates; new submissions get one maintainer review.
The badge on your connector's catalog tile signals to customers what kind of trust they're buying into. Community is the open lane; Verified Partner is the vendor-signed lane; Bundled is shipped-by-CyberCLI. Different runtime caps. Different review processes. Same lint CLI on the way in.
| Tier | Runtime cap | Review | Catalog placement |
|---|---|---|---|
| Community | L3 (AI Proposes) | Lint-clean + maintainer merge | Community tab on /connectors |
| Verified Partner | L5 (AI Acts + Alerts) | Manual security review + Partner Agreement | Featured card with logo · "Works with CyberCLI" badge for your own site |
| Bundled | L7 (per action template) | CyberCLI team builds + maintains | Ships in the CyberCLI binary |
The lint warns (doesn't block) if you declare risk_lock_ceiling above L3 — the runtime caps Community-tier regardless of declaration. Declare what your action should be; the cap normalizes at runtime per tier. Verified Partner review is the path that unlocks the higher levels.
Every PR runs cybercli-connector-lint. ~60 seconds. Fails the build on errors, comments warnings non-blockingly. Run it locally before you push — it catches every class of bug we've seen in submission review.
Required identity fields (name, vendor, type, version). Connector name must match directory. ingest_paths[].type in {api_poll, webhook, syslog, agent_stream}. write_surfaces fields valid (reversibility, approval_tier, risk_lock_ceiling 0-7).
Every onboarding step's vault_key MUST appear in some ingest_path.auth block. Engine enforces this at load time — the lint surfaces it at PR time so reviewers don't see broken playbooks.
Static-grep for get_env_var (use the manifest auth declaration), shell-out, backtick expansion, $-token env interpolation (Vector expands these at config render), arbitrary file IO, outbound HTTP. VRL is sandbox-by-design; the lint mirrors what the runtime engine would reject anyway.
If fixtures/*.json + matching *.expected.json exist and the vector binary is on PATH, each fixture is parsed through your VRL and diffed against expected. Required for CI to ship a green badge.
Warns (not blocks unless --strict) if any write_surfaces[].risk_lock_ceiling > L3 — Community submissions are runtime-capped at L3. The warning points you at the Verified Partner review path to unlock L5+.
Engine rails · 2026-06-02
The connector spec doesn't exist in a vacuum — it lands on top of primitives the engine guarantees. Knowing what's already wired tells you how thin your code needs to be.
verification.py dispatches api_probe on params["connector"] to a registered handler. Add yours alongside _probe_api_wazuh / _probe_api_unifi / _probe_api_m365. Fail-closed: zero-result probes return a specific failure_code, never a false HEALTHY.
Each connector pack ships a client_factory.py with wire_<name>_client(vault). Runtime, smoke, and the onboarding probe all reach for the same factory — so probe path == runtime path by construction. Closes the F1/F1b drift class. Mandatory for new packs.
Syslog + file-tail connectors enrol via cybercli setup add-syslog-source / add-file-source. Adopters read syslog.substrate.enrolled_sources(connector=<name>) — never SourceRegistry. The dashboard's /api/syslog/enroll shells out to the same CLI; one writer, three surfaces.
The onboarding wizard + the syslog enrol + the install-Wazuh job all call connector_entitlement(license_service, connector) BEFORE vault write. Declare your free_tier: true in the manifest if it's OSS; the Free allowlist is derived at load time. Above-tier connectors refuse with ONB-NOT-ENTITLED.
Connector adopt, syslog source bind/unbind, destination CRUD, routing matrix set/clear — every security-relevant config change writes a hash-chained AuditEntry with operator id, before/after diff, and a stable decision_id. The chain replays from genesis to head deterministically.
API + syslog connectors (Wazuh, UniFi, pfSense, OPNsense) get an automatic "Enrol syslog now →" CTA after the API path adopts. Declare both ingest_paths in the manifest; the dashboard wires the rest. Operators don't have to know two surfaces exist.
Discipline · what we apply to ourselves
Before every shipping window we run 3-way adversarial reviews (Codex + Gemini + Cursor in parallel, blind to each other) on the connector + notification + onboarding surface. Findings are deduped into a severity-tagged punch list and worked blockers-first. v1 ship had 4 rounds — every BLOCKER and HIGH closed before tag.
Connector roster: api_probe dispatch, substrate adoption, OPNsense alias, syslog-capable gates on bind/enrol, m365 + unifi playbooks, install-wazuh wizard.
CHANNEL_SCHEMAS ↔ adapter alignment, runtime factory route-through, destination CRUD audit + secret redaction, routing matrix audit, test_send tier gate, marketing built-flag.
Your connector submission lands on the same pipeline: cybercli-connector-lint runs the static-shape checks, the fixture round-trip proves the VRL, and a maintainer cycles through the manual review for Verified Partner tier. Build to the rails and the review is short.
Reach every CyberCLI customer · one PR
The Developer Preview is the on-ramp. Spec is locked, the lint is live, the reference connectors are written. The public repo opens at v1 launch (~1 week). Early-access partners get hands-on with the spec + reference repos today — DM partners@cybercli.com.
Developer Preview · Connector Spec v1.0 · 2026-05-26 · Public repo cybercli-co/cybercli-connectors opens at v1 launch