patterns.js

/**
 * @typedef {Object} PatternMatch
 * @property {string} [filePath]
 * @property {string} [relativePath]
 * @property {{line: number, column: number}} [loc]
 * @property {number} [line]
 * @property {number} [column]
 * @property {string} [detail]
 */

/**
 * @typedef {Object} PatternDefinition
 * @property {string} id
 * @property {"critical" | "high" | "medium" | "low"} severity
 * @property {string} category
 * @property {"file" | "manifest"} scope
 * @property {string} description
 * @property {(context: object) => PatternMatch[]} detector
 */

/**
 * Severity weights used by the report generator.
 * @type {Readonly<Record<"critical" | "high" | "medium" | "low", number>>}
 */
export const SEVERITY_POINTS = Object.freeze({
  critical: 40,
  high: 20,
  medium: 10,
  low: 5,
});

/**
 * Convert a detector match into a normalized finding object.
 * @param {PatternDefinition} pattern
 * @param {object} context
 * @param {PatternMatch} match
 * @returns {object}
 */
function createFinding(pattern, context, match) {
  const location = match.loc ?? {
    line: match.line ?? 1,
    column: match.column ?? 1,
  };

  return {
    id: pattern.id,
    severity: pattern.severity,
    category: pattern.category,
    description: pattern.description,
    filePath: match.filePath ?? context.filePath,
    relativePath: match.relativePath ?? context.relativePath,
    line: location.line,
    column: location.column,
    detail: match.detail ?? pattern.description,
  };
}

/**
 * Create a match array when a detector only has one aggregate result.
 * @param {string} filePath
 * @param {string} relativePath
 * @param {{line: number, column: number}} loc
 * @param {string} detail
 * @returns {PatternMatch[]}
 */
function createAggregateMatch(filePath, relativePath, loc, detail) {
  return [
    {
      filePath,
      relativePath,
      loc,
      detail,
    },
  ];
}

/**
 * Determine whether sensitive env access should count as a finding.
 * @param {object} context
 * @returns {boolean}
 */
function fileHasSuspiciousCompanions(context) {
  const hasExternalNetwork = context.evidence.networkCalls.some((entry) => entry.external);
  const hasExecution = context.evidence.execution.length > 0;
  const hasSuspiciousFs = context.evidence.fsAccesses.some((entry) => entry.classification !== "safe");
  return hasExternalNetwork || hasExecution || hasSuspiciousFs;
}

/**
 * Normalize detector output into findings.
 * @param {PatternDefinition} pattern
 * @param {object} context
 * @returns {object[]}
 */
function runPattern(pattern, context) {
  const matches = pattern.detector(context);
  return matches.map((match) => createFinding(pattern, context, match));
}

/**
 * Detect dynamic `eval()` calls.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectDynamicEval(context) {
  return context.evidence.obfuscation.filter((entry) => entry.type === "eval-dynamic");
}

/**
 * Detect `new Function()` with runtime-built arguments.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectDynamicFunction(context) {
  return context.evidence.obfuscation.filter((entry) => entry.type === "function-dynamic");
}

/**
 * Detect base64 staging patterns.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectBase64Payloads(context) {
  return context.evidence.obfuscation.filter((entry) => entry.type === "base64-decode");
}

/**
 * Detect executable string assembly.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectExecutableConcat(context) {
  return context.evidence.obfuscation.filter((entry) => entry.type === "executable-concat");
}

/**
 * Detect escape-heavy strings.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectEscapeHeavyStrings(context) {
  return context.evidence.strings.filter((entry) => entry.escapeRatio > 0.3);
}

/**
 * Detect plain external network calls.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectExternalNetwork(context) {
  return context.evidence.networkCalls.filter(
    (entry) =>
      entry.external &&
      entry.kind !== "websocket" &&
      entry.kind !== "dns",
  );
}

/**
 * Detect external WebSocket connections.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectExternalWebSockets(context) {
  return context.evidence.networkCalls.filter(
    (entry) => entry.external && entry.kind === "websocket",
  );
}

/**
 * Detect external DNS lookups.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectExternalDns(context) {
  return context.evidence.networkCalls.filter(
    (entry) => entry.external && entry.kind === "dns",
  );
}

/**
 * Detect environment values that are sent over the network.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectEnvToNetwork(context) {
  return context.evidence.networkCalls.filter(
    (entry) => entry.external && entry.taintedEnvNames.length > 0,
  );
}

/**
 * Detect environment harvesting plus network usage in the same scope.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectScopeHarvest(context) {
  return context.scopeSummaries
    .filter(
      (entry) =>
        entry.hasExternalNetwork &&
        entry.envReadCount > 0 &&
        !entry.hasTaintedNetworkCall,
    )
    .map((entry) => ({
      filePath: context.filePath,
      relativePath: context.relativePath,
      loc: entry.loc,
      detail: "Reads environment values and makes an external network call in the same scope.",
    }));
}

/**
 * Detect dynamic `exec()` and `execSync()` usage.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectDynamicExec(context) {
  return context.evidence.execution.filter(
    (entry) =>
      (entry.kind === "exec" || entry.kind === "execSync") &&
      entry.dynamic === true,
  );
}

/**
 * Detect `spawn()` with a non-literal binary.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectDynamicSpawn(context) {
  return context.evidence.execution.filter(
    (entry) =>
      (entry.kind === "spawn" || entry.kind === "spawnSync") &&
      entry.dynamic === true,
  );
}

/**
 * Detect VM context execution.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectVmExecution(context) {
  return context.evidence.execution.filter(
    (entry) => entry.kind === "runInNewContext" || entry.kind === "runInThisContext",
  );
}

/**
 * Detect dynamic `require()` calls.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectDynamicRequire(context) {
  return context.evidence.execution.filter((entry) => entry.kind === "dynamic-require");
}

/**
 * Detect reads of sensitive filesystem locations.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectSensitiveRead(context) {
  return context.evidence.fsAccesses.filter((entry) => entry.classification === "sensitive-read");
}

/**
 * Detect writes into system directories.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectSystemWrite(context) {
  return context.evidence.fsAccesses.filter((entry) => entry.classification === "system-write");
}

/**
 * Detect accesses outside the allowed root.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectOutsideRootAccess(context) {
  return context.evidence.fsAccesses.filter((entry) => entry.classification === "outside-root");
}

/**
 * Detect sensitive env access when the same file already shows suspicious behavior.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectSensitiveEnvAccess(context) {
  if (!fileHasSuspiciousCompanions(context)) {
    return [];
  }

  return context.evidence.envReads.filter((entry) => entry.sensitiveNames.length > 0);
}

/**
 * Detect prototype pollution writes.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectPrototypePollution(context) {
  return context.evidence.prototypeAssignments;
}

/**
 * Detect undeclared permissions in `SKILL.md`.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectUndeclaredPermissions(context) {
  const missingBins = [...context.summary.actualBins].filter(
    (entry) => !context.manifest.declaredBins.has(entry),
  );
  const missingEnv = [...context.summary.sensitiveEnvVars].filter(
    (entry) => !context.manifest.declaredEnv.has(entry),
  );

  if (missingBins.length === 0 && missingEnv.length === 0) {
    return [];
  }

  const parts = [];
  if (missingBins.length > 0) {
    parts.push(`undeclared bins: ${missingBins.join(", ")}`);
  }
  if (missingEnv.length > 0) {
    parts.push(`undeclared env vars: ${missingEnv.join(", ")}`);
  }

  return createAggregateMatch(
    context.filePath,
    context.relativePath,
    context.manifest.metadataLoc,
    `SKILL.md metadata does not declare actual capabilities (${parts.join("; ")}).`,
  );
}

/**
 * Detect suspicious manifest requirements.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectSuspiciousManifestEntries(context) {
  const suspiciousBins = [...context.manifest.declaredBins].filter((entry) =>
    ["bash", "sh", "curl", "wget", "powershell", "pwsh", "python", "ssh", "scp", "nc"].includes(entry),
  );
  const suspiciousEnv = [...context.manifest.declaredEnv].filter((entry) =>
    /(?:key|token|secret|pass|password|private|cookie|session)/i.test(entry),
  );

  if (suspiciousBins.length === 0 && suspiciousEnv.length === 0) {
    return [];
  }

  const details = [];
  if (suspiciousBins.length > 0) {
    details.push(`suspicious bins: ${suspiciousBins.join(", ")}`);
  }
  if (suspiciousEnv.length > 0) {
    details.push(`suspicious env entries: ${suspiciousEnv.join(", ")}`);
  }

  return createAggregateMatch(
    context.filePath,
    context.relativePath,
    context.manifest.metadataLoc,
    `Manifest declares high-risk requirements (${details.join("; ")}).`,
  );
}

/**
 * Detect homepage URLs that do not align with external network destinations.
 * @param {object} context
 * @returns {PatternMatch[]}
 */
function detectHomepageMismatch(context) {
  if (context.manifest.homepageDomains.size === 0 || context.summary.externalHosts.size === 0) {
    return [];
  }

  const sharedDomain = [...context.manifest.homepageDomains].some((entry) =>
    context.summary.externalHosts.has(entry),
  );
  if (sharedDomain) {
    return [];
  }

  return createAggregateMatch(
    context.filePath,
    context.relativePath,
    context.manifest.urlLoc,
    "Homepage or documented URLs do not match the code's external network destinations.",
  );
}

/**
 * Community-extensible registry of findings.
 * @type {Readonly<PatternDefinition[]>}
 */
export const patterns = Object.freeze([
  {
    id: "OBFUSC_001",
    severity: "critical",
    category: "Obfuscation",
    scope: "file",
    description: "Dynamic eval() call with non-literal input.",
    detector: detectDynamicEval,
  },
  {
    id: "OBFUSC_002",
    severity: "high",
    category: "Obfuscation",
    scope: "file",
    description: "new Function() is built from runtime input.",
    detector: detectDynamicFunction,
  },
  {
    id: "OBFUSC_003",
    severity: "medium",
    category: "Obfuscation",
    scope: "file",
    description: "Base64 decoding pattern that can hide staged payloads.",
    detector: detectBase64Payloads,
  },
  {
    id: "OBFUSC_004",
    severity: "medium",
    category: "Obfuscation",
    scope: "file",
    description: "Executable code is assembled through string concatenation.",
    detector: detectExecutableConcat,
  },
  {
    id: "OBFUSC_005",
    severity: "low",
    category: "Obfuscation",
    scope: "file",
    description: "Escape-heavy string suggests hex or unicode obfuscation.",
    detector: detectEscapeHeavyStrings,
  },
  {
    id: "EXFIL_001",
    severity: "low",
    category: "Exfiltration",
    scope: "file",
    description: "External network call to a non-local destination.",
    detector: detectExternalNetwork,
  },
  {
    id: "EXFIL_002",
    severity: "medium",
    category: "Exfiltration",
    scope: "file",
    description: "External WebSocket connection.",
    detector: detectExternalWebSockets,
  },
  {
    id: "EXFIL_003",
    severity: "medium",
    category: "Exfiltration",
    scope: "file",
    description: "DNS lookup targets an external domain.",
    detector: detectExternalDns,
  },
  {
    id: "EXFIL_004",
    severity: "high",
    category: "Exfiltration",
    scope: "file",
    description: "Environment data is passed into an external network call.",
    detector: detectEnvToNetwork,
  },
  {
    id: "EXFIL_005",
    severity: "medium",
    category: "Exfiltration",
    scope: "file",
    description: "Environment harvesting and external network activity occur in the same scope.",
    detector: detectScopeHarvest,
  },
  {
    id: "EXEC_001",
    severity: "high",
    category: "Dangerous Execution",
    scope: "file",
    description: "child_process exec() or execSync() uses runtime input.",
    detector: detectDynamicExec,
  },
  {
    id: "EXEC_002",
    severity: "high",
    category: "Dangerous Execution",
    scope: "file",
    description: "child_process spawn() uses a non-literal command.",
    detector: detectDynamicSpawn,
  },
  {
    id: "EXEC_003",
    severity: "high",
    category: "Dangerous Execution",
    scope: "file",
    description: "vm context execution is present.",
    detector: detectVmExecution,
  },
  {
    id: "EXEC_004",
    severity: "medium",
    category: "Dangerous Execution",
    scope: "file",
    description: "require() resolves a runtime-generated path.",
    detector: detectDynamicRequire,
  },
  {
    id: "FS_001",
    severity: "high",
    category: "File System Abuse",
    scope: "file",
    description: "Sensitive filesystem path is read.",
    detector: detectSensitiveRead,
  },
  {
    id: "FS_002",
    severity: "high",
    category: "File System Abuse",
    scope: "file",
    description: "Writes into a system directory.",
    detector: detectSystemWrite,
  },
  {
    id: "FS_003",
    severity: "medium",
    category: "File System Abuse",
    scope: "file",
    description: "Filesystem access targets a path outside process.cwd() or ~/.openclaw/.",
    detector: detectOutsideRootAccess,
  },
  {
    id: "ENV_001",
    severity: "low",
    category: "Environment Harvesting",
    scope: "file",
    description: "Sensitive environment variables are accessed.",
    detector: detectSensitiveEnvAccess,
  },
  {
    id: "POLL_001",
    severity: "high",
    category: "Prototype Pollution",
    scope: "file",
    description: "Writes to __proto__, Object.prototype, or constructor.prototype.",
    detector: detectPrototypePollution,
  },
  {
    id: "META_001",
    severity: "medium",
    category: "SKILL.md Analysis",
    scope: "manifest",
    description: "SKILL.md permissions do not match actual code capabilities.",
    detector: detectUndeclaredPermissions,
  },
  {
    id: "META_002",
    severity: "low",
    category: "SKILL.md Analysis",
    scope: "manifest",
    description: "SKILL.md declares suspicious bins or env requirements.",
    detector: detectSuspiciousManifestEntries,
  },
  {
    id: "META_003",
    severity: "low",
    category: "SKILL.md Analysis",
    scope: "manifest",
    description: "Documented URLs do not align with external code destinations.",
    detector: detectHomepageMismatch,
  },
]);

/**
 * Apply the registered detectors to a file or manifest context.
 * @param {object} context
 * @returns {object[]}
 */
export function applyPatterns(context) {
  return patterns
    .filter((pattern) => pattern.scope === context.kind)
    .flatMap((pattern) => runPattern(pattern, context));
}