Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
9.8 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Run Hermes' own plugin install scanner (`tools/plugin_guard.py`) over this
 * repository, the way `hermes plugins install itechmeat/open-second-brain`
 * does, and fail when it would block the install.
 *
 * Hermes scans the fresh clone before it installs anything and refuses a
 * `dangerous` verdict (any critical finding) outright - `--force` does not
 * override it (#188). The scanner reads every tracked file, docs and tests
 * included, so a threat-model sentence or a hardening comment can block the
 * install as surely as real code. This gate runs the same scanner here, so
 * the pull request that adds such a line is the one that goes red.
 *
 * The scanner is fetched from NousResearch/hermes-agent (MIT) at a pinned
 * commit and checked against pinned SHA-256 digests before it runs. It is
 * three stdlib-only Python modules; nothing else from Hermes is needed. To
 * move the pin: change HERMES_COMMIT, run with `--print-digests`, paste the
 * new digests, and re-check the verdict. A rate-limited (HTTP 429) or server-error
 * response is retried a bounded number of times with backoff; the last status
 * is reported by name once the attempts run out.
 *
 * Scanned trees (the tracked files only, exported to a temp dir, as a clone
 * would have them):
 *   - `.`               the documented install (`plugin.yaml` at the root)
 *   - `plugins/hermes`  a subdirectory install of the Python provider
 *
 * Usage:
 *   bun run scripts/hermes-plugin-scan.ts             # exit 1 on "dangerous"
 *   bun run scripts/hermes-plugin-scan.ts --verbose   # also list high findings
 *   bun run scripts/hermes-plugin-scan.ts --print-digests
 *
 * Env: PYTHON (default `python3`); GITHUB_TOKEN / GH_TOKEN (optional, lifts
 * the anonymous GitHub API rate limit).
 */

import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import {
  copyFileSync,
  existsSync,
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readlinkSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");

/** hermes-agent v2026.9.24 (package 0.21.5, scanner `plugin-guard-v8`). */
const HERMES_REPO = "NousResearch/hermes-agent";
const HERMES_COMMIT = "f97608f178d1ffeca59860195ab7da295f7c8e5f";
const GUARD_FILES: Readonly<Record<string, string>> = {
  "tools/plugin_guard.py": "6fbece00d5e4f98a05231f958172539cf72cc2869745f1d39c4cd5f427b99573",
  "tools/plugin_guard_context.py":
    "0fd6c698926590b6d4464652b8857c4955795697af6d088452cc79f923eab7d8",
  "tools/skills_guard.py": "ad9d3616c67fa2f0707dd8c6007d652a0cb44ad6ae51eb5d888ed57be2230bd1",
};

const TARGETS: readonly string[] = [".", "plugins/hermes"];

const argv = new Set(process.argv.slice(2));
const verbose = argv.has("--verbose");
const printDigests = argv.has("--print-digests");

function sha256(data: Uint8Array): string {
  return createHash("sha256").update(data).digest("hex");
}

/** Attempts per scanner file before a rate limit or server error is final. */
export const GUARD_FETCH_ATTEMPTS = 5;
/** Wait before the first retry; each later retry doubles it. */
export const GUARD_FETCH_BASE_DELAY_MS = 2000;
const HTTP_TOO_MANY_REQUESTS = 429;
const HTTP_SERVER_ERROR_MIN = 500;
const MS_PER_SECOND = 1000;

/** The network and clock a fetch uses; tests pass stubs. */
export interface GuardFetchDeps {
  fetch: (url: string, init: RequestInit) => Promise<Response>;
  sleep: (ms: number) => Promise<void>;
}

const defaultDeps: GuardFetchDeps = {
  fetch: (url, init) => fetch(url, init),
  sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
};

/** A shared runner can hit the API rate limit or a transient server error. */
function isRetryable(status: number): boolean {
  return status === HTTP_TOO_MANY_REQUESTS || status >= HTTP_SERVER_ERROR_MIN;
}

/** The wait the server asked for (`Retry-After` in seconds), else exponential backoff. */
function retryDelayMs(res: Response, retry: number): number {
  const seconds = Number(res.headers.get("Retry-After"));
  if (Number.isFinite(seconds) && seconds > 0) return seconds * MS_PER_SECOND;
  return GUARD_FETCH_BASE_DELAY_MS * 2 ** retry;
}

export async function fetchGuardFile(
  path: string,
  deps: GuardFetchDeps = defaultDeps,
): Promise<Uint8Array> {
  const url = `https://api.github.com/repos/${HERMES_REPO}/contents/${path}?ref=${HERMES_COMMIT}`;
  const token = process.env["GITHUB_TOKEN"] ?? process.env["GH_TOKEN"];
  const headers: Record<string, string> = {
    Accept: "application/vnd.github.raw",
    "User-Agent": "open-second-brain-hermes-plugin-scan",
  };
  if (token) headers["Authorization"] = `Bearer ${token}`;
  // Retries are sequential by design: each waits on the previous response.
  for (let attempt = 1; ; attempt++) {
    // oxlint-disable-next-line no-await-in-loop
    const res = await deps.fetch(url, { headers });
    // oxlint-disable-next-line no-await-in-loop
    if (res.ok) return new Uint8Array(await res.arrayBuffer());
    if (!isRetryable(res.status) || attempt === GUARD_FETCH_ATTEMPTS) {
      const tries = `${attempt} attempt${attempt === 1 ? "" : "s"}`;
      throw new Error(`fetch ${path}@${HERMES_COMMIT}: HTTP ${res.status} after ${tries}`);
    }
    // oxlint-disable-next-line no-await-in-loop
    await deps.sleep(retryDelayMs(res, attempt - 1));
  }
}

/** Write the scanner modules at the pinned commit, digest-checked, under `dir`. */
async function writeGuard(dir: string): Promise<void> {
  const files = await Promise.all(
    Object.entries(GUARD_FILES).map(async ([path, digest]) => ({
      path,
      digest,
      data: await fetchGuardFile(path),
    })),
  );
  for (const { path, digest, data } of files) {
    const actual = sha256(data);
    if (printDigests) {
      process.stdout.write(`${path} ${actual}\n`);
      continue;
    }
    if (actual !== digest) {
      throw new Error(`${path}@${HERMES_COMMIT}: sha256 ${actual}, expected ${digest}`);
    }
    const dest = join(dir, path);
    mkdirSync(dirname(dest), { recursive: true });
    writeFileSync(dest, data);
  }
}

/** Copy the tracked files (working-tree content) under `out`: what a clone holds. */
function exportTrackedTree(out: string): string {
  const ls = spawnSync("git", ["ls-files", "-z", "--cached"], {
    cwd: ROOT,
    encoding: "utf8",
  });
  if (ls.status !== 0) throw new Error(`git ls-files failed: ${ls.stderr}`);
  const tree = join(out, "open-second-brain");
  for (const rel of ls.stdout.split("\0")) {
    if (rel === "") continue;
    const src = join(ROOT, rel);
    if (!existsSync(src) && !isSymlink(src)) continue; // deleted in the working tree
    const dest = join(tree, rel);
    mkdirSync(dirname(dest), { recursive: true });
    if (isSymlink(src)) symlinkSync(readlinkSync(src), dest);
    else copyFileSync(src, dest);
  }
  return tree;
}

function isSymlink(p: string): boolean {
  try {
    return lstatSync(p).isSymbolicLink();
  } catch {
    return false;
  }
}

const DRIVER = `
import json, sys
from pathlib import Path
sys.path.insert(0, sys.argv[1])
from tools.plugin_guard import scan_plugin, PLUGIN_SCANNER_VERSION
out = []
for target in sys.argv[2:]:
    r = scan_plugin(Path(target))
    out.append({"target": target, "verdict": r.verdict, "scanner": PLUGIN_SCANNER_VERSION,
                "findings": [{"severity": f.severity, "pattern": f.pattern_id, "file": f.file,
                              "line": f.line, "match": f.match} for f in r.findings]})
print(json.dumps(out))
`;

interface ScanFinding {
  severity: string;
  pattern: string;
  file: string;
  line: number;
  match: string;
}
interface ScanReport {
  target: string;
  verdict: string;
  scanner: string;
  findings: ScanFinding[];
}

async function main(): Promise<number> {
  // One scratch dir for the scanner and the exported tree, removed below:
  // the run leaves nothing on the machine.
  const scratch = mkdtempSync(join(tmpdir(), "osb-hermes-scan-"));
  try {
    const guard = join(scratch, "guard");
    await writeGuard(guard);
    if (printDigests) return 0;
    const tree = exportTrackedTree(scratch);
    const python = process.env["PYTHON"] ?? "python3";
    const run = spawnSync(python, ["-c", DRIVER, guard, ...TARGETS.map((t) => join(tree, t))], {
      encoding: "utf8",
      maxBuffer: 256 * 1024 * 1024,
    });
    if (run.status !== 0) {
      process.stderr.write(run.stderr);
      throw new Error(`${python} exited ${String(run.status)}`);
    }
    const reports = JSON.parse(run.stdout) as ScanReport[];
    let blocked = false;
    for (const [i, report] of reports.entries()) {
      const counts = { critical: 0, high: 0, medium: 0, low: 0 } as Record<string, number>;
      for (const f of report.findings) counts[f.severity] = (counts[f.severity] ?? 0) + 1;
      process.stdout.write(
        `hermes plugin scan (${report.scanner}, hermes-agent@${HERMES_COMMIT.slice(0, 12)}) ` +
          `${TARGETS[i] ?? report.target}: ${report.verdict} - ` +
          `critical ${counts["critical"]}, high ${counts["high"]}, ` +
          `medium ${counts["medium"]}, low ${counts["low"]}\n`,
      );
      const shown = report.findings.filter(
        (f) => f.severity === "critical" || (verbose && f.severity === "high"),
      );
      for (const f of shown) {
        process.stdout.write(`  [${f.severity}] ${f.pattern} ${f.file}:${f.line}  ${f.match}\n`);
      }
      if (report.verdict === "dangerous") blocked = true;
    }
    if (blocked) {
      process.stdout.write(
        "Hermes would BLOCK the install (a dangerous verdict cannot be forced). " +
          "Reword the critical lines above; JS/TS JSDoc lines are not treated as comments.\n",
      );
    }
    return blocked ? 1 : 0;
  } finally {
    rmSync(scratch, { recursive: true, force: true });
  }
}

if (import.meta.main) {
  process.exit(await main());
}