securityclaw 0.0.1

package/src/domain/services/shell_filesystem_inference.ts

@@ -0,0 +1,360 @@
+export type FilesystemOperation = "list" | "read" | "search" | "write" | "delete" | "archive";
+
+export type ShellFilesystemSemantic = {
+  operation: FilesystemOperation;
+  toolName: `filesystem.${FilesystemOperation}`;
+};
+
+const SEGMENT_SPLITTER = /&&|\|\||;|\||\n/;
+const TOKEN_PATTERN = /"[^"]*"|'[^']*'|`[^`]*`|[^\s]+/g;
+const ENV_ASSIGNMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=.*/;
+const WRITE_REDIRECTION_PATTERN = /(^|[^<])(?:>>?|1>>?|2>>?)\s*(?![&|])/;
+
+const WRAPPER_COMMANDS = new Set([
+  "sudo",
+  "doas",
+  "command",
+  "builtin",
+  "env",
+  "nohup",
+  "time",
+  "stdbuf",
+  "nice",
+  "ionice",
+]);
+
+const LIST_COMMANDS = new Set([
+  "ls",
+  "dir",
+  "tree",
+  "fd",
+  "fdfind",
+  "du",
+]);
+
+const READ_COMMANDS = new Set([
+  "cat",
+  "head",
+  "tail",
+  "less",
+  "more",
+  "bat",
+  "stat",
+  "file",
+  "readlink",
+  "realpath",
+  "wc",
+  "strings",
+]);
+
+const SEARCH_COMMANDS = new Set([
+  "grep",
+  "egrep",
+  "fgrep",
+  "rg",
+  "ripgrep",
+  "ack",
+  "ag",
+  "awk",
+  "jq",
+]);
+
+const WRITE_COMMANDS = new Set([
+  "touch",
+  "cp",
+  "mv",
+  "mkdir",
+  "mktemp",
+  "install",
+  "ln",
+  "chmod",
+  "chown",
+  "chgrp",
+  "truncate",
+  "tee",
+  "dd",
+  "rsync",
+  "scp",
+]);
+
+const DELETE_COMMANDS = new Set([
+  "rm",
+  "unlink",
+  "rmdir",
+  "shred",
+]);
+
+const ARCHIVE_COMMANDS = new Set([
+  "zip",
+  "tar",
+  "gzip",
+  "gunzip",
+  "bzip2",
+  "bunzip2",
+  "xz",
+  "unxz",
+  "7z",
+  "7za",
+  "zstd",
+  "unzstd",
+]);
+
+const FILE_METADATA_COMMANDS = new Set([
+  "test",
+  "[",
+  "basename",
+  "dirname",
+]);
+
+const OPERATION_PRIORITY: Record<FilesystemOperation, number> = {
+  list: 1,
+  read: 2,
+  search: 3,
+  archive: 4,
+  write: 5,
+  delete: 6,
+};
+
+function toTokens(segment: string): string[] {
+  return segment.match(TOKEN_PATTERN) ?? [];
+}
+
+function normalizeToken(token: string): string {
+  const unquoted = token.replace(/^["'`]+|["'`]+$/g, "");
+  const basename = unquoted.includes("/") ? (unquoted.split("/").at(-1) ?? unquoted) : unquoted;
+  return basename.toLowerCase();
+}
+
+function resolvePrimaryCommand(tokens: string[]): { command?: string; remaining: string[] } {
+  let index = 0;
+  while (index < tokens.length) {
+    const raw = tokens[index];
+    const normalized = normalizeToken(raw);
+    if (!normalized || normalized === "(" || normalized === ")") {
+      index += 1;
+      continue;
+    }
+    if (ENV_ASSIGNMENT_PATTERN.test(normalized)) {
+      index += 1;
+      continue;
+    }
+    if (WRAPPER_COMMANDS.has(normalized)) {
+      index += 1;
+      while (index < tokens.length && (tokens[index].startsWith("-") || ENV_ASSIGNMENT_PATTERN.test(tokens[index]))) {
+        index += 1;
+      }
+      continue;
+    }
+    return {
+      command: normalized,
+      remaining: tokens.slice(index + 1),
+    };
+  }
+  return { remaining: [] };
+}
+
+function classifyGitOperation(remaining: string[]): FilesystemOperation | undefined {
+  let subcommand: string | undefined;
+  let skipNext = false;
+
+  for (const token of remaining) {
+    if (skipNext) {
+      skipNext = false;
+      continue;
+    }
+    const normalized = normalizeToken(token);
+    if (!normalized) {
+      continue;
+    }
+    if (normalized === "-c" || normalized === "--git-dir" || normalized === "--work-tree") {
+      skipNext = true;
+      continue;
+    }
+    if (normalized === "-c" || normalized.startsWith("-c")) {
+      continue;
+    }
+    if (normalized === "-C" || normalized === "--super-prefix" || normalized === "--exec-path") {
+      skipNext = true;
+      continue;
+    }
+    if (normalized.startsWith("-")) {
+      continue;
+    }
+    subcommand = normalized;
+    break;
+  }
+
+  if (!subcommand) {
+    return undefined;
+  }
+  if (subcommand === "grep") {
+    return "search";
+  }
+  if (["status", "log", "show", "diff", "cat-file", "blame"].includes(subcommand)) {
+    return "read";
+  }
+  if (["ls-files"].includes(subcommand)) {
+    return "list";
+  }
+  if (["archive"].includes(subcommand)) {
+    return "archive";
+  }
+  if (["rm", "clean"].includes(subcommand)) {
+    return "delete";
+  }
+  if (
+    [
+      "add",
+      "mv",
+      "commit",
+      "checkout",
+      "restore",
+      "reset",
+      "revert",
+      "cherry-pick",
+      "merge",
+      "rebase",
+      "am",
+      "apply",
+      "stash",
+      "pull",
+      "clone",
+    ].includes(subcommand)
+  ) {
+    return "write";
+  }
+  return undefined;
+}
+
+function classifyFindOperation(segment: string): FilesystemOperation {
+  const normalized = segment.toLowerCase();
+  if (/\s-delete(\s|$)/.test(normalized) || /-exec\s+[^\n;]*\brm\b/.test(normalized)) {
+    return "delete";
+  }
+  if (/-exec\s+[^\n;]*\b(cp|mv|chmod|chown|touch|mkdir)\b/.test(normalized)) {
+    return "write";
+  }
+  if (/\s-(name|iname|path|ipath|regex|iregex)\b/.test(normalized)) {
+    return "search";
+  }
+  return "list";
+}
+
+function classifyTarOperation(segment: string): FilesystemOperation {
+  const normalized = segment.toLowerCase();
+  if (/(^|\s)--extract(\s|$)|(^|\s)-[^\s]*x/.test(normalized)) {
+    return "write";
+  }
+  if (/(^|\s)--list(\s|$)|(^|\s)-[^\s]*t/.test(normalized)) {
+    return "list";
+  }
+  return "archive";
+}
+
+function classifyArchiveCommand(command: string, segment: string): FilesystemOperation {
+  if (command === "tar") {
+    return classifyTarOperation(segment);
+  }
+  if (["gunzip", "bunzip2", "unxz", "unzstd"].includes(command)) {
+    return "write";
+  }
+  return "archive";
+}
+
+function classifySegment(segment: string): FilesystemOperation | undefined {
+  const tokens = toTokens(segment);
+  if (tokens.length === 0) {
+    return undefined;
+  }
+
+  const { command, remaining } = resolvePrimaryCommand(tokens);
+  if (!command) {
+    return undefined;
+  }
+
+  const normalizedSegment = segment.toLowerCase();
+
+  if (command === "git") {
+    return classifyGitOperation(remaining);
+  }
+  if (command === "find") {
+    return classifyFindOperation(segment);
+  }
+  if (ARCHIVE_COMMANDS.has(command)) {
+    return classifyArchiveCommand(command, segment);
+  }
+  if (DELETE_COMMANDS.has(command)) {
+    return "delete";
+  }
+  if (WRITE_COMMANDS.has(command)) {
+    return "write";
+  }
+  if (SEARCH_COMMANDS.has(command)) {
+    return "search";
+  }
+  if (READ_COMMANDS.has(command)) {
+    return "read";
+  }
+  if (LIST_COMMANDS.has(command)) {
+    return "list";
+  }
+  if (command === "sed" || command === "perl") {
+    if (/\s-i(?:\s|$)/.test(normalizedSegment)) {
+      return "write";
+    }
+    return "search";
+  }
+  if (command === "unzip") {
+    return "write";
+  }
+  if ((command === "echo" || command === "printf") && WRITE_REDIRECTION_PATTERN.test(segment)) {
+    return "write";
+  }
+  if (FILE_METADATA_COMMANDS.has(command)) {
+    return "read";
+  }
+  if (WRITE_REDIRECTION_PATTERN.test(segment)) {
+    return "write";
+  }
+  return undefined;
+}
+
+function pickHigherPriority(
+  current: FilesystemOperation | undefined,
+  candidate: FilesystemOperation | undefined,
+): FilesystemOperation | undefined {
+  if (!candidate) {
+    return current;
+  }
+  if (!current) {
+    return candidate;
+  }
+  return OPERATION_PRIORITY[candidate] > OPERATION_PRIORITY[current] ? candidate : current;
+}
+
+export function inferShellFilesystemSemantic(
+  commandText: string | undefined,
+  resourcePaths: string[],
+): ShellFilesystemSemantic | undefined {
+  const segments = (commandText ?? "")
+    .split(SEGMENT_SPLITTER)
+    .map((item) => item.trim())
+    .filter(Boolean);
+
+  let operation: FilesystemOperation | undefined;
+  for (const segment of segments) {
+    operation = pickHigherPriority(operation, classifySegment(segment));
+  }
+
+  if (!operation && resourcePaths.length > 0) {
+    operation = "read";
+  }
+  if (!operation) {
+    return undefined;
+  }
+
+  return {
+    operation,
+    toolName: `filesystem.${operation}`,
+  };
+}

package/src/engine/approval_fsm.ts

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+
+import type {
+  ApprovalRecord,
+  ApprovalRequestOptions,
+  ApprovalResolutionMetadata,
+  ApprovalService,
+  DecisionContext,
+} from "../types.ts";
+import { nowIso } from "../utils.ts";
+
+export class ApprovalFsm implements ApprovalService {
+  #records = new Map<string, ApprovalRecord>();
+  #now: () => number;
+
+  constructor(now: () => number) {
+    this.#now = now;
+  }
+
+  requestApproval(
+    context: DecisionContext,
+    options: ApprovalRequestOptions = {},
+  ): ApprovalRecord {
+    const requestedAt = this.#now();
+    const requestContext: ApprovalRecord["request_context"] = {
+      trace_id: context.security_context.trace_id,
+      actor_id: context.actor_id,
+      scope: context.scope,
+      resource_scope: context.resource_scope,
+      resource_paths: [...context.resource_paths],
+      reason_codes: [...(options.reason_codes ?? [])],
+      rule_ids: [...(options.rule_ids ?? [])],
+    };
+    if (context.tool_name !== undefined) {
+      requestContext.tool_name = context.tool_name;
+    }
+    if (context.tool_group !== undefined) {
+      requestContext.tool_group = context.tool_group;
+    }
+    const ttlSeconds = options.ttl_seconds ?? 900;
+    const record: ApprovalRecord = {
+      approval_id: randomUUID(),
+      status: "pending",
+      requested_at: new Date(requestedAt).toISOString(),
+      expires_at: new Date(requestedAt + ttlSeconds * 1000).toISOString(),
+      request_context: requestContext,
+      ...(options.approval_requirements ? { approval_requirements: options.approval_requirements } : {}),
+    };
+    this.#records.set(record.approval_id, record);
+    return record;
+  }
+
+  resolveApproval(
+    approvalId: string,
+    approver: string,
+    decision: "approved" | "rejected",
+    metadata?: ApprovalResolutionMetadata,
+  ): ApprovalRecord | undefined {
+    const record = this.getApprovalStatus(approvalId);
+    if (!record || record.status !== "pending") {
+      return record;
+    }
+    const updated: ApprovalRecord = {
+      ...record,
+      status: decision,
+      decision,
+      approver,
+      ...(metadata?.approver_role ? { approver_role: metadata.approver_role } : {}),
+      ...(metadata?.ticket_id ? { ticket_id: metadata.ticket_id } : {}),
+      decided_at: nowIso(this.#now)
+    };
+    this.#records.set(approvalId, updated);
+    return updated;
+  }
+
+  markApprovalUsed(approvalId: string): ApprovalRecord | undefined {
+    const record = this.getApprovalStatus(approvalId);
+    if (!record || record.status !== "approved") {
+      return record;
+    }
+    const updated: ApprovalRecord = {
+      ...record,
+      used_at: nowIso(this.#now),
+    };
+    this.#records.set(approvalId, updated);
+    return updated;
+  }
+
+  getApprovalStatus(approvalId: string): ApprovalRecord | undefined {
+    const record = this.#records.get(approvalId);
+    if (!record) {
+      return undefined;
+    }
+    if (record.status === "pending" && this.#now() > new Date(record.expires_at).getTime()) {
+      const expired: ApprovalRecord = {
+        ...record,
+        status: "expired"
+      };
+      this.#records.set(approvalId, expired);
+      return expired;
+    }
+    return record;
+  }
+}

package/src/engine/decision_engine.ts

@@ -0,0 +1,39 @@
+import type { DecisionContext, DecisionOutcome, RuleMatch, SecurityClawConfig } from "../types.ts";
+
+export class DecisionEngine {
+  readonly config: SecurityClawConfig;
+
+  constructor(config: SecurityClawConfig) {
+    this.config = config;
+  }
+
+  evaluate(_context: DecisionContext, matches: RuleMatch[]): DecisionOutcome {
+    const decisiveRule = matches.find((match) => Boolean(match.rule.decision));
+
+    if (decisiveRule?.rule.decision) {
+      const outcome: DecisionOutcome = {
+        decision: decisiveRule.rule.decision,
+        decision_source: "rule",
+        reason_codes: decisiveRule.rule.reason_codes,
+        matched_rules: matches.map((match) => match.rule)
+      };
+      if (decisiveRule.rule.decision === "challenge") {
+        outcome.challenge_ttl_seconds =
+          decisiveRule.rule.approval_requirements?.ttl_seconds ??
+          decisiveRule.rule.challenge?.ttl_seconds ??
+          this.config.defaults.approval_ttl_seconds;
+        if (decisiveRule.rule.approval_requirements) {
+          outcome.approval_requirements = decisiveRule.rule.approval_requirements;
+        }
+      }
+      return outcome;
+    }
+
+    return {
+      decision: "allow",
+      decision_source: "default",
+      reason_codes: ["NO_MATCH_DEFAULT_ALLOW"],
+      matched_rules: matches.map((match) => match.rule)
+    };
+  }
+}

package/src/engine/dlp_engine.ts

@@ -0,0 +1,91 @@
+import type { DlpConfig, DlpFinding } from "../types.ts";
+import { deepClone } from "../utils.ts";
+
+function visit(value: unknown, path: string, onString: (text: string, path: string) => void): void {
+  if (typeof value === "string") {
+    onString(value, path);
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => visit(entry, `${path}[${index}]`, onString));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      visit(child, `${path}.${key}`, onString);
+    }
+  }
+}
+
+export class DlpEngine {
+  readonly config: DlpConfig;
+
+  constructor(config: DlpConfig) {
+    this.config = config;
+  }
+
+  scan(content: unknown): DlpFinding[] {
+    const findings: DlpFinding[] = [];
+    visit(content, "root", (text, path) => {
+      for (const pattern of this.config.patterns) {
+        const flags = pattern.flags?.includes("g") ? pattern.flags : `${pattern.flags ?? ""}g`;
+        const regex = new RegExp(pattern.regex, flags);
+        const matches = text.matchAll(regex);
+        for (const match of matches) {
+          findings.push({
+            pattern_name: pattern.name,
+            type: pattern.type,
+            action: pattern.action,
+            path,
+            match: match[0]
+          });
+        }
+      }
+    });
+    return findings;
+  }
+
+  sanitize<T>(content: T, findings: DlpFinding[], mode = this.config.on_dlp_hit): T {
+    if (mode === "warn") {
+      return deepClone(content);
+    }
+    const cloned = deepClone(content) as unknown;
+    return this.#sanitizeNode(cloned, "root", findings) as T;
+  }
+
+  #sanitizeNode(node: unknown, path: string, findings: DlpFinding[]): unknown {
+    const nodeFindings = findings.filter((finding) => finding.path === path);
+    if (typeof node === "string") {
+      if (nodeFindings.length === 0) {
+        return node;
+      }
+      let next = node;
+      for (const finding of nodeFindings) {
+        if (finding.action === "remove") {
+          return undefined;
+        }
+        next = next.split(finding.match).join("[REDACTED]");
+      }
+      return next;
+    }
+
+    if (Array.isArray(node)) {
+      return node
+        .map((entry, index) => this.#sanitizeNode(entry, `${path}[${index}]`, findings))
+        .filter((entry) => entry !== undefined);
+    }
+
+    if (node && typeof node === "object") {
+      const copy: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(node)) {
+        const next = this.#sanitizeNode(value, `${path}.${key}`, findings);
+        if (next !== undefined) {
+          copy[key] = next;
+        }
+      }
+      return copy;
+    }
+
+    return node;
+  }
+}