From be41c70e02beddfdce1631309fa7a82a85cd0feb Mon Sep 17 00:00:00 2001 From: Maxime Date: Thu, 21 May 2026 08:16:39 -0700 Subject: [PATCH] docs: warn that new Hive records are disabled by default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every new Hive record (D&R rules, FP rules, secrets, lookups, YARA sources, cloud sensors, AI skills, playbooks, …) is created disabled unless usr_mtd.enabled is explicitly set to true. Several create/update examples in the docs omit this and would silently produce a disabled record — most painful for secrets and lookups, where the record is stored normally but its consumers (outputs, D&R rules) skip it. - config-hive/index.md: new top-level admonition listing the three create-and-enable paths (CLI --enabled flag, usr_mtd.enabled in body, SDK enabled=True / Enabled: &enabled). - secrets.md and lookups.md: Create/Update examples now set enabled across REST, Python, Go, and CLI tabs. - dr-rules.md, false-positives.md, detection-response/index.md, writing-testing-rules.md tutorial: CLI examples updated to include --enabled. (The REST/Python/Go tabs in those docs already set it.) - yara.md: Python SDK example now passes enabled=True. - python-sdk.md: "Create or update a rule" snippet now sets enabled. - skills.md: CLI ai-skill set examples and Python SDK example now enable the skill at creation. The CLI --enabled / --disabled flag referenced here is being added to python-limacharlie in refractionPOINT/python-limacharlie#296. Until that lands, the SDK/REST patterns still apply, and the CLI path remains "set + enable" two-step. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/3-detection-response/false-positives.md | 3 +- docs/3-detection-response/index.md | 6 ++-- .../tutorials/writing-testing-rules.md | 4 ++- docs/6-developer-guide/sdks/python-sdk.md | 6 ++-- docs/7-administration/config-hive/dr-rules.md | 7 +++-- docs/7-administration/config-hive/index.md | 11 ++++++++ docs/7-administration/config-hive/lookups.md | 28 +++++++++++++------ docs/7-administration/config-hive/secrets.md | 18 ++++++++++-- docs/7-administration/config-hive/yara.md | 4 ++- docs/9-ai-sessions/skills.md | 12 +++++--- 10 files changed, 74 insertions(+), 25 deletions(-) diff --git a/docs/3-detection-response/false-positives.md b/docs/3-detection-response/false-positives.md index 4d12b5a07..dd00f53f9 100644 --- a/docs/3-detection-response/false-positives.md +++ b/docs/3-detection-response/false-positives.md @@ -225,7 +225,8 @@ value: web-server-2 ```bash # Save your FP rule to a file, then: - limacharlie fp set --key suppress-known-app --input-file fp-rule.yaml + # (--enabled is required — new hive records are disabled by default.) + limacharlie fp set --key suppress-known-app --input-file fp-rule.yaml --enabled ``` ### Delete an FP Rule diff --git a/docs/3-detection-response/index.md b/docs/3-detection-response/index.md index 2b8a5a822..6361f7daa 100644 --- a/docs/3-detection-response/index.md +++ b/docs/3-detection-response/index.md @@ -161,8 +161,10 @@ Build custom detection logic with automated response actions. === "CLI" ```bash - # Save your rule to a YAML file, then: - limacharlie dr set --key my-new-rule --input-file rule.yaml + # Save your rule to a YAML file, then create-and-enable in one shot. + # (New hive records are disabled by default; --enabled mirrors the + # `enabled=True` / `IsEnabled: true` in the SDK examples above.) + limacharlie dr set --key my-new-rule --input-file rule.yaml --enabled ``` ### Delete a Rule diff --git a/docs/3-detection-response/tutorials/writing-testing-rules.md b/docs/3-detection-response/tutorials/writing-testing-rules.md index b0563348f..69f108b62 100644 --- a/docs/3-detection-response/tutorials/writing-testing-rules.md +++ b/docs/3-detection-response/tutorials/writing-testing-rules.md @@ -381,5 +381,7 @@ Once your rule is done and you've evaluated various events for matches, you can Now is the time to push the new rule to production, the easy part. -Simply run `limacharlie dr set --key T1196 --input-file T1196.rule` +Simply run `limacharlie dr set --key T1196 --input-file T1196.rule --enabled` and confirm it is operational by running `limacharlie dr list`. +The `--enabled` flag creates the rule and enables it in one shot — without +it the rule is stored disabled and would not fire on matching events. diff --git a/docs/6-developer-guide/sdks/python-sdk.md b/docs/6-developer-guide/sdks/python-sdk.md index e1b84f491..76804affe 100644 --- a/docs/6-developer-guide/sdks/python-sdk.md +++ b/docs/6-developer-guide/sdks/python-sdk.md @@ -436,7 +436,8 @@ for name, record in rules.items(): record = hive.get("my-detection-rule") print(record.data) # {'detect': {...}, 'respond': [...]} -# Create or update a rule +# Create or update a rule. New hive records are disabled by default, +# so pass enabled=True if you want the rule to start firing immediately. new_rule = HiveRecord( name="my-new-rule", data={ @@ -449,7 +450,8 @@ new_rule = HiveRecord( "respond": [ {"action": "report", "name": "mimikatz-detected"} ] - } + }, + enabled=True, ) hive.set(new_rule) diff --git a/docs/7-administration/config-hive/dr-rules.md b/docs/7-administration/config-hive/dr-rules.md index 98084f42a..997e24a2f 100644 --- a/docs/7-administration/config-hive/dr-rules.md +++ b/docs/7-administration/config-hive/dr-rules.md @@ -238,9 +238,10 @@ The D&R rules hive is named `dr-general`. Managed rules use `dr-managed`. === "CLI" ```bash - limacharlie hive set dr-general --key my-rule --data rule.json - # Or use the D&R shortcut: - limacharlie dr set --key my-rule --input-file rule.yaml + # New rules are created disabled by default. Pass --enabled to + # create-and-enable in one shot, or omit and call `dr enable` + # afterwards. + limacharlie dr set --key my-rule --input-file rule.yaml --enabled ``` ### Delete a Rule diff --git a/docs/7-administration/config-hive/index.md b/docs/7-administration/config-hive/index.md index a826bc45e..db63cef8c 100644 --- a/docs/7-administration/config-hive/index.md +++ b/docs/7-administration/config-hive/index.md @@ -18,6 +18,17 @@ Hive records can be: - Managed via the web interface, CLI, or API - Version controlled using the Git Sync extension +!!! warning "New records are disabled by default" + Every new Hive record — D&R rules, FP rules, secrets, lookups, YARA sources, cloud sensors, AI skills, playbooks, etc. — is created **disabled** unless the request explicitly sets `usr_mtd.enabled: true`. A disabled record is stored normally but is skipped by every consumer that respects the flag (rules don't fire, lookups aren't queried, AI skills aren't enumerated). When debugging "the record exists but nothing happens", check `usr_mtd.enabled` first. + + Enable a record at creation time by either: + + 1. Passing `--enabled` on the CLI `set` command (e.g. `limacharlie secret set --key … --input-file … --enabled`). + 2. Including `usr_mtd.enabled: true` in the request body / input file. + 3. Setting `enabled=True` (Python SDK) or `Enabled: &enabled` (Go SDK) on the record before calling `set` / `Add`. + + Or call the matching `enable` subcommand after creation (`limacharlie enable --key …`). + --- ## See Also diff --git a/docs/7-administration/config-hive/lookups.md b/docs/7-administration/config-hive/lookups.md index 00e09dfd4..10a88a4cb 100644 --- a/docs/7-administration/config-hive/lookups.md +++ b/docs/7-administration/config-hive/lookups.md @@ -200,13 +200,17 @@ If your lookups change frequently and you wish to keep them up to date, LimaChar Lookups support three data formats: `lookup_data` (key-value pairs), `newline_content` (newline-separated keys), and `yaml_content` (YAML string). +!!! warning + New hive records are created **disabled by default** — D&R rules that reference the lookup will silently miss every key until you enable it. Each example below explicitly enables the lookup; drop the `enabled` portion to leave it disabled and enable it later via `limacharlie lookup enable --key …`. + === "REST API" ```bash curl -s -X POST \ "https://api.limacharlie.io/v1/hive/lookup/YOUR_OID/my-lookup/data" \ -H "Authorization: Bearer $LC_JWT" \ - -d '{"data": "{\"lookup_data\": {\"8.8.8.8\": {}, \"1.1.1.1\": {}}}"}' + -d 'data={"lookup_data":{"8.8.8.8":{},"1.1.1.1":{}}}' \ + -d 'usr_mtd={"enabled":true}' ``` === "Python" @@ -219,12 +223,16 @@ Lookups support three data formats: `lookup_data` (key-value pairs), `newline_co client = Client(oid="YOUR_OID", api_key="YOUR_API_KEY") org = Organization(client) hive = Hive(org, "lookup") - record = HiveRecord("my-lookup", data={ - "lookup_data": { - "8.8.8.8": {}, - "1.1.1.1": {}, - } - }) + record = HiveRecord( + "my-lookup", + data={ + "lookup_data": { + "8.8.8.8": {}, + "1.1.1.1": {}, + } + }, + enabled=True, + ) hive.set(record) ``` @@ -245,6 +253,7 @@ Lookups support three data formats: `lookup_data` (key-value pairs), `newline_co org, _ := limacharlie.NewOrganization(client) hc := limacharlie.NewHiveClient(org) + enabled := true hc.Add(limacharlie.HiveArgs{ HiveName: "lookup", PartitionKey: "YOUR_OID", @@ -255,6 +264,7 @@ Lookups support three data formats: `lookup_data` (key-value pairs), `newline_co "1.1.1.1": map[string]interface{}{}, }, }, + Enabled: &enabled, }) } ``` @@ -263,7 +273,7 @@ Lookups support three data formats: `lookup_data` (key-value pairs), `newline_co ```bash limacharlie lookup set --key my-lookup \ - --input-file lookup.json + --input-file lookup.json --enabled ``` Where `lookup.json` contains: @@ -279,6 +289,8 @@ Lookups support three data formats: `lookup_data` (key-value pairs), `newline_co } ``` + The `--enabled` flag creates-and-enables the lookup in one shot. Omit it (and `usr_mtd.enabled` in the file) to leave the lookup disabled until you call `limacharlie lookup enable --key my-lookup`. + ### Delete a Lookup === "REST API" diff --git a/docs/7-administration/config-hive/secrets.md b/docs/7-administration/config-hive/secrets.md index ca271d067..e95a4ec56 100644 --- a/docs/7-administration/config-hive/secrets.md +++ b/docs/7-administration/config-hive/secrets.md @@ -176,13 +176,17 @@ Using a secret in combination with an output has very few steps: ### Create / Update a Secret +!!! warning + New hive records are created **disabled by default**. Each example below explicitly enables the secret — drop the `enabled` portion if you want the secret to start disabled and enable it later via `limacharlie secret enable --key …`. + === "REST API" ```bash curl -s -X POST \ "https://api.limacharlie.io/v1/hive/secret/YOUR_OID/my-secret/data" \ -H "Authorization: Bearer $LC_JWT" \ - -d '{"data": "{\"secret\": \"my-secret-value\"}"}' + -d 'data={"secret":"my-secret-value"}' \ + -d 'usr_mtd={"enabled":true}' ``` === "Python" @@ -195,7 +199,11 @@ Using a secret in combination with an output has very few steps: client = Client(oid="YOUR_OID", api_key="YOUR_API_KEY") org = Organization(client) hive = Hive(org, "secret") - record = HiveRecord("my-secret", data={"secret": "my-secret-value"}) + record = HiveRecord( + "my-secret", + data={"secret": "my-secret-value"}, + enabled=True, + ) hive.set(record) ``` @@ -216,11 +224,13 @@ Using a secret in combination with an output has very few steps: org, _ := limacharlie.NewOrganization(client) hc := limacharlie.NewHiveClient(org) + enabled := true hc.Add(limacharlie.HiveArgs{ HiveName: "secret", PartitionKey: "YOUR_OID", Key: "my-secret", Data: limacharlie.Dict{"secret": "my-secret-value"}, + Enabled: &enabled, }) } ``` @@ -229,7 +239,7 @@ Using a secret in combination with an output has very few steps: ```bash limacharlie secret set --key my-secret \ - --input-file secret.json + --input-file secret.json --enabled ``` Where `secret.json` contains: @@ -242,6 +252,8 @@ Using a secret in combination with an output has very few steps: } ``` + The `--enabled` flag creates-and-enables the record in one shot. Omit it (and `usr_mtd.enabled` in the file) to leave the secret disabled until you call `limacharlie secret enable --key my-secret`. + ### Delete a Secret === "REST API" diff --git a/docs/7-administration/config-hive/yara.md b/docs/7-administration/config-hive/yara.md index 74d479898..0f8fc409d 100644 --- a/docs/7-administration/config-hive/yara.md +++ b/docs/7-administration/config-hive/yara.md @@ -174,7 +174,9 @@ The data payload uses a `rule` key containing the YARA rule content. $s } """ - record = HiveRecord("my-rule", data={"rule": yara_content}) + # New hive records are disabled by default — pass enabled=True so + # the rule is picked up by YARA scans. + record = HiveRecord("my-rule", data={"rule": yara_content}, enabled=True) hive.set(record) ``` diff --git a/docs/9-ai-sessions/skills.md b/docs/9-ai-sessions/skills.md index 48fd75465..abdaa4d26 100644 --- a/docs/9-ai-sessions/skills.md +++ b/docs/9-ai-sessions/skills.md @@ -112,11 +112,13 @@ limacharlie ai-skill list # Get one skill (frontmatter, content, and any bundled files). limacharlie ai-skill get --key triage-lateral -# Create or replace a skill from a YAML file. -limacharlie ai-skill set --key triage-lateral --input-file triage.yaml +# Create or replace a skill from a YAML file. New hive records are +# disabled by default, so pass --enabled (or include usr_mtd.enabled: +# true in the file) if you want the skill picked up by AI sessions. +limacharlie ai-skill set --key triage-lateral --input-file triage.yaml --enabled # Or pipe it in. -cat triage.yaml | limacharlie ai-skill set --key triage-lateral +cat triage.yaml | limacharlie ai-skill set --key triage-lateral --enabled # Toggle without deleting the record. limacharlie ai-skill disable --key triage-lateral @@ -156,6 +158,8 @@ client = Client(oid="YOUR_OID", api_key="YOUR_API_KEY") org = Organization(client) hive = Hive(org, "ai_skill") +# enabled=True so the skill is picked up by AI sessions immediately — +# new hive records are disabled by default. hive.set(HiveRecord("triage-lateral", data={ "content": "...SKILL.md body...", "description": "Triage a lateral-movement detection end to end.", @@ -163,7 +167,7 @@ hive.set(HiveRecord("triage-lateral", data={ "files": { "scripts/check_lateral.sh": "#!/bin/bash\n...\n", }, -})) +}, enabled=True)) ``` ## Related