@osfactory/har 0.51.0 → 0.52.0

package/dist/index.js

@@ -69193,7 +69193,7 @@ function harnessExists(repoPath) {
 // src/harness/plugins.ts
 init_schema2();
 init_stages();
-var PLUGIN_IDS = ["playwright", "rocketsim", "kerno"];
+var PLUGIN_IDS = ["playwright", "rocketsim", "kerno", "gitleaks"];
 var PluginManifestFileSchema = external_exports.object({
   src: external_exports.string().min(1),
   dest: external_exports.string().min(1),

package/dist/templates/har-boilerplate/STAGES.md

@@ -1,7 +1,7 @@
 # HAR Stages — authoring guide
 
 Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`), your
 project's test/lint commands, bespoke validation scripts — registers in
 `.har/stages.json` with the same schema, and agents interact with stages only
 through that registry (CLI `har env verify`, MCP `har_run_stage` /
@@ -91,6 +91,6 @@ committed.
 
 `har env add-plugin --list` shows available plugins; `har env add-plugin
 playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
-add-plugin kerno` (backend) installs one. A
+add-plugin kerno` (backend) or `har env add-plugin gitleaks` (secrets scanning, any stack) installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as `add-stage --custom`.

package/dist/templates/har-boilerplate-cli/STAGES.md

@@ -1,7 +1,7 @@
 # HAR Stages — authoring guide
 
 Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`), your
 project's test/lint commands, bespoke validation scripts — registers in
 `.har/stages.json` with the same schema, and agents interact with stages only
 through that registry (CLI `har env verify`, MCP `har_run_stage` /
@@ -91,6 +91,6 @@ committed.
 
 `har env add-plugin --list` shows available plugins; `har env add-plugin
 playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
-add-plugin kerno` (backend) installs one. A
+add-plugin kerno` (backend) or `har env add-plugin gitleaks` (secrets scanning, any stack) installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as `add-stage --custom`.

package/dist/templates/har-boilerplate-ios/STAGES.md

@@ -1,7 +1,7 @@
 # HAR Stages — authoring guide
 
 Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`), your
 project's test/lint commands, bespoke validation scripts — registers in
 `.har/stages.json` with the same schema, and agents interact with stages only
 through that registry (CLI `har env verify`, MCP `har_run_stage` /
@@ -91,6 +91,6 @@ committed.
 
 `har env add-plugin --list` shows available plugins; `har env add-plugin
 playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
-add-plugin kerno` (backend) installs one. A
+add-plugin kerno` (backend) or `har env add-plugin gitleaks` (secrets scanning, any stack) installs one. A
 plugin is just packaging: it copies files, merges `package.json` fragments,
 and registers stages through the exact same registry as `add-stage --custom`.

package/dist/templates/plugins/gitleaks/.github/workflows/gitleaks.yml

@@ -0,0 +1,29 @@
+# Secrets scanning with the official Gitleaks action.
+# Installed by `har env add-plugin gitleaks` (skip with --skip-ci).
+#
+# This CI run is what produces org-level scanning evidence that compliance
+# platforms (Vanta, Drata, …) can ingest via your GitHub organization.
+# Local .har stage runs are pre-merge protection only.
+#
+# GITLEAKS_LICENSE is required for organization repos (free — see
+# https://github.com/gitleaks/gitleaks-action#environment-variables);
+# personal accounts can omit it.
+name: gitleaks
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  scan:
+    name: gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

package/dist/templates/plugins/gitleaks/.gitleaks.toml

@@ -0,0 +1,17 @@
+# Gitleaks configuration — installed by `har env add-plugin gitleaks`.
+# Extends the default ruleset; tune allowlists per repo.
+# Docs: https://github.com/gitleaks/gitleaks#configuration
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "HAR harness defaults — dependencies, build outputs, harness artifacts"
+paths = [
+  '''node_modules/''',
+  '''dist/''',
+  '''build/''',
+  '''vendor/''',
+  '''\.git/''',
+  '''\.har/artifacts/''',
+]

package/dist/templates/plugins/gitleaks/.har/stages/GITLEAKS.md

@@ -0,0 +1,77 @@
+# Gitleaks secrets scan — authoring & adaptation guide
+
+The `secrets-scan` stage runs [Gitleaks](https://github.com/gitleaks/gitleaks)
+against the agent's work dir and fails when hardcoded secrets are found. It is a
+**pre-merge, shift-left** check: it catches credentials before they ever reach the
+default branch.
+
+## Prerequisite
+
+The `gitleaks` binary must be on PATH:
+
+```bash
+brew install gitleaks                 # macOS / Linuxbrew
+# or download a release binary:
+#   https://github.com/gitleaks/gitleaks/releases
+```
+
+The stage fails fast with an install hint when the binary is missing.
+
+## Running
+
+```bash
+./.har/stages/secrets-scan.sh <agent-id>        # dir mode (default)
+./.har/stages/secrets-scan.sh <agent-id> git    # history mode
+```
+
+| Mode | What it scans | Use when |
+|---|---|---|
+| `dir` (default) | Every file currently in the work dir, **including uncommitted changes** | Normal verification — agents usually have uncommitted edits |
+| `git` | The full git history of the worktree | Auditing that a secret never entered history (e.g. committed then removed) |
+
+`git` mode on a repository with pre-existing leaks in old commits will fail on
+findings unrelated to the current session. Generate a
+[baseline](https://github.com/gitleaks/gitleaks#baseline) once and ignore known
+history, or stick to `dir` mode for per-session verification.
+
+## Artifacts
+
+Written to the **main repo root**, not the worktree:
+
+| Path | Content |
+|---|---|
+| `.har/artifacts/secrets-scan/report.json` | JSON findings (rule, file, line — secret values are **redacted** via `--redact`) |
+| `.har/artifacts/secrets-scan/gitleaks.log` | Full scanner output for debugging |
+
+The stage prints a JSON summary to stdout: `status`, `leaks_found`, and the first
+20 findings. Exit code 0 = clean, 1 = leaks found, anything else = scanner error.
+
+## Tuning what gets flagged
+
+The plugin ships a root `.gitleaks.toml` that extends the default ruleset and
+allowlists dependency/build directories (`node_modules`, `dist`, `build`,
+`vendor`, `.git`, `.har/artifacts`). Adapt it per repo:
+
+- **False positive in a specific line** — append `# gitleaks:allow` to that line.
+- **Test fixtures with dummy keys** — add the path to `[allowlist] paths` in
+  `.gitleaks.toml` (entries are regexes).
+- **Custom internal token formats** — add `[[rules]]` entries; the shipped config
+  keeps `useDefault = true`, so default rules stay active.
+
+Gitleaks automatically picks up `.gitleaks.toml` at the scan target root, so the
+same config governs local stage runs and CI.
+
+## CI and compliance platforms (Vanta, Drata, …)
+
+The optional workflow `.github/workflows/gitleaks.yml` (skipped with `--skip-ci`)
+runs the official [`gitleaks/gitleaks-action`](https://github.com/gitleaks/gitleaks-action)
+on pushes and pull requests.
+
+Note the split: **this stage's local runs produce no compliance evidence** — they
+exist so secrets never land on the default branch. Compliance platforms such as
+Vanta ingest evidence from org-level sources (your GitHub organization, code
+scanning results, etc.), which the CI workflow feeds. Keep both: the local stage
+prevents findings; the CI run proves scanning happens.
+
+Organizations (not personal accounts) need a free `GITLEAKS_LICENSE` secret for
+the action — see the workflow comments.

package/dist/templates/plugins/gitleaks/.har/stages/secrets-scan.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Gitleaks secrets scan for an agent slot.
+# Scans the agent work dir for hardcoded secrets and writes a redacted JSON report.
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/stages/secrets-scan.sh <agent-id> [mode]
+#   mode (optional): dir (default) — scan the working tree, incl. uncommitted files
+#                    git           — scan the full git history of the worktree
+#
+# Prerequisite: gitleaks on PATH (brew install gitleaks, or a release binary
+# from https://github.com/gitleaks/gitleaks/releases)
+# See: ./.har/stages/GITLEAKS.md for the adaptation guide.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HARNESS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
+# agent-slot.sh expects SCRIPT_DIR to be .har/ (slot registry lives there)
+SCRIPT_DIR="$HARNESS_DIR"
+
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: secrets-scan.sh <agent-id> [dir|git]}"
+MODE="${2:-dir}"
+
+validate_agent_id "$AGENT_ID"
+
+if [ "$MODE" != "dir" ] && [ "$MODE" != "git" ]; then
+  echo "Error: unknown mode '$MODE' — expected 'dir' or 'git'." >&2
+  exit 1
+fi
+
+log() { echo "==> [secrets-scan agent-$AGENT_ID] $*" >&2; }
+
+# ── Preflight ─────────────────────────────────────────────────────────────────
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "Error: gitleaks not found on PATH." >&2
+  echo "  Install: brew install gitleaks" >&2
+  echo "  Or download a release binary: https://github.com/gitleaks/gitleaks/releases" >&2
+  echo "  Then re-run: ./.har/stages/secrets-scan.sh ${AGENT_ID}" >&2
+  exit 1
+fi
+
+# ── Artifact directory ────────────────────────────────────────────────────────
+# Resolved BEFORE sourcing .env.agent.<id>, which overrides REPO_ROOT with the
+# worktree path — artifacts must land in the main repo root per convention.
+ARTIFACT_DIR="$REPO_ROOT/.har/artifacts/secrets-scan"
+mkdir -p "$ARTIFACT_DIR"
+REPORT_PATH="$ARTIFACT_DIR/report.json"
+SCAN_LOG="$ARTIFACT_DIR/gitleaks.log"
+
+# ── Resolve agent env ─────────────────────────────────────────────────────────
+ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
+  echo "No .env.agent.${AGENT_ID} found." >&2
+  har_suggest_launch "$AGENT_ID" >&2
+  exit 1
+}
+
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+
+WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+
+GITLEAKS_VERSION="$(gitleaks version 2>/dev/null | head -1 || echo unknown)"
+log "gitleaks ${GITLEAKS_VERSION} — ${MODE} scan of $WORK_DIR"
+
+# ── Scan ──────────────────────────────────────────────────────────────────────
+# --exit-code 99 distinguishes "leaks found" (99) from tool errors (other non-zero).
+# --redact keeps discovered secret values out of the report artifact.
+START=$(now_ms)
+
+set +e
+gitleaks "$MODE" "$WORK_DIR" \
+  --report-format json \
+  --report-path "$REPORT_PATH" \
+  --exit-code 99 \
+  --redact \
+  --no-banner \
+  >"$SCAN_LOG" 2>&1
+SCAN_EXIT=$?
+set -e
+
+END=$(now_ms)
+TOTAL_MS=$(( END - START ))
+
+if [ "$SCAN_EXIT" != "0" ] && [ "$SCAN_EXIT" != "99" ]; then
+  log "gitleaks failed (exit $SCAN_EXIT) — last log lines:"
+  tail -20 "$SCAN_LOG" | sed 's/^/    /' >&2
+fi
+
+if [ "$SCAN_EXIT" = "99" ]; then
+  log "Leaks detected — see $REPORT_PATH (redacted)"
+else
+  log "Scan finished in ${TOTAL_MS}ms (exit $SCAN_EXIT)"
+fi
+
+# ── Output ────────────────────────────────────────────────────────────────────
+REPORT_PATH="$REPORT_PATH" SCAN_EXIT="$SCAN_EXIT" TOTAL_MS="$TOTAL_MS" \
+AGENT_ID="$AGENT_ID" MODE="$MODE" node -e "
+const fs = require('fs');
+const scanExit = Number(process.env.SCAN_EXIT);
+let leaks = [];
+try {
+  leaks = JSON.parse(fs.readFileSync(process.env.REPORT_PATH, 'utf8')) || [];
+} catch { /* no report written (older gitleaks writes none on a clean scan) */ }
+const status = scanExit === 0 ? 'pass' : 'fail';
+const out = {
+  status,
+  stageId: 'secrets-scan',
+  kind: 'test',
+  agent_id: Number(process.env.AGENT_ID),
+  total_ms: Number(process.env.TOTAL_MS),
+  mode: process.env.MODE,
+  leaks_found: leaks.length,
+  findings: leaks.slice(0, 20).map((l) => ({
+    rule: l.RuleID,
+    file: l.File,
+    line: l.StartLine,
+    commit: l.Commit || undefined,
+  })),
+  error: scanExit !== 0 && scanExit !== 99 ? 'gitleaks exited ' + scanExit + ' — see .har/artifacts/secrets-scan/gitleaks.log' : undefined,
+  artifacts: [
+    { path: '.har/artifacts/secrets-scan', kind: 'directory' }
+  ]
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+if [ "$SCAN_EXIT" = "99" ]; then
+  exit 1
+fi
+exit "$SCAN_EXIT"

package/dist/templates/plugins/gitleaks/README.md

@@ -0,0 +1,34 @@
+# Gitleaks plugin
+
+Installs a `secrets-scan` stage that runs [Gitleaks](https://github.com/gitleaks/gitleaks)
+against the agent work dir, so hardcoded credentials fail verification before
+they reach the default branch.
+
+```bash
+har env add-plugin gitleaks
+```
+
+What it adds:
+
+- `.har/stages/secrets-scan.sh` — the stage script (registered in `.har/stages.json`
+  and appended to `verificationStages`)
+- `.har/stages/GITLEAKS.md` — adaptation guide
+- `.gitleaks.toml` — default config extending the built-in ruleset with harness
+  allowlists (skipped if the repo already has one)
+- `.github/workflows/gitleaks.yml` — official `gitleaks/gitleaks-action` CI
+  workflow (skip with `--skip-ci`)
+
+Requirements: the `gitleaks` binary on PATH (`brew install gitleaks` or a
+[release binary](https://github.com/gitleaks/gitleaks/releases)). No package.json
+changes — Gitleaks is an external tool, like RocketSim.
+
+Run it:
+
+```bash
+./.har/stages/secrets-scan.sh 1        # scan the working tree (default)
+./.har/stages/secrets-scan.sh 1 git    # scan full git history
+```
+
+Findings land in `.har/artifacts/secrets-scan/report.json` (secret values
+redacted). See `.har/stages/GITLEAKS.md` for tuning allowlists, baselines for
+noisy history, and how the CI workflow feeds compliance platforms like Vanta.

package/dist/templates/plugins/gitleaks/template.manifest.json

@@ -0,0 +1,37 @@
+{
+  "id": "gitleaks",
+  "stageId": "secrets-scan",
+  "verificationStages": [
+    "secrets-scan"
+  ],
+  "stage": {
+    "id": "secrets-scan",
+    "kind": "test",
+    "description": "Gitleaks secrets scan (working tree by default; pass 'git' to scan history)",
+    "script": "stages/secrets-scan.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/secrets-scan",
+        "kind": "directory",
+        "description": "Redacted JSON findings report and scan log"
+      }
+    ]
+  },
+  "files": [
+    { "src": ".har/stages/secrets-scan.sh", "dest": ".har/stages/secrets-scan.sh", "executable": true },
+    { "src": ".har/stages/GITLEAKS.md",     "dest": ".har/stages/GITLEAKS.md" }
+  ],
+  "optionalFiles": [
+    { "src": ".gitleaks.toml",                "dest": ".gitleaks.toml" },
+    { "src": ".github/workflows/gitleaks.yml", "dest": ".github/workflows/gitleaks.yml", "skipFlag": "skipCi" }
+  ],
+  "nextSteps": [
+    "Install gitleaks: brew install gitleaks — or a release binary from https://github.com/gitleaks/gitleaks/releases",
+    "./.har/launch.sh 1",
+    "./.har/stages/secrets-scan.sh 1",
+    "Open .har/artifacts/secrets-scan/report.json for findings (secrets are redacted)",
+    "Tune allowlists in .gitleaks.toml — read .har/stages/GITLEAKS.md for the adaptation guide"
+  ],
+  "docsPath": ".har/stages/GITLEAKS.md"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Open harness for reproducible multi-agent coding workflows",
   "keywords": [
     "har",