refractionPOINT · maximelb · Jul 11, 2026 · Jul 8, 2026 · Jul 11, 2026 · Jul 11, 2026
diff --git a/docs/8-reference/cloud-security-api-iac.md b/docs/8-reference/cloud-security-api-iac.md
@@ -0,0 +1,219 @@
+# Cloud Security: API, Infrastructure-as-Code, and Case Automation
+
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
+This page is the operator reference for automating LimaCharlie Cloud Security: the
+public REST API surface, the Hive records that ARE the Infrastructure-as-Code
+surface (providers, policies, saved queries), and the D&R recipes that close the
+loop between cloud findings and Cases.
+
+## The REST API
+
+All Cloud Security routes live under `https://api.limacharlie.io/v1/cloudsec/{oid}/…`
+and appear in the public OpenAPI spec at
+[`/openapi`](https://api.limacharlie.io/openapi). Reads require the `cloudsec.get`
+permission, finding-triage writes require `cloudsec.set`, and every route requires
+the organization to be subscribed to the cloud security extension (a `403` tells
+you to subscribe).
+
+The read surface includes: `findings` (risk-ranked worklist with keyset pagination
+and server-side filters), `findings/facets`, `attack-paths` (with the same filter
+selectors), `chokepoints` (incl. the principal-exposure metrics), `ciem/public-access`,
+`inventory` (+`inventory/facets`), `compliance` (+`compliance/frameworks`),
+`overview` (incl. the per-tenant `usage` metering block), `risk-trend`, `changes`,
+`scan-status`, `query` (the graph DSL), and `graph/neighbors`.
+
+### CSV export
+
+Add `?format=csv` to `findings`, `inventory`, `compliance`, or `query` to stream the
+result as a CSV attachment instead of JSON. The server walks the full filtered set
+itself (your filter query parameters apply; paging parameters are ignored), capped
+at 100,000 rows with a trailing `#`-comment row as the truncation notice.
+
+```bash
+curl -H "Authorization: Bearer $JWT" \
+  "https://api.limacharlie.io/v1/cloudsec/$OID/findings?severity=CRITICAL&severity=HIGH&format=csv" \
+  -o findings.csv
+```
+
+The compliance CSV carries one row per control including the proving finding ids —
+the auditor-facing evidence export.
+
+## Hive is the IaC surface
+
+Cloud Security is configured entirely through Hive records. Anything you can click
+in the console you can `limacharlie hive set` — which makes tenant onboarding and
+multi-tenant policy management a script, not a UI workflow.
+
+| Hive | Record | Purpose |
+|---|---|---|
+| `cloudsec_provider` | one per cloud/IdP connection | what to collect (GCP / AWS / Azure / Okta / Google Workspace) |
+| `cloudsec_policy` | many, typed by `policy_type` | `classification` (crown jewels), `coverage` (EDR expectation), `scanning` (agentless YARA), `emission` (event feed), `exclusions` (resource escape hatch), `suppression` (finding disposition rules) |
+| `cloudsec_query` | one per saved query | org-shared saved graph queries (the Query Console library) |
+
+### Onboarding a tenant (recipe)
+
+```bash
+# 1. Subscribe the org to the extension (billing/enable gate).
+limacharlie extension subscribe --name ext-cloud-security --oid $OID
+
+# 2. Connect a provider.
+cat > provider.json <<EOF
+{
+  "provider_type": "gcp",
+  "scope": "organizations/123456789",
+  "secret": {"secret_name": "hive://secret/gcp-collector-sa"},
+  "sync_now": "onboard-1"
+}
+EOF
+limacharlie hive set --hive-name cloudsec_provider --key ${ORG_CODE}-gcp \
+  --oid $OID --input-file provider.json --enabled
+
+# 3. Declare the crown jewels (nothing is sensitive without a policy).
+cat > classification.json <<EOF
+{
+  "policy_type": "classification",
+  "classification": {
+    "data_stores": [
+      {"name_contains": ["customer", "pii"], "classes": ["pii"]}
+    ]
+  }
+}
+EOF
+limacharlie hive set --hive-name cloudsec_policy --key classification \
+  --oid $OID --input-file classification.json --enabled
+```
+
+### Multi-tenant policy push (recipe)
+
+The same records applied to N organizations is the MSSP fleet-policy story:
+
+```bash
+for OID in $(cat tenant-oids.txt); do
+  limacharlie hive set --hive-name cloudsec_policy --key classification \
+    --oid "$OID" --input-file classification.json --enabled
+done
+```
+
+### Suppression rules (finding disposition policy)
+
+A `suppression`-typed `cloudsec_policy` record dispositions matching findings
+automatically — the "accept this known risk in the sandbox for 90 days" mechanic.
+An operator's own disposition always wins, deleting a rule releases exactly its own
+findings on the next cycle, and criticals are never auto-suppressed unless a rule's
+`max_severity` says `critical` explicitly.
+
+```json
+{
+  "policy_type": "suppression",
+  "suppression": {
+    "rules": [{
+      "name": "sandbox-key-age",
+      "match": {
+        "rule": ["stale-user-managed-sa-key"],
+        "account": ["proj-sandbox-*"],
+        "max_severity": "high"
+      },
+      "effect": {
+        "kind": "accepted",
+        "reason": "sandbox accepted risk (SEC-123)",
+        "ttl_days": 90
+      }
+    }]
+  }
+}
+```
+
+### Saved queries
+
+```json
+{
+  "version": 1,
+  "name": "Exposed VMs reaching sensitive data",
+  "query": {"text": "MATCH (t:ComputeInstance {is_sensitive:true})<-[:can_reach]-(s:ComputeInstance) RETURN s, t"},
+  "project": "rows",
+  "tags": ["weekly"]
+}
+```
+
+Save it as a `cloudsec_query` record and it appears in every teammate's Query
+Console and as a pinnable Explore lens. The `schedule` and `detection` blocks are
+accepted (so IaC written today survives the scheduled-query phase) but inert.
+
+## Findings ↔ Cases automation
+
+Cloud findings emit lifecycle events into the organization's own event stream via
+the internally-provisioned `cloudsec` webhook adapter: `cloud_finding.created`
+(carries the full finding under `finding`), `cloud_finding.closed`
+(`{finding_id, fingerprint, finding_class}`), and `cloud_finding.still_open`
+(re-asserted at most once per day for open findings with a linked ticket). D&R
+rules match these like any event; the Cases extension actions close the loop.
+
+The console installs these three rules with one click (Settings → Cloud Security →
+Cases, an opt-in), or write them yourself:
+
+**Auto-case on high/critical findings** (async, grouped, storm-safe — one case per
+rule category per window, and first-sync floods are summarized upstream):
+
+```yaml
+detect:
+  event: cloud_finding.created
+  op: in
+  path: event/finding/severity
+  values: [CRITICAL, HIGH]
+respond:
+  - action: extension request
+    extension name: ext-cases
+    extension action: ingest_detection
+    extension request:
+      detect_id: "{{ .event.finding.fingerprint }}"
+      cat: "cloudsec:{{ .event.finding.rule_id }}"
+      source: cloudsec
+      detect: "{{ .event.finding }}"
+```
+
+**Resolve the case when the sweep confirms the fix:**
+
+```yaml
+detect:
+  event: cloud_finding.closed
+  op: exists
+  path: event/fingerprint
+respond:
+  - action: extension request
+    extension name: ext-cases
+    extension action: update_case
+    extension request:
+      detect_id: "{{ .event.fingerprint }}"
+      status: resolved
+      note: "Finding closed: condition no longer detected by sweep"
+```
+
+**Reopen a case that was closed while the cloud wasn't actually fixed:**
+
+```yaml
+detect:
+  event: cloud_finding.still_open
+  op: exists
+  path: event/fingerprint
+respond:
+  - action: extension request
+    extension name: ext-cases
+    extension action: update_case
+    extension request:
+      detect_id: "{{ .event.fingerprint }}"
+      reopen_if_closed: true
+      note: "Linked cloud finding is still open — verified by latest sweep"
+```
+
+`update_case` resolves the case through the detection index (`detect_id` = the
+finding fingerprint), so the rules never need a case number; a finding with no
+linked case is a no-op. Cases never close findings — findings are detection truth
+and close when the sweep confirms the fix (or via operator/policy disposition).
+
+**Non-Cases shops:** route the same `cloud_finding.*` events to Jira/ServiceNow via
+an Output on the `cloudsec` adapter's stream and key your tickets on `fingerprint`
+the same way.
diff --git a/docs/cloud-security/api-reference.md b/docs/cloud-security/api-reference.md
@@ -1,13 +1,18 @@
 # API Reference
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 All Cloud Security routes live under
 `https://api.limacharlie.io/v1/cloudsec/{oid}/…` and appear in the public
 OpenAPI spec at [`/openapi`](https://api.limacharlie.io/openapi).
 Authentication is the standard `Authorization: Bearer <JWT>` header.
 
 !!! info "Permissions & enable gate"
     Reads require `cloudsec.get`; writes require `cloudsec.set`. Every route
-    requires the organization to be subscribed to `ext-cloud-inventory` — a
+    requires the organization to be subscribed to `ext-cloud-security` — a
     `403` on any route means subscribe first. The `oid` is always taken from
     the authorized path.
 

diff --git a/docs/cloud-security/automation.md b/docs/cloud-security/automation.md
@@ -1,5 +1,10 @@
 # Automation & Infrastructure-as-Code
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 Everything Cloud Security does is scriptable: configuration is Hive records,
 the query/triage surface is the [REST API](api-reference.md) and
 [CLI](cli.md), and findings flow through the standard event pipeline. This
@@ -9,7 +14,7 @@ page collects the operator recipes.
 
 ```bash
 # 1. Subscribe the org to the extension (billing/enable gate).
-limacharlie extension subscribe --name ext-cloud-inventory --oid $OID
+limacharlie extension subscribe --name ext-cloud-security --oid $OID
 
 # 2. Store the collector credential as a secret (hive set reads
 #    record data from --input-file or piped stdin).

diff --git a/docs/cloud-security/caasm.md b/docs/cloud-security/caasm.md
@@ -1,5 +1,10 @@
 # CAASM — Cyber Asset Attack Surface Management
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 Your tools already know what you own: the EDR sees devices, the identity
 provider sees users and their devices, MDM and scanners see more. CAASM
 merges those third-party views into one entity-resolved asset inventory and

diff --git a/docs/cloud-security/cli.md b/docs/cloud-security/cli.md
@@ -1,5 +1,10 @@
 # Command Line Interface
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 The `limacharlie cloudsec` command group (Python SDK/CLI v2) covers the full
 Cloud Security API surface. Every command supports the global options
 (`--oid`, `--output json|yaml|csv|table`, `--filter <jmespath>`), and every

diff --git a/docs/cloud-security/compliance.md b/docs/cloud-security/compliance.md
@@ -1,5 +1,10 @@
 # Compliance
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 Cloud Security evaluates compliance frameworks continuously against the live
 estate: each control maps to detection rules, and a control fails when open
 findings prove the violation — so the compliance report is always as fresh

diff --git a/docs/cloud-security/configuration.md b/docs/cloud-security/configuration.md
@@ -1,5 +1,10 @@
 # Configuration Reference
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 Cloud Security is configured entirely through three Hive types. Anything the
 console can configure, `limacharlie hive set` can configure — which makes
 tenant onboarding and fleet-wide policy a script, not a UI workflow (see

diff --git a/docs/cloud-security/findings.md b/docs/cloud-security/findings.md
@@ -1,5 +1,10 @@
 # Findings & Triage
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 Everything Cloud Security detects lands in one place: a merged, risk-ranked
 findings worklist. CSPM misconfigurations, graph-derived attack paths, and
 identity (CIEM) risks are all findings with the same shape, the same triage

diff --git a/docs/cloud-security/getting-started.md b/docs/cloud-security/getting-started.md
@@ -1,18 +1,23 @@
 # Getting Started with Cloud Security
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 This page takes an organization from zero to a populated Cloud Security
 dashboard: subscribe the extension, store a credential, connect a provider,
 and run the first sweep.
 
 ## 1. Subscribe the extension
 
 Cloud Security is enabled per organization by subscribing to the
-`ext-cloud-inventory` extension — the subscription is both the enable gate
+`ext-cloud-security` extension — the subscription is both the enable gate
 and the billing hook. In the web console, open the extension from the
 Add-Ons marketplace and click **Subscribe**, or from the CLI:
 
 ```bash
-limacharlie extension subscribe --name ext-cloud-inventory --oid $OID
+limacharlie extension subscribe --name ext-cloud-security --oid $OID
 ```
 
 Until the organization is subscribed, every Cloud Security API route and

diff --git a/docs/cloud-security/graph.md b/docs/cloud-security/graph.md
@@ -1,5 +1,10 @@
 # Security Graph & Queries
 
+!!! warning "Private Beta"
+    Cloud Security is currently in **Private Beta**. Features, APIs, and
+    configuration formats described here may change before general
+    availability. Contact us if you would like access.
+
 Every sweep builds a graph of the estate: resources, identities, and data
 stores as nodes; reachability, exposure, permissions, and vulnerability
 relationships as edges. The graph is what turns three individually-boring

diff --git a/docs/cloud-security/index.md b/docs/cloud-security/index.md
@@ -44,7 +44,7 @@ on a schedule, on demand, or continuously from a change feed.
 
 ## How it works
 
-1. **Subscribe** the organization to the `ext-cloud-inventory` extension —
+1. **Subscribe** the organization to the `ext-cloud-security` extension —
    this is the product's enable (and billing) gate.
 2. **Connect providers**: one `cloudsec_provider` Hive record per cloud
    account / IdP tenant. A pre-save credential test probes every permission
@@ -74,7 +74,7 @@ onboarded and governed as code.
       connection records in the Hive.
 
     Every route additionally requires the organization to be subscribed to
-    `ext-cloud-inventory`; unsubscribed organizations receive `403`.
+    `ext-cloud-security`; unsubscribed organizations receive `403`.
 
 ## Documentation
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -534,6 +534,7 @@ nav:
       - Story Tags: 8-reference/story-tags.md
       - ID Schema: 8-reference/id-schema.md
       - Permissions: 8-reference/permissions.md
+      - Cloud Security API & IaC: 8-reference/cloud-security-api-iac.md
       - Error Codes: 8-reference/error-codes.md
       - Auth Resource Locator: 8-reference/authentication-resource-locator.md
       - YARA Modules: 8-reference/yara-modules.md