@connexum/agent-standards 0.0.0-stage → 0.1.0-beta.2

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @connexum/agent-standards
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standards coverage for any agent on any stack. On the first scan and every scan after, an agent is scored against:
+
+- **always:** OWASP LLM Top 10, OWASP Agentic Top 10, the My-CC runtime checks;
+- **installed:** every framework whose My-CC pack is bound to the agent (HIPAA, PCI DSS, GDPR, EU AI Act, Colorado AI Act, SOC 2, ISO/IEC 42001, NIST AI RMF): scored;
+- **recommended:** a framework that fits the agent's industry, data classes or regions but has no pack bound: documented with its controls, not scored;
+- **not applicable:** a framework that does not fit: omitted with the reason.
+
+Practice frameworks (agent identity and access, MCP server security) are My-CC checks with no pack: scored when they fit.
+
+One catalogue (`catalogue/catalogue.json`) drives this package and the Python twin (`connexum-agent-standards`); the same conformance cases run in both. Evidence is a map of facts the runtime supplies (`prompt.isolated`, `safe_harbor`, `kill_switch`, ...); a missing fact is **not checked**, never a pass.
+
+```ts
+import { scoreAgent, applicability, standardsLines } from '@connexum/agent-standards'
+const report = scoreAgent({ industry: 'healthcare', dataClasses: ['phi'], regions: ['us'], tools: ['ehr.read_note'], boundPacks: ['hipaa'] }, { safe_harbor: true, 'data.min_necessary': true })
+// report.score, report.frameworks[].pass/total, report.omitted[], report.evidenceMissing[]
+```
+
+End-state item D1 (any stack) and D3 (any agent): the scan that every stack runs. First consumer: the AOL spoke's Secure agent builder (CliniVantIQ); the catalogue replaces the spoke's local copy.
+
+## Which packs an agent needs (0.1.0-beta.2)
+
+`fleetFit(packs, agents)` grades every My-CC pack for every scanned agent, and every requirement in it:
+
+- **Sector from the scan.** `inferIndustry` reads the agent's purpose, tools, data classes and connections (or a declared industry). A legal agent never gets healthcare packs; a pharmacy agent never gets aerospace packs.
+- **Region.** A law applies only where the agent's people are (`us`, `us-ca`, `eu`, `uk`, ...).
+- **Required only with evidence.** A law is *required* only when the scan found on the agent what the law regulates (a requirement touches a capability the agent has: PHI, privileged material, parts, billing, research subjects, a device, cardholder or personal data, ...). A sector or region match without that evidence is *recommended*, with the reason. Standards and frameworks are recommendations.
+- **Per requirement.** Required, recommended or not needed for that agent; a requirement needing a capability the agent lacks is not needed, with the reason; My-CC's own rule enforcement wins where present (block = required, warn = recommended).
+- **Overlaps.** A requirement names the other fitted packs that cover the same control (minimum necessary, audit, consent, ...), so one control can satisfy several.
+- **Scanned only.** `scanned: false` marks packs no scanned agent needs.
+
+Rules and patterns: `catalogue/fit.json`, shared byte-for-byte with the Python twin.

package/catalogue/catalogue.json

@@ -0,0 +1,115 @@
+{
+  "version": "2026-10-20",
+  "note": "Standards an agent is scored against on its first scan and every scan after. OWASP LLM, OWASP Agentic and the My-CC runtime apply to every agent. A framework with a My-CC pack is scored when that pack is bound to the agent; when it fits the agent's industry, data or regions but is not bound it is documented as recommended, not scored; when it does not fit it is omitted with the reason. Practice frameworks (agent identity, MCP security) are My-CC checks with no pack: scored when they fit. Evidence keys name the facts a runtime supplies; a missing fact is 'not checked', never a pass.",
+  "evidence": {
+    "prompt.isolated": "retrieved content and tool output are screened before they reach the prompt",
+    "goal.locked": "the agent's objective cannot be rewritten by content it reads",
+    "output.validated": "model output is validated against a schema before a tool runs it",
+    "citations.required": "answers must cite retrieved sources",
+    "prompt.no_secret": "no secret in the system prompt; keys live in a vault",
+    "data.min_necessary": "tools read the minimum necessary; identifiers never leave the hub",
+    "deid.before_model": "identifiers are removed or tokenized before any model call",
+    "rag.tenant_isolated": "the retrieval index is tenant-scoped",
+    "rag.provenance": "the index accepts only sources with a citable id and a source hash",
+    "memory.validated": "memory writes are validated and expire",
+    "runtime.sandbox": "shell execution is forbidden or sandboxed",
+    "egress.allowlist": "outbound network is allowlisted",
+    "credentials.scoped": "every tool has a scope and a data class; credentials are per tool",
+    "circuit_breaker": "a circuit breaker trips after repeated blocks",
+    "kill_switch": "a kill switch and pause exist and are armed",
+    "human_approval": "high-impact actions require a named person's approval; the raw action is shown",
+    "audit.hash_linked": "every decision is sealed on a hash-linked audit chain",
+    "counterfactual_logging": "blocked actions are logged with what would have happened",
+    "model.pinned": "the model is pinned by provider, name and version",
+    "tac.floor": "a minimum TAC Score is enforced; agents do not run below it",
+    "packs.bound": "at least one signed policy pack is bound",
+    "phi.lineage": "PHI lineage is consent-scoped and recorded",
+    "owner.named": "an accountable owner is named",
+    "intended_use.documented": "purpose, trigger, data and outputs are documented",
+    "evals.present": "a pre-deployment evaluation suite exists, including red-team prompts",
+    "incident.response": "incident response exists: kill switch, pause, escalation",
+    "tools.scoped": "tools are limited to the directory of record and the agent's steps",
+    "tools.validated": "tool parameters are validated on every call",
+    "identity.passport": "the agent holds its own Agent Passport and credentials",
+    "messages.signed": "agent-to-agent messages are signed and allowlisted",
+    "supply.pinned": "runtime packages are pinned and locked",
+    "supply.signed": "components are signed and tracked in an AI bill of materials",
+    "limits.set": "token, tool-call and rate limits are set",
+    "audit.controls": "every access is recorded on the chain",
+    "cardholder.masked": "cardholder data is masked or tokenized before storage and model use",
+    "safe_harbor": "Safe Harbor de-identification is applied before model use"
+  },
+  "frameworks": [
+    { "id": "owasp-llm", "name": "OWASP LLM", "authority": "OWASP Top 10 for LLM Applications (2025)", "kind": "always", "packIds": ["owasp-llm", "owasp"], "controls": [
+      { "id": "LLM01", "control": "Prompt injection", "writesTo": "policy.yaml", "evidence": "prompt.isolated" },
+      { "id": "LLM02", "control": "Sensitive information disclosure", "writesTo": "policy.yaml", "evidence": "data.min_necessary" },
+      { "id": "LLM03", "control": "Supply chain", "writesTo": "agent.yaml", "evidence": "supply.pinned" },
+      { "id": "LLM04", "control": "Data and model poisoning", "writesTo": "memory.yaml", "evidence": "rag.provenance" },
+      { "id": "LLM05", "control": "Improper output handling", "writesTo": "policy.yaml", "evidence": "output.validated" },
+      { "id": "LLM06", "control": "Excessive agency", "writesTo": "tools.json", "evidence": "tools.scoped" },
+      { "id": "LLM07", "control": "System prompt leakage", "writesTo": "prompts/system.md", "evidence": "prompt.no_secret" },
+      { "id": "LLM08", "control": "Vector and embedding weaknesses", "writesTo": "memory.yaml", "evidence": "rag.tenant_isolated" },
+      { "id": "LLM09", "control": "Misinformation", "writesTo": "policy.yaml", "evidence": "citations.required" },
+      { "id": "LLM10", "control": "Unbounded consumption", "writesTo": "policy.yaml", "evidence": "limits.set" } ] },
+    { "id": "owasp-agentic", "name": "OWASP Agentic", "authority": "OWASP Top 10 for Agentic Applications", "kind": "always", "packIds": ["owasp-agentic", "owasp"], "controls": [
+      { "id": "ASI01", "control": "Agent goal hijack", "writesTo": "policy.yaml", "evidence": "goal.locked" },
+      { "id": "ASI02", "control": "Tool misuse and exploitation", "writesTo": "tools.json", "evidence": "tools.validated" },
+      { "id": "ASI03", "control": "Identity and privilege abuse", "writesTo": "agent.yaml", "evidence": "identity.passport" },
+      { "id": "ASI04", "control": "Agentic supply chain", "writesTo": "aibom.json", "evidence": "supply.signed" },
+      { "id": "ASI05", "control": "Unexpected code execution", "writesTo": "policy.yaml", "evidence": "runtime.sandbox" },
+      { "id": "ASI06", "control": "Memory and context poisoning", "writesTo": "memory.yaml", "evidence": "memory.validated" },
+      { "id": "ASI07", "control": "Insecure inter-agent communication", "writesTo": "agent.yaml", "evidence": "messages.signed" },
+      { "id": "ASI08", "control": "Cascading failures", "writesTo": "policy.yaml", "evidence": "circuit_breaker" },
+      { "id": "ASI09", "control": "Human-agent trust exploitation", "writesTo": "policy.yaml", "evidence": "human_approval" },
+      { "id": "ASI10", "control": "Rogue agents", "writesTo": "agent.yaml", "evidence": "identity.passport" } ] },
+    { "id": "mycc-runtime", "name": "My-CC runtime", "authority": "My Compliance Citadel runtime checks", "kind": "always", "packIds": [], "controls": [
+      { "id": "CIT-01", "control": "Required policy packs bound", "writesTo": "policy.yaml", "evidence": "packs.bound" },
+      { "id": "CIT-02", "control": "Model provenance pinning", "writesTo": "agent.yaml", "evidence": "model.pinned" },
+      { "id": "CIT-03", "control": "Hash-linked audit", "writesTo": "policy.yaml", "evidence": "audit.hash_linked" },
+      { "id": "CIT-04", "control": "Counterfactual logging", "writesTo": "policy.yaml", "evidence": "counterfactual_logging" },
+      { "id": "CIT-05", "control": "Consent-scoped PHI lineage", "writesTo": "policy.yaml", "evidence": "phi.lineage", "onlyWith": { "dataClasses": ["phi"] } },
+      { "id": "CIT-06", "control": "TAC band floor enforced", "writesTo": "policy.yaml", "evidence": "tac.floor" } ] },
+    { "id": "nist-ai-rmf", "name": "NIST AI RMF", "authority": "US NIST AI RMF 1.0, AI 600-1", "kind": "pack", "packIds": ["nist_ai_rmf", "nist-ai-rmf"], "fits": {}, "why": "US best-practice framework for every agent", "controls": [
+      { "id": "GOV-1.2", "control": "Accountable owner (Govern)", "writesTo": "owner", "evidence": "owner.named" },
+      { "id": "MAP-1.1", "control": "Intended use documented (Map)", "writesTo": "docs/intended-use.md", "evidence": "intended_use.documented" },
+      { "id": "MEA-2.3", "control": "Pre-deployment evaluation (Measure)", "writesTo": "evals/suite.yaml", "evidence": "evals.present" },
+      { "id": "MAN-4.1", "control": "Incident response (Manage)", "writesTo": "policy.yaml", "evidence": "incident.response" } ] },
+    { "id": "hipaa", "name": "HIPAA", "authority": "US HHS Office for Civil Rights", "kind": "pack", "packIds": ["hipaa", "hipaa-core"], "fits": { "dataClasses": ["phi"] }, "why": "handles PHI", "notFit": "no PHI on this agent", "controls": [
+      { "id": "164.502(b)", "control": "Minimum necessary", "writesTo": "tools.json", "evidence": "data.min_necessary" },
+      { "id": "164.514(b)", "control": "Safe Harbor de-identification", "writesTo": "policy.yaml", "evidence": "safe_harbor" },
+      { "id": "164.312(b)", "control": "Audit controls", "writesTo": "policy.yaml", "evidence": "audit.controls" } ] },
+    { "id": "pci-dss", "name": "PCI DSS", "authority": "PCI Security Standards Council", "kind": "pack", "packIds": ["pci-dss"], "fits": { "dataClasses": ["cardholder"] }, "why": "handles cardholder data", "notFit": "no cardholder data on this agent", "controls": [
+      { "id": "3.4", "control": "Render PAN unreadable", "writesTo": "policy.yaml", "evidence": "cardholder.masked" },
+      { "id": "7.1", "control": "Restrict access to cardholder data", "writesTo": "tools.json", "evidence": "credentials.scoped" },
+      { "id": "10.2", "control": "Audit trail of access", "writesTo": "policy.yaml", "evidence": "audit.controls" } ] },
+    { "id": "gdpr", "name": "GDPR", "authority": "EU data protection authorities; UK ICO for UK GDPR", "kind": "pack", "packIds": ["gdpr", "uk-gdpr"], "fits": { "regions": ["eu", "uk"] }, "why": "people in the EU or the UK", "notFit": "no people in the EU or the UK", "controls": [
+      { "id": "Art.5", "control": "Data minimisation", "writesTo": "tools.json", "evidence": "data.min_necessary" },
+      { "id": "Art.25", "control": "Data protection by design", "writesTo": "policy.yaml", "evidence": "deid.before_model" },
+      { "id": "Art.22", "control": "Automated decisions: human involvement", "writesTo": "policy.yaml", "evidence": "human_approval" },
+      { "id": "Art.30", "control": "Records of processing", "writesTo": "policy.yaml", "evidence": "audit.controls" } ] },
+    { "id": "eu-ai-act", "name": "EU AI Act", "authority": "European Commission AI Office", "kind": "pack", "packIds": ["eu-ai-act"], "fits": { "regions": ["eu"] }, "why": "people in the EU", "notFit": "no people in the EU", "controls": [
+      { "id": "Art.9", "control": "Risk management and testing", "writesTo": "evals/suite.yaml", "evidence": "evals.present" },
+      { "id": "Art.12", "control": "Record keeping", "writesTo": "policy.yaml", "evidence": "audit.hash_linked" },
+      { "id": "Art.14", "control": "Human oversight", "writesTo": "policy.yaml", "evidence": "human_approval" } ] },
+    { "id": "colorado-ai", "name": "Colorado AI Act", "authority": "Colorado Attorney General", "kind": "pack", "packIds": ["colorado-ai"], "fits": { "regions": ["us-co"] }, "why": "people in Colorado", "notFit": "no people in Colorado", "controls": [
+      { "id": "6-1-1703(2)", "control": "Impact assessment", "writesTo": "evals/suite.yaml", "evidence": "evals.present" },
+      { "id": "6-1-1703(4)", "control": "Notice and human review of consequential decisions", "writesTo": "policy.yaml", "evidence": "human_approval" },
+      { "id": "6-1-1703(1)", "control": "Documented intended use", "writesTo": "docs/intended-use.md", "evidence": "intended_use.documented" } ] },
+    { "id": "soc2", "name": "SOC 2", "authority": "AICPA Trust Services Criteria", "kind": "pack", "packIds": ["soc2"], "fits": { "dataClassesAbsent": ["phi", "cardholder"] }, "why": "no PHI or cardholder data; general controls apply", "notFit": "PHI or cardholder data on this agent; the sector framework applies first", "controls": [
+      { "id": "CC6.1", "control": "Logical access", "writesTo": "tools.json", "evidence": "credentials.scoped" },
+      { "id": "CC7.2", "control": "Monitoring of system components", "writesTo": "policy.yaml", "evidence": "audit.hash_linked" },
+      { "id": "CC8.1", "control": "Change management", "writesTo": "aibom.json", "evidence": "supply.signed" } ] },
+    { "id": "iso-42001", "name": "ISO/IEC 42001", "authority": "ISO/IEC", "kind": "pack", "packIds": ["iso_42001", "iso-42001"], "fits": {}, "why": "international AI management system; certifiable", "controls": [
+      { "id": "6.1", "control": "AI risk assessment", "writesTo": "docs/intended-use.md", "evidence": "intended_use.documented" },
+      { "id": "8.4", "control": "AI system verification and validation", "writesTo": "evals/suite.yaml", "evidence": "evals.present" },
+      { "id": "9.1", "control": "Monitoring and measurement", "writesTo": "policy.yaml", "evidence": "audit.controls" } ] },
+    { "id": "agent-identity", "name": "Agent identity and access", "authority": "NIST NCCoE, CoSAI and FIDO Alliance guidance (2026)", "kind": "practice", "packIds": ["agent-identity"], "fits": {}, "why": "every agent needs its own Agent Passport and credentials", "controls": [
+      { "id": "AID-1", "control": "Own passport and credentials", "writesTo": "agent.yaml", "evidence": "identity.passport" },
+      { "id": "AID-2", "control": "Scoped credentials per tool", "writesTo": "tools.json", "evidence": "credentials.scoped" },
+      { "id": "AID-3", "control": "Signed agent-to-agent messages", "writesTo": "agent.yaml", "evidence": "messages.signed" } ] },
+    { "id": "mcp-security", "name": "MCP server security", "authority": "CoSAI MCP Security Taxonomy (2026)", "kind": "practice", "packIds": ["mcp-security"], "fits": { "mcp": true }, "why": "the agent calls MCP tools", "notFit": "the agent calls no MCP tools", "controls": [
+      { "id": "MCP-1", "control": "Tool parameters validated per call", "writesTo": "tools.json", "evidence": "tools.validated" },
+      { "id": "MCP-2", "control": "Egress allowlist for tool servers", "writesTo": "policy.yaml", "evidence": "egress.allowlist" },
+      { "id": "MCP-3", "control": "Tools limited to the directory of record", "writesTo": "tools.json", "evidence": "tools.scoped" } ] }
+  ]
+}