@ikon85/agent-workflow-kit 0.24.0 → 0.25.0

package/scripts/safety-guardrails/core.py

@@ -0,0 +1,221 @@
+"""Profile-driven decisions for independently activatable Safety Guardrails."""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from search import scan as scan_search
+
+
+@dataclass(frozen=True)
+class GuardDecision:
+    action: str
+    message: str = ""
+    log_message: str = ""
+
+
+def load_profile(path: Path) -> dict[str, Any]:
+    document = json.loads(path.read_text(encoding="utf-8"))
+    section = document.get("safetyGuardrails")
+    if not isinstance(section, dict):
+        return {}
+    return section
+
+
+def inactive() -> GuardDecision:
+    return GuardDecision("allow")
+
+
+def _secret_name_is_sensitive(name: str, policy: dict[str, Any]) -> bool:
+    suffixes = tuple(policy.get("safeTemplateSuffixes") or ())
+    if name.startswith(".env"):
+        return not any(name.endswith(suffix) for suffix in suffixes)
+    return name in set(policy.get("sensitiveNames") or ())
+
+
+def _secret_path_is_sensitive(path: str, policy: dict[str, Any]) -> bool:
+    candidate = Path(path)
+    if _secret_name_is_sensitive(candidate.name, policy):
+        return True
+    normalized = str(candidate).replace("\\", "/")
+    return any(fragment in normalized for fragment in policy.get("sensitivePathFragments") or ())
+
+
+def secret_decision(policy: dict[str, Any], payload: dict[str, Any]) -> GuardDecision:
+    if policy.get("enabled") is not True:
+        return inactive()
+    tool = payload.get("tool_name")
+    tool_input = payload.get("tool_input") or {}
+    if tool == "Bash":
+        return _secret_bash_decision(policy, str(tool_input.get("command") or ""))
+    path = str(tool_input.get("file_path") or "")
+    if not path or tool not in {"Read", "Edit", "Write", "MultiEdit"}:
+        return inactive()
+    if tool == "Write" and Path(path).name.startswith(".env"):
+        return inactive()
+    if not _secret_path_is_sensitive(path, policy):
+        return inactive()
+    return GuardDecision(
+        "block",
+        f"BLOCKED: access to sensitive path '{path}' is not allowed.",
+        f"blocked tool={tool} path={path!r}",
+    )
+
+
+_DUMP_COMMANDS = {
+    "cat", "head", "tail", "less", "more", "strings", "nl", "xxd", "od",
+    "bat", "tac", "rev", "grep", "egrep", "fgrep", "rg", "ag", "awk", "sed", "cut",
+}
+_QUIET_GREP = {"grep", "egrep", "fgrep", "rg", "ag"}
+_INSTALL_RE = re.compile(
+    r"\b(?P<manager>npm|pnpm|yarn|bun)\s+(?:install|i|ci)\b"
+)
+_BACKGROUND_RE = re.compile(r"(?<![<>&])&[ \t]*(?:;|$)", re.MULTILINE)
+
+
+def _secret_bash_decision(policy: dict[str, Any], command: str) -> GuardDecision:
+    if not command:
+        return inactive()
+    try:
+        segments = re.split(r"\n|;|&&|\|\||\|", command)
+        for segment in segments:
+            tokens = shlex.split(segment)
+            dumps = set(tokens) & _DUMP_COMMANDS
+            paths = [token for token in tokens if _secret_path_is_sensitive(token, policy)]
+            if not dumps or not paths:
+                continue
+            if dumps <= _QUIET_GREP and any(flag == "--quiet" or flag.startswith("-q") for flag in tokens):
+                continue
+            return GuardDecision(
+                "block",
+                f"BLOCKED: command would print sensitive path '{paths[0]}' to the transcript.",
+                f"blocked bash secret dump path={paths[0]!r}",
+            )
+    except ValueError:
+        return inactive()
+    return inactive()
+
+
+def _effective_cwd(command: str, match_pos: int, fallback: Path) -> Path:
+    target = None
+    for match in re.finditer(r"(?:^|[;&|]\s*)cd\s+([^\s;&|]+)", command):
+        if match.end() <= match_pos:
+            target = match.group(1).strip("'\"")
+    if target is None:
+        return fallback
+    path = Path(target).expanduser()
+    return path if path.is_absolute() else fallback / path
+
+
+def _detected_manager(policy: dict[str, Any], start: Path) -> tuple[str, Path] | None:
+    lockfiles = policy.get("lockfiles") or {}
+    try:
+        current = start.resolve()
+    except OSError:
+        return None
+    while True:
+        for filename, manager in lockfiles.items():
+            candidate = current / filename
+            if candidate.is_file():
+                return str(manager), candidate
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def package_manager_decision(
+    policy: dict[str, Any],
+    payload: dict[str, Any],
+    cwd: Path,
+) -> GuardDecision:
+    if policy.get("enabled") is not True or payload.get("tool_name") != "Bash":
+        return inactive()
+    command = str((payload.get("tool_input") or {}).get("command") or "")
+    match = _INSTALL_RE.search(command)
+    if match is None:
+        return inactive()
+    requested = match.group("manager")
+    detected = _detected_manager(policy, _effective_cwd(command, match.start(), cwd))
+    if detected is None or detected[0] == requested:
+        return inactive()
+    manager, lockfile = detected
+    return GuardDecision(
+        "block",
+        f"BLOCKED: `{match.group(0)}` conflicts with {lockfile.name}. "
+        f"Use `{manager} install` in this project.",
+        f"blocked package-manager requested={requested} expected={manager} lock={lockfile}",
+    )
+
+
+def double_background_decision(
+    policy: dict[str, Any],
+    payload: dict[str, Any],
+) -> GuardDecision:
+    if policy.get("enabled") is not True or payload.get("tool_name") != "Bash":
+        return inactive()
+    surface = str(payload.get("surface") or "claude")
+    if surface not in set(policy.get("surfaces") or ()):
+        return inactive()
+    tool_input = payload.get("tool_input") or {}
+    is_background = tool_input.get("run_in_background") is True or (
+        str(tool_input.get("run_in_background") or "").lower() == "true"
+    )
+    command = str(tool_input.get("command") or "")
+    if not is_background or not _BACKGROUND_RE.search(command):
+        return inactive()
+    return GuardDecision(
+        "block",
+        "BLOCKED: run_in_background already detaches and captures this command; "
+        "remove the inner `&` background operator.",
+        "blocked double-background command",
+    )
+
+
+def search_shim_decision(
+    policy: dict[str, Any],
+    payload: dict[str, Any],
+) -> GuardDecision:
+    if (
+        policy.get("enabled") is not True
+        or policy.get("detected") is not True
+        or payload.get("tool_name") != "Bash"
+    ):
+        return inactive()
+    command = str((payload.get("tool_input") or {}).get("command") or "")
+    finding = scan_search(command, set(policy.get("commandNames") or ()))
+    if finding is None:
+        return inactive()
+    reason, pattern = finding
+    return GuardDecision(
+        "block",
+        f"BLOCKED: search shim cannot safely evaluate pattern `{pattern}` ({reason}). "
+        "Use `--fixed-strings` or `command grep`.",
+        f"blocked search-shim breaker reason={reason}",
+    )
+
+
+def evaluate(kind: str, profile: dict[str, Any], payload: dict[str, Any]) -> GuardDecision:
+    if kind == "secrets":
+        return secret_decision(profile.get("secrets") or {}, payload)
+    if kind == "package-manager":
+        return package_manager_decision(
+            profile.get("packageManager") or {},
+            payload,
+            Path.cwd(),
+        )
+    if kind == "double-background":
+        return double_background_decision(
+            profile.get("doubleBackground") or {},
+            payload,
+        )
+    if kind == "search-shim":
+        return search_shim_decision(
+            profile.get("searchShim") or {},
+            payload,
+        )
+    return inactive()

package/scripts/safety-guardrails/search.py

@@ -0,0 +1,92 @@
+"""Verified search-shim breaker detection."""
+
+from __future__ import annotations
+
+import shlex
+
+OPERATORS = {"|", "||", "&&", ";", "&", "|&"}
+
+
+def _count_unescaped(value: str, character: str) -> int:
+    count = index = 0
+    while index < len(value):
+        if value[index] == "\\":
+            index += 2
+            continue
+        if value[index] == character:
+            count += 1
+        index += 1
+    return count
+
+
+def _pattern_and_flags(args: list[str]) -> tuple[str | None, set[str]]:
+    pattern = None
+    flags = set()
+    after_options = False
+    index = 0
+    while index < len(args):
+        value = args[index]
+        if value == "--":
+            after_options = True
+        elif not after_options and value in {"-e", "--regexp"}:
+            index += 1
+            if index < len(args) and pattern is None:
+                pattern = args[index]
+        elif not after_options and value.startswith("--regexp="):
+            if pattern is None:
+                pattern = value.split("=", 1)[1]
+        elif not after_options and value.startswith("-"):
+            flags.add(value)
+        elif pattern is None:
+            pattern = value
+        index += 1
+    return pattern, flags
+
+
+def _has_flag(flags: set[str], letter: str, long: str) -> bool:
+    return long in flags or any(
+        flag.startswith("-") and not flag.startswith("--") and letter in flag[1:]
+        for flag in flags
+    )
+
+
+def _breaker(pattern: str, flags: set[str]) -> str | None:
+    if _has_flag(flags, "F", "--fixed-strings"):
+        return None
+    if _count_unescaped(pattern, "(") != _count_unescaped(pattern, ")"):
+        return "unbalanced parentheses"
+    extended = _has_flag(flags, "E", "--extended-regexp") or _has_flag(
+        flags, "P", "--perl-regexp"
+    )
+    if not extended and _count_unescaped(pattern, "|"):
+        return "bare alternation without extended-regexp mode"
+    return None
+
+
+def scan(command: str, command_names: set[str]) -> tuple[str, str] | None:
+    try:
+        tokens = shlex.split(command, posix=True)
+    except ValueError:
+        return None
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        shim = token in command_names
+        if token == "grep" and index and tokens[index - 1] in {"command", "git"}:
+            shim = False
+        if token == "grep" and index and tokens[index - 1] == "rtk":
+            shim = True
+        if not shim:
+            index += 1
+            continue
+        end = index + 1
+        args = []
+        while end < len(tokens) and tokens[end] not in OPERATORS:
+            args.append(tokens[end])
+            end += 1
+        pattern, flags = _pattern_and_flags(args)
+        reason = _breaker(pattern, flags) if pattern is not None else None
+        if reason:
+            return reason, pattern
+        index = end
+    return None

package/scripts/security/audit-gate.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+
+const SEVERITIES = ['info', 'low', 'moderate', 'high', 'critical'];
+
+function emptyCounts() {
+  return Object.fromEntries(SEVERITIES.map((severity) => [severity, 0]));
+}
+
+function normalizedCounts(input) {
+  const counts = emptyCounts();
+  for (const severity of SEVERITIES) {
+    const value = Number(input?.[severity] ?? 0);
+    if (!Number.isInteger(value) || value < 0) throw new Error('invalid vulnerability count');
+    counts[severity] = value;
+  }
+  return counts;
+}
+
+function parseJson(input) {
+  return JSON.parse(input);
+}
+
+function countsFromAdvisories(data) {
+  const counts = emptyCounts();
+  for (const advisories of Object.values(data)) {
+    if (!Array.isArray(advisories)) throw new Error('invalid advisory collection');
+    for (const advisory of advisories) {
+      const severity = advisory?.severity;
+      if (!SEVERITIES.includes(severity)) throw new Error('invalid advisory severity');
+      counts[severity] += 1;
+    }
+  }
+  return counts;
+}
+
+function parseAudit(manager, input) {
+  let data;
+  try {
+    data = parseJson(input);
+  } catch (error) {
+    if (manager !== 'yarn') throw error;
+    const events = input.trim().split(/\r?\n/).map(parseJson);
+    const summary = events.find((event) => event?.type === 'auditSummary');
+    if (!summary?.data?.vulnerabilities) throw error;
+    return {
+      counts: normalizedCounts(summary.data.vulnerabilities),
+      data: summary,
+    };
+  }
+  if (manager === 'npm' || manager === 'pnpm') {
+    if (data?.error && typeof data.error === 'object') {
+      return { counts: emptyCounts(), data };
+    }
+    if (!data?.metadata?.vulnerabilities) throw new Error('missing metadata.vulnerabilities');
+    return { counts: normalizedCounts(data.metadata.vulnerabilities), data };
+  }
+  if (manager === 'yarn' || manager === 'bun') {
+    if (data?.error && typeof data.error === 'object') {
+      return { counts: emptyCounts(), data };
+    }
+    return { counts: countsFromAdvisories(data), data };
+  }
+  throw new Error(`unsupported package manager: ${manager}`);
+}
+
+export function auditCommand(manager) {
+  const commands = {
+    npm: ['npm', 'audit', '--omit=dev', '--json'],
+    pnpm: ['pnpm', 'audit', '--prod', '--json'],
+    yarn: ['yarn', 'npm', 'audit', '--environment', 'production', '--recursive', '--json'],
+    bun: ['bun', 'audit', '--prod', '--json'],
+  };
+  if (!commands[manager]) throw new Error(`unsupported package manager: ${manager}`);
+  return commands[manager];
+}
+
+export function evaluateAudit({
+  manager,
+  input,
+  serviceOutage = 'warn',
+  blockingSeverities = ['high', 'critical'],
+}) {
+  let parsed;
+  try {
+    parsed = parseAudit(manager, input);
+  } catch (error) {
+    return { status: 'malformed', exitCode: 2, message: error.message };
+  }
+
+  if (parsed.data?.error && typeof parsed.data.error === 'object') {
+    return serviceOutage === 'block'
+      ? { status: 'service-outage-blocked', exitCode: 3 }
+      : { status: 'service-outage-warning', exitCode: 0 };
+  }
+
+  const isBlocking = blockingSeverities.some((severity) => parsed.counts[severity] > 0);
+  return {
+    status: isBlocking ? 'blocking-findings' : 'passed',
+    exitCode: isBlocking ? 1 : 0,
+    counts: parsed.counts,
+  };
+}
+
+async function main() {
+  const manager = process.argv[2];
+  const serviceOutageArg = process.argv.find((arg) => arg.startsWith('--service-outage='));
+  const serviceOutage = serviceOutageArg?.split('=', 2)[1] ?? 'warn';
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk;
+  const verdict = evaluateAudit({ manager, input, serviceOutage });
+  const output = JSON.stringify(verdict);
+  (verdict.exitCode === 0 ? console.log : console.error)(output);
+  process.exitCode = verdict.exitCode;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(JSON.stringify({ status: 'malformed', message: error.message }));
+    process.exitCode = 2;
+  });
+}

package/scripts/security/ensure-gitleaks.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  chmod, copyFile, mkdir, mkdtemp, readFile, rename, rm, unlink, writeFile,
+} from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const DEFAULT_GITLEAKS_PROFILE = JSON.parse(
+  await readFile(join(HERE, 'gitleaks-profile.json'), 'utf8'),
+);
+
+async function defaultIsAvailable() {
+  try {
+    await exec('gitleaks', ['version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function defaultFetchArchive(url) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`download returned HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+async function defaultInstallArchive({ bytes, destination }) {
+  const scratch = await mkdtemp(join(tmpdir(), 'awkit-gitleaks-'));
+  const archive = join(scratch, 'gitleaks.tar.gz');
+  const extracted = join(scratch, 'gitleaks');
+  const staged = `${destination}.tmp-${process.pid}`;
+  try {
+    await writeFile(archive, bytes);
+    await exec('tar', ['-xzf', archive, '-C', scratch, 'gitleaks']);
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(extracted, staged);
+    await chmod(staged, 0o755);
+    await rename(staged, destination);
+  } finally {
+    await unlink(staged).catch(() => {});
+    await rm(scratch, { recursive: true, force: true });
+  }
+}
+
+export async function ensureGitleaks({
+  profile = DEFAULT_GITLEAKS_PROFILE,
+  platform = process.platform,
+  arch = process.arch,
+  destination = join(homedir(), '.local', 'bin', 'gitleaks'),
+  isAvailable = defaultIsAvailable,
+  fetchArchive = defaultFetchArchive,
+  installArchive = defaultInstallArchive,
+} = {}) {
+  if (await isAvailable()) return { status: 'already-available' };
+
+  const target = profile.platforms?.[`${platform}-${arch}`];
+  if (!target?.asset || !/^[a-f0-9]{64}$/i.test(target.sha256 ?? '')) {
+    return { status: 'unsupported-platform', platform, arch };
+  }
+
+  const url = `${profile.baseUrl ?? ''}/${target.asset}`;
+  let bytes;
+  try {
+    bytes = await fetchArchive(url);
+  } catch (error) {
+    return { status: 'offline', message: error.message };
+  }
+
+  const actual = createHash('sha256').update(bytes).digest('hex');
+  if (actual !== target.sha256.toLowerCase()) {
+    return { status: 'checksum-mismatch', expected: target.sha256, actual };
+  }
+
+  try {
+    await installArchive({ bytes, destination, asset: target.asset });
+  } catch (error) {
+    return { status: 'unwritable', message: error.message };
+  }
+  return { status: 'installed', destination, version: profile.version };
+}
+
+async function main() {
+  const result = await ensureGitleaks({ destination: process.argv[2] });
+  if (result.status === 'installed' || result.status === 'already-available') {
+    console.log(`Gitleaks provisioning: ${result.status}.`);
+  } else {
+    console.error(`Gitleaks provisioning skipped safely: ${result.status}.`);
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`Gitleaks provisioning failed safely: ${error.message}`);
+  });
+}

package/scripts/security/gitleaks-profile.json

@@ -0,0 +1,14 @@
+{
+  "version": "8.30.1",
+  "baseUrl": "https://github.com/gitleaks/gitleaks/releases/download/v8.30.1",
+  "platforms": {
+    "linux-x64": {
+      "asset": "gitleaks_8.30.1_linux_x64.tar.gz",
+      "sha256": "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
+    },
+    "linux-arm64": {
+      "asset": "gitleaks_8.30.1_linux_arm64.tar.gz",
+      "sha256": "e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080"
+    }
+  }
+}

package/scripts/security/install-git-hooks.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+
+async function defaultRunGit(cwd, args) {
+  const result = await exec('git', args, { cwd });
+  return result.stdout.trim();
+}
+
+export async function installGitHooks({
+  cwd = process.cwd(),
+  hooksPath = '.githooks',
+  runGit = defaultRunGit,
+} = {}) {
+  try {
+    await runGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+  } catch (error) {
+    if (error?.code === 128) return { status: 'not-a-repository' };
+    throw error;
+  }
+
+  let current = '';
+  try {
+    current = await runGit(cwd, ['config', '--get', 'core.hooksPath']);
+  } catch (error) {
+    if (error?.code !== 1) throw error;
+  }
+  if (current === hooksPath) return { status: 'unchanged', hooksPath };
+
+  await runGit(cwd, ['config', 'core.hooksPath', hooksPath]);
+  return { status: 'wired', hooksPath };
+}
+
+async function main() {
+  const hooksPath = process.argv[2] ?? '.githooks';
+  const result = await installGitHooks({ hooksPath });
+  if (result.status === 'not-a-repository') {
+    console.log('Git hooks not wired: current directory is not a Git work tree.');
+    return;
+  }
+  console.log(`Git hooks ${result.status}: core.hooksPath=${result.hooksPath}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`Git hook wiring failed: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/workflow-advisories/capabilities.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "capabilities": [
+    {
+      "profileKey": "largeRead",
+      "artifact": ".claude/hooks/recon-size-hint.py"
+    },
+    {
+      "profileKey": "baseline",
+      "artifact": ".claude/hooks/baseline-capture-hint.py"
+    },
+    {
+      "profileKey": "preRefactor",
+      "artifact": ".claude/hooks/pre-refactor-sweep.py"
+    },
+    {
+      "profileKey": "stopChecks",
+      "artifact": ".claude/hooks/typecheck-on-stop.sh"
+    },
+    {
+      "profileKey": "freshness",
+      "artifact": ".claude/hooks/convention-drift-hint.py"
+    },
+    {
+      "profileKey": "migration",
+      "artifact": ".claude/hooks/migration-snapshot-reminder.py"
+    },
+    {
+      "profileKey": "locForewarn",
+      "artifact": ".claude/hooks/loc-offender-forewarn.py"
+    }
+  ]
+}