securityclaw 0.0.1

package/src/engine/rule_engine.ts

@@ -0,0 +1,208 @@
+import type { DecisionContext, PolicyRule, RuleMatch } from "../types.ts";
+
+function intersects(targets: string[] | undefined, value: string | undefined): boolean {
+  return !targets || targets.length === 0 || (value !== undefined && targets.includes(value));
+}
+
+function includesAny(targets: string[] | undefined, values: string[]): boolean {
+  return !targets || targets.length === 0 || targets.some((target) => values.includes(target));
+}
+
+function matchesPathPrefixes(prefixes: string[] | undefined, paths: string[]): boolean {
+  if (!prefixes || prefixes.length === 0) {
+    return true;
+  }
+  if (paths.length === 0) {
+    return false;
+  }
+  return prefixes.some((prefix) => paths.some((candidate) => candidate.startsWith(prefix)));
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let source = "";
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index];
+    const next = pattern[index + 1];
+    if (char === "*" && next === "*") {
+      source += ".*";
+      index += 1;
+      continue;
+    }
+    if (char === "*") {
+      source += "[^/]*";
+      continue;
+    }
+    if (char === "?") {
+      source += ".";
+      continue;
+    }
+    source += escapeRegExp(char);
+  }
+  return new RegExp(`^${source}$`);
+}
+
+function matchesPathGlobs(globs: string[] | undefined, paths: string[]): boolean {
+  if (!globs || globs.length === 0) {
+    return true;
+  }
+  if (paths.length === 0) {
+    return false;
+  }
+  const regexes = globs.map((pattern) => globToRegExp(pattern));
+  return regexes.some((regex) => paths.some((candidate) => regex.test(candidate)));
+}
+
+function matchesRegexList(patterns: string[] | undefined, value: string | undefined): boolean {
+  if (!patterns || patterns.length === 0) {
+    return true;
+  }
+  if (!value) {
+    return false;
+  }
+  return patterns.some((pattern) => {
+    try {
+      return new RegExp(pattern, "i").test(value);
+    } catch {
+      return false;
+    }
+  });
+}
+
+function matchesPathRegexes(patterns: string[] | undefined, paths: string[]): boolean {
+  if (!patterns || patterns.length === 0) {
+    return true;
+  }
+  if (paths.length === 0) {
+    return false;
+  }
+  return patterns.some((pattern) => {
+    try {
+      const regex = new RegExp(pattern, "i");
+      return paths.some((candidate) => regex.test(candidate));
+    } catch {
+      return false;
+    }
+  });
+}
+
+function matchesDomains(patterns: string[] | undefined, value: string | undefined): boolean {
+  if (!patterns || patterns.length === 0) {
+    return true;
+  }
+  if (!value) {
+    return false;
+  }
+  const normalized = value.toLowerCase();
+  return patterns.some((pattern) => {
+    const candidate = pattern.toLowerCase();
+    if (candidate.startsWith("*.")) {
+      const suffix = candidate.slice(1);
+      return normalized.endsWith(suffix);
+    }
+    return normalized === candidate;
+  });
+}
+
+function matchesSubstrings(patterns: string[] | undefined, value: string | undefined): boolean {
+  if (!patterns || patterns.length === 0) {
+    return true;
+  }
+  if (!value) {
+    return false;
+  }
+  const normalized = value.toLowerCase();
+  return patterns.some((pattern) => normalized.includes(pattern.toLowerCase()));
+}
+
+function meetsMinimum(minimum: number | undefined, actual: number | undefined): boolean {
+  return minimum === undefined || (actual !== undefined && actual >= minimum);
+}
+
+function precedence(rule: PolicyRule): number {
+  let score = 1;
+  const weights: Array<[unknown, number]> = [
+    [rule.match.identity, 4],
+    [rule.match.scope, 3],
+    [rule.match.tool, 3],
+    [rule.match.tool_group, 2],
+    [rule.match.operation, 2],
+    [rule.match.tags, 1],
+    [rule.match.resource_scope, 1],
+    [rule.match.path_prefix, 2],
+    [rule.match.path_glob, 2],
+    [rule.match.path_regex, 2],
+    [rule.match.file_type, 1],
+    [rule.match.asset_labels, 2],
+    [rule.match.data_labels, 2],
+    [rule.match.trust_level, 2],
+    [rule.match.destination_type, 2],
+    [rule.match.dest_domain, 2],
+    [rule.match.dest_ip_class, 1],
+    [rule.match.tool_args_summary, 1],
+    [rule.match.tool_args_regex, 1],
+    [rule.match.min_file_count, 1],
+    [rule.match.min_bytes, 1],
+    [rule.match.min_record_count, 1],
+  ];
+
+  for (const [value, weight] of weights) {
+    if (Array.isArray(value) ? value.length > 0 : value !== undefined) {
+      score += weight;
+    }
+  }
+  return score;
+}
+
+export class RuleEngine {
+  readonly rules: PolicyRule[];
+
+  constructor(rules: PolicyRule[]) {
+    this.rules = [...rules];
+  }
+
+  match(context: DecisionContext): RuleMatch[] {
+    const matches = this.rules
+      .filter((rule) => {
+        if (!rule.enabled) {
+          return false;
+        }
+        return (
+          intersects(rule.match.identity, context.actor_id) &&
+          intersects(rule.match.scope, context.scope) &&
+          intersects(rule.match.tool, context.tool_name) &&
+          intersects(rule.match.tool_group, context.tool_group) &&
+          intersects(rule.match.operation, context.operation) &&
+          includesAny(rule.match.tags, context.tags) &&
+          intersects(rule.match.resource_scope, context.resource_scope) &&
+          matchesPathPrefixes(rule.match.path_prefix, context.resource_paths) &&
+          matchesPathGlobs(rule.match.path_glob, context.resource_paths) &&
+          matchesPathRegexes(rule.match.path_regex, context.resource_paths) &&
+          intersects(rule.match.file_type, context.file_type) &&
+          includesAny(rule.match.asset_labels, context.asset_labels) &&
+          includesAny(rule.match.data_labels, context.data_labels) &&
+          intersects(rule.match.trust_level, context.trust_level) &&
+          intersects(rule.match.destination_type, context.destination_type) &&
+          matchesDomains(rule.match.dest_domain, context.dest_domain) &&
+          intersects(rule.match.dest_ip_class, context.dest_ip_class) &&
+          matchesSubstrings(rule.match.tool_args_summary, context.tool_args_summary) &&
+          matchesRegexList(rule.match.tool_args_regex, context.tool_args_summary) &&
+          meetsMinimum(rule.match.min_file_count, context.volume.file_count) &&
+          meetsMinimum(rule.match.min_bytes, context.volume.bytes) &&
+          meetsMinimum(rule.match.min_record_count, context.volume.record_count)
+        );
+      })
+      .map((rule) => ({ rule, precedence: precedence(rule) }));
+
+    matches.sort((left, right) => {
+      if (right.precedence !== left.precedence) {
+        return right.precedence - left.precedence;
+      }
+      return right.rule.priority - left.rule.priority;
+    });
+    return matches;
+  }
+}

package/src/events/emitter.ts

@@ -0,0 +1,86 @@
+import type { EventSink, SecurityDecisionEvent } from "../types.ts";
+
+export class HttpEventSink implements EventSink {
+  readonly url: string;
+  readonly timeoutMs: number;
+
+  constructor(url: string, timeoutMs: number) {
+    this.url = url;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async send(event: SecurityDecisionEvent): Promise<void> {
+    const response = await fetch(this.url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(event),
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!response.ok) {
+      throw new Error(`Webhook sink failed with status ${response.status}.`);
+    }
+  }
+}
+
+type QueueItem = {
+  event: SecurityDecisionEvent;
+  attempts: number;
+};
+
+export class EventEmitter {
+  #sink: EventSink | undefined;
+  #maxBuffer: number;
+  #retryLimit: number;
+  #queue: QueueItem[] = [];
+  #dropped = 0;
+
+  constructor(sink: EventSink | undefined, maxBuffer: number, retryLimit: number) {
+    this.#sink = sink;
+    this.#maxBuffer = maxBuffer;
+    this.#retryLimit = retryLimit;
+  }
+
+  async emitSecurityEvent(event: SecurityDecisionEvent): Promise<void> {
+    if (!this.#sink) {
+      return;
+    }
+    try {
+      await this.#sink.send(event);
+      await this.flush();
+    } catch {
+      this.enqueue(event, 1);
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (!this.#sink) {
+      this.#queue = [];
+      return;
+    }
+    const pending = [...this.#queue];
+    this.#queue = [];
+    for (const item of pending) {
+      try {
+        await this.#sink.send(item.event);
+      } catch {
+        this.enqueue(item.event, item.attempts + 1);
+      }
+    }
+  }
+
+  getStats(): { queued: number; dropped: number } {
+    return { queued: this.#queue.length, dropped: this.#dropped };
+  }
+
+  enqueue(event: SecurityDecisionEvent, attempts: number): void {
+    if (attempts > this.#retryLimit) {
+      this.#dropped += 1;
+      return;
+    }
+    if (this.#queue.length >= this.#maxBuffer) {
+      this.#queue.shift();
+      this.#dropped += 1;
+    }
+    this.#queue.push({ event, attempts });
+  }
+}

package/src/events/schema.ts

@@ -0,0 +1,27 @@
+export const securityDecisionEventSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  title: "SecurityDecisionEvent",
+  type: "object",
+  required: [
+    "schema_version",
+    "event_type",
+    "trace_id",
+    "hook",
+    "decision",
+    "reason_codes",
+    "latency_ms",
+    "ts"
+  ],
+  properties: {
+    schema_version: { type: "string" },
+    event_type: { const: "SecurityDecisionEvent" },
+    trace_id: { type: "string" },
+    hook: { type: "string" },
+    decision: { type: "string" },
+    decision_source: { type: "string" },
+    resource_scope: { type: "string" },
+    reason_codes: { type: "array", items: { type: "string" } },
+    latency_ms: { type: "number" },
+    ts: { type: "string", format: "date-time" }
+  }
+} as const;

package/src/hooks/context_guard.ts

@@ -0,0 +1,36 @@
+import type { BeforePromptBuildInput, GuardComputation, SecurityContext } from "../types.ts";
+
+export function runContextGuard(
+  input: BeforePromptBuildInput,
+  policyVersion: string,
+  traceId: string,
+  nowIso: string,
+): GuardComputation<BeforePromptBuildInput> {
+  const untrusted = input.source === "external";
+  const tags = [...(input.tags ?? [])];
+  if (untrusted && !tags.includes("untrusted")) {
+    tags.push("untrusted");
+  }
+  const securityContext: SecurityContext = {
+    trace_id: traceId,
+    actor_id: input.actor_id,
+    workspace: input.workspace,
+    policy_version: policyVersion,
+    untrusted,
+    tags,
+    created_at: nowIso
+  };
+  return {
+    mutated_payload: {
+      ...input,
+      tags,
+      trace_id: traceId,
+      prompt: input.prompt,
+      security_context: securityContext
+    } as BeforePromptBuildInput,
+    decision: "allow",
+    reason_codes: [untrusted ? "CONTENT_MARKED_UNTRUSTED" : "CONTEXT_INJECTED"],
+    sanitization_actions: [],
+    security_context: securityContext
+  };
+}

package/src/hooks/output_guard.ts

@@ -0,0 +1,66 @@
+import type { GuardComputation, MessageSendingInput, SanitizationAction, SecurityContext } from "../types.ts";
+import type { DlpEngine } from "../engine/dlp_engine.ts";
+
+function buildSecurityContext(input: MessageSendingInput, traceId: string, policyVersion: string, nowIso: string): SecurityContext {
+  return {
+    trace_id: input.security_context?.trace_id ?? traceId,
+    actor_id: input.actor_id,
+    workspace: input.workspace,
+    policy_version: input.security_context?.policy_version ?? policyVersion,
+    untrusted: input.security_context?.untrusted ?? false,
+    tags: [...(input.security_context?.tags ?? [])],
+    created_at: input.security_context?.created_at ?? nowIso
+  };
+}
+
+function redactRestrictedTerms(message: unknown, restrictedTerms: string[]): { output: unknown; actions: SanitizationAction[] } {
+  if (typeof message !== "string" || restrictedTerms.length === 0) {
+    return { output: message, actions: [] };
+  }
+  let output = message;
+  const actions: SanitizationAction[] = [];
+  for (const term of restrictedTerms) {
+    if (output.includes(term)) {
+      output = output.split(term).join("[REDACTED]");
+      actions.push({
+        path: "root",
+        action: "mask",
+        detail: `restricted_term:${term}`
+      });
+    }
+  }
+  return { output, actions };
+}
+
+export function runOutputGuard(
+  input: MessageSendingInput,
+  traceId: string,
+  policyVersion: string,
+  nowIso: string,
+  dlpEngine: DlpEngine,
+): GuardComputation<MessageSendingInput> {
+  const securityContext = buildSecurityContext(input, traceId, policyVersion, nowIso);
+  const restricted = redactRestrictedTerms(input.message, input.restricted_terms ?? []);
+  const findings = dlpEngine.scan(restricted.output);
+  const sanitized = findings.length > 0 ? dlpEngine.sanitize(restricted.output, findings, "sanitize") : restricted.output;
+  const dlpActions: SanitizationAction[] = findings.map((finding) => ({
+    path: finding.path,
+    action: finding.action,
+    detail: `${finding.pattern_name}:${finding.type}`
+  }));
+
+  return {
+    mutated_payload: {
+      ...input,
+      message: sanitized,
+      security_context: securityContext
+    } as MessageSendingInput,
+    decision: findings.length > 0 || restricted.actions.length > 0 ? "warn" : "allow",
+    reason_codes:
+      findings.length > 0 || restricted.actions.length > 0
+        ? ["MESSAGE_SANITIZED"]
+        : ["MESSAGE_OK"],
+    sanitization_actions: [...restricted.actions, ...dlpActions],
+    security_context: securityContext
+  };
+}

package/src/hooks/persist_guard.ts

@@ -0,0 +1,69 @@
+import type { GuardComputation, SanitizationAction, SecurityContext, ToolResultPersistInput } from "../types.ts";
+import type { DlpEngine } from "../engine/dlp_engine.ts";
+
+function buildSecurityContext(
+  input: ToolResultPersistInput,
+  traceId: string,
+  policyVersion: string,
+  nowIso: string,
+): SecurityContext {
+  return {
+    trace_id: input.security_context?.trace_id ?? traceId,
+    actor_id: input.actor_id,
+    workspace: input.workspace,
+    policy_version: input.security_context?.policy_version ?? policyVersion,
+    untrusted: input.security_context?.untrusted ?? false,
+    tags: [...(input.security_context?.tags ?? [])],
+    created_at: input.security_context?.created_at ?? nowIso
+  };
+}
+
+export function runPersistGuard(
+  input: ToolResultPersistInput,
+  traceId: string,
+  policyVersion: string,
+  nowIso: string,
+  dlpEngine: DlpEngine,
+  defaultMode: "strict" | "compat",
+): GuardComputation<ToolResultPersistInput> {
+  const securityContext = buildSecurityContext(input, traceId, policyVersion, nowIso);
+  const findings = dlpEngine.scan(input.result);
+  const mode = input.mode ?? defaultMode;
+  const sanitizationActions: SanitizationAction[] = findings.map((finding) => ({
+    path: finding.path,
+    action: finding.action,
+    detail: `${finding.pattern_name}:${finding.type}`
+  }));
+
+  if (findings.length === 0) {
+    return {
+      mutated_payload: { ...input, security_context: securityContext } as ToolResultPersistInput,
+      decision: "allow",
+      reason_codes: ["PERSIST_OK"],
+      sanitization_actions: [],
+      security_context: securityContext
+    };
+  }
+
+  if (mode === "strict") {
+    return {
+      mutated_payload: { ...input, security_context: securityContext } as ToolResultPersistInput,
+      decision: "block",
+      reason_codes: ["PERSIST_BLOCKED_DLP"],
+      sanitization_actions: sanitizationActions,
+      security_context: securityContext
+    };
+  }
+
+  return {
+    mutated_payload: {
+      ...input,
+      result: dlpEngine.sanitize(input.result, findings, "sanitize"),
+      security_context: securityContext
+    } as ToolResultPersistInput,
+    decision: "warn",
+    reason_codes: ["PERSIST_REDACTED"],
+    sanitization_actions: sanitizationActions,
+    security_context: securityContext
+  };
+}