@waratahlabs/canopy 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waratah Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# Canopy
+
+**Threat model your agentic AI systems. No API key required.**
+
+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.
+
+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.
+
+```bash
+npm install -g @waratahlabs/canopy
+```
+
+Or run it without installing:
+
+```bash
+npx @waratahlabs/canopy schema
+```
+
+---
+
+## Getting started
+
+### 1. Get the input shape
+
+```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": []
+}
+```
+
+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
+```
+
+```
+✓ 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.
+
+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
+
+### Assess agent definitions
+
+```typescript
+import { assessWorkflow } from "@waratahlabs/canopy";
+import type { AgentDefinition } from "@waratahlabs/canopy";
+
+const agents: AgentDefinition[] = [
+  {
+    id: "agent-001",
+    name: "Mortgage Assistant",
+    model: "claude-sonnet-4-6",
+    systemPrompt: "You are a mortgage application assistant...",
+    tools: [
+      { name: "retrieve_document", description: "Fetch a stored document by ID", dangerous: false },
+      { name: "credit_check", description: "Query credit bureau API", dangerous: true },
+    ],
+    permissions: ["read:applications", "write:notes"],
+    deploymentContext: "FinancialServices",
+    modelComplexity: "Moderate",
+    mitigationMultiplier: 1.1,
+    finetuned: false,
+    dependencies: ["document-store", "credit-api"],
+    secretManagement: "AWS Secrets Manager",
+    deployment: "AWS ECS Fargate",
+  },
+];
+
+const tcFormat = await assessWorkflow({
+  input: { type: "agents", agents },
+  applicationName: "Mortgage Platform",
+});
+```
+
+### Input adapters
+
+Canopy can derive `AgentDefinition[]` from systems you already run:
+
+```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 });
+
+// Live OpenClaw install — reads ~/.openclaw/openclaw.json and workspace/skills/
+import { parseOpenClawConfig } from "@waratahlabs/canopy";
+const { agents, handoffs, undeclaredSkills } = parseOpenClawConfig();
+```
+
+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
+
+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.
+
+```typescript
+import { assessWorkflow, parseLangfuseTraces, loadOverlaysFromYaml } from "@waratahlabs/canopy";
+
+const overlays = loadOverlaysFromYaml("./langfuse-overlay.yaml");
+const { agents, handoffs } = await parseLangfuseTraces(
+  {
+    host: process.env.LANGFUSE_HOST!,
+    secretKey: process.env.LANGFUSE_SECRET_KEY!,
+    publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+    limit: 100,
+  },
+  overlays,
+);
+```
+
+Trace metadata only — no prompt or completion content leaves your environment. No Langfuse SDK required; the adapter uses `fetch` with HTTP Basic auth.
+
+---
+
+## Model-inferred severity
+
+For richer threat prose, wire in a `BatchProvider`. Note this trades reproducibility for reasoning — the artifact will be stamped `scoring-mode: model`.
+
+```typescript
+import { assessWorkflow, createBatchProvider } from "@waratahlabs/canopy";
+
+// Anthropic Messages Batches
+await assessWorkflow({
+  input: { type: "agents", agents },
+  batchProvider: createBatchProvider({ type: "anthropic", model: "claude-haiku-4-5-20251001" }),
+});
+
+// Amazon Bedrock Batch Inference
+await assessWorkflow({
+  input: { type: "agents", agents },
+  batchProvider: createBatchProvider({
+    type: "bedrock",
+    region: "us-east-1",
+    s3InputUri: "s3://my-bucket/canopy-input/",
+    s3OutputUri: "s3://my-bucket/canopy-output/",
+  }),
+});
+
+// Ollama — local or cloud
+await assessWorkflow({
+  input: { type: "agents", agents },
+  batchProvider: createBatchProvider({ type: "ollama", model: "llama3.2" }),
+});
+```
+
+Custom backends implement one interface:
+
+```typescript
+import type { BatchProvider } from "@waratahlabs/canopy";
+
+const myProvider: BatchProvider = {
+  name: "my-provider",
+  async runBatch(agents, options) {
+    // return MetricAssessmentResponse[]
+  },
+};
+```
+
+**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.
+
+---
+
+## CLI reference
+
+```
+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
+```
+
+---
+
+## Standards and sources
+
+**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) — 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 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** — 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)
+
+**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)
+
+**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** — `--diagram` emits an architecture model alongside the threat model: agents, tools, data stores, handoff relationships, dangerous tools highlighted. [likec4.dev](https://likec4.dev)
+
+---
+
+## Contributing
+
+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.
+
+Security issues: please use private disclosure rather than a public issue — see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — Waratah Labs

package/SKILL.md

@@ -0,0 +1,97 @@
+# Canopy — AI Threat Modelling Skill
+
+Use this skill to generate a multi-framework threat model for any agentic AI system in the current codebase. Produces a `.tc.json` file openable in AWS Threat Composer and a LikeC4 architecture diagram.
+
+## When to invoke
+
+- User asks to "threat model", "assess", or "generate a security assessment" for agents in the codebase
+- A new agent, tool, or handoff is added to the system
+- Preparing for a security review, compliance audit, or workshop
+- CI pipeline needs a threat model artifact
+
+## How to invoke
+
+### Step 1 — get the input schema
+
+```bash
+bunx @waratahlabs/canopy schema
+```
+
+This prints the `AgentDefinition` JSON schema and a complete example. Read it before constructing input.
+
+### Step 2 — read the codebase and construct input JSON
+
+Read the agent source files (system prompts, tool definitions, environment config, docker-compose or k8s manifests for secrets/deployment context). Construct a `canopy-input.json` matching the schema:
+
+```json
+{
+  "applicationName": "My System",
+  "agents": [ ...AgentDefinition[] ],
+  "handoffs": [ ...HandoffEdge[] ]
+}
+```
+
+**Key fields to get right:**
+- `tools[].dangerous` — mark any tool that can exfiltrate data, execute SQL/shell, write files, or call external APIs as `true`. This drives the AIVSS MR/AA/DC metrics.
+- `secretManagement` — be specific. "env vars, no rotation" scores differently from "Vault, 24h TTL".
+- `deploymentContext` — use `FinancialServices` for fintech/banking, `Healthcare` for health data, `General` for everything else. Drives AIVSS weight profiles.
+- `mitigationMultiplier` — start at `1.0` (no mitigations). Reduce toward `0.5` only if guardrails, prompt shields, or tool-call validation are demonstrably deployed.
+- `handoffs` — every agent-to-agent message passing edge is a potential context-injection surface. Include all of them.
+
+### Step 3 — run the assessment
+
+```bash
+bunx @waratahlabs/canopy assess \
+  --input canopy-input.json \
+  --deterministic \
+  --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.
+
+### Step 4 — augment with your own reasoning (optional but recommended)
+
+Read the generated `threat-model.tc.json` alongside the reference examples in `demo/data/`:
+
+```
+demo/data/openclaw-demo.tc.json            — personal AI assistant threat model
+demo/data/openclaw-nemoclaw-demo.tc.json   — sandboxed vs baseline comparison
+```
+
+Use these as few-shot references to understand threat statement quality and depth. Then augment the generated output with your own analysis:
+
+- **Slot-fill prose** — replace stub `threatSource` / `threatAction` / `threatImpact` fields with context-specific language derived from reading the actual agent code (system prompt wording, tool descriptions, deployment topology)
+- **Additional threats** — reason about threats the AIVSS/ATLAS engine doesn't surface: business logic abuse, data exfiltration paths specific to this system's data model, trust boundary violations between services you observed in the codebase
+- **MEAID ethical findings** — for agents with `EI` or `GV` metric findings, articulate the specific ethical risk in terms of this system: who is affected, what accountability gap exists, whether BAU misappropriation is plausible given the agent's permissions
+- **Severity uplift** — if you have strong evidence a finding should be Critical or High (e.g. a `dangerous: true` tool with no guardrails handling PII), note it; the mock severity is Medium across the board
+
+When adding threats, match the existing TC schema shape exactly — copy a threat entry from the output and modify it. The `id` field must be a fresh UUID.
+
+### Step 5 — report findings
+
+After running, read the output and summarise:
+- Total threats by severity (Critical / High / Medium / Low)
+- Top 3 ATLAS techniques by frequency
+- Any `dangerous: true` tools and their associated MR/AA findings
+- MEAID ethical/compliance findings on `EI` and `GV` metrics (audience: legal/ethics teams)
+- Handoff threats (AML.T0080.000) — one per agent-to-agent edge
+
+Tell the user where the files were written and how to open them:
+```
+Threat Composer: open threat-model.tc.json at https://awslabs.github.io/threat-composer
+Architecture:    npx likec4 serve <diagram>.c4
+```
+
+## What Canopy produces
+
+Each threat is annotated with:
+- `aivss-metric` + `aivss-score` — OWASP AIVSS V4 scoring
+- `atlas-technique-id` — MITRE ATLAS adversary TTP
+- `acsc-risk-id` — ASD/ACSC Five Eyes agentic AI risk category
+- `dstg-meaid-risk-id` — DSTG MEAID ethical/compliance risk (where applicable)
+- `agent-name`, `deployment-context`, `priority`
+
+## 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.