From b2fcc3448758d02461e28ff1af1d0138f0016fa9 Mon Sep 17 00:00:00 2001 From: Maxime Lamothe-Brassard Date: Wed, 11 Feb 2026 14:23:02 -0800 Subject: [PATCH 001/112] Add CLI & SDK v2.0.0 - complete rewrite with Click framework Full rewrite of the LimaCharlie Python SDK and CLI (v2.0.0) with AI/LLM-first discoverability. All commands follow a consistent noun-verb pattern with rich help, --explain flags, and multiple output formats (json/yaml/csv/table/jsonl). Core infrastructure: - Click-based CLI with auto-discovered command modules - HTTP client with JWT auth, retry with backoff, rate limiting - Config system supporting ~/.limacharlie, env vars, named environments - Structured error hierarchy with suggestion messages - Output formatting with jmespath filtering SDK (31 modules in limacharlie/sdk/): - Organization, Sensor, D&R Rules, FP Rules, Hive, Outputs - Artifacts, Payloads, Search, Extensions, Installation/Ingestion Keys - Users, Groups, API Keys, Billing, Spout, Replay - Integrity, Exfil, Logging Rules, Configs (sync), AI generation - Investigations, USP, Jobs, YARA, ARL CLI (49 command modules in limacharlie/commands/): - Full CRUD for all resource types - Hive shortcuts: secret, lookup, playbook, adapter, cloud-sensor, sop, note - Help system: discover, help topics, cheatsheets, schema - Streaming, sync, search with LCQL support Tests: - 481 unit tests (v2) covering all SDK and core modules - 25 integration test files (63 tests) for API validation - Removed 3 obsolete v1 unit tests replaced by v2 equivalents Packaging: - Entry point updated to limacharlie.cli:main - Added click>=8.0 and jmespath dependencies Co-Authored-By: Claude Opus 4.6 --- NEW_CLI.md | 1291 +++++++++++++++++++ README.md | 513 ++++---- limacharlie/__main__.py | 593 +-------- limacharlie/cli.py | 109 ++ limacharlie/client.py | 400 ++++++ limacharlie/commands/__init__.py | 1 + limacharlie/commands/_hive_shortcut.py | 130 ++ limacharlie/commands/adapter.py | 3 + limacharlie/commands/ai.py | 134 ++ limacharlie/commands/api_key.py | 193 +++ limacharlie/commands/arl.py | 96 ++ limacharlie/commands/artifact.py | 131 ++ limacharlie/commands/audit.py | 116 ++ limacharlie/commands/auth.py | 288 +++++ limacharlie/commands/billing.py | 180 +++ limacharlie/commands/cloud_sensor.py | 3 + limacharlie/commands/detection.py | 134 ++ limacharlie/commands/event.py | 145 +++ limacharlie/commands/exfil.py | 243 ++++ limacharlie/commands/extension.py | 163 +++ limacharlie/commands/fp.py | 250 ++++ limacharlie/commands/group.py | 201 +++ limacharlie/commands/help_cmd.py | 186 +++ limacharlie/commands/hive.py | 365 ++++++ limacharlie/commands/ingestion_key.py | 175 +++ limacharlie/commands/installation_key.py | 188 +++ limacharlie/commands/integrity.py | 193 +++ limacharlie/commands/investigation.py | 224 ++++ limacharlie/commands/ioc.py | 192 +++ limacharlie/commands/job.py | 221 ++++ limacharlie/commands/logging_cmd.py | 192 +++ limacharlie/commands/lookup.py | 3 + limacharlie/commands/net_policy.py | 171 +++ limacharlie/commands/note.py | 3 + limacharlie/commands/org.py | 324 +++++ limacharlie/commands/output_cmd.py | 213 +++ limacharlie/commands/payload.py | 137 ++ limacharlie/commands/playbook.py | 3 + limacharlie/commands/replay_cmd.py | 155 +++ limacharlie/commands/rule.py | 421 ++++++ limacharlie/commands/schema.py | 124 ++ limacharlie/commands/search.py | 145 +++ limacharlie/commands/secret.py | 3 + limacharlie/commands/sensor.py | 284 ++++ limacharlie/commands/sop.py | 3 + limacharlie/commands/spotcheck.py | 63 + limacharlie/commands/stream.py | 193 +++ limacharlie/commands/sync.py | 252 ++++ limacharlie/commands/tag.py | 212 +++ limacharlie/commands/task.py | 121 ++ limacharlie/commands/user.py | 175 +++ limacharlie/commands/usp.py | 132 ++ limacharlie/commands/yara.py | 352 +++++ limacharlie/config.py | 242 ++++ limacharlie/discovery.py | 171 +++ limacharlie/errors.py | 169 +++ limacharlie/help_topics.py | 800 ++++++++++++ limacharlie/output.py | 236 ++++ limacharlie/sdk/__init__.py | 1 + limacharlie/sdk/ai.py | 49 + limacharlie/sdk/api_keys.py | 15 + limacharlie/sdk/arl.py | 24 + limacharlie/sdk/artifacts.py | 87 ++ limacharlie/sdk/billing.py | 33 + limacharlie/sdk/configs.py | 278 ++++ limacharlie/sdk/dr_rules.py | 35 + limacharlie/sdk/exfil.py | 43 + limacharlie/sdk/extensions.py | 33 + limacharlie/sdk/firehose.py | 264 ++++ limacharlie/sdk/fp_rules.py | 23 + limacharlie/sdk/groups.py | 42 + limacharlie/sdk/hive.py | 270 ++++ limacharlie/sdk/ingestion_keys.py | 18 + limacharlie/sdk/insight.py | 88 ++ limacharlie/sdk/installation_keys.py | 18 + limacharlie/sdk/integrity.py | 27 + limacharlie/sdk/investigations.py | 33 + limacharlie/sdk/jobs.py | 43 + limacharlie/sdk/logging_rules.py | 31 + limacharlie/sdk/organization.py | 996 ++++++++++++++ limacharlie/sdk/outputs.py | 17 + limacharlie/sdk/payloads.py | 50 + limacharlie/sdk/replay.py | 60 + limacharlie/sdk/search.py | 121 ++ limacharlie/sdk/sensor.py | 294 +++++ limacharlie/sdk/spout.py | 171 +++ limacharlie/sdk/users.py | 24 + limacharlie/sdk/usp.py | 51 + limacharlie/sdk/yara.py | 52 + requirements.txt | 2 + setup.py | 8 +- tests/integration/test_v2_ai.py | 51 + tests/integration/test_v2_artifacts.py | 62 + tests/integration/test_v2_auth.py | 50 + tests/integration/test_v2_billing.py | 20 + tests/integration/test_v2_cli_e2e.py | 47 + tests/integration/test_v2_exfil.py | 111 ++ tests/integration/test_v2_extensions.py | 25 + tests/integration/test_v2_groups.py | 70 + tests/integration/test_v2_hive.py | 62 + tests/integration/test_v2_integrity.py | 128 ++ tests/integration/test_v2_jobs.py | 37 + tests/integration/test_v2_keys.py | 184 +++ tests/integration/test_v2_logging.py | 74 ++ tests/integration/test_v2_org.py | 44 + tests/integration/test_v2_org_management.py | 72 ++ tests/integration/test_v2_outputs.py | 60 + tests/integration/test_v2_replay.py | 44 + tests/integration/test_v2_rules.py | 103 ++ tests/integration/test_v2_search.py | 48 + tests/integration/test_v2_sensors.py | 25 + tests/integration/test_v2_stream.py | 71 + tests/integration/test_v2_sync.py | 63 + tests/integration/test_v2_users.py | 42 + tests/integration/test_v2_usp.py | 69 + tests/integration/test_v2_yara.py | 36 + tests/integration/v2_conftest.py | 47 + tests/unit/test_cli_commands.py | 38 + tests/unit/test_cli_sanity.py | 66 - tests/unit/test_client.py | 224 ++++ tests/unit/test_config.py | 225 ++++ tests/unit/test_discovery.py | 70 + tests/unit/test_errors.py | 115 ++ tests/unit/test_login.py | 225 ---- tests/unit/test_output.py | 162 +++ tests/unit/test_sdk_configs.py | 139 ++ tests/unit/test_sdk_dr_rules.py | 77 ++ tests/unit/test_sdk_hive.py | 179 +++ tests/unit/test_sdk_misc.py | 389 ++++++ tests/unit/test_sdk_organization.py | 167 +++ tests/unit/test_sdk_search.py | 87 ++ tests/unit/test_sdk_sensor.py | 104 ++ tests/unit/test_sdk_spout.py | 133 ++ tests/unit/test_user_invite.py | 125 -- 134 files changed, 18557 insertions(+), 1274 deletions(-) create mode 100644 NEW_CLI.md create mode 100644 limacharlie/cli.py create mode 100644 limacharlie/client.py create mode 100644 limacharlie/commands/__init__.py create mode 100644 limacharlie/commands/_hive_shortcut.py create mode 100644 limacharlie/commands/adapter.py create mode 100644 limacharlie/commands/ai.py create mode 100644 limacharlie/commands/api_key.py create mode 100644 limacharlie/commands/arl.py create mode 100644 limacharlie/commands/artifact.py create mode 100644 limacharlie/commands/audit.py create mode 100644 limacharlie/commands/auth.py create mode 100644 limacharlie/commands/billing.py create mode 100644 limacharlie/commands/cloud_sensor.py create mode 100644 limacharlie/commands/detection.py create mode 100644 limacharlie/commands/event.py create mode 100644 limacharlie/commands/exfil.py create mode 100644 limacharlie/commands/extension.py create mode 100644 limacharlie/commands/fp.py create mode 100644 limacharlie/commands/group.py create mode 100644 limacharlie/commands/help_cmd.py create mode 100644 limacharlie/commands/hive.py create mode 100644 limacharlie/commands/ingestion_key.py create mode 100644 limacharlie/commands/installation_key.py create mode 100644 limacharlie/commands/integrity.py create mode 100644 limacharlie/commands/investigation.py create mode 100644 limacharlie/commands/ioc.py create mode 100644 limacharlie/commands/job.py create mode 100644 limacharlie/commands/logging_cmd.py create mode 100644 limacharlie/commands/lookup.py create mode 100644 limacharlie/commands/net_policy.py create mode 100644 limacharlie/commands/note.py create mode 100644 limacharlie/commands/org.py create mode 100644 limacharlie/commands/output_cmd.py create mode 100644 limacharlie/commands/payload.py create mode 100644 limacharlie/commands/playbook.py create mode 100644 limacharlie/commands/replay_cmd.py create mode 100644 limacharlie/commands/rule.py create mode 100644 limacharlie/commands/schema.py create mode 100644 limacharlie/commands/search.py create mode 100644 limacharlie/commands/secret.py create mode 100644 limacharlie/commands/sensor.py create mode 100644 limacharlie/commands/sop.py create mode 100644 limacharlie/commands/spotcheck.py create mode 100644 limacharlie/commands/stream.py create mode 100644 limacharlie/commands/sync.py create mode 100644 limacharlie/commands/tag.py create mode 100644 limacharlie/commands/task.py create mode 100644 limacharlie/commands/user.py create mode 100644 limacharlie/commands/usp.py create mode 100644 limacharlie/commands/yara.py create mode 100644 limacharlie/config.py create mode 100644 limacharlie/discovery.py create mode 100644 limacharlie/errors.py create mode 100644 limacharlie/help_topics.py create mode 100644 limacharlie/output.py create mode 100644 limacharlie/sdk/__init__.py create mode 100644 limacharlie/sdk/ai.py create mode 100644 limacharlie/sdk/api_keys.py create mode 100644 limacharlie/sdk/arl.py create mode 100644 limacharlie/sdk/artifacts.py create mode 100644 limacharlie/sdk/billing.py create mode 100644 limacharlie/sdk/configs.py create mode 100644 limacharlie/sdk/dr_rules.py create mode 100644 limacharlie/sdk/exfil.py create mode 100644 limacharlie/sdk/extensions.py create mode 100644 limacharlie/sdk/firehose.py create mode 100644 limacharlie/sdk/fp_rules.py create mode 100644 limacharlie/sdk/groups.py create mode 100644 limacharlie/sdk/hive.py create mode 100644 limacharlie/sdk/ingestion_keys.py create mode 100644 limacharlie/sdk/insight.py create mode 100644 limacharlie/sdk/installation_keys.py create mode 100644 limacharlie/sdk/integrity.py create mode 100644 limacharlie/sdk/investigations.py create mode 100644 limacharlie/sdk/jobs.py create mode 100644 limacharlie/sdk/logging_rules.py create mode 100644 limacharlie/sdk/organization.py create mode 100644 limacharlie/sdk/outputs.py create mode 100644 limacharlie/sdk/payloads.py create mode 100644 limacharlie/sdk/replay.py create mode 100644 limacharlie/sdk/search.py create mode 100644 limacharlie/sdk/sensor.py create mode 100644 limacharlie/sdk/spout.py create mode 100644 limacharlie/sdk/users.py create mode 100644 limacharlie/sdk/usp.py create mode 100644 limacharlie/sdk/yara.py create mode 100644 tests/integration/test_v2_ai.py create mode 100644 tests/integration/test_v2_artifacts.py create mode 100644 tests/integration/test_v2_auth.py create mode 100644 tests/integration/test_v2_billing.py create mode 100644 tests/integration/test_v2_cli_e2e.py create mode 100644 tests/integration/test_v2_exfil.py create mode 100644 tests/integration/test_v2_extensions.py create mode 100644 tests/integration/test_v2_groups.py create mode 100644 tests/integration/test_v2_hive.py create mode 100644 tests/integration/test_v2_integrity.py create mode 100644 tests/integration/test_v2_jobs.py create mode 100644 tests/integration/test_v2_keys.py create mode 100644 tests/integration/test_v2_logging.py create mode 100644 tests/integration/test_v2_org.py create mode 100644 tests/integration/test_v2_org_management.py create mode 100644 tests/integration/test_v2_outputs.py create mode 100644 tests/integration/test_v2_replay.py create mode 100644 tests/integration/test_v2_rules.py create mode 100644 tests/integration/test_v2_search.py create mode 100644 tests/integration/test_v2_sensors.py create mode 100644 tests/integration/test_v2_stream.py create mode 100644 tests/integration/test_v2_sync.py create mode 100644 tests/integration/test_v2_users.py create mode 100644 tests/integration/test_v2_usp.py create mode 100644 tests/integration/test_v2_yara.py create mode 100644 tests/integration/v2_conftest.py create mode 100644 tests/unit/test_cli_commands.py delete mode 100644 tests/unit/test_cli_sanity.py create mode 100644 tests/unit/test_client.py create mode 100644 tests/unit/test_config.py create mode 100644 tests/unit/test_discovery.py create mode 100644 tests/unit/test_errors.py delete mode 100644 tests/unit/test_login.py create mode 100644 tests/unit/test_output.py create mode 100644 tests/unit/test_sdk_configs.py create mode 100644 tests/unit/test_sdk_dr_rules.py create mode 100644 tests/unit/test_sdk_hive.py create mode 100644 tests/unit/test_sdk_misc.py create mode 100644 tests/unit/test_sdk_organization.py create mode 100644 tests/unit/test_sdk_search.py create mode 100644 tests/unit/test_sdk_sensor.py create mode 100644 tests/unit/test_sdk_spout.py delete mode 100644 tests/unit/test_user_invite.py diff --git a/NEW_CLI.md b/NEW_CLI.md new file mode 100644 index 00000000..cc525902 --- /dev/null +++ b/NEW_CLI.md @@ -0,0 +1,1291 @@ +# LimaCharlie Python SDK & CLI v2.0.0 - Design & Implementation Plan + +## Executive Summary + +This document describes the design for a complete rewrite of the LimaCharlie Python SDK and CLI (v2.0.0). The primary design goal is **AI/LLM-first discoverability**: every command, parameter, and concept should be self-documenting enough that an AI agent (like Claude Code) can operate the CLI effectively without prior LimaCharlie knowledge. + +The new CLI covers 100%+ of the current CLI features, plus new capabilities from the API gateway (AI generation, groups, investigations, SOPs, org notes, etc.). + +--- + +## Table of Contents + +1. [Design Principles](#1-design-principles) +2. [CLI Architecture](#2-cli-architecture) +3. [Authentication & Configuration](#3-authentication--configuration) +4. [SDK Core Classes](#4-sdk-core-classes) +5. [Command Groups & Commands](#5-command-groups--commands) +6. [Output & Formatting](#6-output--formatting) +7. [AI/LLM Discoverability Features](#7-aillm-discoverability-features) +8. [Testing Strategy](#8-testing-strategy) +9. [Migration & Packaging](#9-migration--packaging) +10. [Detailed Command Reference](#10-detailed-command-reference) +11. [Implementation Checklist](#11-implementation-checklist) + +--- + +## 1. Design Principles + +### 1.1 AI/LLM-First Discoverability +- [ ] Every command has a `--explain` flag that prints a detailed paragraph explaining what the command does, when to use it, and common patterns +- [ ] Every parameter has a rich `help=` string with type info, examples, and constraints +- [ ] `limacharlie help ` provides concept guides (e.g., `limacharlie help d&r-rules`, `limacharlie help hive`, `limacharlie help lcql`) +- [ ] `limacharlie discover` lists all commands grouped by use-case profile (matching MCP server profiles: sensor_management, detection_engineering, platform_admin, etc.) +- [ ] `limacharlie cheatsheet ` prints quick-reference examples +- [ ] Every error message includes a suggestion for what to do next +- [ ] JSON Schema output available for every command's parameters via `limacharlie schema ` + +### 1.2 Consistent Command Structure +- [ ] All commands follow `limacharlie ` pattern (e.g., `limacharlie sensor list`, `limacharlie rule create`) +- [ ] CRUD operations use consistent verbs: `list`, `get`, `create`, `update`, `delete` +- [ ] Bulk operations use consistent verbs: `export`, `import`, `sync` +- [ ] Destructive operations require `--confirm` or print a confirmation prompt +- [ ] All identifiers use consistent flag names: `--oid`, `--sid`, `--name`, `--key` + +### 1.3 Machine-Readable Output +- [ ] Default output is human-readable tables (for interactive use) +- [ ] `--output json` for JSON (default when stdout is piped/not a TTY) +- [ ] `--output yaml` for YAML +- [ ] `--output csv` for CSV +- [ ] `--output jsonl` for newline-delimited JSON (for streaming) +- [ ] `--quiet` / `-q` suppresses all output except errors +- [ ] Exit codes are meaningful: 0=success, 1=general error, 2=auth error, 3=not found, 4=validation error + +### 1.4 Composability +- [ ] All commands accept `--oid` to specify org (overrides env/config) +- [ ] All create/update commands support `--input-file` to read parameters from JSON/YAML file (rule create, hive set, output create, extension config set, etc.) +- [ ] All list commands support `--filter` for client-side jmespath filtering +- [ ] All list commands support `--limit` and `--offset` for pagination +- [ ] Stdin support for piping data between commands + +--- + +## 2. CLI Architecture + +### 2.1 Entry Point & Framework +- [ ] Use `click` library for CLI framework (replacing raw argparse) +- [ ] Single entry point: `limacharlie` command with click groups +- [ ] Plugin architecture: each command group is a separate module auto-discovered from `limacharlie/commands/` +- [ ] Global options: `--oid`, `--env`, `--output`, `--debug`, `--quiet`, `--profile` +- [ ] Version command: `limacharlie version` (replaces `limacharlie version`) + +### 2.2 Module Structure + +v2 replaces the existing code directly in the `limacharlie/` package (no backwards compatibility with v1 needed). Old v1 modules are removed. + +``` +limacharlie/ +├── __init__.py +├── __main__.py # Entry point: limacharlie CLI +├── cli.py # Main CLI entry point & click groups +├── config.py # Auth & configuration management +├── client.py # HTTP client with retry, auth, rate limiting +├── output.py # Output formatting (json/yaml/csv/table) +├── errors.py # Custom exception hierarchy +├── help_topics.py # Inline help topic content +├── discovery.py # Command discovery & explain system +├── sdk/ +│ ├── __init__.py +│ ├── organization.py # Organization management +│ ├── sensor.py # Sensor operations +│ ├── dr_rules.py # Detection & Response rules +│ ├── fp_rules.py # False positive rules +│ ├── hive.py # Hive key-value store +│ ├── outputs.py # Output integrations +│ ├── artifacts.py # Artifact/log management +│ ├── payloads.py # Payload management +│ ├── search.py # Search & LCQL queries +│ ├── insight.py # IOC search & event queries +│ ├── extensions.py # Extension management +│ ├── installation_keys.py # Installation key management +│ ├── ingestion_keys.py # Ingestion key management +│ ├── users.py # User & permission management +│ ├── groups.py # Organization group management +│ ├── api_keys.py # API key management +│ ├── billing.py # Billing & usage +│ ├── spout.py # Real-time streaming (WebSocket) +│ ├── firehose.py # Real-time streaming (TCP/TLS) +│ ├── replay.py # D&R rule replay/testing +│ ├── integrity.py # Integrity monitoring rules +│ ├── exfil.py # Exfil prevention rules +│ ├── logging_rules.py # Logging/log collection rules +│ ├── configs.py # Configuration sync (IaC) +│ ├── ai.py # AI-powered generation +│ ├── investigations.py # Investigation management +│ ├── usp.py # USP adapter validation +│ ├── jobs.py # Service job tracking +│ ├── yara.py # YARA scanning & rule management +│ └── arl.py # Authenticated Resource Locator resolution +├── commands/ +│ ├── __init__.py +│ ├── auth.py # login, logout, whoami, use-org +│ ├── sensor.py # sensor list, get, delete, upgrade, export, dump, sweep +│ ├── rule.py # rule list, get, create, delete, test, ... +│ ├── fp.py # fp list, get, create, delete +│ ├── hive.py # hive list, get, set, delete, validate, ... +│ ├── output_cmd.py # output list, create, delete +│ ├── artifact.py # artifact upload, list, download +│ ├── payload.py # payload list, upload, download, delete +│ ├── search.py # search run, validate, interactive, saved-queries +│ ├── ioc.py # ioc search, batch-search, enrich +│ ├── event.py # event list, get, timeline +│ ├── detection.py # detection list, get +│ ├── extension.py # extension list, subscribe, unsubscribe, convert-rules, ... +│ ├── installation_key.py # installation-key list, create, delete +│ ├── ingestion_key.py # ingestion-key list, create, delete, configure +│ ├── user.py # user list, invite, remove, permission +│ ├── group.py # group list, create, delete, member, ... +│ ├── api_key.py # api-key list, create, delete +│ ├── org.py # org info, create, delete, rename, config, errors, ... +│ ├── billing.py # billing status, details, invoice, plans +│ ├── stream.py # stream events, detections, audit (spout) +│ ├── replay_cmd.py # replay run, test-rule +│ ├── integrity.py # integrity list, create, delete +│ ├── exfil.py # exfil list, create, delete +│ ├── logging_cmd.py # logging list, create, delete +│ ├── sync.py # sync push, pull, diff +│ ├── ai.py # ai generate-rule, generate-query, ... +│ ├── investigation.py # investigation list, get, create, delete +│ ├── usp.py # usp validate +│ ├── schema.py # schema list, get +│ ├── tag.py # tag list, add, remove, mass-tag +│ ├── task.py # task send, reliable-send, list-reliable +│ ├── net_policy.py # net-policy (isolate, rejoin) +│ ├── yara.py # yara scan, rules, sources +│ ├── cloud_sensor.py # cloud-sensor list, get, set, delete +│ ├── job.py # job list, get, delete, wait +│ ├── arl.py # arl get +│ ├── spotcheck.py # spotcheck run +│ ├── secret.py # secret list, get, set, delete (NEW) +│ ├── lookup.py # lookup list, get, set, query, delete (NEW) +│ ├── playbook.py # playbook list, get, set, delete (NEW) +│ ├── adapter.py # adapter list, get, set, delete (NEW) +│ ├── sop.py # sop list, get, set, delete (NEW) +│ ├── note.py # note list, get, set, delete (NEW) +│ ├── audit.py # audit list +│ └── help_cmd.py # help, discover, cheatsheet, schema +tests/ +├── unit/ +│ ├── __init__.py +│ ├── conftest.py +│ ├── test_cli_commands.py +│ ├── test_config.py +│ ├── test_client.py +│ ├── test_output.py +│ ├── test_errors.py +│ ├── test_sdk_organization.py +│ ├── test_sdk_sensor.py +│ ├── test_sdk_dr_rules.py +│ ├── test_sdk_hive.py +│ ├── test_sdk_search.py +│ ├── test_sdk_configs.py +│ └── ... +└── integration/ + ├── __init__.py + ├── conftest.py # Integration fixtures with cleanup + ├── test_auth.py + ├── test_sensor.py + ├── test_rules.py + ├── test_hive.py + ├── test_outputs.py + ├── test_artifacts.py + ├── test_search.py + ├── test_extensions.py + ├── test_users.py + ├── test_api_keys.py + ├── test_installation_keys.py + ├── test_ingestion_keys.py + ├── test_sync.py + ├── test_replay.py + ├── test_stream.py + ├── test_ai.py + ├── test_billing.py + ├── test_groups.py + ├── test_org_management.py + ├── test_usp.py + ├── test_integrity.py + ├── test_exfil.py + ├── test_logging.py + ├── test_yara.py + ├── test_jobs.py + └── test_cli_e2e.py # End-to-end CLI tests +``` + +- [ ] Create this directory structure (remove all v1 modules) +- [ ] Each command module auto-registers its click group + +### 2.3 Clean Break from v1 +This is a full v2.0.0 rewrite with no backwards compatibility requirement: +- [ ] v2 code replaces v1 code directly in the `limacharlie/` package (no `v2/` subpackage) +- [ ] All v1 modules (Manager.py, Sensor.py, etc.) are removed +- [ ] Entry point `limacharlie` runs the new Click-based CLI +- [ ] SDK classes available as `limacharlie.sdk.*` (e.g., `from limacharlie.sdk.organization import Organization`) +- [ ] No fallback to v1 CLI, no `limacharlie-v1` entry point + +--- + +## 3. Authentication & Configuration + +### 3.1 Credential Storage +- [ ] Same file location: `~/.limacharlie` (YAML format) +- [ ] Support named environments/profiles: `limacharlie auth use-env production` +- [ ] Environment variables: `LC_OID`, `LC_API_KEY`, `LC_UID`, `LC_CURRENT_ENV`, `LC_CREDS_FILE`, `LC_EPHEMERAL_CREDS` +- [ ] Ephemeral mode (no disk writes) via `LC_EPHEMERAL_CREDS=1` +- [ ] File permissions enforced at 600 + +### 3.2 Auth Commands +- [ ] `limacharlie auth login` - Interactive login (OAuth or API key) +- [ ] `limacharlie auth login --api-key --oid ` - Non-interactive API key login +- [ ] `limacharlie auth login --uid --api-key ` - User-scoped API key login +- [ ] `limacharlie auth logout` - Clear stored credentials +- [ ] `limacharlie auth whoami` - Show current identity, permissions, accessible orgs +- [ ] `limacharlie auth test [--permissions perm1,perm2]` - Test current auth and optional specific permissions +- [ ] `limacharlie auth use-env ` - Switch named environment +- [ ] `limacharlie auth list-envs` - List configured environments +- [ ] `limacharlie auth use-org ` - Set default organization (resolves names to OIDs) +- [ ] `limacharlie auth list-orgs [--filter ]` - List accessible organizations + +### 3.3 Client Features +- [ ] Automatic JWT generation and refresh +- [ ] Retry logic: 3 retries with exponential backoff for 429/504 +- [ ] Rate limit awareness: log warnings on rate limit headers +- [ ] Request debugging via `--debug` (prints curl-equivalent commands) +- [ ] User-Agent header: `limacharlie-cli/2.0.0 python/3.x` +- [ ] Idempotent key support for safe retries on write operations + +--- + +## 4. SDK Core Classes + +### 4.1 Client +- [ ] `limacharlie.Client(oid, api_key, uid, environment, jwt, ...)` +- [ ] Automatic credential resolution: explicit params > env vars > config file +- [ ] Thread-safe JWT management with automatic refresh +- [ ] Request/response logging for debugging +- [ ] Rate limit tracking and backoff +- [ ] Context manager support (`with Client(...) as client:`) + +### 4.2 Organization +- [ ] `Organization(client)` - Main entry point for all org-scoped operations +- [ ] Properties: `oid`, `name`, `info`, `urls` +- [ ] Methods for all org-level operations (sensors, rules, hives, etc.) +- [ ] Lazy-loaded cached properties for org info and URLs + +### 4.3 Sensor +- [ ] `Sensor(organization, sid)` - Represents a single sensor +- [ ] Properties: `sid`, `hostname`, `platform`, `architecture`, `external_ip`, `internal_ip`, `is_online`, `is_isolated`, `tags`, `version`, `enrollment_time`, `last_seen` +- [ ] Platform helpers: `is_windows`, `is_linux`, `is_macos`, `is_chrome` +- [ ] Task methods: `task()`, `request()`, `simple_request()` +- [ ] Tag methods: `add_tag()`, `remove_tag()`, `get_tags()` +- [ ] Network methods: `isolate()`, `rejoin()`, `is_isolated` +- [ ] Lifecycle methods: `delete()`, `seal()`, `unseal()` +- [ ] Event methods: `get_events()`, `get_timeline()`, `get_overview()` + +### 4.4 Hive +- [ ] `Hive(organization, hive_name, partition_key=None)` - Key-value store +- [ ] `HiveRecord` - Record with data, metadata, etag support +- [ ] Methods: `list()`, `get()`, `set()`, `delete()`, `validate()`, `rename()` +- [ ] Transaction support: `update_tx(callback)` with automatic etag retry +- [ ] Batch operations: `batch().get().set().delete().execute()` + +### 4.5 Search +- [ ] `Search(organization)` - LCQL query execution +- [ ] Methods: `validate()`, `estimate()`, `execute()`, `execute_streaming()` +- [ ] Iterator-based pagination for large result sets +- [ ] Progress callback support +- [ ] Saved query management: `list_saved()`, `get_saved()`, `create_saved()`, `delete_saved()` + +### 4.6 Spout (Real-time Streaming) +- [ ] `Spout(organization, data_type, filters=...)` - WebSocket streaming +- [ ] Configurable filters: investigation_id, tags, categories, sensor_ids +- [ ] Auto-reconnect with exponential backoff +- [ ] Queue-based buffering with configurable max +- [ ] Context manager: `with Spout(...) as spout: for event in spout: ...` +- [ ] Future results tracking for sensor tasking + +### 4.7 Configs (Infrastructure-as-Code) +- [ ] `Configs(organization)` - Configuration sync +- [ ] `fetch(components)` - Download current config +- [ ] `push(config, components, force=False, dry_run=False)` - Upload config +- [ ] `diff(config, components)` - Show differences +- [ ] Component selection: rules, fps, outputs, integrity, exfil, logging, artifacts, extensions, org_configs, hives, installation_keys, yara + +### 4.8 AI Generation (NEW) +- [ ] `AI(organization)` - AI-powered generation +- [ ] `generate_dr_rule(description)` - Generate D&R rule from natural language +- [ ] `generate_detection(description)` - Generate detection component +- [ ] `generate_response(description)` - Generate response component +- [ ] `generate_lcql(description)` - Generate LCQL query from natural language +- [ ] `generate_sensor_selector(description)` - Generate bexpr selector +- [ ] `generate_playbook(description)` - Generate Python playbook +- [ ] `summarize_detection(detection_data)` - Summarize a detection + +--- + +## 5. Command Groups & Commands + +### Organization Commands - `limacharlie org` +- [ ] `org info` - Get organization details (sensor count, version, quotas, name) +- [ ] `org list` - List accessible organizations (with --filter support) +- [ ] `org create --location [--template ]` - Create new org +- [ ] `org delete --confirm ` - Delete organization (two-step) +- [ ] `org rename ` - Rename organization +- [ ] `org config get []` - Get org configuration value(s) +- [ ] `org config set ` - Set org configuration value +- [ ] `org urls` - Get service URLs for organization +- [ ] `org quota set ` - Set sensor quota +- [ ] `org stats` - Get usage statistics +- [ ] `org errors [--dismiss ]` - List/dismiss org errors +- [ ] `org mitre-report` - Get MITRE ATT&CK coverage report +- [ ] `org schema [--event-type ] [--platform ]` - Get event schemas/ontology +- [ ] `org runtime-metadata [--entity-type ] [--entity-name ]` - Get runtime metadata +- [ ] `org check-name ` - Check if organization name is available + +### Sensor Commands - `limacharlie sensor` +- [ ] `sensor list [--selector ] [--limit ] [--online-only] [--with-ip ] [--with-hostname ]` - List sensors with rich filtering +- [ ] `sensor get ` - Get sensor details +- [ ] `sensor delete --confirm` - Delete sensor +- [ ] `sensor online ` - Check if sensor is online +- [ ] `sensor wait-online --timeout ` - Wait for sensor to come online +- [ ] `sensor upgrade [--selector ]` - Upgrade sensors to latest version across fleet +- [ ] `sensor set-version --version ` - Set sensor version/branch for organization +- [ ] `sensor export [--selector ]` - Export full sensor manifest as JSON/CSV +- [ ] `sensor dump --confirm` - Trigger full memory dump on sensor (DESTRUCTIVE/HEAVY) +- [ ] `sensor sweep --config ` - Run host sweep/scan on sensor + +### Tag Commands - `limacharlie tag` +- [ ] `tag list [--sensor ]` - List all tags or tags for a sensor +- [ ] `tag add [--ttl ]` - Add tag to sensor +- [ ] `tag remove ` - Remove tag from sensor +- [ ] `tag find ` - Find all sensors with a tag +- [ ] `tag mass-add --selector --tag [--ttl ]` - Bulk tag sensors +- [ ] `tag mass-remove --selector --tag ` - Bulk untag sensors + +### Network Policy Commands - `limacharlie net-policy` +- [ ] `net-policy isolate --confirm` - Isolate sensor from network (DESTRUCTIVE) +- [ ] `net-policy rejoin --confirm` - Rejoin sensor to network (DESTRUCTIVE) +- [ ] `net-policy status ` - Check isolation status +- [ ] `net-policy seal ` - Seal sensor +- [ ] `net-policy unseal ` - Unseal sensor + +### Sensor Tasking Commands - `limacharlie task` +- [ ] `task send [--investigation-id ]` - Send task to sensor (fire-and-forget) +- [ ] `task request [--timeout ]` - Send task and wait for response +- [ ] `task reliable-send ` - Guaranteed delivery task +- [ ] `task reliable-list ` - List pending reliable tasks +- [ ] `task reliable-delete ` - Cancel reliable task + +### D&R Rule Commands - `limacharlie rule` +- [ ] `rule list [--namespace ]` - List D&R rules (namespace: general, managed, service) +- [ ] `rule get [--namespace ]` - Get rule details +- [ ] `rule create --detect --respond [--namespace ] [--enabled] [--ttl ] [--replace]` - Create/replace rule +- [ ] `rule create --input-file ` - Create rule from file +- [ ] `rule update --detect --respond [--namespace ]` - Update existing rule +- [ ] `rule delete [--namespace ]` - Delete rule +- [ ] `rule test --events [--trace]` - Test rule against sample events +- [ ] `rule replay --start