@waratahlabs/canopy 0.5.0 → 0.6.0

package/README.md

@@ -1,153 +1,39 @@
-# Canopy
+# Canopy — `@waratahlabs/canopy`
 
-**Threat model your agentic AI systems. No API key required.**
+Multi-framework threat modelling for agentic AI systems. Point the library at an agent definition, an N8N workflow, or a live OpenClaw install. It assesses the system across OWASP AIVSS V4 (9 AI-specific metrics, 39 sub-categories), maps findings to MITRE ATLAS adversary TTPs, cross-references ASD/ACSC Five Eyes government guidance, and writes structured threat statements in AWS Threat Composer format (`.tc.json`).
 
-Canopy scores an agent system against [OWASP AIVSS V4](https://aivss.owasp.org), maps every finding to [MITRE ATLAS](https://atlas.mitre.org) adversary techniques, annotates it against six risk frameworks, and writes an [AWS Threat Composer](https://github.com/awslabs/threat-composer) `.tc.json` you can open, edit, and hand to your security team.
+## How the analysis works
 
-It runs offline, deterministically, with no credentials — so you can try it on your own system in about a minute and get a number you can actually defend.
+![Canopy analysis pipeline](docs/diagrams/pipeline.png)
 
-```bash
-npm install -g @waratahlabs/canopy
-```
-
-Or run it without installing:
+The pipeline diagram is generated from [`docs/architecture.c4`](docs/architecture.c4) — a live LikeC4 model of the library itself. To explore it interactively or export updated PNGs:
 
 ```bash
-npx @waratahlabs/canopy schema
+bunx likec4 serve docs/architecture.c4
+bunx likec4 export png -o docs/diagrams/ docs/
 ```
 
----
+**Scoring layer** — the pluggable `BatchProvider` routes metric assessments to whichever inference backend you have available:
 
-## Getting started
+![BatchProvider scoring layer](docs/diagrams/batch-providers.png)
 
-### 1. Get the input shape
+## Quick start
 
 ```bash
-npx @waratahlabs/canopy schema > canopy-schema.json
-```
-
-This prints the `AgentDefinition` JSON schema plus a worked example. One entry per agent or autonomous process in your system.
-
-### 2. Describe your system
-
-Create `my-agents.json`. Describe what your agent actually is — what model, what tools, what it's allowed to touch:
-
-```json
-{
-  "applicationName": "Sales Data Pipeline",
-  "agents": [
-    {
-      "id": "reporting-agent-01",
-      "name": "reporting-agent",
-      "model": "claude-sonnet-4-6",
-      "systemPrompt": "Retrieve sales data via the reporting API. Fall back to direct DB query only if the API is unavailable.",
-      "tools": [
-        { "name": "call_reporting_api", "description": "Fetch sales data via the authorised HTTP API.", "dangerous": false },
-        { "name": "query_database", "description": "Execute SQL directly against the sales database.", "dangerous": true }
-      ],
-      "permissions": ["read:reporting_api", "read:postgres_salesdb", "write:audit_log"],
-      "deploymentContext": "FinancialServices",
-      "modelComplexity": "Simple",
-      "mitigationMultiplier": 1.0,
-      "finetuned": false,
-      "dependencies": ["reporting-api:8080", "postgres:5432"],
-      "secretManagement": "Environment variables, no rotation.",
-      "deployment": "Docker container",
-      "autonomyLevel": "semi-autonomous",
-      "objectives": ["Retrieve monthly sales data"],
-      "externalApiCount": 1
-    }
-  ],
-  "handoffs": []
-}
-```
+bun install
+bun run build
 
-The fields that move the score most: `tools[].dangerous`, `permissions`, `autonomyLevel`, `deploymentContext`, and `secretManagement`. Be honest about them — an assessment of an idealised system tells you nothing.
-
-### 3. Assess it
-
-```bash
-npx @waratahlabs/canopy assess --input my-agents.json --deterministic --out threat-model.tc.json
-```
+# Run the demo (writes output/demo-threat-model.tc.json)
+# Falls back to mock severity if no provider credentials are set
+bun run threat-model
 
+# Serve the web demo
+bun run demo   # http://localhost:3000
 ```
-✓ 35 threats · 29 mitigations → threat-model.tc.json
-```
-
-No API key. No account. No network call. Open the result at [threat-composer.awslabs.dev](https://awslabs.github.io/threat-composer/).
-
-### 4. Gate it in CI
-
-```bash
-canopy assess --input my-agents.json --deterministic --diff
-```
-
-Saves a baseline and diffs against the previous run. **Exits non-zero when severities regress**, so a change that makes your agent riskier fails the build.
-
----
-
-## Running inside a coding agent
-
-Canopy can use the LLM you're already talking to as its inference engine — no API key, no subprocess, no extra model call.
-
-```bash
-canopy assess --input my-agents.json --harness --out threat-model.tc.json
-```
-
-The first run writes the assessment prompts to `canopy-batch-requests.json` and exits with instructions. Your coding agent (Claude Code, Cursor, or anything driving a shell) reads that file, answers each prompt with its own reasoning, writes `canopy-batch-responses.json`, and you re-run. Two runs, one round trip, zero network calls Canopy has to authenticate.
-
-`SKILL.md` in this package is a ready-made skill file for that workflow — point your agent at it.
-
----
-
-## Scoring modes — know where your number came from
-
-A score you cannot reproduce is not evidence. Canopy always records which mode produced a finding, stamped on every threat as `scoring-mode` and in the artifact's audit trail.
-
-| Mode | Flag | Reproducible | Credentials | Use it for |
-|---|---|---|---|---|
-| **Deterministic** | `--deterministic` | **Yes** — byte-identical across runs and machines | None | CI gating, audit trails, anything you have to defend |
-| **Harness** | `--harness` | No — depends on the driving model | None | Exploring a new system interactively |
-| **Model** | *(default with `ANTHROPIC_API_KEY`)* | No — varies with model version | Provider key | Richer reasoning on threat prose |
 
-Deterministic mode is a pure function of the agent definition. Every rule is readable in [`src/aivss/scoring/heuristic-scorer.ts`](src/aivss/scoring/heuristic-scorer.ts) — you can trace any severity back to the condition that produced it, which is the property CVSS vectors and OpenSSF Scorecard checks earn their trust from.
+Open `output/demo-threat-model.tc.json` in [AWS Threat Composer](https://github.com/awslabs/threat-composer).
 
-Changing emitted scores is treated as a breaking change requiring a major version bump. Your baselines stay meaningful.
-
----
-
-## Registered frameworks
-
-Assess once, map many — one assessment engine, findings annotated against every registered framework:
-
-| Framework | Risks | Type |
-|---|---|---|
-| ASD/ACSC — Careful Adoption of Agentic AI Services (Five Eyes, 2025) | 15 | security |
-| CSA AI Controls Matrix (AICM) | 32 | compliance |
-| DSTG — A Method for Ethical AI in Defence (MEAID) | 21 | ethical / compliance |
-| NIST AI Risk Management Framework 1.0 | 52 | compliance |
-| OWASP Top 10 for Agentic Applications 2026 | 10 | security |
-| NeMo Claw — Security Wrapper for OpenClaw | 5 | security |
-
-Adding a framework is one file plus one registration line — see [CONTRIBUTING.md](CONTRIBUTING.md). This table is asserted against the live registry by `src/references/registry-parity.test.ts`: a framework advertised here but not registered fails the build.
-
----
-
-## What you get
-
-Every threat in the `.tc.json` carries:
-
-- **Threat Composer slots** — `threatSource`, `prerequisites`, `threatAction`, `threatImpact`, `impactedGoal[]`, `impactedAssets[]`, `statement`
-- **AIVSS metadata** — metric code (MR/DS/EI/DC/AD/AA/LL/GV/CS), sub-category, severity, score
-- **ATLAS metadata** — technique ID (e.g. `AML.T0051`), technique name, tactic
-- **Framework annotations** — risk ID, category, and risk type from each registered framework
-- **Provenance** — `scoring-mode`, deployment context, and version stamps for Canopy, AIVSS, and both ATLAS version fields
-
-Agent-to-agent handoffs are surfaced as first-class threats (`AML.T0080.000` — implicit trust grants), because the trust boundary between two agents is where the interesting failures live.
-
----
-
-## Library usage
+## Usage
 
 ### Assess agent definitions
 
@@ -180,35 +66,31 @@ const tcFormat = await assessWorkflow({
   input: { type: "agents", agents },
   applicationName: "Mortgage Platform",
 });
-```
 
-### Input adapters
+await Bun.write("output/threat-model.tc.json", JSON.stringify(tcFormat, null, 2));
+```
 
-Canopy can derive `AgentDefinition[]` from systems you already run:
+### Assess an N8N workflow
 
 ```typescript
-// N8N workflow export
-await assessWorkflow({ input: { type: "n8n", workflow }, applicationName: "My Workflow" });
-
-// A2A agent cards — fetches /.well-known/agent.json and walks the delegation graph
-import { walkA2AGraph } from "@waratahlabs/canopy";
-const { agents, handoffs } = await walkA2AGraph({ urls: ["https://agent.example.com"], maxHops: 2 });
+import { assessWorkflow } from "@waratahlabs/canopy";
+import n8nWorkflow from "./my-workflow.json";
 
-// Live OpenClaw install — reads ~/.openclaw/openclaw.json and workspace/skills/
-import { parseOpenClawConfig } from "@waratahlabs/canopy";
-const { agents, handoffs, undeclaredSkills } = parseOpenClawConfig();
+const tcFormat = await assessWorkflow({
+  input: { type: "n8n", workflow: n8nWorkflow },
+  applicationName: "My Agent Workflow",
+});
 ```
 
-Where a system declares less than it can do, Canopy names the gap rather than papering over it — `undeclaredSkills` and `UNDECLARED_CAPABILITY_RISK` exist because a declared tool schema is not the same as actual behaviour.
-
-### Langfuse traces
+### Assess Langfuse traces (Tier 4 — runtime telemetry)
 
-Traces don't carry system prompts, tool declarations, or permissions, so you supply those through a config overlay — a YAML file mapping agent name patterns to the fields traces can't provide.
+Fetch live agent traces from a Langfuse instance and assess them against AIVSS V4. Because traces don't carry system prompts, tool declarations, or permissions, you supply those via a config overlay — a YAML file that maps agent name patterns to the fields traces can't provide.
 
 ```typescript
 import { assessWorkflow, parseLangfuseTraces, loadOverlaysFromYaml } from "@waratahlabs/canopy";
 
 const overlays = loadOverlaysFromYaml("./langfuse-overlay.yaml");
+
 const { agents, handoffs } = await parseLangfuseTraces(
   {
     host: process.env.LANGFUSE_HOST!,
@@ -218,44 +100,114 @@ const { agents, handoffs } = await parseLangfuseTraces(
   },
   overlays,
 );
+
+const tcFormat = await assessWorkflow({
+  input: { type: "agents", agents, handoffs },
+  applicationName: "My Agent System",
+});
 ```
 
-Trace metadata only — no prompt or completion content leaves your environment. No Langfuse SDK required; the adapter uses `fetch` with HTTP Basic auth.
+See [`src/examples/langfuse-overlay.example.yaml`](src/examples/langfuse-overlay.example.yaml) for a complete overlay template. The `agentNamePattern` field accepts a plain string (exact or substring match) or a `/regex/flags` literal.
+
+No `langfuse` SDK required — the adapter uses `fetch` with HTTP Basic auth directly.
+
+### Sample frontend (dev tool)
 
----
+`sample-fe/` is a Bun server + Vite React app that lets you point a browser at your Langfuse instance and see per-agent AIVSS scores in a local tab. It exists so you can iterate quickly on overlay configuration and verify assessments are landing correctly.
+
+> **It is not a deployment artefact.** Canopy is designed to integrate into existing observability stacks — Langfuse, Arize Phoenix, Datadog, or anything else — via the same adapter pattern, producing OWASP AIVSS-grounded findings wherever you already collect traces. The sample frontend is a debugging aid for validating that integration; your integration is the product.
+
+```bash
+cd sample-fe
+bun install
+cp .env.example .env   # fill in Langfuse host + keys
+bun run dev            # server on :3001, Vite on :5173
+```
 
-## Model-inferred severity
+See [`sample-fe/README.md`](sample-fe/README.md) for setup details.
 
-For richer threat prose, wire in a `BatchProvider`. Note this trades reproducibility for reasoning — the artifact will be stamped `scoring-mode: model`.
+### Assess a live OpenClaw installation
 
 ```typescript
-import { assessWorkflow, createBatchProvider } from "@waratahlabs/canopy";
+import { assessWorkflow, parseOpenClawConfig } from "@waratahlabs/canopy";
 
-// Anthropic Messages Batches
-await assessWorkflow({
-  input: { type: "agents", agents },
-  batchProvider: createBatchProvider({ type: "anthropic", model: "claude-haiku-4-5-20251001" }),
+// Reads ~/.openclaw/openclaw.json and workspace/skills/
+const { agents, handoffs, undeclaredSkills } = parseOpenClawConfig();
+
+if (undeclaredSkills.length > 0) {
+  console.warn("Skills with unknown capabilities:", undeclaredSkills);
+}
+
+const tcFormat = await assessWorkflow({
+  input: { type: "agents", agents, handoffs },
+  applicationName: "My OpenClaw Assistant",
 });
+```
+
+Config path resolution order: explicit option → `OPENCLAW_CONFIG_PATH` env → `OPENCLAW_STATE_DIR/openclaw.json` → `~/.openclaw/openclaw.json` → `~/.clawdbot/clawdbot.json`.
+
+## Batch providers — real severity scoring
+
+By default Canopy mocks every sub-category severity as Medium. Wire in a `BatchProvider` for real AI-assessed severity.
+
+### Amazon Bedrock Batch Inference
+
+```typescript
+import { assessWorkflow, createBatchProvider } from "@waratahlabs/canopy";
 
-// Amazon Bedrock Batch Inference
-await assessWorkflow({
+const tcFormat = await assessWorkflow({
   input: { type: "agents", agents },
   batchProvider: createBatchProvider({
     type: "bedrock",
     region: "us-east-1",
+    // modelId defaults to "us.amazon.nova-2-lite-v1:0"
     s3InputUri: "s3://my-bucket/canopy-input/",
     s3OutputUri: "s3://my-bucket/canopy-output/",
   }),
+  onBatchProgress: (status) => console.log(status),
 });
+```
 
-// Ollama — local or cloud
-await assessWorkflow({
+### Anthropic Messages Batches
+
+```typescript
+const tcFormat = await assessWorkflow({
   input: { type: "agents", agents },
-  batchProvider: createBatchProvider({ type: "ollama", model: "llama3.2" }),
+  batchProvider: createBatchProvider({
+    type: "anthropic",
+    // apiKey defaults to ANTHROPIC_API_KEY env var
+    model: "claude-haiku-4-5-20251001",
+  }),
 });
 ```
 
-Custom backends implement one interface:
+### Ollama (local or cloud)
+
+```typescript
+// Local
+const tcFormat = await assessWorkflow({
+  input: { type: "agents", agents },
+  batchProvider: createBatchProvider({
+    type: "ollama",
+    model: "llama3.2",
+    // baseUrl defaults to http://localhost:11434
+    concurrency: 2,
+  }),
+});
+
+// Ollama cloud (ollama.com)
+const tcFormat = await assessWorkflow({
+  input: { type: "agents", agents },
+  batchProvider: createBatchProvider({
+    type: "ollama",
+    model: "llama3.3:70b",
+    baseUrl: "https://ollama.com/api",
+    apiKey: process.env.OLLAMA_API_KEY,
+  }),
+});
+```
+
+Custom providers implement one interface:
 
 ```typescript
 import type { BatchProvider } from "@waratahlabs/canopy";
@@ -268,55 +220,152 @@ const myProvider: BatchProvider = {
 };
 ```
 
-**Choosing a local model:** `runModelEval()` runs several Ollama models over the same agent set and reports parse success rate, finding coverage by metric, pairwise agreement, and a written verdict — worth doing before committing to a full batch run.
+## Model evaluation
+
+`runModelEval()` runs N Ollama models against the same agent set and produces a comparison report — useful for deciding which open-source models generate meaningful AIVSS assessments before committing to a full batch run.
+
+```typescript
+import { runModelEval, createBatchProvider } from "@waratahlabs/canopy";
+
+const report = await runModelEval({
+  agents,
+  models: [
+    createBatchProvider({ type: "ollama", model: "llama3.2" }),
+    createBatchProvider({ type: "ollama", model: "qwen2.5:14b" }),
+    createBatchProvider({ type: "ollama", model: "mistral-nemo" }),
+  ],
+});
+
+console.log(report.summary);
+// → "qwen2.5:14b: recommended (87% parse success, 0.76 pairwise agreement)"
+// → "llama3.2: conditional (61% parse success)"
+// → "mistral-nemo: not-recommended (low finding coverage on AA/AD metrics)"
+```
+
+Report includes: per-model parse success rate, finding coverage by metric, mean severity, pairwise agreement matrix, per-metric outlier detection, and written verdict with reasons.
 
----
+## Web demo
 
-## CLI reference
+```bash
+bun run demo   # http://localhost:3000
+```
+
+The demo explorer loads a pre-generated OpenClaw threat model with a comparison toggle for OpenClaw + NeMo Claw. Toggle between them to see per-threat severity deltas, NeMo Claw control annotations (what each isolation layer actually addresses), and a Jarkas layer breakdown of what the kernel-level sandbox handles — and what it doesn't.
+
+NeMo Claw is NVIDIA's kernel-level security sandbox for OpenClaw (Landlock + seccomp + network namespaces). The comparison illustrates the Jarkas taxonomy in action:
+
+| Jarkas layer | NeMo Claw impact |
+|---|---|
+| L4 Host | Largely mitigated — host FS read-only, `openclaw.json` inaccessible |
+| L3 Engine | Largely mitigated — seccomp blocks dangerous syscalls |
+| L2 Application | Partially mitigated — egress allowlist + Privacy Router reduce blast radius |
+| L1 Orchestration | **Unchanged** — cron persistence and prompt injection operate inside the sandbox |
+
+## Output format
+
+Every threat in the `.tc.json` carries:
+
+- **Threat Composer slots**: `threatSource`, `prerequisites`, `threatAction`, `threatImpact`, `impactedGoal[]`, `impactedAssets[]`, `statement`
+- **AIVSS metadata**: metric code (MR/DS/EI/DC/AD/AA/LL/GV/CS), sub-category, severity
+- **ATLAS metadata**: technique ID (e.g. `AML.T0051`), technique name, tactic
+- **ASD/ACSC metadata**: risk family and risk ID from the Five Eyes joint advisory
+- **Jarkas layer**: container security layer implicated (when applicable)
+- **Deployment context**: AIVSS weight profile used for scoring
+- **Version stamps**: `canopy-version`, `aivss-version`, `atlas-version`, `acsc-version`, `generated-at`
+
+Agent-to-agent handoffs are automatically surfaced as first-class threats (`AML.T0080.000` — implicit trust grants).
+
+## Project structure
 
 ```
-canopy assess [options]
-  --input <file>     Input JSON (default: stdin)
-  --out <file>       Output .tc.json (default: stdout)
-  --deterministic    Heuristic scorer — reproducible, no credentials
-  --harness          Let the calling LLM agent answer the assessment prompts
-  --diagram          Also write a LikeC4 architecture diagram
-  --save             Save a baseline snapshot
-  --diff             Save and diff against the previous run; exit 1 on regressions
-
-canopy a2a-assess    Walk an A2A delegation graph and assess it
-canopy schema        Print the AgentDefinition input schema
-canopy diff          Compare the two most recent baselines
-canopy batch-submit  Submit a provider batch job for model-inferred severity
-canopy batch-fetch   Collect a completed batch job into a .tc.json
-canopy demo          Serve the interactive threat model explorer
+src/
+├── aivss/
+│   ├── metrics/           — 9 metric prompt builders (MR DS EI DC AD AA LL GV CS)
+│   ├── scoring/           — V4 formula, 7 deployment-context weight profiles, unit tests
+│   ├── atlas/             — ATLAS loader, sub-category coverage matrix (39 entries)
+│   ├── batch/             — Prompt → batch request builders
+│   └── prompts/           — Base system prompt, prompt composer
+├── batch/
+│   ├── providers/         — BedrockBatchProvider, AnthropicBatchProvider, OllamaBatchProvider
+│   │   └── index.ts       — createBatchProvider() factory
+│   ├── bedrock-batch-runner.ts
+│   └── response-parser.ts
+├── adapters/
+│   ├── n8n.ts             — N8N workflow → AgentDefinition[] + HandoffEdge[]
+│   └── openclaw.ts        — OpenClaw config → AgentDefinition[] + HandoffEdge[]
+├── providers/             — InferenceProvider (slot filling): Bedrock, Anthropic
+├── output/
+│   ├── slot-filler.ts     — fillThreatSlots() — per-threat AI inference
+│   ├── tc-assembler.ts    — assembleTCFormat() — DataExchangeFormat builder
+│   ├── tc-types.ts        — DataExchangeFormat type definitions
+│   └── likec4-generator.ts — Architecture diagram generator
+├── references/            — Framework adapters: ACSC, Jarkas, MEAID, NIST AI RMF,
+│   │                        OWASP Agentic Top 10, NeMo Claw
+│   └── registry.ts        — FrameworkAdapter / FrameworkRisk interfaces
+├── tools/
+│   └── model-eval.ts      — runModelEval() — cross-model comparison
+└── index.ts               — assessWorkflow() public entry point
+
+vendor/
+├── owasp-aivss/           — OWASP AIVSS V4 reference (cloned)
+├── atlas-data/            — MITRE ATLAS submodule (provenance/license; dist/ATLAS.yaml is deprecated format)
+└── atlas-release/         — MITRE ATLAS format-6 data (ATLAS-2026.07.yaml, downloaded release asset — see its README)
+
+demo/
+├── index.html             — Static threat model explorer (baseline + NeMo Claw comparison)
+└── data/
+    ├── openclaw-demo.tc.json            — Pre-generated OpenClaw threat model
+    └── openclaw-nemoclaw-demo.tc.json   — NeMo Claw comparison with severity deltas
 ```
 
----
+## References
 
-## Standards and sources
+### OWASP AIVSS v0.8
+Scoring methodology, 9 AI-specific metrics, 39 sub-categories, V4 formula, 7 deployment-context weight profiles.
+- [aivss.owasp.org](https://aivss.owasp.org)
 
-**OWASP AIVSS v0.8** — scoring methodology: 9 AI-specific metrics, 39 sub-categories, the V4 formula, and 7 deployment-context weight profiles. [aivss.owasp.org](https://aivss.owasp.org)
+### MITRE ATLAS™ (format-6.0.0, content 2026.07)
+Adversary tactics, techniques, and mitigations for ML systems. ATLAS techniques are injected into metric prompts as test specifications — each threat is grounded in documented attack patterns. 16 tactics, 178 techniques (101 parent + 77 sub-techniques), 37 mitigations, 68 case studies. MITRE ships monthly calendar-versioned content releases (`YYYY.MM.N`) decoupled from rarer semver schema (`format-version`) bumps.
+- [atlas.mitre.org](https://atlas.mitre.org)
 
-**MITRE ATLAS™** (format-6.0.0, content 2026.07) — 16 tactics, 178 technique-level items, 37 mitigations, 68 case studies. ATLAS techniques are injected into metric prompts as test specifications, so each threat is grounded in a documented attack pattern rather than asserted. MITRE ships monthly calendar-versioned content releases decoupled from rarer schema bumps; Canopy tracks both fields separately and pins deliberately. [atlas.mitre.org](https://atlas.mitre.org)
+### ASD/ACSC: Careful Adoption of Agentic AI Services (2025)
+Joint advisory from ASD/ACSC, CISA, NSA, Cyber Centre (CA), NCSC-NZ, and NCSC-UK. Five risk families cross-referenced to AIVSS metrics and ATLAS techniques.
+- [cyber.gov.au](https://www.cyber.gov.au/business-government/secure-design/artificial-intelligence/careful-adoption-of-agentic-ai-services)
 
-**ASD/ACSC — Careful adoption of agentic AI services** (2025) — joint guidance from ASD/ACSC, CISA, NSA, Cyber Centre (CA), NCSC-NZ, and NCSC-UK. Five risk families cross-referenced to AIVSS metrics and ATLAS techniques. [cyber.gov.au](https://www.cyber.gov.au/business-government/secure-design/artificial-intelligence/careful-adoption-of-agentic-ai-services)
+### CSA AI Controls Matrix (AICM) v1.1.1 (2026)
+Cloud Security Alliance's AI-specific control extension to the Cloud Controls Matrix — 247 controls across 18 domains. Canopy maps the 31 controls CSA tags "AI-Specific" (agent boundaries, sandboxing, data poisoning, model hardening, explainability, human oversight) to AIVSS metrics and ATLAS techniques; the remaining 216 "Cloud & AI Related"/"Cloud-Specific" controls are general cloud-security hygiene outside this adapter's scope.
+- [cloudsecurityalliance.org/artifacts/ai-controls-matrix](https://cloudsecurityalliance.org/artifacts/ai-controls-matrix)
+- Machine-readable bundle (JSON/YAML/OSCAL, generated 2026-07-22) — [cloudsecurityalliance.org/artifacts/aicm-machine-readable-bundle-json-yaml-oscal](https://cloudsecurityalliance.org/artifacts/aicm-machine-readable-bundle-json-yaml-oscal)
 
-**CSA AI Controls Matrix (AICM) v1.1.1** — Canopy maps the 31 controls CSA tags "AI-Specific" (agent boundaries, sandboxing, data poisoning, model hardening, explainability, human oversight); the remaining "Cloud & AI Related" controls are general cloud hygiene outside this adapter's scope. [cloudsecurityalliance.org](https://cloudsecurityalliance.org/artifacts/ai-controls-matrix)
+### Jarkas et al. — Container Security Taxonomy (2025)
+200+ container CVEs classified into 47 exploit types across 5 architectural layers (L1–L5). Applied when `deployment` indicates a container runtime.
+- Jarkas, O., Ko, R. K. L., Dong, N., and Mahmud, R. *A Container Security Survey.* ACM Computing Surveys, vol. 57, no. 7, 2025. https://doi.org/10.1145/3715001
 
-**DSTG — A Method for Ethical AI in Defence (MEAID)** — ethical and compliance risk that the CIA triad does not capture. Staff using AI outside its sanctioned purpose is not a confidentiality breach, but it is a real risk; MEAID surfaces that class. [dst.defence.gov.au](https://www.dst.defence.gov.au/publication/ethical-ai)
+### NeMo Claw (alpha-2026)
+NVIDIA's kernel-level security sandbox for OpenClaw. Canopy documents residual risks (L1/L2 Jarkas layers) and mitigated vectors (L3/L4) for baseline vs. sandboxed comparison.
+- [secondtalent.com — NeMo Claw vs OpenClaw](https://www.secondtalent.com/resources/nemoclaw-vs-openclaw/)
 
-**AWS Threat Composer** — the output format. `.tc.json` opens directly for collaborative modelling. [github.com/awslabs/threat-composer](https://github.com/awslabs/threat-composer)
+### LikeC4 — Architecture as Code
+Generated alongside every threat model — agents, tools, data stores, handoff relationships, dangerous tool highlighting.
+```bash
+npx likec4 serve output/my-system.c4
+npx likec4 export png -o docs/diagrams/ output/my-system.c4
+```
+- [likec4.dev](https://likec4.dev)
 
-**LikeC4** — `--diagram` emits an architecture model alongside the threat model: agents, tools, data stores, handoff relationships, dangerous tools highlighted. [likec4.dev](https://likec4.dev)
+### AWS Threat Composer
+Output format. `.tc.json` files open directly in Threat Composer for collaborative modelling.
+- [github.com/awslabs/threat-composer](https://github.com/awslabs/threat-composer)
 
----
+## Contributing — versioning and changelogs
 
-## Contributing
+This repo uses [Changesets](https://github.com/changesets/changesets) for version bumps and `CHANGELOG.md`. Every PR that changes the package needs a changeset:
 
-Framework adapters are the contribution most wanted — one file plus one registration line. See [CONTRIBUTING.md](CONTRIBUTING.md) for the `FrameworkAdapter` contract, the conventions, and the score-stability policy.
+```bash
+bunx changeset          # describe your change and pick a bump type (patch/minor/major)
+```
 
-Security issues: please use private disclosure rather than a public issue — see [SECURITY.md](SECURITY.md).
+`changeset-check.yml` fails the PR if one is missing (`bunx changeset add --empty` for changes that don't need a release, e.g. docs-only). Merging to `main` opens/updates a "Version Packages" PR (`changesets-release.yml`) that bumps `package.json` and writes `CHANGELOG.md`; merging *that* PR auto-tags the new version, which fires `publish.yml` (test → build → publish) — no manual step required.
 
 ## License
 

package/SKILL.md

@@ -43,12 +43,12 @@ Read the agent source files (system prompts, tool definitions, environment confi
 ```bash
 bunx @waratahlabs/canopy assess \
   --input canopy-input.json \
-  --deterministic \
+  --no-provider \
   --diagram \
   --out threat-model.tc.json
 ```
 
-`--deterministic` skips a separate LLM API call — the calling agent (you) is the intelligence. The AIVSS scoring and ATLAS technique mapping are deterministic; only the threat statement prose uses stub fills. The structural threat model is complete and accurate regardless.
+`--no-provider` skips a separate LLM API call — the calling agent (you) is the intelligence. The AIVSS scoring and ATLAS technique mapping are deterministic; only the threat statement prose uses stub fills. The structural threat model is complete and accurate regardless.
 
 ### Step 4 — augment with your own reasoning (optional but recommended)
 
@@ -57,6 +57,7 @@ Read the generated `threat-model.tc.json` alongside the reference examples in `d
 ```
 demo/data/openclaw-demo.tc.json            — personal AI assistant threat model
 demo/data/openclaw-nemoclaw-demo.tc.json   — sandboxed vs baseline comparison
+demo/data/insaider-threat-model.tc.json    — insider threat / credential abuse scenario
 ```
 
 Use these as few-shot references to understand threat statement quality and depth. Then augment the generated output with your own analysis:
@@ -92,6 +93,16 @@ Each threat is annotated with:
 - `dstg-meaid-risk-id` — DSTG MEAID ethical/compliance risk (where applicable)
 - `agent-name`, `deployment-context`, `priority`
 
+## Worked example — insAIder threat workshop
+
+The insAIder workshop has two agents: `operative-agent` (LangChain ReAct, `qwen3.5:4b`, direct DB access) and `supervisor-agent` (autonomous Redis pub/sub escalation trigger). The key threat is the supervisor injecting authorization-expansion language into the operative's task queue, causing it to use `query_database` instead of the authorised API path.
+
+Input highlights:
+- `operative.tools[query_database].dangerous = true` — drives MR and AA findings
+- `operative.secretManagement = "env vars, no rotation"` — drives DS findings  
+- `handoffs: [{ from: supervisor, to: operative }]` — generates AML.T0080.000 context-injection threat
+- `deploymentContext = "FinancialServices"` — applies the FinancialServices AIVSS weight profile
+
 ## Adding frameworks
 
 New risk frameworks are added by contributing to `src/references/` — one file per framework implementing `FrameworkAdapter`, registered in `src/references/index.ts`. No changes to the CLI or assembler required.