@safefence/openclaw-guardrails 0.3.0

package/README.md

@@ -0,0 +1,182 @@
+# OpenClaw Guardrails v3
+
+Native TypeScript security kernel for OpenClaw (`>=2026.2.25`) with deterministic local enforcement, principal-aware authorization, and owner approval for group/multi-user safety.
+
+## Repository Context
+
+- Root project overview: [`../../README.md`](../../README.md)
+- Research and threat analysis: [`../../docs/openclaw-llm-security-research.md`](../../docs/openclaw-llm-security-research.md)
+- OWASP LLM coverage mapping: see the research doc above.
+
+## Core Model
+
+- One engine path for all phases (`GuardrailsEngine`).
+- Declarative policy + deterministic reason codes.
+- Monotonic precedence: `DENY > REDACT > ALLOW`.
+- No runtime dependency on remote inference or policy services.
+- Audit mode still applies redaction by default.
+
+## v3 Security Features
+
+- Principal-aware identity model (`owner/admin/member/unknown`).
+- **Anti-spoofing**: privileged roles (`owner`/`admin`) are derived exclusively from `principal.ownerIds`/`adminIds` in config — caller-supplied `metadata.role` values of `"owner"` or `"admin"` are downgraded to `"member"`.
+- Group-aware authorization (mention-gating + role tool policy).
+- One-time owner approval challenges with TTL, action digest binding, anti-replay, and requester identity binding.
+- Optional persistent approval store (`approval.storagePath`) with storage path validation (must be within `workspaceRoot`) and expired record pruning.
+- **Reason code sanitization**: sensitive internal reason codes (e.g. `PROMPT_INJECTION`) are replaced with `CONTENT_POLICY_VIOLATION` in client-facing output to prevent detection fingerprinting.
+- Principal-partitioned budgets (`agent + principal + conversation`).
+- Restricted-info redaction for non-privileged group principals.
+- Rollout controls (`stage_a_audit`, `stage_b_high_risk_enforce`, `stage_c_full_enforce`).
+- Monitoring snapshot with false-positive threshold signaling.
+
+## Architecture
+
+```
+src/
+├── index.ts                          # Public exports
+├── core/
+│   ├── engine.ts                     # Ordered detector pipeline + final decisioning
+│   ├── identity.ts                   # Principal normalization + anti-spoofing
+│   ├── authorization.ts              # Role/channel/data-class policy evaluation
+│   ├── approval.ts                   # Owner approval broker
+│   ├── approval-store.ts             # Persistent approval state + pruning
+│   ├── budget-store.ts               # Per-principal budget tracking
+│   ├── normalize.ts                  # Event normalization
+│   ├── event-utils.ts                # Guard event helpers
+│   ├── scoring.ts                    # Risk score aggregation
+│   ├── reason-codes.ts               # Canonical reason code constants
+│   ├── types.ts                      # Core type definitions
+│   ├── command-parse.ts              # Command string parsing
+│   ├── network-guard.ts              # Network host/URL validation
+│   ├── path-canonical.ts             # Path canonicalization + symlink checks
+│   ├── retrieval-trust.ts            # Retrieval trust level evaluation
+│   ├── supply-chain.ts               # Skill source + hash policy
+│   └── detectors/                    # Security detector modules
+├── plugin/
+│   ├── openclaw-adapter.ts           # OpenClaw hook adapter + summary telemetry
+│   └── openclaw-extension.ts         # Plugin entry point (registerOpenClawGuardrails)
+├── redaction/
+│   └── redact.ts                     # Secret/PII redaction engine
+└── rules/
+    ├── default-policy.ts             # Default config factory + merge
+    └── patterns.ts                   # Detection pattern definitions
+```
+
+## Owner Approval Flow
+
+1. Member in group requests a restricted action.
+2. Engine returns `DENY` with `OWNER_APPROVAL_REQUIRED` and `approvalChallenge`.
+3. Owner/admin approves out-of-band and issues one-time token.
+4. Caller retries with `metadata.approval.token` (and optionally `requestId`).
+5. Engine verifies TTL, digest, conversation binding, requester identity binding, requestId (when provided), and replay status.
+6. Valid token allows reevaluation and execution.
+
+Approval works across all channel types (DM, group, thread), not just groups — group context merely triggers the initial challenge for restricted actions.
+
+## Install in OpenClaw
+
+```bash
+openclaw plugins install @safefence/openclaw-guardrails
+openclaw plugins list
+```
+
+### Configure `openclaw.config.ts`
+
+```ts
+import { defineConfig } from "openclaw/config";
+
+export default defineConfig({
+  plugins: {
+    entries: {
+      "openclaw-guardrails": {
+        enabled: true,
+        config: {
+          workspaceRoot: "/workspace/project",
+          mode: "enforce",
+          failClosed: true
+        }
+      }
+    }
+  }
+});
+```
+
+After changing plugin install/config, restart the OpenClaw service or gateway process so hook registration is reloaded.
+
+## Usage
+
+Three main entry points:
+
+```ts
+// 1. Plugin factory — returns an OpenClaw-compatible plugin with hook handlers
+import { createOpenClawGuardrailsPlugin } from "@safefence/openclaw-guardrails";
+
+const plugin = createOpenClawGuardrailsPlugin({
+  workspaceRoot: "/workspace/project",
+  mode: "enforce",
+  failClosed: true
+});
+
+// Out-of-band owner approval
+const token = plugin.approveRequest(requestId, "owner-user-id", "owner");
+
+// 2. OpenClaw extension entry — auto-registers all hooks from plugin config
+import { registerOpenClawGuardrails } from "@safefence/openclaw-guardrails";
+registerOpenClawGuardrails(api);
+
+// 3. Engine directly — for custom integrations outside OpenClaw
+import { GuardrailsEngine } from "@safefence/openclaw-guardrails";
+const engine = new GuardrailsEngine(config);
+const decision = await engine.evaluate(event);
+```
+
+**Exported types**: `ApproverRole`, `ChannelType`, `DataClass`, `Decision`, `PrincipalContext`, `PrincipalRole`, `RolloutStage`, `GuardDecision`, `GuardEvent`, `GuardrailsConfig`, `Phase`.
+
+**Exported constants**: `REASON_CODES`, `UNKNOWN_SENDER`, `UNKNOWN_CONVERSATION`.
+
+**Config helpers**: `createDefaultConfig()`, `mergeConfig(base, overrides)`.
+
+## Config Example (Minimal Overrides)
+
+Most config has secure defaults. Override only what you need:
+
+```ts
+const plugin = createOpenClawGuardrailsPlugin({
+  workspaceRoot: "/workspace/project",
+  principal: {
+    ownerIds: ["owner-user-id"],
+    adminIds: ["admin-user-id"]
+  },
+  approval: {
+    enabled: true,
+    storagePath: "/workspace/project/.openclaw/approval-store.json"
+  }
+});
+```
+
+See the [research doc](../../docs/openclaw-llm-security-research.md) for a full config reference with all fields.
+
+## Migration (v2 -> v3)
+
+1. Add `principal`, `authorization`, `approval`, and `tenancy` blocks.
+2. Pass sender/channel metadata in hook contexts (`senderId`, `conversationId`, `channelType`, `mentionedAgent`).
+3. Integrate owner approval handling via `approvalChallenge.requestId` + `plugin.approveRequest(...)`.
+4. Keep secure defaults unless you have a validated exception.
+5. Use `rollout.stage` for staged deployment and monitor `metadata.guardrailsMonitoring`.
+6. **Breaking**: callers can no longer self-assign privileged roles (`owner`/`admin`) via `metadata.role`. Privileged roles are now derived exclusively from `principal.ownerIds`/`adminIds` in config. Any caller-supplied `"owner"` or `"admin"` role is downgraded to `"member"`.
+
+## Limitations
+
+- Deterministic patterns are not a full semantic jailbreak solution.
+- Persistent approval store prunes expired records on write; replayed tokens are still caught within the TTL window. Approval tokens survive restarts when `storagePath` is configured.
+- Retrieval trust still depends on upstream metadata quality.
+
+## Development
+
+```bash
+cd packages/openclaw-guardrails
+npm install
+npm test
+npm run test:coverage
+npm run build
+```

package/dist/core/approval-store.d.ts

@@ -0,0 +1,29 @@
+import type { ApproverRole } from "./types.js";
+export interface ApprovalRecord {
+    requestId: string;
+    actionDigest: string;
+    requesterId: string;
+    conversationId: string;
+    requiredRole: ApproverRole;
+    reason: string;
+    createdAt: number;
+    expiresAt: number;
+    token?: string;
+    approvedBy?: string;
+    approverIds: string[];
+    usedAt?: number;
+}
+export declare class ApprovalStore {
+    private readonly byRequestId;
+    private readonly requestIdByToken;
+    private readonly storagePath?;
+    constructor(storagePath?: string, allowedRoot?: string);
+    save(record: ApprovalRecord): void;
+    getByRequestId(requestId: string): ApprovalRecord | undefined;
+    getByToken(token: string): ApprovalRecord | undefined;
+    setToken(requestId: string, token: string, approvedBy: string): ApprovalRecord | undefined;
+    markUsed(requestId: string, usedAt: number): ApprovalRecord | undefined;
+    private pruneExpired;
+    private loadFromDisk;
+    private flushToDisk;
+}

package/dist/core/approval-store.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import path from "node:path";
+export class ApprovalStore {
+    byRequestId = new Map();
+    requestIdByToken = new Map();
+    storagePath;
+    constructor(storagePath, allowedRoot) {
+        if (storagePath && allowedRoot) {
+            const resolved = path.resolve(storagePath);
+            const resolvedRoot = path.resolve(allowedRoot);
+            if (!resolved.startsWith(resolvedRoot + path.sep) && resolved !== resolvedRoot) {
+                throw new Error(`storagePath must be within ${resolvedRoot}`);
+            }
+        }
+        this.storagePath = storagePath;
+        this.loadFromDisk();
+    }
+    save(record) {
+        this.byRequestId.set(record.requestId, record);
+        if (record.token) {
+            this.requestIdByToken.set(record.token, record.requestId);
+        }
+        this.flushToDisk();
+    }
+    getByRequestId(requestId) {
+        return this.byRequestId.get(requestId);
+    }
+    getByToken(token) {
+        const requestId = this.requestIdByToken.get(token);
+        if (!requestId) {
+            return undefined;
+        }
+        return this.byRequestId.get(requestId);
+    }
+    setToken(requestId, token, approvedBy) {
+        const record = this.byRequestId.get(requestId);
+        if (!record) {
+            return undefined;
+        }
+        if (record.token) {
+            this.requestIdByToken.delete(record.token);
+        }
+        const updated = {
+            ...record,
+            token,
+            approvedBy
+        };
+        this.byRequestId.set(requestId, updated);
+        this.requestIdByToken.set(token, requestId);
+        this.flushToDisk();
+        return updated;
+    }
+    markUsed(requestId, usedAt) {
+        const record = this.byRequestId.get(requestId);
+        if (!record) {
+            return undefined;
+        }
+        const updated = {
+            ...record,
+            usedAt
+        };
+        this.byRequestId.set(requestId, updated);
+        this.pruneExpired(usedAt);
+        this.flushToDisk();
+        return updated;
+    }
+    pruneExpired(nowMs) {
+        for (const [id, record] of this.byRequestId) {
+            // Only prune records that are both expired AND used (or expired without a token).
+            // Used-but-not-expired records must be retained for replay detection.
+            if (record.expiresAt <= nowMs) {
+                if (record.token) {
+                    this.requestIdByToken.delete(record.token);
+                }
+                this.byRequestId.delete(id);
+            }
+        }
+    }
+    loadFromDisk() {
+        if (!this.storagePath) {
+            return;
+        }
+        try {
+            const raw = fs.readFileSync(this.storagePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed)) {
+                return;
+            }
+            const nowMs = Date.now();
+            for (const record of parsed) {
+                if (!record || typeof record.requestId !== "string") {
+                    continue;
+                }
+                if (record.expiresAt <= nowMs || record.usedAt) {
+                    continue;
+                }
+                this.byRequestId.set(record.requestId, record);
+                if (record.token) {
+                    this.requestIdByToken.set(record.token, record.requestId);
+                }
+            }
+        }
+        catch {
+            // Fail closed at higher layers; ignore corrupted persistence artifacts here.
+        }
+    }
+    flushToDisk() {
+        if (!this.storagePath) {
+            return;
+        }
+        try {
+            const dir = path.dirname(this.storagePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const nowMs = Date.now();
+            const records = Array.from(this.byRequestId.values()).filter((record) => !record.usedAt && record.expiresAt > nowMs);
+            const tempPath = `${this.storagePath}.tmp`;
+            fs.writeFileSync(tempPath, JSON.stringify(records, null, 2), "utf8");
+            fs.renameSync(tempPath, this.storagePath);
+        }
+        catch {
+            // Best-effort durability; in-memory state remains authoritative for this process.
+        }
+    }
+}

package/dist/core/approval.d.ts

@@ -0,0 +1,18 @@
+import type { ApprovalRequirement } from "./detectors/types.js";
+import { ApprovalStore } from "./approval-store.js";
+import type { GuardDecision, GuardrailsConfig, NormalizedEvent, PrincipalRole } from "./types.js";
+export type ApprovalVerifyResult = "valid" | "invalid" | "expired" | "replayed";
+export interface ApprovalChallengeInput {
+    event: NormalizedEvent;
+    requirement: ApprovalRequirement;
+    nowMs?: number;
+}
+export declare function buildApprovalActionDigest(event: NormalizedEvent): string;
+export declare class ApprovalBroker {
+    private readonly config;
+    private readonly store;
+    constructor(config: GuardrailsConfig, store?: ApprovalStore);
+    createChallenge({ event, requirement, nowMs }: ApprovalChallengeInput): GuardDecision["approvalChallenge"];
+    approveRequest(requestId: string, approverId: string, approverRole: PrincipalRole, nowMs?: number): string | null;
+    verifyAndConsumeToken(token: string, event: NormalizedEvent, requestId?: string, nowMs?: number): ApprovalVerifyResult;
+}

package/dist/core/approval.js

@@ -0,0 +1,129 @@
+import crypto from "node:crypto";
+import { ApprovalStore } from "./approval-store.js";
+import { UNKNOWN_SENDER, UNKNOWN_CONVERSATION } from "./identity.js";
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+            const sorted = {};
+            for (const k of Object.keys(v).sort()) {
+                sorted[k] = v[k];
+            }
+            return sorted;
+        }
+        return v;
+    });
+}
+export function buildApprovalActionDigest(event) {
+    const principal = event.metadata.principal;
+    const canonical = stableStringify({
+        toolName: event.toolName ?? "",
+        args: event.args ?? {},
+        dataClass: event.metadata.dataClass ?? "public",
+        conversationId: principal?.conversationId ?? UNKNOWN_CONVERSATION,
+        requesterId: principal?.senderId ?? UNKNOWN_SENDER
+    });
+    return crypto.createHash("sha256").update(canonical).digest("hex");
+}
+function canRoleApprove(requiredRole, approverRole) {
+    if (requiredRole === "owner") {
+        return approverRole === "owner";
+    }
+    return approverRole === "owner" || approverRole === "admin";
+}
+export class ApprovalBroker {
+    config;
+    store;
+    constructor(config, store) {
+        this.config = config;
+        this.store = store ?? new ApprovalStore(config.approval.storagePath, config.workspaceRoot);
+    }
+    createChallenge({ event, requirement, nowMs = Date.now() }) {
+        const principal = event.metadata.principal;
+        const requestId = crypto.randomUUID();
+        const expiresAt = nowMs + this.config.approval.ttlSeconds * 1_000;
+        const actionDigest = buildApprovalActionDigest(event);
+        const conversationId = principal?.conversationId ?? UNKNOWN_CONVERSATION;
+        const requesterId = principal?.senderId ?? UNKNOWN_SENDER;
+        const record = {
+            requestId,
+            actionDigest,
+            requesterId,
+            conversationId,
+            requiredRole: requirement.requiredRole,
+            reason: requirement.reason,
+            createdAt: nowMs,
+            expiresAt,
+            approverIds: []
+        };
+        this.store.save(record);
+        return {
+            requestId,
+            expiresAt,
+            reason: requirement.reason,
+            requiredRole: requirement.requiredRole
+        };
+    }
+    approveRequest(requestId, approverId, approverRole, nowMs = Date.now()) {
+        const record = this.store.getByRequestId(requestId);
+        if (!record) {
+            return null;
+        }
+        if (record.expiresAt <= nowMs) {
+            return null;
+        }
+        if (!canRoleApprove(record.requiredRole, approverRole)) {
+            return null;
+        }
+        if (record.requesterId === approverId) {
+            return null;
+        }
+        const hasApproved = record.approverIds.includes(approverId);
+        const approverIds = hasApproved
+            ? record.approverIds
+            : [...record.approverIds, approverId];
+        const quorum = Math.max(1, this.config.approval.ownerQuorum);
+        if (approverIds.length < quorum) {
+            this.store.save({
+                ...record,
+                approverIds
+            });
+            return null;
+        }
+        if (record.token) {
+            return record.usedAt ? null : record.token;
+        }
+        const token = `apr_${crypto.randomUUID().replace(/-/g, "")}`;
+        this.store.setToken(requestId, token, approverIds.join(","));
+        return token;
+    }
+    verifyAndConsumeToken(token, event, requestId, nowMs = Date.now()) {
+        const record = this.store.getByToken(token);
+        if (!record) {
+            return "invalid";
+        }
+        if (record.expiresAt <= nowMs) {
+            return "expired";
+        }
+        if (record.usedAt) {
+            return "replayed";
+        }
+        if (requestId && record.requestId !== requestId) {
+            return "invalid";
+        }
+        const principal = event.metadata.principal;
+        const requesterId = principal?.senderId ?? UNKNOWN_SENDER;
+        if (record.requesterId !== requesterId) {
+            return "invalid";
+        }
+        if (this.config.approval.bindToConversation &&
+            record.conversationId !== (principal?.conversationId ?? UNKNOWN_CONVERSATION)) {
+            return "invalid";
+        }
+        const digest = buildApprovalActionDigest(event);
+        if (record.actionDigest !== digest) {
+            return "invalid";
+        }
+        this.store.markUsed(record.requestId, nowMs);
+        return "valid";
+    }
+}

package/dist/core/authorization.d.ts

@@ -0,0 +1,7 @@
+import type { GuardrailsConfig, NormalizedEvent, RuleHit } from "./types.js";
+import type { ApprovalRequirement } from "./detectors/types.js";
+export interface AuthorizationResult {
+    hits: RuleHit[];
+    approvalRequirement?: ApprovalRequirement;
+}
+export declare function evaluateAuthorization(event: NormalizedEvent, config: GuardrailsConfig): AuthorizationResult;

package/dist/core/authorization.js

@@ -0,0 +1,114 @@
+import { REASON_CODES } from "./reason-codes.js";
+function isOwnerRole(role) {
+    return role === "owner";
+}
+function shouldAllowByDefault(config) {
+    return config.authorization.defaultEffect === "allow";
+}
+function isRestrictedDataClass(dataClass, config) {
+    return config.authorization.restrictedDataClasses.includes(dataClass);
+}
+function dataClassNeedsApproval(dataClass, config) {
+    return (dataClass === "restricted" || dataClass === "secret"
+        ? config.approval.requireForDataClasses.includes(dataClass)
+        : false);
+}
+export function evaluateAuthorization(event, config) {
+    const hits = [];
+    const principal = event.metadata.principal;
+    if (!principal) {
+        return {
+            hits: [
+                {
+                    ruleId: "principal.context.missing",
+                    reasonCode: REASON_CODES.PRINCIPAL_CONTEXT_MISSING,
+                    decision: "DENY",
+                    weight: 0.9
+                }
+            ]
+        };
+    }
+    if (config.principal.requireContext &&
+        event.metadata.principalMissingContext &&
+        principal.channelType === "group") {
+        hits.push({
+            ruleId: "principal.context.group_missing",
+            reasonCode: REASON_CODES.PRINCIPAL_CONTEXT_MISSING,
+            decision: "DENY",
+            weight: 0.95
+        });
+    }
+    if (principal.channelType === "group") {
+        if (config.principal.failUnknownInGroup && principal.role === "unknown") {
+            hits.push({
+                ruleId: "principal.group.unknown_sender",
+                reasonCode: REASON_CODES.GROUP_SENDER_NOT_ALLOWED,
+                decision: "DENY",
+                weight: 0.95
+            });
+        }
+        if (config.authorization.requireMentionInGroups &&
+            principal.mentionedAgent !== true &&
+            (event.phase === "message_received" || event.phase === "before_tool_call")) {
+            hits.push({
+                ruleId: "principal.group.require_mention",
+                reasonCode: REASON_CODES.GROUP_SENDER_NOT_ALLOWED,
+                decision: "DENY",
+                weight: 0.7
+            });
+        }
+    }
+    let approvalRequirement;
+    if (event.phase === "before_tool_call" && event.toolName) {
+        const toolName = event.toolName;
+        const roleAllowlist = config.authorization.toolAllowByRole[principal.role] ?? [];
+        const isRestrictedTool = config.authorization.restrictedTools.includes(toolName);
+        const roleAllowsTool = roleAllowlist.includes(toolName);
+        if (isRestrictedTool &&
+            !roleAllowsTool) {
+            const needsApproval = config.approval.enabled &&
+                config.approval.requireForTools.includes(toolName) &&
+                principal.role !== "owner";
+            if (needsApproval) {
+                approvalRequirement = {
+                    reason: `Owner approval required for restricted tool: ${toolName}`,
+                    requiredRole: "owner"
+                };
+            }
+            else if (!shouldAllowByDefault(config)) {
+                hits.push({
+                    ruleId: "authorization.role.tool_restricted",
+                    reasonCode: REASON_CODES.ROLE_TOOL_NOT_ALLOWED,
+                    decision: "DENY",
+                    weight: 0.9
+                });
+            }
+        }
+    }
+    if (event.phase === "before_tool_call") {
+        const dataClass = (event.metadata.dataClass ?? "public");
+        if (isRestrictedDataClass(dataClass, config) && !isOwnerRole(principal.role)) {
+            const needsApproval = config.approval.enabled &&
+                dataClassNeedsApproval(dataClass, config) &&
+                principal.role !== "owner";
+            if (needsApproval && !approvalRequirement) {
+                approvalRequirement = {
+                    reason: `Owner approval required for ${dataClass} data access`,
+                    requiredRole: "owner"
+                };
+            }
+            else if (!needsApproval && !shouldAllowByDefault(config)) {
+                hits.push({
+                    ruleId: "authorization.data_class.restricted",
+                    reasonCode: REASON_CODES.RESTRICTED_INFO_ROLE_BLOCKED,
+                    decision: "DENY",
+                    weight: 0.9
+                });
+            }
+        }
+    }
+    return {
+        hits,
+        approvalRequirement
+    };
+}

package/dist/core/budget-store.d.ts

@@ -0,0 +1,6 @@
+export type BudgetKind = "request" | "toolCall";
+export declare class BudgetStore {
+    private readonly perKey;
+    checkAndRecord(subjectKey: string, kind: BudgetKind, limitPerMinute: number, nowMs?: number): boolean;
+    private getOrCreateAgentBudget;
+}

package/dist/core/budget-store.js

@@ -0,0 +1,33 @@
+export class BudgetStore {
+    perKey = new Map();
+    checkAndRecord(subjectKey, kind, limitPerMinute, nowMs = Date.now()) {
+        if (limitPerMinute <= 0) {
+            return true;
+        }
+        const budget = this.getOrCreateAgentBudget(subjectKey);
+        const bucket = kind === "request" ? budget.requests : budget.toolCalls;
+        const windowStart = nowMs - 60_000;
+        while (bucket.length > 0 && bucket[0] < windowStart) {
+            bucket.shift();
+        }
+        bucket.push(nowMs);
+        const exceeded = bucket.length > limitPerMinute;
+        // Prune empty entries to prevent unbounded Map growth from high-cardinality keys.
+        if (budget.requests.length === 0 && budget.toolCalls.length === 0) {
+            this.perKey.delete(subjectKey);
+        }
+        return exceeded;
+    }
+    getOrCreateAgentBudget(subjectKey) {
+        const current = this.perKey.get(subjectKey);
+        if (current) {
+            return current;
+        }
+        const created = {
+            requests: [],
+            toolCalls: []
+        };
+        this.perKey.set(subjectKey, created);
+        return created;
+    }
+}

package/dist/core/command-parse.d.ts

@@ -0,0 +1,11 @@
+export interface ParsedCommand {
+    raw: string;
+    binary: string;
+    args: string;
+    tokens: string[];
+    hasShellOperators: boolean;
+    operatorHits: string[];
+}
+export declare function extractCommandFromArgs(args: Record<string, unknown>): string | undefined;
+export declare function extractUrlCandidatesFromCommand(command: string): string[];
+export declare function parseCommand(rawCommand: string, shellOperatorPatterns: string[]): ParsedCommand;