sentinel-agentos 0.3.8 → 0.3.10

package/dist/guard/risk-gate.d.ts

@@ -0,0 +1,101 @@
+import { RiskScore } from '../types';
+/**
+ * Impact level — how broadly the operation affects the system.
+ */
+export type ImpactLevel = 'local' | 'workspace' | 'project' | 'system';
+/**
+ * Sensitivity level — how sensitive the data involved is.
+ */
+export type SensitivityLevel = 'none' | 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Tool-level risk profile — users define this per tool.
+ */
+export interface ToolRiskProfile {
+    /** Tool name to match */
+    tool: string;
+    /** Impact level of this tool */
+    impact: ImpactLevel;
+    /** How reversible the operation is (0 = irreversible, 1 = fully reversible) */
+    reversibility: number;
+    /** Sensitivity of data this tool accesses */
+    sensitivity: SensitivityLevel;
+    /** Tool category for default error rate */
+    category?: 'read' | 'write' | 'delete' | 'network' | 'compute';
+    /** Optional override for initial error rate (skips category default) */
+    initialErrorRate?: number;
+}
+/**
+ * Tool call statistics for dynamic error-rate tracking.
+ */
+interface ToolStats {
+    totalCalls: number;
+    failures: number;
+    errorRate: number;
+    lastUpdated: number;
+}
+/**
+ * Threshold configuration for risk-based actions.
+ */
+export interface RiskThresholds {
+    /** Score ≤ autoApprove → execute immediately */
+    autoApprove: number;
+    /** Score ≤ notify → execute but notify user */
+    notify: number;
+    /** Score ≤ confirm → pause and ask for user confirmation */
+    confirm: number;
+    /** Score > deny → block entirely */
+    deny: number;
+}
+/**
+ * Default thresholds — conservative but workable.
+ */
+export declare const DEFAULT_RISK_THRESHOLDS: RiskThresholds;
+/**
+ * Risk Gate — deterministic, pure-math risk scoring.
+ *
+ * Formula: RiskScore = Impact × (1 - Reversibility) × Sensitivity × (1 + ErrorRate)
+ *
+ * Zero LLM dependency. The formula, thresholds, and mappings are all
+ * explicit and auditable.
+ */
+export declare class RiskGate {
+    private profiles;
+    private stats;
+    private thresholds;
+    constructor(thresholds?: RiskThresholds);
+    /** Register a risk profile for a tool */
+    registerProfile(profile: ToolRiskProfile): void;
+    /** Register multiple profiles at once */
+    registerProfiles(profiles: ToolRiskProfile[]): void;
+    /** Get all registered profiles */
+    getProfiles(): ToolRiskProfile[];
+    /** Check if a tool has a registered profile */
+    hasProfile(tool: string): boolean;
+    /**
+     * Compute the risk score for a tool call.
+     *
+     * If no profile is registered, returns a default moderate-risk score
+     * (auto-approve with notification).
+     */
+    evaluate(tool: string, _params?: Record<string, unknown>): RiskScore;
+    /**
+     * Evaluate risk for an unregistered tool by scanning params for danger patterns.
+     */
+    private evaluateUntracked;
+    /** Record the outcome of a tool call to update stats */
+    recordOutcome(tool: string, success: boolean): void;
+    /** Get tool statistics */
+    getStats(tool: string): ToolStats | undefined;
+    /** Get all tool statistics */
+    getAllStats(): Map<string, ToolStats>;
+    /** Update thresholds at runtime */
+    setThresholds(thresholds: Partial<RiskThresholds>): void;
+    /** Get current thresholds */
+    getThresholds(): RiskThresholds;
+    /**
+     * Map a numeric risk score to the appropriate action.
+     */
+    private scoreToAction;
+}
+export {};
+//# sourceMappingURL=risk-gate.d.ts.map

package/dist/guard/risk-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-gate.d.ts","sourceRoot":"","sources":["../../src/guard/risk-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,SAAS,EAAE,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AASvE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAsC/E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,WAAW,EAAE,gBAAgB,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAC/D,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,UAAU,SAAS;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAKrC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,UAAU,CAAiB;gBAEvB,UAAU,GAAE,cAAwC;IAIhE,yCAAyC;IACzC,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAgB/C,yCAAyC;IACzC,gBAAgB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,IAAI;IAInD,kCAAkC;IAClC,WAAW,IAAI,eAAe,EAAE;IAIhC,+CAA+C;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IA+BpE;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiCzB,wDAAwD;IACxD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAWnD,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI7C,8BAA8B;IAC9B,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC;IAIrC,mCAAmC;IACnC,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;IAIxD,6BAA6B;IAC7B,aAAa,IAAI,cAAc;IAI/B;;OAEG;IACH,OAAO,CAAC,aAAa;CAMtB"}

package/dist/guard/risk-gate.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RiskGate = exports.DEFAULT_RISK_THRESHOLDS = void 0;
+const IMPACT_VALUES = {
+    local: 1,
+    workspace: 3,
+    project: 6,
+    system: 10,
+};
+const SENSITIVITY_VALUES = {
+    none: 0.0,
+    low: 0.3,
+    medium: 0.6,
+    high: 0.9,
+    critical: 1.0,
+};
+/**
+ * Default error rates by tool category (cold start).
+ */
+const DEFAULT_ERROR_RATES = {
+    read: 0.01,
+    write: 0.05,
+    delete: 0.10,
+    network: 0.08,
+    compute: 0.02,
+};
+// Danger patterns for content-based fallback (used when no profile registered)
+const DANGER_PATTERNS = [
+    { regex: new RegExp('rm\\s+-rf\\s+(?:[/~]|\\*)', 'i'), impact: 'system', reversibility: 0.0, sensitivity: 'critical' },
+    { regex: new RegExp('sudo\\s+rm\\s+-rf', 'i'), impact: 'system', reversibility: 0.0, sensitivity: 'critical' },
+    { regex: new RegExp('del\\s+[/][fsq]\\s+[a-z]:[\\\\]?', 'i'), impact: 'system', reversibility: 0.0, sensitivity: 'critical' },
+    { regex: new RegExp('\\bmkfs\\b', 'i'), impact: 'system', reversibility: 0.0, sensitivity: 'critical' },
+    { regex: new RegExp('\\bdd\\s+if=', 'i'), impact: 'system', reversibility: 0.0, sensitivity: 'critical' },
+    { regex: new RegExp('chmod\\s+777\\s+-R', 'i'), impact: 'system', reversibility: 0.1, sensitivity: 'high' },
+    { regex: /drop\s+(table|database|schema)/i, impact: 'project', reversibility: 0.0, sensitivity: 'critical' },
+    { regex: /truncate\s+(table\s+)?/i, impact: 'project', reversibility: 0.0, sensitivity: 'high' },
+    { regex: /git\s+push\s+[\w\s-]*--force/i, impact: 'project', reversibility: 0.2, sensitivity: 'high' },
+    { regex: /git\s+reset\s+--hard/i, impact: 'project', reversibility: 0.3, sensitivity: 'high' },
+    { regex: /npm\s+unpublish\b/i, impact: 'project', reversibility: 0.0, sensitivity: 'high' },
+    { regex: /\.(?:env|key|pem|p12|pfx|jks|keystore)/i, impact: 'workspace', reversibility: 0.5, sensitivity: 'critical' },
+];
+/**
+ * Default thresholds — conservative but workable.
+ */
+exports.DEFAULT_RISK_THRESHOLDS = {
+    autoApprove: 0.5,
+    notify: 1.0,
+    confirm: 3.0,
+    deny: 8.0,
+};
+/**
+ * Risk Gate — deterministic, pure-math risk scoring.
+ *
+ * Formula: RiskScore = Impact × (1 - Reversibility) × Sensitivity × (1 + ErrorRate)
+ *
+ * Zero LLM dependency. The formula, thresholds, and mappings are all
+ * explicit and auditable.
+ */
+class RiskGate {
+    profiles = new Map();
+    stats = new Map();
+    thresholds;
+    constructor(thresholds = exports.DEFAULT_RISK_THRESHOLDS) {
+        this.thresholds = thresholds;
+    }
+    /** Register a risk profile for a tool */
+    registerProfile(profile) {
+        this.profiles.set(profile.tool, profile);
+        // Initialize stats if not already tracked
+        if (!this.stats.has(profile.tool)) {
+            const errorRate = profile.initialErrorRate ??
+                (profile.category ? (DEFAULT_ERROR_RATES[profile.category] ?? 0.05) : 0.05);
+            this.stats.set(profile.tool, {
+                totalCalls: 0,
+                failures: 0,
+                errorRate,
+                lastUpdated: Date.now(),
+            });
+        }
+    }
+    /** Register multiple profiles at once */
+    registerProfiles(profiles) {
+        profiles.forEach((p) => this.registerProfile(p));
+    }
+    /** Get all registered profiles */
+    getProfiles() {
+        return Array.from(this.profiles.values());
+    }
+    /** Check if a tool has a registered profile */
+    hasProfile(tool) {
+        return this.profiles.has(tool);
+    }
+    /**
+     * Compute the risk score for a tool call.
+     *
+     * If no profile is registered, returns a default moderate-risk score
+     * (auto-approve with notification).
+     */
+    evaluate(tool, _params) {
+        const profile = this.profiles.get(tool);
+        // Fallback for unregistered tools — content-based danger analysis
+        if (!profile) {
+            return this.evaluateUntracked(_params ?? {});
+        }
+        const impact = IMPACT_VALUES[profile.impact];
+        const reversibility = Math.min(1, Math.max(0, profile.reversibility));
+        const sensitivity = SENSITIVITY_VALUES[profile.sensitivity];
+        const stats = this.stats.get(profile.tool);
+        const errorRate = stats?.errorRate ?? 0.05;
+        const score = impact * (1 - reversibility) * sensitivity * (1 + errorRate);
+        const action = this.scoreToAction(score);
+        return {
+            score: Math.round(score * 100) / 100, // round to 2 decimal places
+            action,
+            dimensions: {
+                impact,
+                reversibility,
+                sensitivity,
+                errorRate: Math.round(errorRate * 1000) / 1000,
+            },
+        };
+    }
+    /**
+     * Evaluate risk for an unregistered tool by scanning params for danger patterns.
+     */
+    evaluateUntracked(params) {
+        const paramText = Object.values(params).join(' ');
+        for (const pattern of DANGER_PATTERNS) {
+            if (pattern.regex.test(paramText)) {
+                const impact = IMPACT_VALUES[pattern.impact];
+                const reversibility = Math.min(1, Math.max(0, pattern.reversibility));
+                const sensitivity = SENSITIVITY_VALUES[pattern.sensitivity];
+                const errorRate = DEFAULT_ERROR_RATES['write'] ?? 0.05;
+                const score = impact * (1 - reversibility) * sensitivity * (1 + errorRate);
+                let action;
+                if (score >= this.thresholds.deny)
+                    action = 'deny';
+                else if (score >= this.thresholds.confirm)
+                    action = 'confirm';
+                else if (score >= this.thresholds.notify)
+                    action = 'notify';
+                else
+                    action = 'auto';
+                return {
+                    score: Math.round(score * 100) / 100,
+                    action,
+                    dimensions: { impact, reversibility, sensitivity, errorRate: Math.round(errorRate * 1000) / 1000 },
+                };
+            }
+        }
+        // No danger pattern matched — low risk
+        return {
+            score: 0.2,
+            action: 'auto',
+            dimensions: { impact: 1, reversibility: 1, sensitivity: 0, errorRate: 0 },
+        };
+    }
+    /** Record the outcome of a tool call to update stats */
+    recordOutcome(tool, success) {
+        const stats = this.stats.get(tool);
+        if (!stats)
+            return;
+        stats.totalCalls++;
+        if (!success)
+            stats.failures++;
+        stats.errorRate =
+            stats.totalCalls > 0 ? stats.failures / stats.totalCalls : 0;
+        stats.lastUpdated = Date.now();
+    }
+    /** Get tool statistics */
+    getStats(tool) {
+        return this.stats.get(tool);
+    }
+    /** Get all tool statistics */
+    getAllStats() {
+        return new Map(this.stats);
+    }
+    /** Update thresholds at runtime */
+    setThresholds(thresholds) {
+        this.thresholds = { ...this.thresholds, ...thresholds };
+    }
+    /** Get current thresholds */
+    getThresholds() {
+        return { ...this.thresholds };
+    }
+    /**
+     * Map a numeric risk score to the appropriate action.
+     */
+    scoreToAction(score) {
+        if (score <= this.thresholds.autoApprove)
+            return 'auto';
+        if (score <= this.thresholds.notify)
+            return 'notify';
+        if (score <= this.thresholds.confirm)
+            return 'confirm';
+        return 'deny';
+    }
+}
+exports.RiskGate = RiskGate;
+//# sourceMappingURL=risk-gate.js.map

package/dist/guard/risk-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk-gate.js","sourceRoot":"","sources":["../../src/guard/risk-gate.ts"],"names":[],"mappings":"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"}

package/dist/guard/sandbox.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Execution mode — from DESIGN.md §4.5
+ */
+export type ExecutionMode = 'direct' | 'sandbox' | 'dry-run';
+/**
+ * Network access policy for sandbox mode.
+ */
+export type NetworkPolicy = 'none' | 'localhost' | 'whitelist';
+/**
+ * Execution context configuration — full DESIGN.md §4.5 interface.
+ */
+export interface ExecutionContext {
+    /** Execution mode */
+    mode: ExecutionMode;
+    /** Timeout in milliseconds */
+    timeoutMs: number;
+    /** Network policy (sandbox mode only) */
+    networkAccess?: NetworkPolicy;
+    /** Allowed network hosts (sandbox + whitelist mode only) */
+    networkWhitelist?: string[];
+    /** Writable paths (sandbox mode) */
+    writablePaths?: string[];
+    /** Read-only paths (sandbox mode) */
+    readonlyPaths?: string[];
+    /** Workspace root */
+    workspaceRoot: string;
+    /** Max output size before truncation */
+    maxOutputSize?: number;
+    /** Allowed tools in sandbox mode */
+    allowedTools?: string[];
+    /** Forbidden tools in any mode */
+    forbiddenTools?: string[];
+}
+/**
+ * Sandbox execution result.
+ */
+export interface SandboxResult {
+    /** Execution outcome */
+    success: boolean;
+    /** Exit code (0 = success) */
+    exitCode: number;
+    /** stdout */
+    stdout: string;
+    /** stderr */
+    stderr: string;
+    /** Truncated flag */
+    truncated: boolean;
+    /** Error message if sandbox rejected */
+    sandboxRejectReason?: string;
+    /** Dry-run: what would have happened */
+    dryRunSummary?: string;
+    /** Execution time in ms */
+    durationMs: number;
+}
+/**
+ * Sandbox Violation types.
+ */
+export declare enum SandboxViolation {
+    NETWORK_FORBIDDEN = "NETWORK_FORBIDDEN",
+    PATH_NOT_WRITABLE = "PATH_NOT_WRITABLE",
+    PATH_READONLY = "PATH_READONLY",
+    TOOL_FORBIDDEN = "TOOL_FORBIDDEN",
+    TOOL_NOT_ALLOWED = "TOOL_NOT_ALLOWED",
+    COMMAND_FORBIDDEN = "COMMAND_FORBIDDEN"
+}
+/**
+ * Sandbox Executor — controlled execution environment.
+ *
+ * Implements three execution modes from DESIGN.md §4.5:
+ * - direct: Execute in shared environment (default, no sandboxing)
+ * - sandbox: Restricted execution with network + filesystem policies
+ * - dry-run: Preview only, no actual execution
+ */
+export declare class SandboxExecutor {
+    private config;
+    /** Forbidden shell commands (dangerous patterns) */
+    private static FORBIDDEN_COMMANDS;
+    constructor(config: ExecutionContext);
+    /**
+     * Validate and possibly reject a tool call before execution.
+     *
+     * @returns {SandboxResult} with sandboxRejectReason if rejected
+     */
+    validate(toolName: string, params: Record<string, unknown>): SandboxResult | null;
+    /**
+     * Execute a shell command in the configured mode.
+     */
+    execute(toolName: string, params: Record<string, unknown>): Promise<SandboxResult>;
+    /**
+     * Dry-run: return a summary of what would happen.
+     */
+    private dryRun;
+    /**
+     * Execute shell commands with sandbox policies.
+     */
+    private executeShell;
+    /**
+     * Build environment with sandbox network restrictions.
+     */
+    private buildSandboxEnv;
+    /**
+     * Validate a filesystem path against sandbox policies.
+     */
+    private validatePath;
+    /**
+     * Validate a shell command against forbidden patterns.
+     */
+    private validateCommand;
+    private isShellTool;
+    private isWriteTool;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/guard/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/guard/sandbox.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,IAAI,EAAE,aAAa,CAAC;IACpB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,kCAAkC;IAClC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,iBAAiB,sBAAsB;IACvC,iBAAiB,sBAAsB;IACvC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;CACxC;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAmB;IAEjC,oDAAoD;IACpD,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAU/B;gBAEU,MAAM,EAAE,gBAAgB;IAOpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,GAAG,IAAI;IA6DjF;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IA6BxF;;OAEG;IACH,OAAO,CAAC,MAAM;IAiCd;;OAEG;YACW,YAAY;IAuD1B;;OAEG;IACH,OAAO,CAAC,eAAe;IAsCvB;;OAEG;IACH,OAAO,CAAC,YAAY;IA0DpB;;OAEG;IACH,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,WAAW;CAQpB"}