Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
eaf8aca
Add Investigation Engine SDK and investigate CLI group
maximelb Nov 10, 2026
1f90fb0
Investigation Engine: tests, docs, help topic, changelog
maximelb Nov 10, 2026
cad3f10
Investigation Engine CLI: review round 1
maximelb Nov 10, 2026
8fc2401
Investigation Engine CLI: landed-write guard also compares comment an…
maximelb Nov 10, 2026
4c42051
Investigation Engine CLI: YAML 1.2 input files, structured errors for…
maximelb Nov 10, 2026
5a4302f
Investigation Engine CLI: drop a dead assignment in a test
maximelb Nov 10, 2026
5e20b76
Investigation Engine CLI: flags, enums and help match the engine
maximelb Nov 10, 2026
178a9fd
Investigation CLI: tests and docs for report.summary sentences of bot…
maximelb Nov 11, 2026
aef84c4
Investigation CLI: read and write scalars exactly as the engine's YAM…
maximelb Nov 11, 2026
5f77b1f
Investigation CLI: pin the typed template fields to the engine's type…
maximelb Nov 11, 2026
85824ba
Explain read-only live sensor identity permissions
maximelb Nov 11, 2026
b0b05c8
Add investigation run deletion to the SDK and CLI
maximelb Nov 11, 2026
3cc81af
Investigation CLI: say when the API does not serve run deletion; drop…
maximelb Nov 11, 2026
7834408
Investigation CLI: rebuild the run-deletion 404 error so the message …
maximelb Nov 11, 2026
39a1891
Preserve template test decision diagnostics in CLI output (#456)
maximelb Nov 12, 2026
4dbb801
Merge current master into investigation CLI preparation
maximelb Nov 14, 2026
c2d1b8d
Bound investigation pagination and add resumable follow controls
maximelb Nov 14, 2026
0d4a0e9
Make investigation compatibility fixture regeneration reproducible
maximelb Nov 14, 2026
ce651d5
Use explicit UTF-8 for investigation fixture text I/O
maximelb Nov 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,41 @@
`Client(max_decoded_response_bytes=...)`; 0 or a negative value removes it.
Uncompressed responses are not limited.

### Investigation Engine — `limacharlie investigate` (experimental)

- New `investigate` command group and `limacharlie.sdk.investigation.Investigation`
SDK class to build, test and tune Investigation Engine templates and to run
investigations, so a person or an AI agent can drive the whole loop from the
CLI: `kit` (authoring kit, fetched in sections), `operators`, `packs`,
`templates list|get|validate|test|save|promote|delete|install-defaults`,
`runs start|get|list|events|steps|case|cancel|delete`, `wave`,
`actions list|approve|deny` and `policy get|status|pause|resume`. See
`doc/cli/investigation-engine.md`.
- `templates save` always writes a DRAFT (a source that says `status: active`
is refused; only a person's explicit `--status active` activates), never
overwrites a record without `--overwrite`, and never replaces an active
template with a draft. `templates test` dry-runs a template on real past
detections or cases and prints per-sample verdicts and the agreement summary.
- Engine failures keep the engine's coded issues (`code`, `path`, `message`,
`suggestion`) and error code verbatim, and say when the feature is not
enabled for the deployment or the permissions are missing.
- `wave` and `templates test --samples-file` read YAML with 1.2 scalar rules (`off`/`yes`
stay text, an unquoted date stays a string) so values reach the engine as written;
unreadable or malformed input files and every Hive/API failure are reported as
structured JSON (with the backend's `error_code`) in a structured output format.
- `templates install-defaults` reads the authoring kit's `library` section; it
needs an engine version that serves it.
- The typed 401/403/404/422/429 errors raised for an HTTP error answer now carry
the parsed answer as `response_body`, as `ApiError` already did.
- The `investigate` flags and help match the engine: `runs start --urgency` is
`low|medium|high|critical` (default derived from the alert, else medium);
`--auto` sends no plan (the engine refuses `plan.auto` for a person's run) so
the engine picks the active template by `applies_to`, with new `--category`,
`--severity`, `--priority` and `--tag` to say what the alert looks like;
`templates test --strict` refuses overrides that would loosen the policy;
`runs list --trigger` takes the trigger kind (detection, message, entity, case,
question) and `--verdict` also takes `undecided`; `policy get` takes `--template`.

### Sync — `sync push` no longer turns quoted strings into numbers

- `sync push` (and `Configs.push` / `Configs.push_from_file`) stored some
Expand Down
1 change: 1 addition & 0 deletions doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
| [Hive & Data Stores](cli/hive-data.md) | hive, secret, lookup, playbook, note, sop, app-control, adapter, cloud-sensor, extension |
| [Infrastructure](cli/infrastructure.md) | sync, output, artifact, payload, yara, integrity, logging, exfil |
| [Cloud Security & Code Security](cli/cloud-security.md) | cloudsec (findings, inventory, graph, compliance, CAASM, code lane, container images, fleet, exports) |
| [Investigation Engine](cli/investigation-engine.md) | investigate (authoring kit, templates, dry runs on past alerts, runs, waves, approvals, policy) |
| [Email Security](cli/email-security.md) | mailsec (onboarding, coverage, triage, EML, remediation, campaigns, reports, sample submission, rules, tenant purge) |
| [Other Commands](cli/other-commands.md) | api, arl, usp, spotcheck, job, schema, completion, help/discover |

Expand Down
1 change: 1 addition & 0 deletions doc/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,7 @@ limacharlie schema dr create
| [Infrastructure](infrastructure.md) | sync, output, artifact, payload, yara, integrity, logging, exfil |
| [Cloud Security & Code Security](cloud-security.md) | cloudsec (findings, inventory, graph, compliance, CAASM, code lane, container images, fleet, exports) |
| [Email Security](email-security.md) | mailsec (onboarding, coverage, triage, EML, remediation, campaigns, reports, sample submission, rules, tenant purge) |
| [Investigation Engine](investigation-engine.md) | investigate (authoring kit, templates, dry runs on past alerts, runs, waves, approvals, policy) |
| [Other Commands](other-commands.md) | api, arl, usp, spotcheck, job, schema, completion, help/discover, case |

## See Also
Expand Down
243 changes: 243 additions & 0 deletions doc/cli/investigation-engine.md

Large diffs are not rendered by default.

4 changes: 4 additions & 0 deletions doc/sdk/other-classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,10 @@ The Cloud Security (CNAPP) surface also includes Code Security: repository and c

`limacharlie.sdk.mailsec.Mailsec` wraps Email Security onboarding, provider tests, coverage, messages, justified EML downloads, verdict revisions, campaigns, remediation, and user reports. See [Security Products](security-products.md#email-security) for setup, examples, and pagination, and [CLI: mailsec](../cli/email-security.md) for complete workflows.

## Investigation

`limacharlie.sdk.investigation.Investigation` wraps the Investigation Engine (experimental): the authoring kit, plan validation and dry runs on past alerts, template records (saved as drafts unless a person passes `status="active"`), runs, waves, the approvals inbox and the autonomy switch. Failures raise `InvestigationError`, which keeps the engine's `error_code` and coded `issues`. See [CLI: investigate](../cli/investigation-engine.md) for the workflow and permissions.

## See Also

- [CLI: case](../cli/other-commands.md#case) — Case CLI commands
Expand Down
1 change: 1 addition & 0 deletions limacharlie/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@ def _wants_help() -> bool:
"hive": ("hive", "group"),
"ingestion-key": ("ingestion_key", "group"),
"installation-key": ("installation_key", "group"),
"investigate": ("investigate", "group"),
"integrity": ("integrity", "group"),
"ioc": ("ioc", "group"),
"job": ("job", "group"),
Expand Down
4 changes: 3 additions & 1 deletion limacharlie/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -967,11 +967,13 @@ def request(self, verb: str, url: str, params: dict[str, Any] | None = None, alt
self._debug(f"Rate limited, waiting {wait}s before retry...")
time.sleep(wait)
continue
raise RateLimitError(
rate_err = RateLimitError(
f"Rate limit exceeded: {data}",
retry_after=parse_retry_after(error_headers.get("retry-after")),
code=code,
)
rate_err.response_body = data
raise rate_err

if code == HTTP_SERVICE_UNAVAILABLE:
if retry_service_unavailable and not has_unavailable_retried and retries < max_retries:
Expand Down
Loading
Loading