CQLmatic documentation
CQLmatic maps a CrowdStrike NG-SIEM environment into a reusable local snapshot and constructs/checks CQL against explicit intent and evidence. The host analyst or model reasons about the question and parser meaning; the Rust CLI supplies deterministic mechanics. It makes no internal model calls.
Read these guides at docs.cqlmatic.dev, visit the project page, or use the Markdown files offline with a release archive.
This manual describes CQLmatic 0.1.0, JSON contracts v1, and executable profile cqlmatic-ngsiem-core-v2. Use cqlmatic catalog --profile for the running binary's knowledge revision and limits. These identifiers do not attest to a tenant, execution, completeness, or unrestricted-English accuracy.
Start as an operator
- Read the project README for prerequisites and executable/source-build instructions, then setup and authentication.
- Follow inventory and status: scout visible sources, confirm the target/context, inventory and review parsers, measure fields, and reconcile evidence. Review costs and budgets first.
- Read environment packs to inspect/import/refresh evidence and understand its limits.
- Use query construction, the command reference, and result assessment for the question at hand.
- Use troubleshooting to decide whether to fix input, resume, or start a new bounded run.
Start as an agent integrator
- Read application flow, machine contracts, and CLI modes/exits.
- Follow the analyst workflow and MCP companion loop. The optional agent snippet and agent skill point to the same workflow.
- Retrieve the relevant status/pack and catalog entries explicitly; setup/discovery does not create model memory or silently select the generation pack.
- Construct/review typed requests, execute only through an authorized client with the confirmed target/window, retain exact query/result bytes, and assess/report limits.
Guides and references
| Document | Use it for |
|---|---|
| Setup | Clients, authentication choices/permissions, previews, saved host evidence, native recovery. |
| Inventory | Every guided action, parser review/bindings, field batches, completion and status. |
| Application flow | End-to-end operator/model/CLI boundaries. |
| Command reference | Every command/flag, default, mode, input/output and exit policy. |
| Contracts | Nine schemas, request/result/state fields, JSONL and diagnostics. |
| Query reference | Typed plans, all recipes/functions, bounded English and raw CQL checks. |
| Environment | Identity, credentials, native/legacy packs, discovery budgets, evidence and refresh. |
| MCP companion | Exact agent-relayed probes/results, state lifecycle, activation and recovery. |
| Result assessment | Saved-result checks, caps, nulls, empty/zero, outcomes and limits. |
| Coverage | Implemented profile, assurance boundaries and exclusions. |
| Troubleshooting | Diagnostic families and safe next actions. |
| Architecture | Data flow, module ownership, I/O and trust boundaries. |
| Development, contributing, releasing | Build, validation, contribution and authorized publication procedures. |
Offline, authenticated, and local effects
| Operation | Network/authentication | Local effects |
|---|---|---|
| Generate/check, catalog, schemas, assess, inspect, status | Offline; no Falcon/model key needed. | Read explicit inputs/state; emit assessments. |
No-request setup --json |
Offline; no native capability/config probing. | Read saved setup status without creating state. |
| Setup detect/select/preview/apply | Capability probes are local; native apply/login can open browser consent and use the client's connection. | Save setup state, preview/backup and reviewed native configuration where applicable. |
| Inventory actions | Most are local; parser fetch uses a separate protected Falcon API client; emitted scout/discovery probes are run by the host's authorized MCP connection. | Save sensitive workflow evidence, snapshots, parser review and cumulative active pack. |
env identity |
Reads credentials, no network. | Emit local account binding; not a provider-verified CID. |
env import |
Offline. | Validate and create/explicitly replace a protected pack. |
env discover without execution/relay flags |
Offline plan. | Print initial probes/deferred stages; no credentials or searches. |
env discover --mcp |
CLI relays saved results; host performs authorized read-only searches. | Save state/captures and eventually activate pack/receipt. |
env discover --execute, env parsers |
Explicit authenticated Falcon API operation. | Bounded jobs/cleanup or metadata reads; discovery saves report/pack. |
The API search-job lifecycle needs READ and WRITE scopes for creating/polling/stopping jobs; it does not write tenant configuration. Read-only MCP search and parser API reads have separate permissions. Client OAuth consent is not proof of telemetry visibility or parser access. See permissions.
Runnable synthetic material
- Setup requests.
- Inventory and parser review.
- MCP relay, generation and assessment.
- Query-family requests and expected CQL.
- Offline observation import.
- Assessment outcomes.
Examples demonstrate mechanics, not real source names, observed tenant fields, or runtime correctness. Use protected operator-supplied identity/data for authorized operations. No automatic query execution, tenant-configuration deployment, broad search authorization, model memory, or evidence freshness policy is implied.
For sensitive issues follow security reporting. Keep credentials, environment maps, parser definitions, states, receipts, and raw results out of public feedback. Licensing and retained third-party attribution are in LICENSE and NOTICE.