@safefence/openclaw-guardrails 0.3.0

package/dist/core/reason-codes.d.ts

@@ -0,0 +1,43 @@
+export declare const REASON_CODES: {
+    readonly AUDIT_WOULD_DENY: "AUDIT_WOULD_DENY";
+    readonly AUDIT_WOULD_REDACT: "AUDIT_WOULD_REDACT";
+    readonly BUDGET_REQUEST_EXCEEDED: "BUDGET_REQUEST_EXCEEDED";
+    readonly BUDGET_TOOL_CALL_EXCEEDED: "BUDGET_TOOL_CALL_EXCEEDED";
+    readonly COMMAND_ARG_PATTERN_BLOCKED: "COMMAND_ARG_PATTERN_BLOCKED";
+    readonly COMMAND_BINARY_NOT_ALLOWED: "COMMAND_BINARY_NOT_ALLOWED";
+    readonly COMMAND_SHELL_OPERATOR_BLOCKED: "COMMAND_SHELL_OPERATOR_BLOCKED";
+    readonly DESTRUCTIVE_COMMAND: "DESTRUCTIVE_COMMAND";
+    readonly ENGINE_FAILURE: "ENGINE_FAILURE";
+    readonly ENGINE_FAILURE_FAIL_OPEN: "ENGINE_FAILURE_FAIL_OPEN";
+    readonly EXFIL_PATTERN: "EXFIL_PATTERN";
+    readonly INPUT_LIMIT_EXCEEDED: "INPUT_LIMIT_EXCEEDED";
+    readonly INVALID_NETWORK_HOST: "INVALID_NETWORK_HOST";
+    readonly INVALID_NETWORK_URL: "INVALID_NETWORK_URL";
+    readonly NETWORK_HOST_BLOCKED: "NETWORK_HOST_BLOCKED";
+    readonly NETWORK_PRIVATE_BLOCKED: "NETWORK_PRIVATE_BLOCKED";
+    readonly PATH_OUTSIDE_WORKSPACE: "PATH_OUTSIDE_WORKSPACE";
+    readonly PATH_SYMLINK_TRAVERSAL: "PATH_SYMLINK_TRAVERSAL";
+    readonly PATH_TRAVERSAL: "PATH_TRAVERSAL";
+    readonly PII_DETECTED: "PII_DETECTED";
+    readonly PRINCIPAL_CONTEXT_MISSING: "PRINCIPAL_CONTEXT_MISSING";
+    readonly PROMPT_INJECTION: "PROMPT_INJECTION";
+    readonly GROUP_SENDER_NOT_ALLOWED: "GROUP_SENDER_NOT_ALLOWED";
+    readonly ROLE_TOOL_NOT_ALLOWED: "ROLE_TOOL_NOT_ALLOWED";
+    readonly ROLLOUT_AUDIT_OVERRIDE: "ROLLOUT_AUDIT_OVERRIDE";
+    readonly RESTRICTED_INFO_ROLE_BLOCKED: "RESTRICTED_INFO_ROLE_BLOCKED";
+    readonly OWNER_APPROVAL_REQUIRED: "OWNER_APPROVAL_REQUIRED";
+    readonly OWNER_APPROVAL_INVALID: "OWNER_APPROVAL_INVALID";
+    readonly OWNER_APPROVAL_EXPIRED: "OWNER_APPROVAL_EXPIRED";
+    readonly OWNER_APPROVAL_REPLAYED: "OWNER_APPROVAL_REPLAYED";
+    readonly RETRIEVAL_SIGNATURE_INVALID: "RETRIEVAL_SIGNATURE_INVALID";
+    readonly RETRIEVAL_TRUST_LEVEL_TOO_LOW: "RETRIEVAL_TRUST_LEVEL_TOO_LOW";
+    readonly RETRIEVAL_TRUST_REQUIRED: "RETRIEVAL_TRUST_REQUIRED";
+    readonly SECRET_DETECTED: "SECRET_DETECTED";
+    readonly SUPPLY_CHAIN_HASH_BLOCKED: "SUPPLY_CHAIN_HASH_BLOCKED";
+    readonly SUPPLY_CHAIN_HASH_REQUIRED: "SUPPLY_CHAIN_HASH_REQUIRED";
+    readonly SUPPLY_CHAIN_UNTRUSTED_SOURCE: "SUPPLY_CHAIN_UNTRUSTED_SOURCE";
+    readonly TOOL_NOT_ALLOWED: "TOOL_NOT_ALLOWED";
+    readonly UNTRUSTED_OUTPUT: "UNTRUSTED_OUTPUT";
+    readonly CONTENT_POLICY_VIOLATION: "CONTENT_POLICY_VIOLATION";
+};
+export type ReasonCode = (typeof REASON_CODES)[keyof typeof REASON_CODES];

package/dist/core/reason-codes.js

@@ -0,0 +1,42 @@
+export const REASON_CODES = {
+    AUDIT_WOULD_DENY: "AUDIT_WOULD_DENY",
+    AUDIT_WOULD_REDACT: "AUDIT_WOULD_REDACT",
+    BUDGET_REQUEST_EXCEEDED: "BUDGET_REQUEST_EXCEEDED",
+    BUDGET_TOOL_CALL_EXCEEDED: "BUDGET_TOOL_CALL_EXCEEDED",
+    COMMAND_ARG_PATTERN_BLOCKED: "COMMAND_ARG_PATTERN_BLOCKED",
+    COMMAND_BINARY_NOT_ALLOWED: "COMMAND_BINARY_NOT_ALLOWED",
+    COMMAND_SHELL_OPERATOR_BLOCKED: "COMMAND_SHELL_OPERATOR_BLOCKED",
+    DESTRUCTIVE_COMMAND: "DESTRUCTIVE_COMMAND",
+    ENGINE_FAILURE: "ENGINE_FAILURE",
+    ENGINE_FAILURE_FAIL_OPEN: "ENGINE_FAILURE_FAIL_OPEN",
+    EXFIL_PATTERN: "EXFIL_PATTERN",
+    INPUT_LIMIT_EXCEEDED: "INPUT_LIMIT_EXCEEDED",
+    INVALID_NETWORK_HOST: "INVALID_NETWORK_HOST",
+    INVALID_NETWORK_URL: "INVALID_NETWORK_URL",
+    NETWORK_HOST_BLOCKED: "NETWORK_HOST_BLOCKED",
+    NETWORK_PRIVATE_BLOCKED: "NETWORK_PRIVATE_BLOCKED",
+    PATH_OUTSIDE_WORKSPACE: "PATH_OUTSIDE_WORKSPACE",
+    PATH_SYMLINK_TRAVERSAL: "PATH_SYMLINK_TRAVERSAL",
+    PATH_TRAVERSAL: "PATH_TRAVERSAL",
+    PII_DETECTED: "PII_DETECTED",
+    PRINCIPAL_CONTEXT_MISSING: "PRINCIPAL_CONTEXT_MISSING",
+    PROMPT_INJECTION: "PROMPT_INJECTION",
+    GROUP_SENDER_NOT_ALLOWED: "GROUP_SENDER_NOT_ALLOWED",
+    ROLE_TOOL_NOT_ALLOWED: "ROLE_TOOL_NOT_ALLOWED",
+    ROLLOUT_AUDIT_OVERRIDE: "ROLLOUT_AUDIT_OVERRIDE",
+    RESTRICTED_INFO_ROLE_BLOCKED: "RESTRICTED_INFO_ROLE_BLOCKED",
+    OWNER_APPROVAL_REQUIRED: "OWNER_APPROVAL_REQUIRED",
+    OWNER_APPROVAL_INVALID: "OWNER_APPROVAL_INVALID",
+    OWNER_APPROVAL_EXPIRED: "OWNER_APPROVAL_EXPIRED",
+    OWNER_APPROVAL_REPLAYED: "OWNER_APPROVAL_REPLAYED",
+    RETRIEVAL_SIGNATURE_INVALID: "RETRIEVAL_SIGNATURE_INVALID",
+    RETRIEVAL_TRUST_LEVEL_TOO_LOW: "RETRIEVAL_TRUST_LEVEL_TOO_LOW",
+    RETRIEVAL_TRUST_REQUIRED: "RETRIEVAL_TRUST_REQUIRED",
+    SECRET_DETECTED: "SECRET_DETECTED",
+    SUPPLY_CHAIN_HASH_BLOCKED: "SUPPLY_CHAIN_HASH_BLOCKED",
+    SUPPLY_CHAIN_HASH_REQUIRED: "SUPPLY_CHAIN_HASH_REQUIRED",
+    SUPPLY_CHAIN_UNTRUSTED_SOURCE: "SUPPLY_CHAIN_UNTRUSTED_SOURCE",
+    TOOL_NOT_ALLOWED: "TOOL_NOT_ALLOWED",
+    UNTRUSTED_OUTPUT: "UNTRUSTED_OUTPUT",
+    CONTENT_POLICY_VIOLATION: "CONTENT_POLICY_VIOLATION"
+};

package/dist/core/retrieval-trust.d.ts

@@ -0,0 +1,2 @@
+import type { GuardrailsConfig, NormalizedEvent, RuleHit } from "./types.js";
+export declare function detectRetrievalTrust(event: NormalizedEvent, config: GuardrailsConfig): RuleHit[];

package/dist/core/retrieval-trust.js

@@ -0,0 +1,65 @@
+import { REASON_CODES } from "./reason-codes.js";
+const HIGH_RISK_TOOLS = new Set([
+    "exec",
+    "process",
+    "write",
+    "edit",
+    "apply_patch",
+    "skills.install"
+]);
+function trustRank(level) {
+    switch (level) {
+        case "high":
+            return 3;
+        case "medium":
+            return 2;
+        case "low":
+            return 1;
+        default:
+            return 0;
+    }
+}
+export function detectRetrievalTrust(event, config) {
+    if (event.phase !== "before_tool_call") {
+        return [];
+    }
+    if (!config.retrievalTrust?.requiredForToolExecution) {
+        return [];
+    }
+    if (!event.toolName || !HIGH_RISK_TOOLS.has(event.toolName)) {
+        return [];
+    }
+    if (event.metadata.sourceType !== "retrieval") {
+        return [];
+    }
+    const hits = [];
+    const trustLevel = event.metadata.trustLevel;
+    if (!trustLevel) {
+        hits.push({
+            ruleId: "retrieval.trust.required",
+            reasonCode: REASON_CODES.RETRIEVAL_TRUST_REQUIRED,
+            decision: "DENY",
+            weight: 0.7
+        });
+        return hits;
+    }
+    const minimumRank = trustRank(config.retrievalTrust.minimumTrustLevel);
+    if (trustRank(trustLevel) < minimumRank) {
+        hits.push({
+            ruleId: "retrieval.trust.level",
+            reasonCode: REASON_CODES.RETRIEVAL_TRUST_LEVEL_TOO_LOW,
+            decision: "DENY",
+            weight: 0.75
+        });
+    }
+    if (config.retrievalTrust.requireSignedSource &&
+        event.metadata.sourceSignatureValid !== true) {
+        hits.push({
+            ruleId: "retrieval.trust.signature",
+            reasonCode: REASON_CODES.RETRIEVAL_SIGNATURE_INVALID,
+            decision: "DENY",
+            weight: 0.8
+        });
+    }
+    return hits;
+}

package/dist/core/scoring.d.ts

@@ -0,0 +1,2 @@
+import type { RuleHit } from "./types.js";
+export declare function aggregateRisk(hits: RuleHit[]): number;

package/dist/core/scoring.js

@@ -0,0 +1,18 @@
+const DECISION_MULTIPLIER = {
+    DENY: 1,
+    REDACT: 0.6
+};
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+export function aggregateRisk(hits) {
+    if (hits.length === 0) {
+        return 0;
+    }
+    const weighted = hits.reduce((acc, hit) => {
+        const multiplier = DECISION_MULTIPLIER[hit.decision] ?? 0.5;
+        return acc + clamp(hit.weight, 0, 1) * multiplier;
+    }, 0);
+    const normalized = 1 - Math.exp(-weighted);
+    return Number(clamp(normalized, 0, 1).toFixed(4));
+}

package/dist/core/supply-chain.d.ts

@@ -0,0 +1,2 @@
+import type { GuardrailsConfig, NormalizedEvent, RuleHit } from "./types.js";
+export declare function detectSupplyChainRisk(event: NormalizedEvent, config: GuardrailsConfig): Promise<RuleHit[]>;

package/dist/core/supply-chain.js

@@ -0,0 +1,78 @@
+import { canonicalizePathCandidate, canonicalizeRoots, isCanonicalPathWithinRoots } from "./path-canonical.js";
+import { REASON_CODES } from "./reason-codes.js";
+function pickString(args, keys) {
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function isRemoteSource(source) {
+    return /^(?:https?:\/\/|git@|ssh:\/\/)/iu.test(source) || source.includes("github.com/");
+}
+function isTrustedSource(source, trustedSources) {
+    const normalized = source.toLowerCase();
+    return trustedSources.some((trusted) => normalized.startsWith(trusted.toLowerCase()));
+}
+export async function detectSupplyChainRisk(event, config) {
+    if (event.phase !== "before_tool_call" || event.toolName !== "skills.install") {
+        return [];
+    }
+    const hits = [];
+    const source = pickString(event.args, ["source", "repo", "repository", "url", "skillSource"]);
+    if (!source || !isTrustedSource(source, config.supplyChain.trustedSkillSources)) {
+        hits.push({
+            ruleId: "supply_chain.untrusted_source",
+            reasonCode: REASON_CODES.SUPPLY_CHAIN_UNTRUSTED_SOURCE,
+            decision: "DENY",
+            weight: 0.85
+        });
+    }
+    const hash = pickString(event.args, ["hash", "sha256", "digest"]);
+    if (source && isRemoteSource(source) && config.supplyChain.requireSkillHash && !hash) {
+        hits.push({
+            ruleId: "supply_chain.hash.required",
+            reasonCode: REASON_CODES.SUPPLY_CHAIN_HASH_REQUIRED,
+            decision: "DENY",
+            weight: 0.8
+        });
+    }
+    if (hash &&
+        config.supplyChain.allowedSkillHashes.length > 0 &&
+        !config.supplyChain.allowedSkillHashes.includes(hash)) {
+        hits.push({
+            ruleId: "supply_chain.hash.allowlist",
+            reasonCode: REASON_CODES.SUPPLY_CHAIN_HASH_BLOCKED,
+            decision: "DENY",
+            weight: 0.8
+        });
+    }
+    const targetDir = pickString(event.args, ["targetDir", "path", "installDir"]);
+    if (targetDir) {
+        const canonicalRoots = await canonicalizeRoots([
+            config.workspaceRoot,
+            ...config.allow.writablePaths
+        ]);
+        const checked = await canonicalizePathCandidate(targetDir, config.workspaceRoot);
+        if (config.pathPolicy.enforceCanonicalRealpath &&
+            !isCanonicalPathWithinRoots(checked.canonicalPath, canonicalRoots)) {
+            hits.push({
+                ruleId: "supply_chain.target_dir.outside_workspace",
+                reasonCode: REASON_CODES.PATH_OUTSIDE_WORKSPACE,
+                decision: "DENY",
+                weight: 0.9
+            });
+        }
+        if (config.pathPolicy.denySymlinkTraversal && checked.traversedSymlink) {
+            hits.push({
+                ruleId: "supply_chain.target_dir.symlink_traversal",
+                reasonCode: REASON_CODES.PATH_SYMLINK_TRAVERSAL,
+                decision: "DENY",
+                weight: 0.9
+            });
+        }
+    }
+    return hits;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,149 @@
+export type Phase = "before_agent_start" | "message_received" | "before_tool_call" | "tool_result_persist" | "agent_end";
+export type Decision = "ALLOW" | "REDACT" | "DENY";
+export type PrincipalRole = "owner" | "admin" | "member" | "unknown";
+export type ApproverRole = Extract<PrincipalRole, "owner" | "admin">;
+export type ChannelType = "dm" | "group" | "thread" | "unknown";
+export type DataClass = "public" | "internal" | "restricted" | "secret";
+export interface AllowedCommand {
+    binary: string;
+    argPattern?: string;
+    allowShellOperators?: boolean;
+}
+export interface PrincipalContext {
+    senderId: string;
+    senderHandle?: string;
+    role: PrincipalRole;
+    channelId?: string;
+    conversationId: string;
+    channelType: ChannelType;
+    mentionedAgent?: boolean;
+    pairedDevice?: boolean;
+}
+export interface ApprovalContext {
+    token?: string;
+    requestId?: string;
+}
+export type RolloutStage = "stage_a_audit" | "stage_b_high_risk_enforce" | "stage_c_full_enforce";
+export interface GuardMetadata extends Record<string, unknown> {
+    sourceType?: "user" | "retrieval" | "tool";
+    sourceId?: string;
+    trustLevel?: "low" | "medium" | "high";
+    sourceSignatureValid?: boolean;
+    principal?: PrincipalContext;
+    approval?: ApprovalContext;
+    dataClass?: DataClass;
+}
+export interface GuardrailsConfig {
+    mode: "enforce" | "audit";
+    failClosed: boolean;
+    workspaceRoot: string;
+    allow: {
+        tools: string[];
+        commands: AllowedCommand[];
+        writablePaths: string[];
+        networkHosts: string[];
+        allowPrivateEgress: boolean;
+    };
+    deny: {
+        commandPatterns: string[];
+        pathPatterns: string[];
+        promptInjectionPatterns: string[];
+        exfiltrationPatterns: string[];
+        shellOperatorPatterns: string[];
+    };
+    redaction: {
+        secretPatterns: string[];
+        piiPatterns: string[];
+        replacement: string;
+        applyInAuditMode: boolean;
+    };
+    limits: {
+        maxInputChars: number;
+        maxToolArgChars: number;
+        maxOutputChars: number;
+        maxRequestsPerMinute: number;
+        maxToolCallsPerMinute: number;
+    };
+    pathPolicy: {
+        enforceCanonicalRealpath: boolean;
+        denySymlinkTraversal: boolean;
+    };
+    supplyChain: {
+        trustedSkillSources: string[];
+        requireSkillHash: boolean;
+        allowedSkillHashes: string[];
+    };
+    retrievalTrust?: {
+        requiredForToolExecution: boolean;
+        minimumTrustLevel: "high" | "medium";
+        requireSignedSource: boolean;
+    };
+    principal: {
+        requireContext: boolean;
+        ownerIds: string[];
+        adminIds: string[];
+        failUnknownInGroup: boolean;
+    };
+    authorization: {
+        defaultEffect: "deny" | "allow";
+        requireMentionInGroups: boolean;
+        restrictedTools: string[];
+        restrictedDataClasses: Array<Exclude<DataClass, "public">>;
+        toolAllowByRole: Record<PrincipalRole, string[]>;
+    };
+    approval: {
+        enabled: boolean;
+        ttlSeconds: number;
+        requireForTools: string[];
+        requireForDataClasses: Array<"restricted" | "secret">;
+        ownerQuorum: number;
+        bindToConversation: boolean;
+        storagePath?: string;
+    };
+    tenancy: {
+        budgetKeyMode: "agent" | "agent+principal+conversation";
+        redactCrossPrincipalOutput: boolean;
+    };
+    rollout: {
+        stage: RolloutStage;
+        highRiskTools: string[];
+    };
+    monitoring: {
+        falsePositiveThresholdPct: number;
+        consecutiveDaysForTuning: number;
+    };
+}
+export interface GuardEvent {
+    phase: Phase;
+    agentId: string;
+    toolName?: string;
+    content?: string;
+    args?: Record<string, unknown>;
+    metadata?: GuardMetadata;
+}
+export interface GuardDecision {
+    decision: Decision;
+    reasonCodes: string[];
+    riskScore: number;
+    redactedContent?: string;
+    approvalChallenge?: {
+        requestId: string;
+        expiresAt: number;
+        reason: string;
+        requiredRole: ApproverRole;
+    };
+    telemetry: {
+        matchedRules: string[];
+        elapsedMs: number;
+    };
+}
+export interface RuleHit {
+    ruleId: string;
+    reasonCode: string;
+    decision: Exclude<Decision, "ALLOW">;
+    weight: number;
+}
+export interface NormalizedEvent extends GuardEvent {
+    args: Record<string, unknown>;
+    metadata: GuardMetadata;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { GuardrailsEngine } from "./core/engine.js";
+export { REASON_CODES } from "./core/reason-codes.js";
+export type { ApproverRole, ChannelType, DataClass, Decision, PrincipalContext, PrincipalRole, RolloutStage, GuardDecision, GuardEvent, GuardrailsConfig, Phase } from "./core/types.js";
+export { UNKNOWN_SENDER, UNKNOWN_CONVERSATION } from "./core/identity.js";
+export { createDefaultConfig, mergeConfig } from "./rules/default-policy.js";
+export { createOpenClawGuardrailsPlugin } from "./plugin/openclaw-adapter.js";
+export { registerOpenClawGuardrails } from "./plugin/openclaw-extension.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { GuardrailsEngine } from "./core/engine.js";
+export { REASON_CODES } from "./core/reason-codes.js";
+export { UNKNOWN_SENDER, UNKNOWN_CONVERSATION } from "./core/identity.js";
+export { createDefaultConfig, mergeConfig } from "./rules/default-policy.js";
+export { createOpenClawGuardrailsPlugin } from "./plugin/openclaw-adapter.js";
+export { registerOpenClawGuardrails } from "./plugin/openclaw-extension.js";

package/dist/plugin/openclaw-adapter.d.ts

@@ -0,0 +1,41 @@
+import type { ApproverRole, ChannelType, DataClass, GuardDecision, GuardrailsConfig, PrincipalRole } from "../core/types.js";
+export interface OpenClawContext extends Record<string, unknown> {
+    agentId?: string;
+    toolName?: string;
+    args?: Record<string, unknown>;
+    content?: string;
+    message?: string;
+    output?: string;
+    prompt?: string;
+    systemPrompt?: string;
+    senderId?: string;
+    senderHandle?: string;
+    role?: PrincipalRole;
+    conversationId?: string;
+    channelId?: string;
+    channelType?: ChannelType;
+    mentionedAgent?: boolean;
+    pairedDevice?: boolean;
+    dataClass?: DataClass;
+    metadata?: Record<string, unknown>;
+}
+export interface OpenClawHookResult extends OpenClawContext {
+    blocked?: boolean;
+    reasonCodes?: string[];
+    guardrails?: {
+        decision: GuardDecision;
+    };
+}
+export interface OpenClawPlugin {
+    name: string;
+    version: string;
+    approveRequest: (requestId: string, approverId: string, approverRole: ApproverRole) => string | null;
+    hooks: {
+        before_agent_start: (context: OpenClawContext) => Promise<OpenClawHookResult>;
+        message_received: (context: OpenClawContext) => Promise<OpenClawHookResult>;
+        before_tool_call: (context: OpenClawContext) => Promise<OpenClawHookResult>;
+        tool_result_persist: (context: OpenClawContext) => Promise<OpenClawHookResult>;
+        agent_end: (context: OpenClawContext) => Promise<OpenClawHookResult>;
+    };
+}
+export declare function createOpenClawGuardrailsPlugin(overrides?: Partial<GuardrailsConfig>): OpenClawPlugin;