@osfactory/har 0.52.0 → 0.54.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", "gitleaks"];
+var PLUGIN_IDS = ["playwright", "rocketsim", "kerno", "gitleaks", "trivy", "semgrep"];
 var PluginManifestFileSchema = external_exports.object({
   src: external_exports.string().min(1),
   dest: external_exports.string().min(1),
@@ -70292,8 +70292,8 @@ init_logging();
 init_manifest();
 var ADAPTATION_PROMPT_FILE = "ADAPT-PROMPT.md";
 var PROFILE_HINTS = {
-  default: "Web app profile (SaaS/full-stack) \u2014 Docker Compose for shared infra (HARNESS_INFRA_SERVICES), PM2 for the primary application only, git worktree per agent slot by default. Launch provisions toolchain via harness.env (HARNESS_ECOSYSTEM, HARNESS_INSTALL_CMD) and writes paths to .env.agent.<id>. Identify the primary app agents modify; run supporting services shared.",
-  cli: "CLI/library profile (typical SWE-bench) \u2014 no PM2. Optional Docker Compose via HARNESS_INFRA_SERVICES. Git worktree by default. Launch provisions toolchain declaratively (HARNESS_ECOSYSTEM auto-detects common ecosystems); verify must use resolved tool paths from .env.agent.<id>, never hardcoded interpreter or package-manager paths.",
+  default: "Web app profile (SaaS/full-stack) \u2014 Docker Compose for shared infra (HARNESS_INFRA_SERVICES), PM2 for the primary application only, git worktree per agent slot by default. Launch provisions toolchain via harness.env (HARNESS_ECOSYSTEM, HARNESS_INSTALL_CMD) and writes paths to .env.agent.<id>. Identify the primary app agents modify; run supporting services shared. Install the Semgrep plugin (har env add-plugin semgrep) when the repo needs a SAST verification stage.",
+  cli: "CLI/library profile (typical SWE-bench) \u2014 no PM2. Optional Docker Compose via HARNESS_INFRA_SERVICES. Git worktree by default. Launch provisions toolchain declaratively (HARNESS_ECOSYSTEM auto-detects common ecosystems); verify must use resolved tool paths from .env.agent.<id>, never hardcoded interpreter or package-manager paths. Install the Semgrep plugin (har env add-plugin semgrep) when the repo needs a SAST verification stage.",
   ios: "iOS mobile app profile \u2014 xcodebuild + iOS Simulator in an isolated git worktree. Set HARNESS_XCODE_SCHEME, workspace/project, HARNESS_SIMULATOR_NAME, HARNESS_BUNDLE_ID. Launch writes XCODEBUILD_BIN to .env.agent.<id>; verify uses it. Install RocketSim plugin (har env add-plugin rocketsim) for user-flow validation."
 };
 function loadTemplate(name) {

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`, `gitleaks`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`, `trivy`, `semgrep`), 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,9 @@ 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) or `har env add-plugin gitleaks` (secrets scanning, any stack) installs one. A
+add-plugin kerno` (backend), `har env add-plugin gitleaks` (secrets scanning, any
+stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack),
+or `har env add-plugin semgrep` (SAST, 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`, `gitleaks`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`, `trivy`, `semgrep`), 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,9 @@ 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) or `har env add-plugin gitleaks` (secrets scanning, any stack) installs one. A
+add-plugin kerno` (backend), `har env add-plugin gitleaks` (secrets scanning, any
+stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack),
+or `har env add-plugin semgrep` (SAST, 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`, `gitleaks`), your
+actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`, `trivy`, `semgrep`), 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,9 @@ 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) or `har env add-plugin gitleaks` (secrets scanning, any stack) installs one. A
+add-plugin kerno` (backend), `har env add-plugin gitleaks` (secrets scanning, any
+stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack),
+or `har env add-plugin semgrep` (SAST, 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/semgrep/.github/workflows/semgrep.yml

@@ -0,0 +1,39 @@
+# Semgrep SAST — official recipe (https://semgrep.dev/docs/semgrep-ci/sample-ci-configs)
+#
+# With a SEMGREP_APP_TOKEN secret (Semgrep AppSec Platform → Settings), `semgrep ci`
+# publishes findings to the AppSec Platform — the org-level evidence layer that
+# compliance tools like Vanta ingest natively:
+# https://help.vanta.com/en/articles/15705377-connecting-vanta-semgrep
+# Without the token, this falls back to a Community Edition scan that still blocks
+# the PR on findings but publishes nothing.
+name: Semgrep
+
+on:
+  pull_request: {}
+  push:
+    branches: ["main", "master"]
+  workflow_dispatch: {}
+  schedule:
+    # Daily scan so new registry rules surface without a code change
+    - cron: '17 5 * * *'
+
+jobs:
+  semgrep:
+    name: semgrep/ci
+    runs-on: ubuntu-latest
+    container:
+      image: semgrep/semgrep
+    if: (github.actor != 'dependabot[bot]')
+    steps:
+      # Pinned to a SHA so semgrep's own mutable-action-tag rule stays quiet
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Run Semgrep
+        env:
+          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+        run: |
+          if [ -n "$SEMGREP_APP_TOKEN" ]; then
+            semgrep ci
+          else
+            echo "SEMGREP_APP_TOKEN not set — running Community Edition scan (no platform/Vanta reporting)"
+            semgrep scan --config auto --error
+          fi

package/dist/templates/plugins/semgrep/.har/stages/SEMGREP.md

@@ -0,0 +1,91 @@
+# Semgrep SAST Stage
+
+The `sast` stage scans the agent's session worktree with [Semgrep](https://semgrep.dev)
+and fails verification when blocking findings exist. Full verify (`verify --full`)
+runs it automatically once it is listed in `verificationStages`.
+
+## Running
+
+```bash
+# Whole worktree
+./.har/stages/sast.sh 1
+
+# Only specific paths
+./.har/stages/sast.sh 1 src/ lib/auth.py
+
+# Included in full verify
+./.har/verify.sh 1 --full
+```
+
+Reports land under `.har/artifacts/sast/` in the **main repo root** (not the worktree):
+
+| File | Contents |
+|------|----------|
+| `semgrep.json` | Full findings report (machine-readable) |
+| `semgrep.sarif` | SARIF report — upload to GitHub code scanning if desired |
+| `scan.log` | Semgrep's own text output for the run |
+
+Exit codes pass through from Semgrep: `0` clean, `1` findings, `>=2` scan error.
+
+## Choosing rules
+
+The stage runs `semgrep scan --config "$HARNESS_SEMGREP_CONFIG"` (default `auto`).
+Set the variable in `.har/harness.env` to pin behavior:
+
+```bash
+# .har/harness.env
+export HARNESS_SEMGREP_CONFIG="p/ci"          # curated low-noise ruleset
+# export HARNESS_SEMGREP_CONFIG="p/security-audit"
+# export HARNESS_SEMGREP_CONFIG=".semgrep/"   # local rules only (works offline)
+```
+
+Honest notes about `--config auto` and registry rulesets (`p/...`):
+
+- They **fetch rules from the Semgrep registry**, so the stage needs network access.
+- Semgrep **sends pseudonymized metrics** to semgrep.dev when registry configs are
+  used (this cannot be disabled for registry configs). For fully offline, metric-free
+  scans, commit local rule files and point `HARNESS_SEMGREP_CONFIG` at them.
+- `auto` picks rulesets based on the languages it detects — convenient, but pin a
+  named ruleset (`p/ci`) when you want reproducible results.
+
+## Tuning noise
+
+- Semgrep respects `.gitignore` by default; add a [`.semgrepignore`](https://semgrep.dev/docs/ignoring-files-folders-code)
+  file for extra exclusions (vendored code, generated files, fixtures).
+- The stage always passes `--exclude .har` — harness scaffolding is not your
+  project's code and semgrep cannot parse some of its bash.
+- Suppress a single finding with a trailing `# nosemgrep: <rule-id>` comment —
+  prefer rule-scoped suppressions over blanket `# nosemgrep`.
+- Write repo-specific rules under `.semgrep/` and add the directory to your config.
+
+## CI and compliance (Vanta)
+
+Of the security plugins, this one has the strongest compliance story. The optional
+workflow `.github/workflows/semgrep.yml` runs `semgrep ci` in the official
+`semgrep/semgrep` container. With a `SEMGREP_APP_TOKEN` secret (generated in
+Semgrep AppSec Platform → Settings), findings publish to the
+[Semgrep AppSec Platform](https://semgrep.dev/login) — which has a
+[native Vanta integration](https://help.vanta.com/en/articles/15705377-connecting-vanta-semgrep):
+Vanta pulls findings, projects, and scan history from Semgrep automatically as
+compliance evidence.
+
+Division of labor:
+
+- **This local stage** is the shift-left layer — agents catch findings *before*
+  code lands on the default branch. Local runs are invisible to Vanta (no noise).
+- **The CI run** (`semgrep ci` on the default branch and PRs) is the org-level
+  evidence layer Vanta reads.
+
+Without a token, the workflow falls back to `semgrep scan --config auto --error`
+(Community Edition — CI still blocks on findings, but nothing publishes to the
+platform and there is no Vanta evidence).
+
+## Adapting per repo
+
+- Pin `HARNESS_SEMGREP_CONFIG` to the ruleset your team standardizes on.
+- Add `.semgrepignore` entries for paths that produce noise.
+- If findings should not block agents yet, keep `sast` out of `verificationStages`
+  in `.har/stages.json` and run it manually while you triage the baseline.
+- The stage summarizes reports with `node`; it assumes a Node.js toolchain is
+  available (true for HAR-provisioned slots on node ecosystems — on other stacks,
+  ensure `node` is on PATH or adapt the summary block).

package/dist/templates/plugins/semgrep/.har/stages/sast.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Semgrep SAST scan for an agent slot.
+# Scans the session worktree with Semgrep and writes JSON + SARIF reports.
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/stages/sast.sh <agent-id> [paths...]
+#   paths (optional): scan only these paths instead of the whole worktree
+#
+# Config: HARNESS_SEMGREP_CONFIG (default "auto") — any semgrep --config value,
+#   e.g. "p/ci", "p/security-audit", or a local rules file/dir. Set it in
+#   .har/harness.env to pin rulesets. Registry configs (auto, p/...) need
+#   network access and send pseudonymized metrics to semgrep.dev.
+#
+# Prerequisite: ./.har/launch.sh <agent-id> AND the semgrep CLI installed
+# See: ./.har/stages/SEMGREP.md for the full 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: sast.sh <agent-id> [paths...]}"
+shift
+SCAN_PATHS=("$@")
+
+validate_agent_id "$AGENT_ID"
+
+log() { echo "==> [semgrep agent-$AGENT_ID] $*" >&2; }
+
+# ── Preflight ─────────────────────────────────────────────────────────────────
+if ! command -v semgrep >/dev/null 2>&1; then
+  echo "Error: semgrep CLI not found." >&2
+  echo "  Install with one of:" >&2
+  echo "    pipx install semgrep      # recommended" >&2
+  echo "    pip install semgrep" >&2
+  echo "    brew install semgrep      # may lag behind the latest release" >&2
+  echo "  Then re-run: ./.har/stages/sast.sh ${AGENT_ID}" >&2
+  exit 1
+fi
+
+# ── 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
+}
+
+# .env.agent.<id> exports REPO_ROOT pointing at the worktree — keep the main
+# checkout path so artifacts land in the main repo root, not the worktree.
+MAIN_REPO_ROOT="$REPO_ROOT"
+
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+
+WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+
+# ── Artifact directory (main repo root, not the worktree) ─────────────────────
+ARTIFACT_DIR="$MAIN_REPO_ROOT/.har/artifacts/sast"
+mkdir -p "$ARTIFACT_DIR"
+
+SEMGREP_CONFIG="${HARNESS_SEMGREP_CONFIG:-auto}"
+JSON_REPORT="$ARTIFACT_DIR/semgrep.json"
+SARIF_REPORT="$ARTIFACT_DIR/semgrep.sarif"
+SCAN_LOG="$ARTIFACT_DIR/scan.log"
+
+# ── Run semgrep ───────────────────────────────────────────────────────────────
+log "Scanning $WORK_DIR (config: $SEMGREP_CONFIG)..."
+START=$(now_ms)
+
+set +e
+(
+  cd "$WORK_DIR" &&
+  semgrep scan \
+    --config "$SEMGREP_CONFIG" \
+    --error \
+    --exclude .har \
+    --json-output "$JSON_REPORT" \
+    --sarif-output "$SARIF_REPORT" \
+    ${SCAN_PATHS[@]+"${SCAN_PATHS[@]}"}
+) >"$SCAN_LOG" 2>&1
+SEMGREP_EXIT=$?
+set -e
+
+END=$(now_ms)
+TOTAL_MS=$(( END - START ))
+
+# Surface the scan tail so failures are diagnosable without opening the log
+tail -20 "$SCAN_LOG" | sed 's/^/    /' >&2
+
+# semgrep exit codes: 0 = clean, 1 = findings (--error), >=2 = scan error
+if [ "$SEMGREP_EXIT" = "0" ]; then
+  STATUS="pass"
+  log "✓ No blocking findings (${TOTAL_MS}ms)"
+elif [ "$SEMGREP_EXIT" = "1" ]; then
+  STATUS="fail"
+  log "✗ Semgrep reported findings (${TOTAL_MS}ms) — see $JSON_REPORT"
+else
+  STATUS="fail"
+  log "✗ Semgrep scan errored with exit code $SEMGREP_EXIT (${TOTAL_MS}ms) — see $SCAN_LOG"
+fi
+
+# ── Output ────────────────────────────────────────────────────────────────────
+node -e "
+const fs = require('fs');
+let findings = null;
+let errors = null;
+try {
+  const report = JSON.parse(fs.readFileSync('$JSON_REPORT', 'utf8'));
+  findings = report.results ? report.results.length : 0;
+  errors = report.errors ? report.errors.length : 0;
+} catch { /* report missing when the scan itself errored */ }
+const out = {
+  status: '$STATUS',
+  stageId: 'sast',
+  kind: 'test',
+  agent_id: $AGENT_ID,
+  total_ms: $TOTAL_MS,
+  exit_code: $SEMGREP_EXIT,
+  config: '$SEMGREP_CONFIG',
+  findings,
+  scan_errors: errors,
+  artifacts: [
+    { path: '.har/artifacts/sast', kind: 'directory' },
+    { path: '.har/artifacts/sast/semgrep.json', kind: 'report' }
+  ]
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+if [ "$SEMGREP_EXIT" != "0" ]; then
+  exit "$SEMGREP_EXIT"
+fi

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

@@ -0,0 +1,57 @@
+# Semgrep plugin
+
+Add a Semgrep SAST stage to your harness so agents catch security findings
+before code lands.
+
+```bash
+har env add-plugin semgrep
+```
+
+## What this installs
+
+| File | Purpose |
+|------|---------|
+| `.har/stages/sast.sh` | Stage runner — scans the session worktree with Semgrep |
+| `.har/stages/SEMGREP.md` | Adaptation guide: rulesets, noise tuning, CI/Vanta story |
+| `.github/workflows/semgrep.yml` | Optional CI workflow (`--skip-ci` to omit) — official `semgrep ci` recipe |
+
+## Workflow
+
+```
+        Code change
+             │
+       launch slot
+             │
+   typecheck + unit-tests
+             │
+           sast  ◄── semgrep scan over the worktree
+             │
+          pass/fail
+```
+
+Full verify (`verify --full`) runs the scan after lint. Reports (JSON + SARIF)
+land under `.har/artifacts/sast/`.
+
+## Requirements
+
+- `semgrep` CLI: `pipx install semgrep` (recommended), `pip install semgrep`,
+  or `brew install semgrep`
+- Network access for registry rulesets (`auto`, `p/ci`, …) — or commit local
+  rules and set `HARNESS_SEMGREP_CONFIG` to their path for offline scans
+
+## Compliance (Vanta)
+
+The local stage is shift-left only — compliance platforms never see it. The CI
+workflow's `semgrep ci` run (with a `SEMGREP_APP_TOKEN` secret) publishes to the
+Semgrep AppSec Platform, which Vanta ingests natively as vulnerability-management
+evidence. See `.har/stages/SEMGREP.md` for the full story.
+
+## Quick start after install
+
+```bash
+pipx install semgrep
+./.har/launch.sh 1
+./.har/stages/sast.sh 1
+# reports: .har/artifacts/sast/semgrep.json (+ .sarif, scan.log)
+./.har/verify.sh 1 --full
+```

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

@@ -0,0 +1,44 @@
+{
+  "id": "semgrep",
+  "stageId": "sast",
+  "verificationStages": [
+    "typecheck",
+    "unit-tests",
+    "lint",
+    "sast"
+  ],
+  "stage": {
+    "id": "sast",
+    "kind": "test",
+    "description": "Static analysis (SAST) with Semgrep — scans the session worktree for security findings",
+    "script": "stages/sast.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/sast",
+        "kind": "directory",
+        "description": "Semgrep JSON + SARIF reports and scan log"
+      },
+      {
+        "path": ".har/artifacts/sast/semgrep.json",
+        "kind": "report"
+      }
+    ]
+  },
+  "files": [
+    { "src": ".har/stages/sast.sh", "dest": ".har/stages/sast.sh", "executable": true },
+    { "src": ".har/stages/SEMGREP.md", "dest": ".har/stages/SEMGREP.md" }
+  ],
+  "optionalFiles": [
+    { "src": ".github/workflows/semgrep.yml", "dest": ".github/workflows/semgrep.yml", "skipFlag": "skipCi" }
+  ],
+  "nextSteps": [
+    "pipx install semgrep   # or: pip install semgrep / brew install semgrep",
+    "./.har/launch.sh 1",
+    "./.har/stages/sast.sh 1",
+    "Open .har/artifacts/sast/ for the JSON and SARIF reports",
+    "Read .har/stages/SEMGREP.md to pin rulesets (HARNESS_SEMGREP_CONFIG) or add local rules",
+    "CI: set the SEMGREP_APP_TOKEN secret so semgrep ci reports to the Semgrep AppSec Platform (compliance evidence, e.g. Vanta)"
+  ],
+  "docsPath": ".har/stages/SEMGREP.md"
+}

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

@@ -0,0 +1,40 @@
+name: Trivy scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Trivy (filesystem scan)
+        uses: aquasecurity/trivy-action@a9c7b0f06e461e9d4b4d1711f154ee024b8d7ab8 # v0.36.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln,misconfig
+          severity: HIGH,CRITICAL
+          format: sarif
+          output: trivy-results.sarif
+          exit-code: 0
+      - name: Upload SARIF to GitHub code scanning
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: trivy-results.sarif
+      - name: Fail on HIGH/CRITICAL findings
+        uses: aquasecurity/trivy-action@a9c7b0f06e461e9d4b4d1711f154ee024b8d7ab8 # v0.36.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln,misconfig
+          severity: HIGH,CRITICAL
+          format: table
+          exit-code: 1
+          skip-setup-trivy: true

package/dist/templates/plugins/trivy/.har/stages/TRIVY.md

@@ -0,0 +1,88 @@
+# Trivy Vulnerability & Misconfiguration Scanning
+
+The `vuln-scan` stage runs [Trivy](https://trivy.dev) against the agent's
+worktree: known CVEs in dependency lockfiles (`vuln` scanner) and IaC/config
+misconfigurations in Terraform, Dockerfiles, Kubernetes manifests, Helm charts,
+and CloudFormation (`misconfig` scanner). Full verify (`verify --full`) runs it
+automatically.
+
+Trivy absorbed **tfsec** — its Terraform checks now live in Trivy's `misconfig`
+scanner, so this plugin covers the Terraform/IaC use case without a separate tool.
+
+## What runs
+
+```bash
+trivy fs --scanners vuln,misconfig --severity HIGH,CRITICAL --exit-code 1 \
+  --format json --output .har/artifacts/vuln-scan/report.json <work-dir>
+```
+
+The stage **fails** when any finding at or above the severity threshold exists.
+Findings below the threshold are not reported at all — raise or lower the bar
+via configuration.
+
+## Configuration
+
+Set in `harness.env` (or export before running):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HARNESS_TRIVY_SEVERITY` | `HIGH,CRITICAL` | Comma-separated severities that fail the stage (`UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL`) |
+| `HARNESS_TRIVY_SCANNERS` | `vuln,misconfig` | Scanners to run (`vuln`, `misconfig`, `secret`, `license`) |
+| `TRIVY_CACHE_DIR` | `~/.cache/trivy` | Vulnerability DB cache — kept **outside** the worktrees so every slot shares one DB download (~60MB, refreshed every ~6h) |
+
+## Artifacts
+
+| Path | Contents |
+|------|----------|
+| `.har/artifacts/vuln-scan/report.json` | Full Trivy JSON report (machine-readable) |
+| `.har/artifacts/vuln-scan/summary.txt` | Human-readable table (`trivy convert`) |
+
+Artifacts always land in the **main repo root** `.har/artifacts/`, not the worktree.
+
+## Suppressing findings
+
+Add IDs to `.trivyignore` at the repo root — one CVE / check ID per line, no
+trailing comments on the ID line:
+
+```
+# Accepted risk: dev-only dependency, fix tracked in TICKET-123 (expires when bumped)
+CVE-2021-23337
+# Terraform check that conflicts with our architecture
+AVD-AWS-0086
+```
+
+The stage passes the **worktree's** copy via `--ignorefile`, so a suppression
+travels with the change batch that introduces it and gets reviewed in the same
+PR. Prefer fixing (bump the dependency, correct the config) over ignoring.
+
+## Adaptations per repo
+
+- **Container images**: the default stage scans the filesystem only. If the repo
+  builds an image, add a second invocation after the build:
+  `trivy image --severity "$SEVERITY" --exit-code 1 <image:tag>`.
+- **Monorepos**: scope the scan by replacing `"$WORK_DIR"` with a subdirectory,
+  or add `--skip-dirs 'vendor/**,examples/**'`.
+- **Lockfile-only scanning**: Trivy reads lockfiles (`package-lock.json`,
+  `yarn.lock`, `poetry.lock`, `go.sum`, `Cargo.lock`, …). Repos without a
+  lockfile get no dependency findings — commit one for meaningful results.
+- **Secrets**: this harness pairs well with a dedicated secrets stage
+  (gitleaks plugin, which scans git history, not just the checkout). Add
+  `secret` to `HARNESS_TRIVY_SCANNERS` only if you don't run one.
+
+## CI and compliance platforms (Vanta, Drata, …)
+
+The local stage is **pre-merge shift-left** — it keeps findings from ever
+reaching your default branch. Compliance platforms never see local runs.
+
+The optional workflow `.github/workflows/trivy.yml` runs the same scan in CI and
+uploads SARIF to **GitHub code scanning** (the repo's Security tab). That
+org-level layer is what compliance platforms like Vanta ingest as evidence (via
+their GitHub integration). Keep both: local stage to catch early, CI workflow to
+produce the evidence.
+
+## Running
+
+```bash
+./.har/stages/vuln-scan.sh 1        # standalone
+./.har/verify.sh 1 --full           # as part of full verification
+```

package/dist/templates/plugins/trivy/.har/stages/vuln-scan.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Trivy vulnerability + misconfiguration scan for an agent slot.
+# Scans the agent's worktree filesystem: dependency lockfiles (vuln) and
+# IaC/config files — Terraform, Dockerfile, Kubernetes, CloudFormation (misconfig).
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/stages/vuln-scan.sh <agent-id>
+#
+# Tune via harness.env or the environment:
+#   HARNESS_TRIVY_SEVERITY  fail threshold (default: HIGH,CRITICAL)
+#   HARNESS_TRIVY_SCANNERS  scanners to run (default: vuln,misconfig)
+#   TRIVY_CACHE_DIR         vulnerability DB cache (default: ~/.cache/trivy —
+#                           shared across slots so the DB downloads once)
+#
+# Prerequisite: ./.har/launch.sh <agent-id>
+# See: ./.har/stages/TRIVY.md for the full 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: vuln-scan.sh <agent-id>}"
+
+validate_agent_id "$AGENT_ID"
+
+log() { echo "==> [vuln-scan agent-$AGENT_ID] $*" >&2; }
+
+# ── Preflight ─────────────────────────────────────────────────────────────────
+if ! command -v trivy >/dev/null 2>&1; then
+  echo "Error: trivy CLI not found." >&2
+  echo "  Install: https://trivy.dev/latest/getting-started/installation/" >&2
+  echo "    macOS:  brew install trivy" >&2
+  echo "    Linux:  curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b ~/.local/bin" >&2
+  echo "  Then re-run: ./.har/stages/vuln-scan.sh ${AGENT_ID}" >&2
+  exit 1
+fi
+
+# ── 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")"
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+SEVERITY="${HARNESS_TRIVY_SEVERITY:-HIGH,CRITICAL}"
+SCANNERS="${HARNESS_TRIVY_SCANNERS:-vuln,misconfig}"
+# One shared DB cache for every slot/worktree — first run downloads ~60MB,
+# subsequent runs reuse it.
+export TRIVY_CACHE_DIR="${TRIVY_CACHE_DIR:-$HOME/.cache/trivy}"
+
+# ── Artifact directory ────────────────────────────────────────────────────────
+ARTIFACT_DIR="$REPO_ROOT/.har/artifacts/vuln-scan"
+mkdir -p "$ARTIFACT_DIR"
+REPORT_JSON="$ARTIFACT_DIR/report.json"
+
+# ── Scan ──────────────────────────────────────────────────────────────────────
+# Use the WORKTREE's .trivyignore (not the main checkout's) so suppressions are
+# reviewed with the code change that introduces them.
+IGNOREFILE_ARGS=()
+if [ -f "$WORK_DIR/.trivyignore" ]; then
+  IGNOREFILE_ARGS=(--ignorefile "$WORK_DIR/.trivyignore")
+fi
+
+log "Scanning $WORK_DIR (scanners: $SCANNERS, fail on: $SEVERITY)..."
+START=$(now_ms)
+
+set +e
+trivy fs \
+  --scanners "$SCANNERS" \
+  --severity "$SEVERITY" \
+  --exit-code 1 \
+  --format json \
+  --output "$REPORT_JSON" \
+  --no-progress \
+  ${IGNOREFILE_ARGS[@]+"${IGNOREFILE_ARGS[@]}"} \
+  "$WORK_DIR" 2> >(sed 's/^/  /' >&2)
+TRIVY_EXIT=$?
+set -e
+
+END=$(now_ms)
+TOTAL_MS=$(( END - START ))
+
+if [ ! -f "$REPORT_JSON" ]; then
+  echo "Error: trivy did not produce a report (exit $TRIVY_EXIT) — see stderr above." >&2
+  exit "$TRIVY_EXIT"
+fi
+
+# Human-readable summary next to the JSON report (best effort)
+trivy convert --format table "$REPORT_JSON" > "$ARTIFACT_DIR/summary.txt" 2>/dev/null || true
+
+# ── Output ────────────────────────────────────────────────────────────────────
+STATUS="pass"
+if [ "$TRIVY_EXIT" -ne 0 ]; then
+  STATUS="fail"
+fi
+
+node -e "
+const fs = require('fs');
+const report = JSON.parse(fs.readFileSync('$REPORT_JSON', 'utf8'));
+const results = report.Results || [];
+let vulnerabilities = 0;
+let misconfigurations = 0;
+let secrets = 0;
+const findings = [];
+for (const r of results) {
+  for (const v of r.Vulnerabilities || []) {
+    vulnerabilities++;
+    findings.push({ type: 'vuln', target: r.Target, id: v.VulnerabilityID, pkg: v.PkgName, installed: v.InstalledVersion, fixed: v.FixedVersion || null, severity: v.Severity, title: (v.Title || '').slice(0, 120) });
+  }
+  for (const m of r.Misconfigurations || []) {
+    misconfigurations++;
+    findings.push({ type: 'misconfig', target: r.Target, id: m.ID, severity: m.Severity, title: (m.Title || '').slice(0, 120) });
+  }
+  for (const s of r.Secrets || []) {
+    secrets++;
+    findings.push({ type: 'secret', target: r.Target, id: s.RuleID, severity: s.Severity, title: (s.Title || '').slice(0, 120) });
+  }
+}
+const out = {
+  status: '$STATUS',
+  stageId: 'vuln-scan',
+  kind: 'test',
+  agent_id: $AGENT_ID,
+  total_ms: $TOTAL_MS,
+  severity_threshold: '$SEVERITY',
+  scanners: '$SCANNERS',
+  counts: { vulnerabilities, misconfigurations, secrets },
+  findings: findings.slice(0, 50),
+  artifacts: [
+    { path: '.har/artifacts/vuln-scan/report.json', kind: 'report' },
+    { path: '.har/artifacts/vuln-scan/summary.txt', kind: 'report' }
+  ]
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+if [ "$STATUS" = "fail" ]; then
+  log "✗ Findings at or above $SEVERITY — see .har/artifacts/vuln-scan/summary.txt"
+  exit 1
+fi
+log "✓ No findings at or above $SEVERITY (${TOTAL_MS}ms)"

package/dist/templates/plugins/trivy/.trivyignore

@@ -0,0 +1,9 @@
+# .trivyignore — suppress specific Trivy findings (one ID per line, no trailing
+# comments). Prefer fixing over ignoring. Document every entry with a comment
+# line above it saying why and when it can go.
+#
+# Example:
+# # dev-only dependency, fix tracked in TICKET-123
+# CVE-2021-23337
+# # S3 public access is intentional for the www bucket
+# AVD-AWS-0086

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

@@ -0,0 +1,32 @@
+# Trivy plugin
+
+Installs a `vuln-scan` stage that runs [Trivy](https://trivy.dev) against the
+agent's worktree:
+
+- **Dependency vulnerabilities** — known CVEs in lockfiles (`package-lock.json`,
+  `yarn.lock`, `poetry.lock`, `go.sum`, `Cargo.lock`, …)
+- **IaC misconfigurations** — Terraform, Dockerfile, Kubernetes, Helm,
+  CloudFormation (Trivy absorbed tfsec, so this covers the Terraform use case)
+
+```bash
+har env add-plugin trivy            # --skip-ci to omit the GitHub workflow
+```
+
+What it adds:
+
+- `.har/stages/vuln-scan.sh` — the stage, registered in `.har/stages.json` and
+  appended to `verificationStages` (runs on `verify --full`)
+- `.har/stages/TRIVY.md` — adaptation guide (severity threshold, scanners,
+  container-image scanning, monorepo scoping)
+- `.trivyignore` — suppression file scaffold
+- `.github/workflows/trivy.yml` *(optional)* — same scan in CI with SARIF upload
+  to GitHub code scanning; that org-level layer is what compliance platforms
+  like Vanta ingest as evidence
+
+External requirement: the `trivy` binary (`brew install trivy` or the
+[install script](https://trivy.dev/latest/getting-started/installation/)).
+The stage fails fast with an install hint when it is missing.
+
+Fail threshold defaults to `HIGH,CRITICAL` — override with
+`HARNESS_TRIVY_SEVERITY` in `.har/harness.env`. Reports land in
+`.har/artifacts/vuln-scan/`.

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

@@ -0,0 +1,44 @@
+{
+  "id": "trivy",
+  "stageId": "vuln-scan",
+  "verificationStages": [
+    "typecheck",
+    "unit-tests",
+    "lint",
+    "vuln-scan"
+  ],
+  "stage": {
+    "id": "vuln-scan",
+    "kind": "test",
+    "description": "Trivy vulnerability + IaC misconfiguration scan (dependencies, Terraform, Dockerfile, K8s)",
+    "script": "stages/vuln-scan.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/vuln-scan",
+        "kind": "directory",
+        "description": "Trivy JSON report and human-readable summary"
+      },
+      {
+        "path": ".har/artifacts/vuln-scan/report.json",
+        "kind": "report"
+      }
+    ]
+  },
+  "files": [
+    { "src": ".har/stages/vuln-scan.sh", "dest": ".har/stages/vuln-scan.sh", "executable": true },
+    { "src": ".har/stages/TRIVY.md",     "dest": ".har/stages/TRIVY.md" },
+    { "src": ".trivyignore",             "dest": ".trivyignore" }
+  ],
+  "optionalFiles": [
+    { "src": ".github/workflows/trivy.yml", "dest": ".github/workflows/trivy.yml", "skipFlag": "skipCi" }
+  ],
+  "nextSteps": [
+    "Install trivy: brew install trivy (or https://trivy.dev/latest/getting-started/installation/)",
+    "./.har/launch.sh 1",
+    "./.har/stages/vuln-scan.sh 1",
+    "Open .har/artifacts/vuln-scan/summary.txt for findings",
+    "Tune HARNESS_TRIVY_SEVERITY / HARNESS_TRIVY_SCANNERS in .har/harness.env — read .har/stages/TRIVY.md"
+  ],
+  "docsPath": ".har/stages/TRIVY.md"
+}

package/package.json

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