@highflame/policy 2.1.0 → 2.1.2

package/_schemas/overwatch/schema.cedarschema

@@ -1,210 +1,285 @@
-// Overwatch (Guardian) Cedar Schema
+// Overwatch Cedar Schema
 // ===================================
-// IDE Security & Policy Enforcement
+// IDE Agent Security & Policy Enforcement
 //
-// Overwatch protects IDE operations (prompts, tool calls, file access) by evaluating
-// threats detected by YARA and Javelin scanners against Cedar policies.
+// Overwatch protects IDE agent operations (prompts, tool calls, file access, MCP connections)
+// by evaluating threats detected by the detection engine pipeline against Cedar policies.
 //
 // Architecture:
-//   User/Agent → IDE Hook → YARA/Javelin → Cedar Policy → Allow/Deny
+//   User/Agent → IDE Hook → Detection Engine → Cedar Policy → Allow/Deny
 //
 // Supported IDEs:
 //   - Cursor (beforeSubmitPrompt, beforeShellExecution, beforeMCPExecution, etc.)
 //   - Claude Code (UserPromptSubmit, PreToolUse)
 //   - GitHub Copilot (userPromptSubmitted, preToolUse)
+//
+// Threat Coverage:
+//   - OWASP Top 10 for LLM Applications 2025 (LLM01-LLM10)
+//   - OWASP Top 10 for Agentic Applications (ASI01-ASI10)
+//   - OWASP MCP Top 10 (MCP01-MCP05)
+//   - MITRE ATLAS Agent Techniques (AML.T0051, AML.T0080-T0082)
 
 namespace Overwatch {
 
 // =============================================================================
-// ENTITIES - Organization Hierarchy (ReBAC)
+// ENTITIES - Tenant Hierarchy (ReBAC)
 // =============================================================================
+// Aligned with Guardrails entity hierarchy (Account → Project).
+// Overwatch does not have app-specific policies, so App is omitted.
+//
+// Entity hierarchy enables Cedar's `in` operator for policy scoping:
+//   Account (org root)
+//     └── Project in [Account]
+//           └── Tool/Server/FilePath/LlmPrompt in [Project]
+//
+// Policy scoping examples:
+//   resource == Overwatch::Tool::"shell"               → specific tool
+//   resource in Overwatch::Project::"<uuid>"            → project-wide
+//   resource in Overwatch::Account::"<uuid>"            → org-wide
 
-// Top-level organization for multi-tenant policy enforcement
-// Enables policies like: principal in Overwatch::Organization::"acme-corp"
-entity Organization {
-  name: String,            // "Acme Corp", "Highflame"
-};
+/// Account represents an organization (top-level tenant)
+entity Account;
 
-// Team within an organization
-// Enables policies like: principal in Overwatch::Team::"security-team"
-entity Team in [Organization] {
-  name: String,            // "security", "engineering", "devops"
-};
+/// Project represents a project within an account
+entity Project in [Account];
 
 // =============================================================================
 // ENTITIES - Principals
 // =============================================================================
 
-// Human user or service account making requests to the IDE
-entity User in [Team] {
-  user_type: String,      // "external" or "internal"
-  email: String,          // User email (optional)
-};
+/// Human user or service account making requests to the IDE
+entity User;
 
-// AI agent (Claude, GitHub Copilot, etc.)
-entity Agent in [Team] {
-  agent_type: String,      // "claude", "copilot", etc.
-};
+/// AI agent (Claude, GitHub Copilot, etc.)
+entity Agent;
 
-// LLM prompt or session
-entity LlmPrompt {
-  prompt_type: String,     // "user_prompt", "session"
-};
+// =============================================================================
+// ENTITIES - Resources (scoped under Project)
+// =============================================================================
 
-// MCP tool or native IDE tool
-entity Tool {
-  tool_name: String,       // "shell", "read_file", "playwright", etc.
-  risk_level: String,      // "low", "medium", "high"
-};
+/// LLM prompt or session — resource for process_prompt action
+entity LlmPrompt in [Project];
 
-// MCP server
-entity Server {
-  server_name: String,     // "filesystem", "playwright", etc.
-};
+/// MCP tool or native IDE tool — resource for call_tool action
+entity Tool in [Project];
 
-// File system path
-entity FilePath {
-  path: String,
-  is_within_workspace: Bool,
-};
+/// MCP server — resource for connect_server action
+entity Server in [Project];
+
+/// File system path — resource for read_file/write_file/call_tool actions
+entity FilePath in [Project];
 
 // =============================================================================
 // ACTIONS
 // =============================================================================
 
 // User submits a prompt or receives AI response
+// Threat focus: injection, jailbreak, secrets, PII, content safety, invisible chars
 action process_prompt appliesTo {
   principal: [User, Agent],
   resource: [LlmPrompt],
   context: {
-    // Event & Source
-    content: String,                // Raw content being scanned
-    source: String,                 // IDE source: "cursor", "claudecode", "github_copilot"
-    event: String,                  // Hook event name
-    user_email: String,             // User identifier
-
-    // Workspace
-    cwd?: String,                   // Current working directory
-    workspace_root?: String,        // Workspace/repository root
-
-    // Threat Detection
-    threat_count: Long,             // Total threats detected
-    highest_severity: String,       // "critical", "high", "medium", "low"
-    threat_categories: Set<String>, // Threat category names
-    yara_threats: Set<String>,      // YARA rule names
-    max_threat_severity: Long,      // Numeric severity (0-4)
-    contains_secrets: Bool,         // Whether secrets detected
-    prompt_text?: String,           // Same as content (legacy)
-    response_content?: String,      // Response content (if available)
-
-    // Trust/Safety Scores (0-100, from Javelin/Lakera/LlamaGuard classifiers)
-    // Required: content safety classifiers always run for prompt processing
-    violence_score: Long,           // Violence content detection score
-    weapons_score: Long,            // Weapons content detection score
-    hate_speech_score: Long,        // Hate speech detection score
-    crime_score: Long,              // Criminal content detection score
-    sexual_score: Long,             // Sexual content detection score
-    profanity_score: Long,          // Profanity detection score
-
-    // Detector Confidence Scores (0-100, ML classifier confidence)
-    // Required: ML classifiers always run for prompt processing
-    pii_confidence: Long,           // PII detection confidence
-    injection_confidence: Long,     // Prompt injection confidence
-    jailbreak_confidence: Long,     // Jailbreak detection confidence
-
-    // Agent Security (0-100)
-    // Required: agent security scanners always run for prompt processing
-    indirect_injection_score: Long,  // Indirect prompt injection risk
+    // --- Event & Source ---
+    content: String,                  // Raw content being scanned
+    source: String,                   // IDE source: "cursor", "claudecode", "github_copilot"
+    event: String,                    // Hook event name
+    user_email: String,               // User identifier
+
+    // --- Workspace ---
+    cwd?: String,                     // Current working directory
+    workspace_root?: String,          // Workspace/repository root
+
+    // --- Threat Detection (from detection engine pipeline) ---
+    threat_count: Long,               // Total threats detected
+    highest_severity: String,         // "critical", "high", "medium", "low", "none"
+    threat_categories: Set<String>,   // Threat category names
+    detected_threats: Set<String>,    // Detection rule names that matched
+    max_threat_severity: Long,        // Numeric severity (0=none, 1=low, 2=medium, 3=high, 4=critical)
+    contains_secrets: Bool,           // Whether secrets/credentials detected
+
+    // --- Secrets (granular) ---
+    secret_types?: Set<String>,       // Types: "aws_access_key", "github_token", "ssh_private_key", etc.
+    secret_count?: Long,              // Number of distinct secrets found
+
+    // --- PII Detection ---
+    pii_detected?: Bool,              // Whether any PII patterns matched
+    pii_types?: Set<String>,          // Types: "ssn", "credit_card", "email", "phone", etc.
+    pii_count?: Long,                 // Number of PII matches
+
+    // --- Encoding & Unicode Attacks ---
+    contains_invisible_chars?: Bool,  // Zero-width chars, bidi overrides, tag chars detected
+    invisible_chars_score?: Long,     // Unicode attack severity (0-100)
+
+    // --- Content Safety Scores (0-100, from ML classifiers) ---
+    violence_score: Long,
+    weapons_score: Long,
+    hate_speech_score: Long,
+    crime_score: Long,
+    sexual_score: Long,
+    profanity_score: Long,
+
+    // --- ML Detector Confidence Scores (0-100) ---
+    pii_confidence: Long,             // PII detection classifier confidence
+    injection_confidence: Long,       // Prompt injection classifier confidence
+    jailbreak_confidence: Long,       // Jailbreak detection classifier confidence
+
+    // --- Agent Security (0-100) ---
+    indirect_injection_score: Long,   // Indirect prompt injection risk (OWASP LLM01, ASI01)
+
+    // --- Session Detection History (cross-turn sticky flags) ---
+    session_pii_detected?: Bool,
+    session_pii_types?: Set<String>,
+    session_secrets_detected?: Bool,
+    session_secret_types?: Set<String>,
+    session_injection_detected?: Bool,
+    session_command_injection?: Bool,
+    session_threat_turns?: Long,
+
+    // --- Legacy ---
+    prompt_text?: String,             // Same as content (backward compatibility)
+    response_content?: String,        // Response content (if available)
   },
 };
 
 // User calls a tool (native IDE tool or MCP tool)
+// Threat focus: command injection, tool poisoning, rug pull, data exfiltration, loops
 action call_tool appliesTo {
   principal: [User, Agent],
   resource: [Tool, FilePath],
   context: {
-    // Event & Source
-    content: String,                // Raw content being scanned (e.g., shell command)
-    source: String,                 // IDE source
-    event: String,                  // Hook event name
-    user_email: String,             // User identifier
+    // --- Event & Source ---
+    content: String,                  // Raw content being scanned (e.g., shell command, tool args)
+    source: String,                   // IDE source
+    event: String,                    // Hook event name
+    user_email: String,               // User identifier
 
-    // Tool & MCP
-    tool_name?: String,             // Normalized tool name ("shell", "read_file", etc.)
-    mcp_server?: String,            // MCP server name
-    mcp_tool?: String,              // MCP tool name
+    // --- Tool & MCP ---
+    tool_name?: String,               // Normalized tool name ("shell", "read_file", etc.)
+    mcp_server?: String,              // MCP server name
+    mcp_tool?: String,                // MCP tool name
 
-    // File & Path
-    path?: String,                  // File path (if file operation)
+    // --- File & Path ---
+    path?: String,                    // File path (if file operation)
 
-    // Workspace
+    // --- Workspace ---
     cwd?: String,
     workspace_root?: String,
 
-    // Threat Detection (optional: scanning may not have run before tool call)
+    // --- Threat Detection ---
     threat_count?: Long,
     highest_severity?: String,
     threat_categories?: Set<String>,
-    yara_threats?: Set<String>,
+    detected_threats?: Set<String>,
     max_threat_severity?: Long,
     contains_secrets?: Bool,
-    response_content?: String,
 
-    // Trust/Safety Scores (0-100, from Javelin/Lakera/LlamaGuard classifiers)
-    // Optional: only present when trust/safety classifiers have run
-    violence_score?: Long,          // Violence content detection score
-    weapons_score?: Long,           // Weapons content detection score
-    hate_speech_score?: Long,       // Hate speech detection score
-    crime_score?: Long,             // Criminal content detection score
-    sexual_score?: Long,            // Sexual content detection score
-    profanity_score?: Long,         // Profanity detection score
-
-    // Detector Confidence Scores (0-100, ML classifier confidence)
-    // Optional: only present when ML classifiers have run
-    pii_confidence?: Long,          // PII detection confidence
-    injection_confidence?: Long,    // Prompt injection confidence
-    jailbreak_confidence?: Long,    // Jailbreak detection confidence
-
-    // Agent Security (0-100)
-    // Optional: only present when agent security scanners have run
-    tool_poisoning_score?: Long,    // Tool description manipulation risk
-    rug_pull_score?: Long,          // Tool behavior mismatch risk
-    indirect_injection_score?: Long, // Indirect prompt injection risk
-
-    // MCP Trust
-    // Optional: only present when MCP server verification has run
-    mcp_server_verified?: Bool,     // Whether server is from verified registry
+    // --- Secrets (granular) ---
+    secret_types?: Set<String>,
+    secret_count?: Long,
+
+    // --- PII Detection ---
+    pii_detected?: Bool,
+    pii_types?: Set<String>,
+    pii_count?: Long,
+
+    // --- Encoding & Unicode Attacks ---
+    contains_invisible_chars?: Bool,
+    invisible_chars_score?: Long,
+
+    // --- Content Safety Scores (0-100) ---
+    violence_score?: Long,
+    weapons_score?: Long,
+    hate_speech_score?: Long,
+    crime_score?: Long,
+    sexual_score?: Long,
+    profanity_score?: Long,
+
+    // --- ML Detector Confidence Scores (0-100) ---
+    pii_confidence?: Long,
+    injection_confidence?: Long,
+    jailbreak_confidence?: Long,
+
+    // --- Agent Security (0-100) --- (OWASP ASI01, ASI02, ASI04; MITRE AML.T0051)
+    tool_poisoning_score?: Long,      // Hidden instructions in tool description/args
+    tool_poisoning_detected?: Bool,   // Boolean flag for tool poisoning
+    rug_pull_score?: Long,            // Tool behavior drift after trust establishment
+    rug_pull_detected?: Bool,         // Boolean flag for rug pull
+    indirect_injection_score?: Long,  // Indirect injection via tool output
+
+    // --- Tool Risk Assessment ---
+    tool_risk_score?: Long,           // Computed tool risk (0-100)
+    tool_category?: String,           // "safe", "sensitive", "dangerous"
+    tool_is_sensitive?: Bool,         // Sensitivity classification
+    tool_is_builtin?: Bool,           // Built-in IDE tool vs MCP tool
+
+    // --- Behavioral Analysis --- (OWASP LLM10, ASI02, ASI08)
+    loop_detected?: Bool,             // Consecutive same-tool call loop
+    loop_count?: Long,                // Number of consecutive repeat calls
+    loop_tool?: String,               // Tool name in loop
+    suspicious_pattern?: Bool,        // Data exfiltration or attack sequence detected
+    pattern_type?: String,            // "data_exfiltration", "secret_exfiltration", "credential_theft", "destructive_sequence"
+    sequence_risk?: Long,             // Sequence risk score (0-100)
+
+    // --- MCP Trust ---
+    mcp_server_verified?: Bool,       // Whether server is from verified registry
+
+    // --- Session Detection History (cross-turn sticky flags) ---
+    session_pii_detected?: Bool,
+    session_pii_types?: Set<String>,
+    session_secrets_detected?: Bool,
+    session_secret_types?: Set<String>,
+    session_injection_detected?: Bool,
+    session_command_injection?: Bool,
+    session_threat_turns?: Long,
+
+    // --- Legacy ---
+    response_content?: String,
   },
 };
 
 // Connect to an MCP server
+// Threat focus: supply chain, tool poisoning, rug pull, config risk
 action connect_server appliesTo {
   principal: [User, Agent],
   resource: [Server],
   context: {
-    content?: String,               // No content to scan when connecting
+    content?: String,                 // Server config content (if available)
     source: String,
     event: String,
     user_email: String,
     mcp_server?: String,
-    threat_count?: Long,            // Threat scanning may not run for connections
+
+    // --- Threat Detection ---
+    threat_count?: Long,
     highest_severity?: String,
     threat_categories?: Set<String>,
     max_threat_severity?: Long,
 
-    // Agent Security (0-100)
-    // Optional: only present when agent security scanners have run
-    tool_poisoning_score?: Long,    // Tool description manipulation risk
-    rug_pull_score?: Long,          // Tool behavior mismatch risk
-    indirect_injection_score?: Long, // Indirect prompt injection risk
-
-    // MCP Trust
-    // Optional: only present when MCP server verification has run
-    mcp_server_verified?: Bool,     // Whether server is from verified registry
+    // --- Agent Security (0-100) --- (OWASP ASI04, MCP01-MCP05)
+    tool_poisoning_score?: Long,      // Poisoned tool descriptions in server
+    tool_poisoning_detected?: Bool,
+    rug_pull_score?: Long,            // Server behavior change after approval
+    rug_pull_detected?: Bool,
+    indirect_injection_score?: Long,  // Injection payloads in server responses
+
+    // --- MCP Trust & Config Risk ---
+    mcp_server_verified?: Bool,       // Verified registry status
+    mcp_config_risk?: Bool,           // Risky server config detected (inline code exec, etc.)
+    mcp_risk_score?: Long,            // Config risk severity (0-100)
+
+    // --- Session Detection History (cross-turn sticky flags) ---
+    session_pii_detected?: Bool,
+    session_pii_types?: Set<String>,
+    session_secrets_detected?: Bool,
+    session_secret_types?: Set<String>,
+    session_injection_detected?: Bool,
+    session_command_injection?: Bool,
+    session_threat_turns?: Long,
   },
 };
 
 // Read a file from disk
+// Threat focus: secrets exposure, PII exposure, path traversal, sensitive paths
 action read_file appliesTo {
   principal: [User, Agent],
   resource: [FilePath],
@@ -216,15 +291,37 @@ action read_file appliesTo {
     path?: String,
     cwd?: String,
     workspace_root?: String,
-    threat_count?: Long,             // Threat scanning may not have run
+
+    // --- Threat Detection ---
+    threat_count?: Long,
     highest_severity?: String,
     threat_categories?: Set<String>,
+    detected_threats?: Set<String>,
     max_threat_severity?: Long,
     contains_secrets?: Bool,
+
+    // --- Secrets (granular) ---
+    secret_types?: Set<String>,
+    secret_count?: Long,
+
+    // --- PII Detection ---
+    pii_detected?: Bool,
+    pii_types?: Set<String>,
+    pii_count?: Long,
+
+    // --- Session Detection History (cross-turn sticky flags) ---
+    session_pii_detected?: Bool,
+    session_pii_types?: Set<String>,
+    session_secrets_detected?: Bool,
+    session_secret_types?: Set<String>,
+    session_injection_detected?: Bool,
+    session_command_injection?: Bool,
+    session_threat_turns?: Long,
   },
 };
 
 // Write a file to disk
+// Threat focus: secrets in output, PII in output, sensitive paths, malicious code
 action write_file appliesTo {
   principal: [User, Agent],
   resource: [FilePath],
@@ -236,11 +333,32 @@ action write_file appliesTo {
     path?: String,
     cwd?: String,
     workspace_root?: String,
-    threat_count?: Long,             // Threat scanning may not have run
+
+    // --- Threat Detection ---
+    threat_count?: Long,
     highest_severity?: String,
     threat_categories?: Set<String>,
+    detected_threats?: Set<String>,
     max_threat_severity?: Long,
     contains_secrets?: Bool,
+
+    // --- Secrets (granular) ---
+    secret_types?: Set<String>,
+    secret_count?: Long,
+
+    // --- PII Detection ---
+    pii_detected?: Bool,
+    pii_types?: Set<String>,
+    pii_count?: Long,
+
+    // --- Session Detection History (cross-turn sticky flags) ---
+    session_pii_detected?: Bool,
+    session_pii_types?: Set<String>,
+    session_secrets_detected?: Bool,
+    session_secret_types?: Set<String>,
+    session_injection_detected?: Bool,
+    session_command_injection?: Bool,
+    session_threat_turns?: Long,
   },
 };
 

package/dist/explain.d.ts

@@ -46,6 +46,18 @@ export interface PolicyExplanation {
     /** Raw Cedar condition text if the policy uses rawCondition instead of structured conditions */
     raw_condition?: string;
 }
+/**
+ * Identifies the detector that produced a context value.
+ * Used for provenance tracking — linking policy conditions back to their source detector.
+ */
+export interface EvidenceSource {
+    /** Detector name (e.g., "injection", "secrets", "tool_validator") */
+    detector: string;
+    /** Detector execution latency in milliseconds */
+    latency_ms?: number;
+    /** Producer-specific metadata (e.g., "tier", "phase", "priority"). Treated as opaque key-value pairs. */
+    labels?: Record<string, string>;
+}
 /**
  * Result of evaluating a single condition against the request context.
  */
@@ -60,6 +72,15 @@ export interface ConditionResult {
     actual?: unknown;
     /** Whether this condition matched */
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
+}
+/**
+ * Options for explainDecision.
+ */
+export interface ExplainOptions {
+    /** Maps context field names to the detector that produced them */
+    provenance?: Record<string, EvidenceSource>;
 }
 /** Evaluated comparison: context.field <op> value */
 export interface EvaluatedComparison {
@@ -69,6 +90,8 @@ export interface EvaluatedComparison {
     expected: string | number | boolean | string[];
     actual: unknown;
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
 }
 /** Evaluated contains: context.field.contains(value) */
 export interface EvaluatedContains {
@@ -77,6 +100,8 @@ export interface EvaluatedContains {
     expected: string | number | boolean;
     actual: unknown;
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
 }
 /** Evaluated like: context.field like "pattern" */
 export interface EvaluatedLike {
@@ -85,6 +110,8 @@ export interface EvaluatedLike {
     pattern: string;
     actual: unknown;
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
 }
 /** Evaluated has: context has field */
 export interface EvaluatedHas {
@@ -142,9 +169,10 @@ export type EvaluatedExpression = EvaluatedComparison | EvaluatedContains | Eval
  * }
  * ```
  */
-export declare function explainDecision(decision: DecisionInput, rules: PolicyRule[], context: Record<string, unknown>): ExplainedDecision;
+export declare function explainDecision(decision: DecisionInput, rules: PolicyRule[], context: Record<string, unknown>, options?: ExplainOptions): ExplainedDecision;
 /**
  * Recursively evaluate a ConditionExpression tree against a context map.
  * Returns an EvaluatedExpression tree with `matched` booleans and `actual` values.
+ * The optional provenance map links context field names to their source detectors.
  */
-export declare function evaluateExpression(expr: ConditionExpression, context: Record<string, unknown>): EvaluatedExpression;
+export declare function evaluateExpression(expr: ConditionExpression, context: Record<string, unknown>, provenance?: Record<string, EvidenceSource>): EvaluatedExpression;