From 3fe2f0a1bf363533f41210ad5b0ecb2849a8af45 Mon Sep 17 00:00:00 2001 From: "[Steve Brant]" <[steve@limacharlie.com]> Date: Fri, 15 May 2026 11:05:15 -0600 Subject: [PATCH] docs(9-ai-sessions): add Compliance section for the lc-compliance plugin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the `lc-compliance` Claude Code plugin shipping in refractionPOINT/lc-ai. The plugin has two halves and both are covered: - Case-reviewer agents (one per framework, D&R-driven AI Sessions) that classify in-scope cases against control citations on `case_created` events and write audit-grade documentation directly into the case. - Four interactive Claude Code skills (`compliance-lookup`, `compliance-gap`, `compliance-deploy`, `compliance-baseline-deploy`) for ad-hoc control lookups, gap analysis against live orgs, guided reviewer-agent deployment, and full rule-baseline deployment. Covered frameworks: CMMC v2, NIST SP 800-53 Rev 5, PCI DSS v4.0, HIPAA Security Rule, SOC 2, ISO/IEC 27001:2022, CIS Controls v8. ## New files `docs/9-ai-sessions/compliance/`: - index.md (overview, two-shape model, quickstart) - installation.md (plugin install, prerequisites, first-deploy sequence) - frameworks.md (per-framework citation formats, scope tags, verification levels, framework-specific skill args) - skills.md (full reference for all four skills with arguments and examples) - case-reviewer-agent.md (agent lifecycle, permissions, scope check, evidence model, classifications, customization) - gap-analysis.md (report anatomy, remediation paths, multi-tenant note) ## Nav Compliance is nested as a sub-section under AI Sessions (after API Reference), not promoted to a top-level tab. The case-reviewer agent is literally a D&R-driven AI Session and the four skills are Claude Code tooling, so the semantic fit is inside the existing AI Sessions group; this also keeps the top-level nav at 10 tabs. ## Cross-link surface (modified existing pages) To make the new section discoverable from natural parent contexts, seven existing pages get conservative additive edits — each adds one or two "See Also" / "Related" entries pointing at the relevant Compliance page: - `9-ai-sessions/index.md` — adds Compliance to D&R-driven use cases and the Documentation list. - `9-ai-sessions/dr-sessions.md` — new See Also section framing the case-reviewer agent as the canonical D&R-driven session example. - `5-integrations/extensions/limacharlie/cases.md` — two new See Also entries (compliance reviewer operates on cases). - `5-integrations/extensions/limacharlie/integrity.md` — two new Related Articles entries (FIM rules ship as part of every framework baseline). - `5-integrations/extensions/limacharlie/exfil.md` — new See Also section (exfil rules ship as part of every framework baseline). - `2-sensors-deployment/sensor-tags.md` — new See Also entry pointing at the per-framework scope-tag conventions on the Frameworks page. - `7-administration/config-hive/secrets.md` — new See Also section including the existing implicit adapter/output/AI Sessions references, with the Compliance installation step added. ## Validation - `mkdocs build` passes (also tried with --strict; only pre-existing use-case "not in nav" warnings). - `pymarkdown scan` passes on all changed files with the repo's standard rule disables (MD013, MD033, MD041, MD046, MD060, MD024). - 23 internal cross-link probes (every inbound and outbound compliance link) verified 200 against a local mkdocs serve. ## Source Content is generated from the public release at [refractionPOINT/lc-ai](https://github.com/refractionPOINT/lc-ai), specifically `marketplace/plugins/lc-compliance/`. Plugin version 1.0.2. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/2-sensors-deployment/sensor-tags.md | 1 + .../extensions/limacharlie/cases.md | 2 + .../extensions/limacharlie/exfil.md | 5 + .../extensions/limacharlie/integrity.md | 2 + docs/7-administration/config-hive/secrets.md | 7 + .../compliance/case-reviewer-agent.md | 175 +++++++++++++++ docs/9-ai-sessions/compliance/frameworks.md | 155 +++++++++++++ docs/9-ai-sessions/compliance/gap-analysis.md | 171 ++++++++++++++ docs/9-ai-sessions/compliance/index.md | 71 ++++++ docs/9-ai-sessions/compliance/installation.md | 129 +++++++++++ docs/9-ai-sessions/compliance/skills.md | 209 ++++++++++++++++++ docs/9-ai-sessions/dr-sessions.md | 7 + docs/9-ai-sessions/index.md | 2 + mkdocs.yml | 7 + 14 files changed, 943 insertions(+) create mode 100644 docs/9-ai-sessions/compliance/case-reviewer-agent.md create mode 100644 docs/9-ai-sessions/compliance/frameworks.md create mode 100644 docs/9-ai-sessions/compliance/gap-analysis.md create mode 100644 docs/9-ai-sessions/compliance/index.md create mode 100644 docs/9-ai-sessions/compliance/installation.md create mode 100644 docs/9-ai-sessions/compliance/skills.md diff --git a/docs/2-sensors-deployment/sensor-tags.md b/docs/2-sensors-deployment/sensor-tags.md index c8b9bb367..5ec5c5f19 100644 --- a/docs/2-sensors-deployment/sensor-tags.md +++ b/docs/2-sensors-deployment/sensor-tags.md @@ -386,3 +386,4 @@ In LimaCharlie, an Organization represents a tenant within the Agentic SecOps Wo - [Sensor Selectors](../8-reference/sensor-selector-expressions.md) - [Python SDK](../6-developer-guide/sdks/python-sdk.md) - [Go SDK](../6-developer-guide/sdks/go-sdk.md) +- [Compliance Frameworks](../9-ai-sessions/compliance/frameworks.md) -- Scope-tag conventions per framework (`cde` for PCI, `ephi-host` for HIPAA, `cui` for CMMC, `fisma-scope` for NIST 800-53, etc.). The compliance reviewer agents key their in-scope check off these tags. diff --git a/docs/5-integrations/extensions/limacharlie/cases.md b/docs/5-integrations/extensions/limacharlie/cases.md index 7574d6d9c..a99519147 100644 --- a/docs/5-integrations/extensions/limacharlie/cases.md +++ b/docs/5-integrations/extensions/limacharlie/cases.md @@ -1124,3 +1124,5 @@ Unsubscribing from the extension removes the detection-forwarding D&R rules and - [D&R Rules Overview](../../../3-detection-response/index.md) -- Detection rules that generate the detections ingested as cases - [Response Actions](../../../8-reference/response-actions.md) -- The `extension request` action used for D&R rule integration - [Using Extensions](../using-extensions.md) -- General extension subscription and management +- [Compliance Case-Reviewer Agent](../../../9-ai-sessions/compliance/case-reviewer-agent.md) -- Per-framework AI agents (PCI, HIPAA, CMMC, SOC 2, NIST 800-53, ISO 27001, CIS v8) that classify in-scope cases against control citations on `case_created` events and write audit-grade documentation directly into the case record +- [Compliance Plugin Overview](../../../9-ai-sessions/compliance/index.md) -- Installation and capabilities of the `lc-compliance` Claude Code plugin diff --git a/docs/5-integrations/extensions/limacharlie/exfil.md b/docs/5-integrations/extensions/limacharlie/exfil.md index ffad1de09..2304b87a0 100644 --- a/docs/5-integrations/extensions/limacharlie/exfil.md +++ b/docs/5-integrations/extensions/limacharlie/exfil.md @@ -173,3 +173,8 @@ The following REST API actions can be sent to interact with the Exfil extension: "name": "sql-servers" } ``` + +## See Also + +- [Compliance Frameworks](../../../9-ai-sessions/compliance/frameworks.md) -- Exfil rules ship as part of every framework's recommended baseline. The `compliance-baseline-deploy` skill writes them under `data.exfil_rules.list` while preserving existing default rules (e.g., `default-chrome`, `default-linux`). +- [Compliance Gap Analysis](../../../9-ai-sessions/compliance/gap-analysis.md) -- Section A of the gap report enumerates missing exfil events per framework and per platform, with the relevant control citations. diff --git a/docs/5-integrations/extensions/limacharlie/integrity.md b/docs/5-integrations/extensions/limacharlie/integrity.md index d16b881ee..08516ffb1 100644 --- a/docs/5-integrations/extensions/limacharlie/integrity.md +++ b/docs/5-integrations/extensions/limacharlie/integrity.md @@ -118,3 +118,5 @@ The following REST API actions can be sent to interact with the Integrity extens - [Reference: Endpoint Agent Commands](../../../8-reference/endpoint-commands.md) - [Detection and Response Examples](../../../3-detection-response/examples.md) +- [Compliance Frameworks](../../../9-ai-sessions/compliance/frameworks.md) -- FIM rules ship as part of every framework's recommended baseline (PCI DSS Req 11.5.x, HIPAA §164.312(c)(1), CMMC SI.L2-3.14.1, etc.). The Compliance plugin's `compliance-baseline-deploy` skill deploys these rules into `ext-integrity` automatically. +- [Compliance Gap Analysis](../../../9-ai-sessions/compliance/gap-analysis.md) -- Surfaces missing FIM rules per framework and flags when `ext-integrity` is not subscribed. diff --git a/docs/7-administration/config-hive/secrets.md b/docs/7-administration/config-hive/secrets.md index ee5d92d4e..ca271d067 100644 --- a/docs/7-administration/config-hive/secrets.md +++ b/docs/7-administration/config-hive/secrets.md @@ -391,3 +391,10 @@ Next, create an output in the web app, using the value `hive://secret/my-secret` ![secret](../../assets/images/secret.png) And that's it! The output should start as expected, however when viewing the output's configuration, the secret should refer to the `hive` ARN, rather than the actual credentials. + +## See Also + +- [Adapter Usage](../../2-sensors-deployment/adapters/usage.md) -- Common consumer of hive secrets. +- [Outputs](../../5-integrations/outputs/index.md) -- Another common consumer of hive secrets. +- [D&R-Driven AI Sessions](../../9-ai-sessions/dr-sessions.md) -- The `start ai agent` action consumes Anthropic and LC API keys via `hive://secret/` references. +- [Compliance Installation](../../9-ai-sessions/compliance/installation.md) -- The `compliance-deploy` skill stages a scoped LC API key and an Anthropic key in this hive as part of reviewer-agent deployment. diff --git a/docs/9-ai-sessions/compliance/case-reviewer-agent.md b/docs/9-ai-sessions/compliance/case-reviewer-agent.md new file mode 100644 index 000000000..44deb69b8 --- /dev/null +++ b/docs/9-ai-sessions/compliance/case-reviewer-agent.md @@ -0,0 +1,175 @@ +# Case-Reviewer Agent + +The case-reviewer agent is the continuous, event-driven half of `lc-compliance`. Once deployed into a LimaCharlie organization, it watches the [Cases](../../5-integrations/extensions/limacharlie/cases.md) queue and classifies every new case against the framework's specific control citations, writing audit-grade documentation directly into the case record. It is built on top of [D&R-Driven AI Sessions](../dr-sessions.md). + +One reviewer agent exists per framework. Multiple reviewers can be deployed into the same organization (for example, an org that is in scope for both PCI DSS and SOC 2 can run `pci-compliance-reviewer` and `soc2-compliance-reviewer` side by side, each scoped to its own tag). + +## How it works + +```mermaid +stateDiagram-v2 + [*] --> case_created + case_created --> in_scope_check: Triggered by D&R rule + in_scope_check --> classify: Yes + in_scope_check --> [*]: No (note added, exit) + classify --> document + document --> tag + tag --> [*] +``` + +1. A detection fires on an in-scope sensor (e.g., a `cde`-tagged endpoint for PCI). +2. The Cases extension creates a case from the detection. +3. A webhook adapter emits a `case_created` event. +4. A D&R rule installed by `compliance-deploy` matches the event and invokes the agent via the `start ai agent` response action. +5. The agent runs **suppression** (max 10 cases per minute globally) and **debounce** (one review per case at a time) checks before starting work. +6. The agent performs a **scope check**: is this case in scope for the framework? (Is the sensor tagged correctly? Is the detection category one the framework cares about?) + - If not, the agent adds a "not in scope" note to the case and exits. + - If yes, the agent continues. +7. The agent **maps the event** to one or more specific control citations from the framework. +8. The agent **classifies the compliance impact**: + - **Control functioning** — the detection itself is evidence that a control is operating correctly + - **Control gap** — the event reveals a control that is missing or weak + - **In-scope operational** — a routine in-scope event that does not indicate a security incident + - **Security incident with compliance impact** — a real incident that the QSA / ISSO needs to be aware of +9. The agent **writes** a QSA-ready summary, conclusion, and analysis notes directly into the case via the case-investigation API, and tags the case with the compliance classification. + +The agent is **read-only against your deployed configuration**. It reads detections, events, sensor metadata, hive records, and case data; it writes only to the case it was triggered for (notes, conclusion, tags). It does not modify D&R rules, exfil entries, FIM entries, sensors, secrets, or any other org configuration. + +## Deployment + +Deploy the reviewer for a framework using the [`compliance-deploy`](skills.md#compliance-deploy) skill: + +```text +/lc-compliance:compliance-deploy pci-dss --oid +``` + +The skill walks through API-key creation, Anthropic secret staging, agent hive sync, and trigger D&R rule installation, with confirmation at each platform write. The deployment touches three [Config Hive](../../7-administration/config-hive/index.md) areas: + +| Hive | Record name | Purpose | +|---|---|---| +| `ai_agent` | `-compliance-reviewer` | Agent prompt, model, tool allowlist, budget | +| `dr-general` | `-compliance-reviewer-trigger` | The D&R rule that fires the agent on `case_created` | +| `secret` | `-compliance-reviewer` and `anthropic-key` | Scoped LC API key and Anthropic API key | + +After deployment, the agent identifier is `-compliance-reviewer` (e.g., `pci-compliance-reviewer`, `hipaa-compliance-reviewer`). The same identifier can be invoked manually from the CLI for ad-hoc reviews — see [Manual invocation](#manual-invocation). + +## Permissions + +The scoped LimaCharlie API key created by `compliance-deploy` is granted only the permissions the reviewer needs to operate: + +| Permission | Reason | +|---|---| +| `org.get` | Read organization metadata | +| `sensor.list`, `sensor.get` | Identify in-scope sensors via tag selectors | +| `dr.list` | Read deployed D&R rule names and metadata for compliance correlation | +| `insight.det.get` | Read detections linked to the case | +| `insight.evt.get` | Read historical events for context | +| `investigation.get`, `investigation.set` | Read and update the case | +| `ext.request`, `ext.list` | Communicate with the Cases extension and list subscribed extensions | +| `org_notes.read` | Read organization-level notes for context | +| `sop.get`, `sop.get.mtd` | Read Standard Operating Procedures relevant to the case | +| `ai_agent.operate` | Operate as an AI agent in the org | + +The agent does **not** receive write access to D&R rules, FIM rules, exfil configuration, sensor configuration, or installation keys. The least-privilege scoping is enforced at the API-key level — even if the agent's prompt asked it to modify configuration, the API would reject the call. + +## Scope: what the agent reviews + +The reviewer scopes itself by **sensor tag**, **detection category**, **detection rule tags**, and **rule metadata**. A case is treated as in scope when *any* of those signals matches the framework. The canonical scope tags accepted by each reviewer: + +| Framework | Accepted scope tags | +|---|---| +| pci-dss | `cde`, `pci-scope`, `card-data`, `pci-dss` | +| hipaa | `ephi-host`, `hipaa-scope`, `phi-host`, `covered-entity` | +| cmmc | `cui`, `cui-host`, `cmmc-scope`, `dib-host` | +| nist-800-53 | `fisma-scope`, `fedramp-scope`, `federal-system`, `nist-scope` | +| soc2 | `soc2-scope`, `in-scope-system`, `audit-scope` | +| iso-27001 | `isms-scope`, `iso-scope`, `iso-27001-scope`, `soa-included` | +| cis-v8 | `cis-scope`, `cis-v8-scope` (plus optional `cis-ig1`/`cis-ig2`/`cis-ig3` for tier) | + +The reviewer's full scope check considers, in order: + +1. **Sensor tag match.** The case is in scope if the originating sensor carries any tag from the framework's accepted list. +2. **Detection category match.** The case is in scope if the detection category begins with the framework's prefix (`pci-`, `hipaa-`, `cmmc-`, `nist-`, `soc2-`, `iso-`, `cis-`). +3. **Rule-tag match.** The case is in scope if any linked detection's rule tags include the framework identifier (e.g., `pci-dss`). +4. **Rule metadata match.** The case is in scope if any linked detection's rule metadata carries the framework's citation key (e.g., `pci_dss_req:`, `hipaa_safeguard:`, `cis_safeguard:`). + +Cases that match none of these signals receive a single explanatory note ("not in scope. No compliance review performed.") and the reviewer exits without altering classification, severity, status, or tags. + +The scoping logic is encoded in the agent's prompt, which is one of the `ai_agent` hive record fields. Operators can override the scoping behavior by editing the hive record directly — see [Customization](#customization). + +## Evidence model + +The reviewer writes four artifacts into each in-scope case: + +1. **Summary** (`--summary`) — one paragraph stating the host, the event, the control citations implicated, and the compliance classification. +2. **Conclusion** (`--conclusion`) — a few sentences mapping the event to specific control numbers, classifying it (see [Classifications](#classifications) below), citing evidence (sensor ID, hostname, event timestamp, detection rule name), and stating recommended remediation if applicable. +3. **Analysis note** (`case add-note --type analysis`) — a detailed technical timeline in markdown including verbatim event data, correlating events, and an explicit statement of the scope determination. +4. **Classification tags** — added via `case tag add`. Each reviewer uses framework-prefixed tags so multiple framework reviewers can run side-by-side without colliding. + +### Classifications + +Every in-scope case receives one of four classification tags. The tag names follow the framework-prefix convention: + +| Classification | PCI tag | HIPAA tag | Pattern | +|---|---|---|---| +| Control functioning as designed | `pci-control-functioning` | `hipaa-control-functioning` | `-control-functioning` | +| Control gap revealed | `pci-control-gap` | `hipaa-control-gap` | `-control-gap` | +| In-scope operational activity | `pci-in-scope-ops` | `hipaa-in-scope-ops` | `-in-scope-ops` | +| Security incident with framework impact | `pci-security-incident` | `hipaa-security-incident` | `-security-incident` | + +While the review is in flight, the case also carries a transient `-reviewing` tag (e.g., `pci-reviewing`), which the reviewer adds at the start of its workflow and removes when finished. Treat that tag as the in-flight signal, not the final classification. + +Auditors who want to sample evidence work directly from the case queue, filtering by classification tag and framework. The agent does not generate stand-alone reports or PDFs — the case record itself is the evidence. + +For organizations that also want a quarterly or annual roll-up across cases, the case queue can be queried via the [Cases API](https://cases.limacharlie.io/openapi) and the relevant classifications aggregated externally. + +## Manual invocation + +A deployed reviewer can also be invoked ad-hoc against an existing case from the CLI: + +```bash +limacharlie ai start-session \ + --definition -compliance-reviewer \ + --prompt "Review case against controls." +``` + +This is useful for re-reviewing cases after the agent's prompt has been updated, or for reviewing cases that pre-date the agent's deployment. See the [AI Sessions CLI reference](../cli.md) for the full command set. + +## Customization + +The agent's behavior is defined by the `ai_agent` hive record `-compliance-reviewer`. Operators can customize: + +- **The system prompt** — to reflect organization-specific compliance practices, scope rules, escalation paths +- **The tool allowlist** — to restrict or expand the agent's capabilities +- **The model and budget** — to change the AI model used or cap per-session spend +- **The trigger rule** — the `dr-general` record `-compliance-reviewer-trigger` can be edited to change which `case_created` events fire the agent (for example, to only review high-severity cases) + +To inspect or edit the records: + +```bash +limacharlie hive get --hive-name ai_agent --key -compliance-reviewer --oid +limacharlie hive get --hive-name dr-general --key -compliance-reviewer-trigger --oid +``` + +To refresh customizations from a freshly-updated plugin (overwriting local edits), re-run `compliance-deploy`. The skill warns when it would overwrite an existing record. + +## Cost and budget + +Each agent run consumes Anthropic API tokens (billed directly to your Anthropic account via the staged key) plus a small AI Sessions runtime charge from LimaCharlie. The default budget is configured in the agent's hive record; consult the [AI Sessions billing section](../index.md#billing) for the current rates and the `max_budget_usd` parameter for per-session caps. + +Suppression and debounce settings — the global 10-cases-per-minute cap and the per-case single-review lock — protect against runaway invocation when a noisy rule triggers many cases at once. Both are configurable in the trigger D&R rule. + +## Limitations + +- **The agent does not issue compliance attestations.** It produces evidence. The human auditor, QSA, or ISSO decides compliance status. +- **The agent does not take response actions.** It documents and classifies. It does not contain endpoints, kill processes, or modify configuration. +- **The agent depends on accurate scope tags.** A sensor that handles cardholder data but is not tagged `cde` will not be treated as in scope by the PCI reviewer. Tag accuracy is an operational responsibility — consider periodic tag audits using `compliance-gap`, which surfaces sensor-coverage issues. +- **The agent is best-effort, not deterministic.** It is an AI agent, and its outputs vary slightly between runs. For high-stakes cases, treat the agent's output as a first-draft documentation that a human analyst reviews before the auditor sees it. + +## See also + +- [D&R-Driven Sessions](../dr-sessions.md) — the underlying execution model +- [Cases](../../5-integrations/extensions/limacharlie/cases.md) — the case lifecycle the agent operates against +- [Hive Secrets](../../7-administration/config-hive/secrets.md) — where the agent's API keys are stored +- [Alternative AI Providers](../alternative-providers.md) — routing through Bedrock or Vertex AI instead of Anthropic direct +- [Skills Reference](skills.md) — `compliance-deploy` syntax and behavior diff --git a/docs/9-ai-sessions/compliance/frameworks.md b/docs/9-ai-sessions/compliance/frameworks.md new file mode 100644 index 000000000..c42bf04aa --- /dev/null +++ b/docs/9-ai-sessions/compliance/frameworks.md @@ -0,0 +1,155 @@ +# Frameworks + +`lc-compliance` ships reference content and a case-reviewer agent for seven compliance frameworks. Each framework's coverage is bundled inside the plugin under `${CLAUDE_PLUGIN_ROOT}/compliance//`, where the skills resolve it at runtime. + +## Verification levels + +Every framework carries a declared **verification level** that describes how its control IDs have been reconciled against the standard's authoritative publisher: + +| Level | Meaning | +|---|---| +| **MACHINE_VERIFIED** | Every control ID in the mapping has been programmatically reconciled against the standard's authoritative source (e.g., an OSCAL catalog, the eCFR XML, a published API). | +| **ATTESTATION_ONLY** | The format and structure of the citations have been validated, but the wording has not been reconciled programmatically because the authoritative source is a PDF that cannot be parsed reliably. A QSA / ISSO / certified assessor should review citations against the official document before relying on them in an external audit. | +| **UNVERIFIED** | The authoritative source is paywalled or otherwise inaccessible, and the mapping is based on publicly-available summaries. Each affected framework's attribution document explains how to upgrade the level if a licensed source extract is available. | + +The level is declared in each framework's `attribution.md` file inside the plugin and is reported in the output of the `compliance-lookup` skill for every control queried. + +| Framework | Level | Authoritative source | +|---|---|---| +| NIST SP 800-53 Rev 5 | **MACHINE_VERIFIED** | NIST OSCAL catalog | +| HIPAA Security Rule | **MACHINE_VERIFIED** | eCFR 45 CFR §164 | +| CMMC v2 | ATTESTATION_ONLY | NIST SP 800-171 Rev 2 PDF | +| PCI DSS v4.0 | ATTESTATION_ONLY | PCI SSC v4.0 PDF | +| SOC 2 | ATTESTATION_ONLY | AICPA Trust Services Criteria PDF | +| CIS Critical Security Controls v8 | ATTESTATION_ONLY | CIS Controls v8 PDF | +| ISO/IEC 27001:2022 | UNVERIFIED | ISO/IEC 27002:2022 (paywalled) | + +## Per-framework details + +The sections below summarize each framework's scope, recommended scope-tag convention, and any framework-specific arguments that the skills accept. + +### CMMC v2 + +| Property | Value | +|---|---| +| Citation format | `AU.L2-3.3.1`, `AC.L1-3.1.1`, etc. | +| Reviewer agent | `cmmc-compliance-reviewer` | +| Accepted scope tags | `cui`, `cui-host`, `cmmc-scope`, `dib-host` | +| Verification level | ATTESTATION_ONLY (review against NIST SP 800-171 Rev 2) | +| Framework-specific skill args | None | + +CMMC v2 inherits its Level 2 control set from NIST SP 800-171 Rev 2. Citations in the bundled mapping and implementation documents use the standard CMMC short-form (`.L-3.x.x`). The reviewer agent is intended for systems handling Controlled Unclassified Information (CUI). + +### NIST SP 800-53 Rev 5 + +| Property | Value | +|---|---| +| Citation format | `AC-2`, `AU-2`, `SI-4`, etc. | +| Reviewer agent | `nist-800-53-compliance-reviewer` | +| Accepted scope tags | `fisma-scope`, `fedramp-scope`, `federal-system`, `nist-scope` | +| Verification level | **MACHINE_VERIFIED** (NIST OSCAL catalog, 1,196 control IDs) | +| Framework-specific skill args | `--baseline ` on `compliance-gap` | + +NIST 800-53 supports the FIPS 199 Low / Moderate / High baselines. The `compliance-gap` skill accepts a `--baseline` argument to scope the analysis to controls applicable at a given baseline level. The skill itself does not declare a default — if omitted, behaviour is to evaluate all controls in the bundled implementation document. Specify `--baseline` explicitly when the analysis should follow a single FIPS 199 tier. + +### PCI DSS v4.0 + +| Property | Value | +|---|---| +| Citation format | `Req 10.2.1.4`, `Req 7.2.x`, etc. | +| Reviewer agent | `pci-compliance-reviewer` | +| Accepted scope tags | `cde`, `pci-scope`, `card-data`, `pci-dss` | +| Verification level | ATTESTATION_ONLY (review against PCI SSC v4.0 PDF — license restricts redistribution) | +| Framework-specific skill args | None | + +The reviewer agent scopes itself to sensors tagged `cde` (cardholder data environment). PCI DSS v4.0 distinguishes between Requirement (top-level) and Sub-requirement (e.g., `10.2.1.4`). The lookup skill accepts both `pci` and `pci-dss` as the framework shorthand. + +### HIPAA Security Rule + +| Property | Value | +|---|---| +| Citation format | `§164.312(b)`, `§164.308(a)(1)(ii)(D)`, etc. | +| Reviewer agent | `hipaa-compliance-reviewer` | +| Accepted scope tags | `ephi-host`, `hipaa-scope`, `phi-host`, `covered-entity` | +| Verification level | **MACHINE_VERIFIED** (eCFR 45 CFR §164, 1,036 subsection IDs) | +| Framework-specific skill args | None | + +HIPAA citations use the eCFR's section-and-subsection notation. The reviewer agent scopes itself to sensors tagged `phi` (protected health information). The skill accepts both `§164.312(b)` and `164.312(b)` as the control ID. + +### SOC 2 (Trust Services Criteria) + +| Property | Value | +|---|---| +| Citation format | `CC6.1`, `CC7.2`, `A1.2`, etc. | +| Reviewer agent | `soc2-compliance-reviewer` | +| Accepted scope tags | `soc2-scope`, `in-scope-system`, `audit-scope` | +| Verification level | ATTESTATION_ONLY (review against AICPA TSC PDF) | +| Framework-specific skill args | None | + +SOC 2 citations follow the AICPA Trust Services Criteria short-form. CC (Common Criteria) controls apply to all SOC 2 Type II engagements; A, C, P, and PI categories apply only when the corresponding trust service is in scope. + +### ISO/IEC 27001:2022 + +| Property | Value | +|---|---| +| Citation format | `A.8.15`, `A.5.10`, etc. | +| Reviewer agent | `iso-27001-compliance-reviewer` | +| Accepted scope tags | `isms-scope`, `iso-scope`, `iso-27001-scope`, `soa-included` | +| Verification level | **UNVERIFIED** (ISO standard is paywalled at ~$215 / ~$395 for combined 27001+27002) | +| Framework-specific skill args | None | + +ISO/IEC 27002:2022 control identifiers (`A.x.y`) are used. The mapping is based on publicly-available summaries because the official ISO standard is not redistributable. The attribution document explains how to upgrade this framework to MACHINE_VERIFIED if a licensed extract is staged. + +!!! warning "ISO 27001 verification level" + Unlike the other six frameworks, ISO 27001 citations have not been programmatically reconciled against an authoritative source. A certified ISO 27001 lead auditor should review the citations in the mapping document before relying on them in a certification audit. + +### CIS Critical Security Controls v8 + +| Property | Value | +|---|---| +| Citation format | `8.2`, `4.1`, `13.6`, etc. (Safeguard numbering) | +| Reviewer agent | `cis-v8-compliance-reviewer` | +| Accepted scope tags | `cis-scope`, `cis-v8-scope` (plus optional `cis-ig1`, `cis-ig2`, `cis-ig3` for tier) | +| Verification level | ATTESTATION_ONLY (review against CIS Controls v8 PDF — CC BY-NC-ND license) | +| Framework-specific skill args | `--ig <1\|2\|3>` on `compliance-gap` | + +CIS v8 organizes safeguards into Implementation Groups (IG1 / IG2 / IG3) based on enterprise size and risk tolerance. The `compliance-gap` skill accepts an `--ig` argument to scope the analysis to safeguards applicable at a given implementation group. The skill does not declare a hard-coded default; if neither `--ig` is supplied nor a `cis-ig1`/`cis-ig2`/`cis-ig3` tag is set on a sensor, the analysis covers all safeguards in the bundled implementation document. + +## Bundled artifacts per framework + +For each framework, the plugin ships five artifacts under `${CLAUDE_PLUGIN_ROOT}/compliance//`: + +| File | Purpose | +|---|---| +| `-limacharlie-mapping.md` | Control-to-capability mapping. Quoted verbatim by the `compliance-lookup` skill. | +| `-limacharlie-implementation.md` | Deployable D&R / FIM / artifact-collection / exfil rules in YAML, each with the control citation in its metadata. | +| `-attribution.md` | Authoritative publisher, citation format, retrieval date, verification level, independent-re-verification procedure. | +| `recommended-rules.yaml` | Canonical rule-name baseline. The `compliance-gap` skill diffs deployed-rule names against this list. | +| `agent/` | Reviewer agent manifest (`-compliance-reviewer.yaml`) and the hive records (`ai_agent`, `dr-general`, `secret`) that `compliance-deploy` pushes. | + +These artifacts are read at skill-invocation time. They are not synced into your organization automatically — synchronisation happens only when you explicitly invoke `compliance-deploy` or `compliance-baseline-deploy`. + +## Updating to a newer framework version + +When the plugin ships an updated implementation document for a framework (e.g., a new PCI sub-requirement is added), the recommended re-sync sequence is: + +```text +/plugin update lc-compliance@lc-marketplace + +/lc-compliance:compliance-baseline-deploy --oid # dry-run +/lc-compliance:compliance-baseline-deploy --oid --apply +``` + +The baseline deploy is idempotent — rules already present under the same name are skipped, so re-running it picks up only the new rules. To replace existing rules with the updated definitions, use `--overwrite`. + +To refresh the reviewer agent's prompt and tools after a plugin update: + +```text +/lc-compliance:compliance-deploy --oid +``` + +## See also + +- [Skills Reference](skills.md) — argument syntax for `--baseline`, `--ig`, and other framework-specific flags +- [Case-Reviewer Agent](case-reviewer-agent.md) — how the per-framework reviewer agent classifies cases +- [Gap Analysis](gap-analysis.md) — how the framework's recommended baseline is used to compute gaps diff --git a/docs/9-ai-sessions/compliance/gap-analysis.md b/docs/9-ai-sessions/compliance/gap-analysis.md new file mode 100644 index 000000000..9af280190 --- /dev/null +++ b/docs/9-ai-sessions/compliance/gap-analysis.md @@ -0,0 +1,171 @@ +# Gap Analysis + +The [`compliance-gap`](skills.md#compliance-gap) skill produces an on-demand markdown report comparing an organization's currently-deployed configuration against the framework's recommended baseline. This page explains how to read the report, what each section means, and how to act on the findings. + +Gap analysis is the primary way to assess compliance posture in `lc-compliance`. There is no backend gap-analyzer agent — gap reports are engineering punch lists, not audit evidence, and so they are produced interactively and live only in your Claude Code chat. + +## When to run a gap analysis + +Common occasions: + +- **Before an audit window opens.** Three to six weeks before an external assessor begins fieldwork is the most valuable moment — there is still time to remediate. +- **After onboarding a new tenant or new scope.** When sensors are first tagged into scope (e.g., a new acquisition's endpoints get the `cde` tag), run a gap analysis to confirm the framework's expectations are met. +- **After a plugin update.** When the bundled recommended baseline changes, the gap analysis identifies any new rules that should be deployed. +- **As a regular cadence.** Quarterly or monthly gap analyses surface drift (rules disabled, sensors offline, extensions unsubscribed) before they become audit findings. + +## Running the skill + +```text +/lc-compliance:compliance-gap pci-dss --oid +``` + +The skill queries the organization through the standard LimaCharlie CLI session, diffs the deployed configuration against the framework's `recommended-rules.yaml` baseline, and prints the report to your chat. Nothing is written to the organization. + +For NIST 800-53, scope the analysis to a FIPS 199 baseline: + +```text +/lc-compliance:compliance-gap nist --oid --baseline moderate +``` + +For CIS v8, scope to an Implementation Group: + +```text +/lc-compliance:compliance-gap cis --oid --ig 2 +``` + +## Anatomy of a gap report + +The report has a consistent structure across frameworks. A sample run against a PCI DSS org looks like this: + +````text +# PCI DSS v4.0 Gap Analysis (Interactive) + +**Org:** c1ffedc0-ffee-4a1e-b1a5-abc123def456 (example-org) +**Generated:** 2026-04-17T18:42:03Z +**Recommended set version:** 2026-04-17 +**Verification level:** ATTESTATION_ONLY +**Scope:** sensors tagged `cde` (3 found; 2 online / 1 offline > 7d) + +## Summary +- Telemetry gaps: 7 events across windows, linux +- Artifact collection gaps: 9 rules missing +- FIM gaps: 23 rules (ext-integrity not subscribed — see Section C) +- D&R rule gaps: 42 of 57 recommended missing +- Sensor-coverage issues: 1 CDE sensor offline > 7d (Req 10.7.x) +- Name-drift candidates: 2 (manual review) +- Deployed extras: 11 (informational) + +## A. Telemetry Gaps +### Windows +| Missing event | PCI requirement | +|---|---| +| THREAD_INJECTION | Req 10.2.x | +| SENSITIVE_PROCESS_ACCESS | Req 10.2.1.2 | +| NEW_NAMED_PIPE | Req 10.2.x | + +## D. D&R Rule Gaps (top 10 of 42) +| Canonical rule name | PCI requirement | MITRE ATT&CK | +|---|---|---| +| pci-10-failed-logon-windows | Req 10.2.1.4 | T1078 | +| pci-10-brute-force-windows | Req 10.2.1.4 | T1110 | +| pci-10-event-log-cleared | Req 10.2.1.6 | T1070.001 | + +## F. Sensor Coverage +| Sensor | Hostname | Last seen | PCI requirement | +|---|---|---|---| +| aaaabbbb...11 | web-prod-04 | 11 days ago | Req 10.7.x — critical security control failure | + +## Prioritized Remediation +1. Subscribe ext-integrity and deploy the 23 FIM rules — addresses Req 11.5.1 + 11.5.2 +2. Investigate offline CDE sensor web-prod-04 (Req 10.7.x) +3. Deploy the 10 highest-priority D&R rules (Req 10.2.x failed-logon cluster first) +4. Enable missing exfil events on Windows CDE fleet +5. Add 9 missing artifact-collection rules (PowerShell Operational, Defender, Task Scheduler) +```` + +The sections in the report: + +### Header + +The header carries the **organization name and UUID** so reports can be attributed unambiguously, the **timestamp** the report was generated (always UTC), the **recommended set version** (a date string indicating which bundled baseline the analysis ran against), the framework's **verification level** (so readers can calibrate trust appropriately), and the **scope** (which sensors were considered in-scope based on the framework's tag convention). + +### Summary + +A one-glance count of issues across six categories. The counts are not weighted by severity — a missing low-priority D&R rule and a missing critical exfil event each contribute one to the count. Use the Prioritized Remediation section for priority. + +### A. Telemetry Gaps + +Events the framework's recommended baseline expects the in-scope sensors to be collecting, that are absent from the org's deployed exfil profile. Broken down by sensor platform (Windows, Linux, macOS) because exfil profiles are platform-specific. + +A telemetry gap means the rule downstream cannot fire even if deployed, because the underlying event isn't being collected. **Fix these before deploying the corresponding D&R rules.** + +### B. Artifact Collection Gaps + +Rules from the recommended baseline that collect specific artifacts (PowerShell Operational logs, Windows Defender logs, Task Scheduler logs, etc.) which are not deployed. These rules subscribe the sensor to additional log sources that go beyond standard exfil. + +### C. FIM Gaps + +File-integrity-monitoring rules that are not deployed. FIM in LimaCharlie is provided by the `ext-integrity` extension. The gap report explicitly flags whether `ext-integrity` is subscribed to the organization — if it is not, all FIM rules in the baseline will be reported as gaps, and subscribing the extension is the first remediation step. + +See the [Integrity extension](../../5-integrations/extensions/limacharlie/integrity.md). + +### D. D&R Rule Gaps + +D&R rule names from the recommended baseline that are not present in the org's deployed rule set. The report shows the top 10 by default with a count of the remainder; the full list is accessible via the skill's interactive follow-up. + +Each entry carries the framework's control citation and, where the bundled implementation document includes it, the MITRE ATT&CK technique the rule targets. The latter is useful for cross-referencing against an existing detection engineering roadmap. + +### E. Name Drift + +Deployed rules whose names are *close to but not identical to* a recommended-baseline name. This usually indicates one of two things: + +- The org deployed a rule manually with a slightly different name, missing the canonical naming convention by a few characters +- A previous version of the baseline used a different name, and the rule has not been renamed to match the current bundled name + +Name-drift candidates are surfaced for **manual review**, not auto-remediation — the report does not attempt to merge them with their canonical counterparts. To remediate, either rename the deployed rule to match the canonical name, or accept the drift and treat both as in-scope. + +### F. Sensor Coverage + +In-scope sensors that have not reported in more than 7 days. The skill uses a uniform 7-day threshold across all frameworks; per-framework citations attached to each row identify which control(s) the offline sensor risks failing (e.g., PCI DSS Req 10.7.x for cardholder-data environments, HIPAA §164.312(b) for ePHI systems). + +A sensor showing here is, in audit terms, an organization that has stopped collecting required telemetry from an in-scope system. Investigate before the auditor finds it. + +### G. Deployed Extras (informational) + +Rules deployed in the org that are **not** part of the recommended baseline. These are never flagged as gaps — extras are usually intentional (custom detections, threat-intel-driven rules, organization-specific tuning). The list is informational so operators can confirm the deployed set is intentional. + +### Prioritized Remediation + +A short ordered list, typically 4–6 items, reflecting the most impactful gap-closing actions. The ordering takes into account dependencies (e.g., subscribe `ext-integrity` *before* deploying FIM rules) and control criticality (sensor coverage and authentication-logging controls usually rank highest). + +## Acting on the report + +The report is a punch list. Typical follow-up paths: + +| Section | Remediation skill or action | +|---|---| +| A. Telemetry gaps | Edit the org's exfil profile — see [Exfil extension](../../5-integrations/extensions/limacharlie/exfil.md) | +| B. Artifact collection gaps | Run [`compliance-baseline-deploy --apply --kinds artifact`](skills.md#compliance-baseline-deploy) | +| C. FIM gaps | Subscribe [Integrity extension](../../5-integrations/extensions/limacharlie/integrity.md), then `--kinds fim` | +| D. D&R rule gaps | Run [`compliance-baseline-deploy --apply --kinds dr`](skills.md#compliance-baseline-deploy) for the full set, or write/import targeted rules | +| E. Name-drift candidates | Manual rename of deployed rules, or accept the drift | +| F. Sensor-coverage issues | Investigate the offline sensors; if decommissioned, remove from scope | +| G. Deployed extras | No action — informational only | + +## Persisting a gap report + +The skill writes the report to your Claude Code chat. It does not write to the LimaCharlie organization. If you want the report persisted for an auditor to reference, paste the markdown into a [Case](../../5-integrations/extensions/limacharlie/cases.md) note, or store it in your GRC platform of choice. + +This separation is deliberate: gap reports are engineering punch lists with a short half-life. Audit evidence is what the case-reviewer agent produces continuously inside the case queue. Conflating the two would invite auditors to treat a snapshot punch list as compliance evidence, which it is not. + +## Multi-tenant gap analysis + +The skill operates on a single organization per invocation. For a portfolio of organizations (an MSSP book of business, a parent organization with multiple subsidiaries), invoke the skill once per `--oid`. Each report is independent and can be sent to the relevant customer, business unit, or compliance team. + +If you find yourself running the same gap analysis across many orgs on a regular cadence, consider scripting the iteration around the skill invocation, or surface a feature request — a multi-org roll-up is not currently a built-in capability of the plugin. + +## See also + +- [Skills Reference](skills.md#compliance-gap) — full argument reference for the gap-analysis skill +- [Frameworks](frameworks.md) — per-framework recommended scope tags and verification levels +- [Case-Reviewer Agent](case-reviewer-agent.md) — the continuous evidence-production complement to ad-hoc gap analysis diff --git a/docs/9-ai-sessions/compliance/index.md b/docs/9-ai-sessions/compliance/index.md new file mode 100644 index 000000000..440fe2615 --- /dev/null +++ b/docs/9-ai-sessions/compliance/index.md @@ -0,0 +1,71 @@ +# Compliance + +LimaCharlie ships a compliance toolkit, **`lc-compliance`**, that maps seven major compliance frameworks directly onto your deployed sensors, detections, and case queue. It is delivered as a Claude Code plugin sourced from the public [`refractionPOINT/lc-ai`](https://github.com/refractionPOINT/lc-ai) marketplace, and is licensed under Apache 2.0. + +The toolkit has two complementary halves that solve different parts of the compliance problem: + +- A **case-reviewer agent** that runs continuously inside your LimaCharlie organization, classifying every new case against the relevant control citations and writing audit-grade documentation directly into the case record. Built on [AI Sessions](../index.md). +- A set of **four Claude Code skills** that an engineer runs on demand from their Claude Code session: control lookups, ad-hoc gap analysis, guided agent deployment, and full rule-baseline deployment. + +The continuous half produces durable audit evidence. The on-demand half supports the engineering work that surrounds an audit — answering "how does LC cover this control?", "what am I missing before the audit?", and "deploy the recommended rule set to this new tenant." + +## Frameworks covered + +| Framework | Authoritative source | +|---|---| +| **CMMC v2** | NIST SP 800-171 Rev 2 | +| **NIST SP 800-53 Rev 5** | NIST OSCAL catalog | +| **PCI DSS v4.0** | PCI Security Standards Council | +| **HIPAA Security Rule** | eCFR 45 CFR §164 | +| **SOC 2** | AICPA Trust Services Criteria | +| **ISO/IEC 27001:2022** | ISO (Annex A) | +| **CIS Critical Security Controls v8** | Center for Internet Security | + +Each framework ships with a control-to-capability mapping document, a set of deployable D&R / file-integrity / artifact-collection / exfil rules across Windows, Linux, and macOS, a recommended-rules baseline used by the gap-analysis skill, an attribution document declaring the verification level, and a case-reviewer agent manifest ready to deploy. See [Frameworks](frameworks.md). + +## The two shapes — when to use which + +| Use case | Shape | +|---|---| +| Continuous per-case compliance classification | **Agent** (`-compliance-reviewer`) — fires on every `case_created` | +| Ad-hoc "what does LC do for this one control?" | **Skill** (`compliance-lookup`) | +| Ad-hoc "what am I missing?" before an audit | **Skill** (`compliance-gap`) | +| First-time reviewer-agent deployment | **Skill** (`compliance-deploy`) | +| Push the full framework rule baseline into an org | **Skill** (`compliance-baseline-deploy`) | + +The agent owns continuous, event-driven evidence production — cases, notes, tags persisted in the LC org that auditors rely on. Skills own request-driven interactive work that engineers run during development without leaving artifacts behind in the org. + +!!! info "Gap analysis is skill-only" + There is no backend gap-analyzer agent. A gap report is an engineering punch list, not audit evidence. If you want the report persisted in the LC org for an auditor to reference, create a [Case](../../5-integrations/extensions/limacharlie/cases.md) yourself and paste the skill's output into it. + +## Quickstart + +```text +/plugin marketplace add https://github.com/refractionPOINT/lc-ai +/plugin install lc-compliance@lc-marketplace +``` + +Once installed, the four skills are immediately available: + +```text +/lc-compliance:compliance-lookup pci 10.2.1.4 +/lc-compliance:compliance-gap hipaa --oid +/lc-compliance:compliance-deploy cmmc --oid +/lc-compliance:compliance-baseline-deploy pci-dss --oid --apply +``` + +For a step-by-step walkthrough of the first three commands, see [Installation](installation.md). For arguments and behavior of each skill, see [Skills Reference](skills.md). To deploy the case-reviewer agent into an organization, see [Case-Reviewer Agent](case-reviewer-agent.md). + +## What `lc-compliance` does not do + +- **Issue compliance attestations.** The plugin reports evidence. The human auditor / QSA / ISSO decides compliance status. +- **Modify deployed configuration without confirmation.** Every write (API key creation, secret staging, rule deployment) requires explicit confirmation. `compliance-baseline-deploy` defaults to a dry-run; `--apply` is required to write rules. +- **Replace your SOC.** The case-reviewer agent runs in parallel to whatever Level-1 triage flow already exists in the organization, classifying for compliance impact, not security severity. It does not contain, isolate, or remediate. +- **Provide normative control wording.** Mappings paraphrase. The normative text of each standard lives in the publisher's document, linked in every framework's attribution document. + +## See also + +- [AI Sessions](../index.md) — the underlying mechanism the case-reviewer agent runs on +- [Cases](../../5-integrations/extensions/limacharlie/cases.md) — the case lifecycle the agent operates against +- [D&R-Driven Sessions](../dr-sessions.md) — how the case-reviewer agent is triggered +- [Hive Secrets](../../7-administration/config-hive/secrets.md) — where the agent's API keys are stored diff --git a/docs/9-ai-sessions/compliance/installation.md b/docs/9-ai-sessions/compliance/installation.md new file mode 100644 index 000000000..ecb4e6f4a --- /dev/null +++ b/docs/9-ai-sessions/compliance/installation.md @@ -0,0 +1,129 @@ +# Installation + +`lc-compliance` is a Claude Code plugin distributed through the LimaCharlie marketplace at [`refractionPOINT/lc-ai`](https://github.com/refractionPOINT/lc-ai). Installing the plugin gives you the four interactive compliance skills and the bundled reference content for all seven frameworks. The case-reviewer agent is deployed separately on a per-organization basis — see [Case-Reviewer Agent](case-reviewer-agent.md). + +## Prerequisites + +Before installing: + +- A working **Claude Code** environment. Install via `curl -fsSL https://claude.ai/install.sh | bash`, or use Claude Code through the LimaCharlie web interface at [app.limacharlie.io](https://app.limacharlie.io), where `lc-essentials` is pre-configured. +- The **LimaCharlie CLI** (`limacharlie`) installed and authenticated against the organization you will operate on. The skills shell out to the CLI for org operations. +- The **`lc-essentials`** plugin already installed in the same Claude Code session. `lc-compliance` does not duplicate the API access layer — it relies on `lc-essentials` for org listing, sensor operations, and rule deployment. See the [`lc-essentials` README](https://github.com/refractionPOINT/lc-ai/tree/master/marketplace/plugins/lc-essentials) for setup. +- For the case-reviewer agent: an **Anthropic API key** (or other supported provider — see [Alternative AI Providers](../alternative-providers.md)), and a **LimaCharlie API key** with case-investigation permissions. The `compliance-deploy` skill handles key creation and secret staging for you. + +## Installing the plugin + +From any Claude Code session: + +```text +/plugin marketplace add https://github.com/refractionPOINT/lc-ai +/plugin install lc-compliance@lc-marketplace +``` + +After installation, the four skills become available immediately: + +| Slash command | Purpose | +|---|---| +| `/lc-compliance:compliance-lookup` | Look up control coverage | +| `/lc-compliance:compliance-gap` | Run an ad-hoc gap analysis | +| `/lc-compliance:compliance-deploy` | Deploy the case-reviewer agent | +| `/lc-compliance:compliance-baseline-deploy` | Deploy the full framework rule baseline | + +See [Skills Reference](skills.md) for full argument syntax and behavior. + +## Verifying the installation + +Run the lookup skill against a known control to confirm the plugin is loaded and the bundled reference content is accessible: + +```text +/lc-compliance:compliance-lookup nist AU-2 +``` + +You should receive a response that includes: + +- A conceptual coverage description quoted from the NIST 800-53 mapping document +- The verification level for the NIST 800-53 framework (**MACHINE_VERIFIED**) +- A list of deployable rules that cite AU-2 in their metadata + +If the response says the framework cannot be located, the plugin is installed but its bundled content was not found on disk — verify that `${CLAUDE_PLUGIN_ROOT}/compliance/nist-800-53/` exists. + +## First deployment to an organization + +Once the plugin is installed, deploying compliance capabilities to a specific organization is a separate step. The recommended sequence for a new organization is: + +### 1. Choose your framework and identify in-scope sensors + +For most frameworks, only a subset of your fleet is in scope (the cardholder data environment for PCI, systems handling ePHI for HIPAA, etc.). Each reviewer accepts a small set of tag aliases; tagging any *one* of the accepted tags is enough to place the sensor in scope. + +| Framework | Accepted scope tags (any one is sufficient) | +|---|---| +| PCI DSS | `cde`, `pci-scope`, `card-data`, `pci-dss` | +| HIPAA | `ephi-host`, `hipaa-scope`, `phi-host`, `covered-entity` | +| CMMC | `cui`, `cui-host`, `cmmc-scope`, `dib-host` | +| NIST 800-53 | `fisma-scope`, `fedramp-scope`, `federal-system`, `nist-scope` | +| SOC 2 | `soc2-scope`, `in-scope-system`, `audit-scope` | +| ISO 27001 | `isms-scope`, `iso-scope`, `iso-27001-scope`, `soa-included` | +| CIS v8 | `cis-scope`, `cis-v8-scope` (plus optional `cis-ig1`/`cis-ig2`/`cis-ig3` for tier) | + +Use the standard CLI to apply tags: + +```bash +limacharlie tag add --sid -t cde --oid +``` + +See [Sensor Tags](../../2-sensors-deployment/sensor-tags.md) for tagging at scale. + +### 2. Deploy the case-reviewer agent + +```text +/lc-compliance:compliance-deploy pci-dss --oid +``` + +The skill walks you through API-key creation, Anthropic secret staging, agent hive sync, and trigger D&R rule installation, with explicit confirmation at each platform write. See [Case-Reviewer Agent](case-reviewer-agent.md). + +### 3. Deploy the recommended rule baseline (optional) + +```text +/lc-compliance:compliance-baseline-deploy pci-dss --oid +``` + +This is a dry-run by default. It prints exactly which rules would be created, then asks for confirmation. To apply, re-run with `--apply`: + +```text +/lc-compliance:compliance-baseline-deploy pci-dss --oid --apply +``` + +The skill is idempotent — rules already deployed under the same name are skipped, so it is safe to re-run after the bundled implementation document is updated. See [Skills Reference](skills.md#compliance-baseline-deploy) for behavior details and the `--overwrite` / `--kinds` flags. + +### 4. Run an initial gap analysis + +After the baseline is deployed, run a gap analysis to confirm there are no remaining coverage holes: + +```text +/lc-compliance:compliance-gap pci-dss --oid +``` + +The output is a markdown punch list directly in your chat. See [Gap Analysis](gap-analysis.md) for how to read the report. + +## Updating the plugin + +To pick up new framework content, rule definitions, or skill changes: + +```text +/plugin update lc-compliance@lc-marketplace +``` + +The plugin reads its bundled reference content from disk at invocation time, so an update is picked up on the next skill invocation without restarting Claude Code. Already-deployed reviewer agents and rules in your LimaCharlie organizations are unaffected by a plugin update — they continue running their previously-synced configuration. To bring them in line with new plugin content, re-run `compliance-deploy` (for the agent) or `compliance-baseline-deploy` (for the rules) against the relevant orgs. + +!!! info "Multi-tenant operators" + Each skill takes an `--oid` argument. Run the skill once per organization to onboard, audit, or deploy across a portfolio. The plugin itself is installed once into your Claude Code environment, not per organization. See [Skills Reference](skills.md) for the per-skill behavior. + +## Uninstalling + +To remove the plugin from your Claude Code environment: + +```text +/plugin uninstall lc-compliance@lc-marketplace +``` + +This removes the skills and bundled reference content from your local Claude Code installation. **It does not remove anything from your LimaCharlie organizations.** Deployed case-reviewer agents, hive records, secrets, API keys, and D&R rules remain in place and continue running. To remove those, use `limacharlie sync` against an empty manifest or manually delete the affected hive records. diff --git a/docs/9-ai-sessions/compliance/skills.md b/docs/9-ai-sessions/compliance/skills.md new file mode 100644 index 000000000..1b08f4d26 --- /dev/null +++ b/docs/9-ai-sessions/compliance/skills.md @@ -0,0 +1,209 @@ +# Skills Reference + +`lc-compliance` exposes four Claude Code skills. All four follow the same framework-shorthand parsing convention and use `--oid` to target a specific LimaCharlie organization. None of the skills modify your organization without explicit confirmation; the two write-capable skills (`compliance-deploy`, `compliance-baseline-deploy`) prompt for confirmation at each platform write, and `compliance-baseline-deploy` additionally requires `--apply` to leave dry-run mode. + +## Framework shorthand parsing + +All four skills accept the same framework aliases as the first positional argument: + +| Input | Resolved | +|---|---| +| `pci`, `pci-dss` | pci-dss | +| `nist`, `800-53`, `nist-800-53` | nist-800-53 | +| `cmmc` | cmmc | +| `hipaa` | hipaa | +| `soc2` | soc2 | +| `iso`, `iso-27001` | iso-27001 | +| `cis`, `cis-v8` | cis-v8 | + +If a framework cannot be parsed from the input, the skill prompts the user to clarify. + +## `compliance-lookup` + +Look up how LimaCharlie covers a specific compliance control. Returns the control's conceptual coverage (from the framework's mapping document) plus the specific deployable rules that cite it (from the framework's implementation document). Read-only — does not contact your LimaCharlie organization. + +### Syntax + +```text +/lc-compliance:compliance-lookup +``` + +### Arguments + +| Argument | Required | Notes | +|---|---|---| +| `` | Yes | One of the framework shorthand values above. May be inferred from the control ID format if unambiguous (e.g., `CC6.1` → SOC 2, `§164.312` → HIPAA, `AU-2` → NIST 800-53). | +| `` | Yes | Citation in the format the framework uses. See [Frameworks](frameworks.md) for per-framework citation formats. | + +### Examples + +```text +/lc-compliance:compliance-lookup pci 10.2.1.4 +/lc-compliance:compliance-lookup nist AU-2 +/lc-compliance:compliance-lookup cmmc AU.L2-3.3.1 +/lc-compliance:compliance-lookup hipaa §164.312(b) +/lc-compliance:compliance-lookup soc2 CC6.1 +/lc-compliance:compliance-lookup iso A.8.15 +/lc-compliance:compliance-lookup cis 8.2 +``` + +### Output + +A markdown block in your chat containing: + +- The framework name and citation +- The framework's verification level (MACHINE_VERIFIED / ATTESTATION / UNVERIFIED) +- A verbatim quote of the conceptual coverage from the framework's mapping document +- A table listing every deployable rule whose metadata cites this control ID, with the rule name, the LimaCharlie event type it triggers on, and a one-line summary +- Pointers to the bundled source files + +If the control ID is not present in the bundled mapping or implementation document, the skill reports that explicitly rather than fabricating a response. + +### When to use + +- Answering a targeted "how does LC cover control X?" question from an auditor, engineer, or security lead +- Verifying that a specific control citation has deployable rules behind it before referencing the citation in a design document +- Inspecting which rule names you would expect to see in the org for a given control + +If the question is broader — "what am I missing for this whole framework?" — use [`compliance-gap`](#compliance-gap) instead. + +## `compliance-gap` + +Run an ad-hoc gap analysis against a live LimaCharlie organization. Compares what the org is currently collecting and detecting against the framework's recommended rule set, and returns a markdown punch list directly in chat. No case is created; nothing is written to the org. + +### Syntax + +```text +/lc-compliance:compliance-gap [--oid ] [--baseline ] [--ig ] +``` + +### Arguments + +| Argument | Required | Notes | +|---|---|---| +| `` | Yes | Framework shorthand. | +| `--oid ` | No | Target organization UUID. Defaults to the CLI's currently-selected org. | +| `--baseline ` | No | NIST 800-53 only. Scopes analysis to the named FIPS 199 baseline. No hard-coded default — omit to evaluate all bundled controls. | +| `--ig <1\|2\|3>` | No | CIS v8 only. Scopes analysis to safeguards in the named Implementation Group. No hard-coded default — omit to evaluate all bundled safeguards (the skill will also honour `cis-ig1`/`cis-ig2`/`cis-ig3` tags on sensors if set). | + +### Output + +A markdown gap report with these sections: + +- **Summary** — counts of telemetry / artifact / FIM / D&R / sensor-coverage gaps +- **Telemetry (Exfil) Gaps** — events the framework expects that are not in the org's exfil profile, broken down by platform +- **Artifact Collection Gaps** — artifact-collection rules from the recommended baseline that are not deployed +- **FIM Gaps** — file-integrity-monitoring rules that are not deployed (and whether `ext-integrity` is even subscribed) +- **D&R Rule Gaps** — recommended D&R rule names that are not deployed in the org +- **Sensor-Coverage Issues** — in-scope sensors that have gone offline beyond the framework's expected retention window +- **Name-Drift Candidates** — deployed rules whose names are close to but not identical to a recommended name (manual review) +- **Deployed Extras** — rules deployed in the org that are not part of the recommended baseline (informational, never flagged as a gap) +- **Prioritized Remediation** — a short, ordered punch list + +The report is informational only. Nothing is written to the LC org. See [Gap Analysis](gap-analysis.md) for how to read and act on the output. + +!!! info "Persisting a gap report" + If you want a gap report stored in the LC org for auditors to reference, create a [Case](../../5-integrations/extensions/limacharlie/cases.md) yourself and paste the skill's output into a case note. This separation is deliberate — gap reports are engineering punch lists, not audit evidence. + +## `compliance-deploy` + +Guided deployment of a framework's case-reviewer agent to a LimaCharlie organization. Human-in-the-loop at each sensitive step (API-key creation, secret staging, agent hive sync, trigger D&R rule installation). Does not silently modify the org. + +### Syntax + +```text +/lc-compliance:compliance-deploy [--oid ] [--with-rules] +``` + +### Arguments + +| Argument | Required | Notes | +|---|---|---| +| `` | Yes | Framework shorthand. | +| `--oid ` | No | Target organization UUID. Defaults to the CLI's currently-selected org. | +| `--with-rules` | No | Also deploy a small starter rule subset (5–10 representative rules across D&R / FIM / artifact / exfil). Useful for demos. **For the full baseline, use [`compliance-baseline-deploy`](#compliance-baseline-deploy) instead.** | + +### What it does + +The skill walks through these steps, asking for confirmation before each platform write: + +1. **Pre-flight checks** — verifies `ext-cases` is subscribed on the target org, that the framework's bundled assets are accessible, and that an Anthropic key is staged or available to stage. +2. **API-key creation** — creates a scoped LimaCharlie API key for the reviewer agent, with the minimum permissions needed (typically `org.get`, `sensor.list`, `sensor.get`, `dr.list`, `insight.det.get`, `insight.evt.get`, `investigation.get`, `investigation.set`, `ext.request`, `ext.list`, `org_notes.read`, `sop.get`, `sop.get.mtd`, `ai_agent.operate`). +3. **Anthropic secret staging** — captures or stages the Anthropic key into a [Hive Secret](../../7-administration/config-hive/secrets.md). +4. **Agent hive sync** — pushes the reviewer manifest (`ai_agent` record) and its trigger rule (`dr-general` record) into the org. +5. **Verification** — reads the resulting hive records back to confirm the deploy succeeded and reports the agent identifier for follow-up. + +The skill does not deploy the framework's full rule baseline. To do that as a follow-up step, use [`compliance-baseline-deploy`](#compliance-baseline-deploy). + +See [Case-Reviewer Agent](case-reviewer-agent.md) for the runtime behavior of the deployed agent. + +## `compliance-baseline-deploy` + +Deploy the FULL recommended rule baseline for a compliance framework — every D&R rule, FIM rule, artifact-collection rule, and exfil rule defined in the framework's implementation document. Defaults to a dry-run plan; `--apply` is required to actually write to the organization. Idempotent: rules already present under the same name are skipped. + +### Syntax + +```text +/lc-compliance:compliance-baseline-deploy [--oid ] [--apply] [--overwrite] [--kinds ] +``` + +### Arguments + +| Argument | Required | Notes | +|---|---|---| +| `` | Yes | Framework shorthand. | +| `--oid ` | No | Target organization UUID. Defaults to the CLI's currently-selected org. | +| `--apply` | No | Required to leave dry-run mode and write rules to the org. Without this flag, the skill prints the deployment plan and exits. | +| `--overwrite` | No | Replace rules already deployed under the same name with the bundled definitions. Without this flag, existing rules are skipped (idempotent). | +| `--kinds ` | No | Comma-separated subset of rule kinds to deploy. Valid values: `dr`, `fim`, `artifact`, `exfil`. Defaults to all four. | + +### Typical usage + +A two-pass workflow is recommended: + +```text +# First pass — preview the deployment plan +/lc-compliance:compliance-baseline-deploy pci-dss --oid + +# Review the plan with stakeholders, then apply +/lc-compliance:compliance-baseline-deploy pci-dss --oid --apply +``` + +For partial deployments (e.g., only file-integrity rules, deferring D&R rules until after a SOC review): + +```text +/lc-compliance:compliance-baseline-deploy pci-dss --oid --apply --kinds fim +``` + +To re-sync a previously-deployed baseline after a plugin update, picking up only new rules: + +```text +/lc-compliance:compliance-baseline-deploy pci-dss --oid --apply +``` + +To force-replace existing rules with updated definitions: + +```text +/lc-compliance:compliance-baseline-deploy pci-dss --oid --apply --overwrite +``` + +### What it does not do + +`compliance-baseline-deploy` does not: + +- Deploy the case-reviewer agent. Use [`compliance-deploy`](#compliance-deploy) for that. +- Subscribe to extensions. If `ext-integrity` (file-integrity monitoring) or `ext-cases` (case management) are not subscribed, the skill reports the dependency and prompts you to subscribe before continuing. +- Tag sensors. In-scope-sensor tagging (e.g., `cde` for PCI) is a separate operational decision that the skill does not make for you. See [Sensor Tags](../../2-sensors-deployment/sensor-tags.md). + +## Permission and credential model + +All four skills inherit their LimaCharlie credentials from your existing CLI session — there is no separate authentication step for the plugin. The skills shell out to the `limacharlie` CLI for org operations, which uses the same API key resolution as your interactive CLI work. + +For the case-reviewer agent deployed by `compliance-deploy`, a dedicated scoped API key is created inside the target organization (not shared with your interactive CLI key). The agent uses that scoped key plus an Anthropic secret to operate; see [Case-Reviewer Agent](case-reviewer-agent.md#permissions). + +## See also + +- [Frameworks](frameworks.md) — per-framework citation formats and recommended scope tags +- [Case-Reviewer Agent](case-reviewer-agent.md) — runtime behavior of the deployed reviewer +- [Gap Analysis](gap-analysis.md) — how to read and act on `compliance-gap` output +- [Hive Secrets](../../7-administration/config-hive/secrets.md) — where the Anthropic and LC API keys are stored diff --git a/docs/9-ai-sessions/dr-sessions.md b/docs/9-ai-sessions/dr-sessions.md index 51d6feb91..f318878be 100644 --- a/docs/9-ai-sessions/dr-sessions.md +++ b/docs/9-ai-sessions/dr-sessions.md @@ -566,3 +566,10 @@ This approach keeps D&R rules clean and lets you update the agent's behavior (pr - Review the prompt for ambiguity - Check that `allowed_tools` includes necessary tools - Verify `denied_tools` isn't blocking required capabilities + +## See Also + +- [Compliance Case-Reviewer Agent](compliance/case-reviewer-agent.md) -- A production example of a D&R-driven session: classifies every new case against framework control citations on `case_created` events. Useful as a reference for prompt structure, scope-check patterns, debounce keys, and case-write workflows. +- [Tool Permissions & Profiles](tool-permissions.md) -- Configure `allowed_tools` / `denied_tools` for D&R sessions. +- [Runner Environment](runner-environment.md) -- What's pre-installed in the session container. +- [Alternative AI Providers](alternative-providers.md) -- Route through AWS Bedrock or Google Cloud Vertex AI instead of Anthropic direct. diff --git a/docs/9-ai-sessions/index.md b/docs/9-ai-sessions/index.md index 29f1f635f..45b3090cb 100644 --- a/docs/9-ai-sessions/index.md +++ b/docs/9-ai-sessions/index.md @@ -14,6 +14,7 @@ Automatically spawn AI sessions in response to detections, events, or any condit - **Threat hunting**: Automatically investigate suspicious activity patterns - **Enrichment**: Use Claude to correlate data from multiple sources - **Response automation**: Generate recommendations or take automated actions +- **Compliance classification**: Classify in-scope cases against framework controls (PCI DSS, HIPAA, CMMC, SOC 2, NIST 800-53, ISO 27001, CIS v8) and write audit-grade documentation directly into the case record. See [Compliance](compliance/index.md). [Learn more about D&R-Driven Sessions](dr-sessions.md) @@ -89,6 +90,7 @@ respond: - [AI Skills](skills.md) - Reusable Claude Code skill definitions stored in your org - [AI Memory](memory.md) - Per-agent persistent memory with partial-merge writes - [API Reference](api-reference.md) - REST API and WebSocket protocol +- [Compliance](compliance/index.md) - The `lc-compliance` Claude Code plugin: per-framework case-reviewer agents (D&R-driven) plus four interactive skills for control lookups, gap analysis, and guided deploy ## Billing diff --git a/mkdocs.yml b/mkdocs.yml index 05de025b0..079a9e082 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -533,6 +533,13 @@ nav: - Command Line Interface: 9-ai-sessions/cli.md - Alternative Providers: 9-ai-sessions/alternative-providers.md - API Reference: 9-ai-sessions/api-reference.md + - Compliance: + - Overview: 9-ai-sessions/compliance/index.md + - Installation: 9-ai-sessions/compliance/installation.md + - Frameworks: 9-ai-sessions/compliance/frameworks.md + - Skills Reference: 9-ai-sessions/compliance/skills.md + - Case-Reviewer Agent: 9-ai-sessions/compliance/case-reviewer-agent.md + - Gap Analysis: 9-ai-sessions/compliance/gap-analysis.md - Release Notes: - Overview: 10-release-notes/index.md