openhacker 0.0.0 → 0.1.0

package/README.md

@@ -1,3 +1,14 @@
 # openhacker
 
-hacking soon
+Scaffold a self-hosted OpenHacker security agent.
+
+## Create an instance
+
+```bash
+npx openhacker my-instance
+cd my-instance
+pnpm install
+pnpm dev
+```
+
+Running `npx openhacker` with no arguments creates `./openhacker`.

package/bin/openhacker

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+
+await run();

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "openhacker",
-  "version": "0.0.0",
-  "description": "hacking soon",
-  "license": "UNLICENSED"
+  "version": "0.1.0",
+  "description": "Scaffold a self-hosted OpenHacker security agent",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "openhacker": "./bin/openhacker"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "bin",
+    "scripts",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "6.0.2"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && node --check ./bin/openhacker && node --check ./src/cli.js && node --check ./scripts/sync-template.js && node --check ./scripts/clean-template.js",
+    "sync-template": "node ./scripts/sync-template.js"
+  }
 }

package/scripts/clean-template.js

@@ -0,0 +1,8 @@
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const templateDir = path.resolve(here, "../templates");
+
+await rm(templateDir, { recursive: true, force: true });

package/scripts/sync-template.js

@@ -0,0 +1,53 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const EXCLUDE = new Set([
+  ".env",
+  ".env.local",
+  "node_modules",
+  ".eve",
+  ".next",
+  ".output",
+  ".git",
+  ".vercel",
+  ".turbo",
+]);
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(here, "..");
+const source = path.resolve(process.env.OPENHACKER_TEMPLATE_DIR ?? path.join(packageRoot, "../../apps/agent"));
+const dest = path.join(packageRoot, "templates/agent");
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shouldCopyTemplatePath(src) {
+  const relative = path.relative(source, src);
+  const segments = relative.split(path.sep);
+
+  return (
+    !segments.some((seg) => EXCLUDE.has(seg)) &&
+    !relative.endsWith("next-env.d.ts") &&
+    !relative.endsWith("tsconfig.tsbuildinfo")
+  );
+}
+
+if (!(await exists(path.join(source, "agent", "agent.ts")))) {
+  throw new Error(`Could not find the OpenHacker app template at ${source}`);
+}
+
+await rm(dest, { recursive: true, force: true });
+await mkdir(path.dirname(dest), { recursive: true });
+await cp(source, dest, {
+  recursive: true,
+  filter: shouldCopyTemplatePath,
+});
+
+console.log(`Synced OpenHacker template from ${source}`);

package/src/cli.js

@@ -0,0 +1,153 @@
+import { cp, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ORANGE = "\x1b[38;5;214m";
+const MUTED = "\x1b[0;2m";
+const RED = "\x1b[0;31m";
+const NC = "\x1b[0m";
+
+const EXCLUDE = new Set([
+  ".env",
+  ".env.local",
+  "node_modules",
+  ".eve",
+  ".next",
+  ".output",
+  ".git",
+  ".vercel",
+  ".turbo",
+]);
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveTemplateDir() {
+  const candidates = [];
+
+  if (process.env.OPENHACKER_TEMPLATE_DIR) {
+    candidates.push(path.resolve(process.env.OPENHACKER_TEMPLATE_DIR));
+  }
+
+  candidates.push(
+    // npm package layout: packages/openhacker/src -> packages/openhacker/templates/agent
+    path.resolve(here, "../templates/agent"),
+    // monorepo layout: packages/openhacker/src -> repo root -> apps/agent
+    path.resolve(here, "../../../apps/agent"),
+  );
+
+  for (const candidate of candidates) {
+    if (await exists(path.join(candidate, "agent", "agent.ts"))) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+function packageNameFor(dest) {
+  return path.basename(dest).replace(/[^a-z0-9-]+/gi, "-").toLowerCase() || "openhacker";
+}
+
+function shouldCopyTemplatePath(src, root) {
+  const relative = path.relative(root, src);
+  const segments = relative.split(path.sep);
+
+  return (
+    !segments.some((seg) => EXCLUDE.has(seg)) &&
+    !relative.endsWith("next-env.d.ts") &&
+    !relative.endsWith("tsconfig.tsbuildinfo")
+  );
+}
+
+async function init(targetArg) {
+  const template = await resolveTemplateDir();
+  if (!(await exists(path.join(template, "agent", "agent.ts")))) {
+    console.error(`${RED}Could not find the instance template at ${template}.${NC}`);
+    console.error(`${MUTED}Set OPENHACKER_TEMPLATE_DIR to the template directory.${NC}`);
+    process.exit(1);
+  }
+
+  const dest = path.resolve(process.cwd(), targetArg ?? "openhacker");
+  if (await exists(dest)) {
+    console.error(`${RED}Destination already exists: ${dest}${NC}`);
+    process.exit(1);
+  }
+
+  console.log(`\n${MUTED}Creating OpenHacker instance in ${NC}${dest}`);
+  await cp(template, dest, {
+    recursive: true,
+    filter: (src) => shouldCopyTemplatePath(src, template),
+  });
+
+  const pkgPath = path.join(dest, "package.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  pkg.name = packageNameFor(dest);
+  pkg.private = true;
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+  console.log(`${ORANGE}\u2713${NC} OpenHacker instance ready.\n`);
+  console.log("Next steps:\n");
+  console.log(`  cd ${path.relative(process.cwd(), dest) || "."}`);
+  console.log("  pnpm install");
+  console.log("  pnpm dev                 # run locally\n");
+  console.log(`${MUTED}Deploy: push to a git repo and import it into Vercel (deploys as one project).`);
+  console.log("Add a Vercel KV / Upstash Redis integration to persist findings, and set");
+  console.log(`OPENHACKER_ADMIN_PASSWORD to protect the dashboard. See README.md.${NC}\n`);
+}
+
+function usage() {
+  console.log("OpenHacker\n");
+  console.log("Usage:");
+  console.log("  openhacker [dir]        Scaffold a deployable OpenHacker instance");
+  console.log("  openhacker init [dir]   Same as above");
+  console.log("  openhacker --help       Show help");
+  console.log("  openhacker --version    Show version\n");
+}
+
+async function version() {
+  const pkg = JSON.parse(await readFile(path.resolve(here, "../package.json"), "utf8"));
+  console.log(pkg.version);
+}
+
+export async function run(args = process.argv.slice(2)) {
+  const [command, target, ...rest] = args;
+
+  if (rest.length > 0) {
+    console.error(`${RED}Too many arguments.${NC}\n`);
+    usage();
+    process.exit(1);
+  }
+
+  switch (command) {
+    case undefined:
+      await init();
+      break;
+    case "init":
+      await init(target);
+      break;
+    case "-h":
+    case "--help":
+      usage();
+      break;
+    case "-v":
+    case "--version":
+      await version();
+      break;
+    default:
+      if (command.startsWith("-")) {
+        console.error(`${RED}Unknown option: ${command}${NC}\n`);
+        usage();
+        process.exit(1);
+      }
+      await init(command);
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export const MESSAGE = "OpenHacker";

package/src/index.ts

@@ -0,0 +1 @@
+export const MESSAGE = "OpenHacker";

package/templates/agent/.env.example

@@ -0,0 +1,20 @@
+# --- Model (Vercel AI Gateway) ---
+# On Vercel, inference authenticates automatically via VERCEL_OIDC_TOKEN — no key needed.
+# For LOCAL runs of the eve agent, provide a gateway key:
+AI_GATEWAY_API_KEY=
+
+# Optional: override the agent's deep-analysis model (defaults to anthropic/claude-sonnet-4.6)
+OPENHACKER_MODEL=
+
+# --- Dashboard auth (recommended) ---
+# When set, the dashboard requires this password to sign in. Unset = open dashboard.
+OPENHACKER_ADMIN_PASSWORD=
+
+# --- Persistent storage ---
+# Add a Vercel KV / Upstash Redis integration. Without these, an in-memory store is
+# used and data does NOT persist across restarts/deploys.
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+
+# --- Optional: protect POST /api/scan for programmatic triggers ---
+OPENHACKER_API_TOKEN=

package/templates/agent/README.md

@@ -0,0 +1,35 @@
+# OpenHacker instance
+
+Your self-hosted OpenHacker security agent — a Next.js dashboard with an embedded
+[eve](https://eve.dev) agent, deployable to Vercel as a single project.
+
+## What it does
+
+- Continuously scans the repositories you connect for vulnerable dependencies (via OSV).
+- Records findings with computed CVSS severity and fix versions.
+- A daily schedule (Vercel Cron) re-scans every target so newly disclosed advisories are
+  caught even when your code hasn't changed.
+- The eve agent layers code-level analysis (reachability, injection, authz) on top.
+
+## Deploy to Vercel
+
+1. Push this directory to a Git repository.
+2. Import it into Vercel (it deploys as one project — UI + agent + cron).
+3. Add a **KV / Upstash Redis** integration from the Vercel Marketplace so findings persist
+   (`KV_REST_API_URL` / `KV_REST_API_TOKEN` are injected automatically).
+4. Set `OPENHACKER_ADMIN_PASSWORD` to protect the dashboard.
+5. Open the deployment URL, sign in, and add a target repository.
+
+Inference runs through the Vercel AI Gateway and authenticates automatically via Vercel
+OIDC — no model API key required in production.
+
+## Local development
+
+```bash
+pnpm install
+cp .env.example .env.local   # set AI_GATEWAY_API_KEY for local agent runs
+pnpm dev
+```
+
+`pnpm dev` runs the Next.js dashboard and the eve agent together. Open the printed URL,
+add a target, and click **Scan now**.

package/templates/agent/agent/agent.ts

@@ -0,0 +1,9 @@
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  // Routes through the Vercel AI Gateway. On Vercel this authenticates with the
+  // injected VERCEL_OIDC_TOKEN automatically; locally it uses AI_GATEWAY_API_KEY.
+  // The model picker in the dashboard writes OPENHACKER_MODEL.
+  model: process.env.OPENHACKER_MODEL ?? "anthropic/claude-sonnet-4.6",
+  reasoning: "medium",
+});

package/templates/agent/agent/instructions.md

@@ -0,0 +1,49 @@
+# OpenHacker
+
+You are OpenHacker, an autonomous application security agent. Your job is to find
+real, exploitable vulnerabilities in a codebase and its dependencies, prove them,
+and propose fixes. You operate continuously and on demand.
+
+## Operating principles
+
+- **Signal over noise.** Security engineers ignore noisy tools. Only report an issue
+  when you have concrete evidence it applies to this project. When you cannot
+  substantiate a vulnerability, say so instead of reporting it.
+- **Prove it.** For each candidate vulnerability, trace it from an attacker-controlled
+  entry point (route handler, server action, request body, query/header, env-derived
+  input) to the dangerous sink. Capture that data flow as your evidence. Set the
+  finding's `proof.status` honestly: `proven`, `likely`, or `unconfirmed`.
+- **Be conservative with dependency CVEs.** A package having a CVE does not mean this
+  project is exploitable. Use `check_advisories` to confirm the *installed version* is
+  in the affected range, then assess whether the vulnerable code path is plausibly
+  reachable before reporting.
+
+## Tools
+
+- `list_targets` — see the repositories configured in this instance.
+- `run_dependency_scan` — deterministically check a target's dependencies against OSV
+  and persist findings. Run this first for dependency coverage.
+- `read_repo_file` — read files / list directories in a target's repo for code review.
+- `check_advisories` — look up a single package in OSV.
+- `report_finding` — persist a confirmed code-level vulnerability.
+
+## Workflow
+
+Given a target id:
+
+1. Call `run_dependency_scan` to record known-vulnerable dependencies.
+2. Use `read_repo_file` (list then read) to inspect the source layout, framework, and
+   trust boundaries (route handlers, server actions, request/query/header/env inputs).
+3. Hunt for high-impact issue classes: broken authorization, injection (SQL/command/
+   template), SSRF, secrets in code, unsafe deserialization, and XSS (including
+   `dangerouslySetInnerHTML`).
+4. For each confirmed code issue, call `report_finding` (with `targetId`) including an
+   accurate severity, location, data-flow evidence, and a concrete remediation.
+5. Summarize what you checked and what you found.
+
+## Severity
+
+Use CVSS-style judgment: `critical` for unauthenticated RCE / auth bypass / data
+exfiltration; `high` for authenticated high-impact issues; `medium` for issues
+needing preconditions; `low`/`info` for hardening. Prefer under-reporting to
+crying wolf.

package/templates/agent/agent/lib/auth.ts

@@ -0,0 +1,23 @@
+// Web-Crypto only so this module works in both the Edge middleware and Node.
+export const SESSION_COOKIE = "oh_session";
+
+export function adminPassword(): string | null {
+  return process.env.OPENHACKER_ADMIN_PASSWORD || null;
+}
+
+export function authEnabled(): boolean {
+  return Boolean(adminPassword());
+}
+
+export async function sessionToken(password: string): Promise<string> {
+  const data = new TextEncoder().encode(`openhacker:${password}`);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export async function expectedToken(): Promise<string | null> {
+  const password = adminPassword();
+  return password ? sessionToken(password) : null;
+}

package/templates/agent/agent/lib/github.ts

@@ -0,0 +1,74 @@
+const API = "https://api.github.com";
+
+function headers(token?: string | null): Record<string, string> {
+  const h: Record<string, string> = {
+    accept: "application/vnd.github+json",
+    "user-agent": "openhacker-agent",
+    "x-github-api-version": "2022-11-28",
+  };
+  if (token) h.authorization = `Bearer ${token}`;
+  return h;
+}
+
+/** Read a single file's text content. Returns null when the file is absent. */
+export async function getFile(
+  repo: string,
+  path: string,
+  ref: string,
+  token?: string | null,
+): Promise<string | null> {
+  const url = `${API}/repos/${repo}/contents/${encodeURIComponent(path).replace(/%2F/g, "/")}?ref=${encodeURIComponent(ref)}`;
+  const res = await fetch(url, { headers: headers(token) });
+
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(`GitHub getFile ${repo}/${path}: ${res.status} ${res.statusText}`);
+  }
+
+  const data = (await res.json()) as { content?: string; encoding?: string };
+  if (!data.content) return null;
+  if (data.encoding === "base64") {
+    return Buffer.from(data.content, "base64").toString("utf8");
+  }
+  return data.content;
+}
+
+export type RepoEntry = { path: string; type: "file" | "dir"; size?: number };
+
+/** List the entries directly under a directory path ("" for the repo root). */
+export async function listDir(
+  repo: string,
+  path: string,
+  ref: string,
+  token?: string | null,
+): Promise<RepoEntry[]> {
+  const clean = path.replace(/^\/+|\/+$/g, "");
+  const url = `${API}/repos/${repo}/contents/${clean ? `${clean}` : ""}?ref=${encodeURIComponent(ref)}`;
+  const res = await fetch(url, { headers: headers(token) });
+
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new Error(`GitHub listDir ${repo}/${path}: ${res.status} ${res.statusText}`);
+  }
+
+  const data = (await res.json()) as Array<{ path: string; type: string; size?: number }>;
+  if (!Array.isArray(data)) return [];
+  return data.map((e) => ({
+    path: e.path,
+    type: e.type === "dir" ? "dir" : "file",
+    size: e.size,
+  }));
+}
+
+/** Confirm the repo is reachable with the given (optional) token. */
+export async function checkRepoAccess(
+  repo: string,
+  token?: string | null,
+): Promise<{ ok: boolean; private?: boolean; defaultBranch?: string; error?: string }> {
+  const res = await fetch(`${API}/repos/${repo}`, { headers: headers(token) });
+  if (!res.ok) {
+    return { ok: false, error: `${res.status} ${res.statusText}` };
+  }
+  const data = (await res.json()) as { private?: boolean; default_branch?: string };
+  return { ok: true, private: data.private, defaultBranch: data.default_branch };
+}

package/templates/agent/agent/lib/osv.ts

@@ -0,0 +1,152 @@
+export type OsvEcosystem =
+  | "npm"
+  | "PyPI"
+  | "Go"
+  | "crates.io"
+  | "Maven"
+  | "RubyGems"
+  | "NuGet";
+
+export type Severity = "critical" | "high" | "medium" | "low";
+
+export type OsvAdvisory = {
+  id: string;
+  aliases: string[];
+  summary: string | null;
+  cvssVector: string | null;
+  qualitative: string | null;
+  fixedIn: string[];
+  references: string[];
+};
+
+type OsvRawVuln = {
+  id: string;
+  aliases?: string[];
+  summary?: string;
+  severity?: Array<{ type: string; score: string }>;
+  database_specific?: { severity?: string };
+  affected?: Array<{ ranges?: Array<{ events?: Array<Record<string, string>> }> }>;
+  references?: Array<{ type: string; url: string }>;
+};
+
+export async function queryOsv(
+  name: string,
+  version: string | undefined,
+  ecosystem: OsvEcosystem = "npm",
+): Promise<OsvAdvisory[]> {
+  const body: Record<string, unknown> = { package: { name, ecosystem } };
+  if (version) body.version = version;
+
+  const res = await fetch("https://api.osv.dev/v1/query", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`OSV query failed for ${name}: ${res.status} ${res.statusText}`);
+  }
+
+  const data = (await res.json()) as { vulns?: OsvRawVuln[] };
+
+  return (data.vulns ?? []).map((v) => {
+    const fixedIn = [
+      ...new Set(
+        (v.affected ?? [])
+          .flatMap((a) => a.ranges ?? [])
+          .flatMap((r) => r.events ?? [])
+          .map((e) => e.fixed)
+          .filter((x): x is string => Boolean(x)),
+      ),
+    ];
+
+    const cvss = (v.severity ?? []).find((s) => /^CVSS_V3/.test(s.type)) ?? v.severity?.[0];
+
+    return {
+      id: v.id,
+      aliases: v.aliases ?? [],
+      summary: v.summary ?? null,
+      cvssVector: cvss?.score ?? null,
+      qualitative: v.database_specific?.severity ?? null,
+      fixedIn,
+      references: (v.references ?? []).map((r) => r.url).slice(0, 5),
+    };
+  });
+}
+
+function bucket(score: number): Severity {
+  if (score >= 9) return "critical";
+  if (score >= 7) return "high";
+  if (score >= 4) return "medium";
+  return "low";
+}
+
+const QUALITATIVE: Record<string, Severity> = {
+  LOW: "low",
+  MODERATE: "medium",
+  MEDIUM: "medium",
+  HIGH: "high",
+  CRITICAL: "critical",
+};
+
+/** Severity from OSV: prefer the computed CVSS v3 base score, then the GHSA rating. */
+export function severityFromOsv(advisory: OsvAdvisory): Severity {
+  if (advisory.cvssVector) {
+    const score = cvss3BaseScore(advisory.cvssVector);
+    if (score != null) return bucket(score);
+  }
+  if (advisory.qualitative) {
+    const mapped = QUALITATIVE[advisory.qualitative.toUpperCase()];
+    if (mapped) return mapped;
+  }
+  return "medium";
+}
+
+// --- Minimal CVSS v3.x base score calculator -------------------------------
+
+const AV = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 } as const;
+const AC = { L: 0.77, H: 0.44 } as const;
+const UI = { N: 0.85, R: 0.62 } as const;
+const IMPACT = { H: 0.56, L: 0.22, N: 0 } as const;
+
+function roundUp(n: number): number {
+  return Math.ceil(n * 10) / 10;
+}
+
+/** Returns the CVSS v3.x base score for a vector string, or null if unparsable. */
+export function cvss3BaseScore(vector: string): number | null {
+  if (!/^CVSS:3/.test(vector)) return null;
+  const parts = Object.fromEntries(
+    vector
+      .split("/")
+      .slice(1)
+      .map((p) => p.split(":") as [string, string]),
+  );
+
+  const scopeChanged = parts.S === "C";
+  const prMap = scopeChanged
+    ? { N: 0.85, L: 0.68, H: 0.5 }
+    : { N: 0.85, L: 0.62, H: 0.27 };
+
+  const av = AV[parts.AV as keyof typeof AV];
+  const ac = AC[parts.AC as keyof typeof AC];
+  const pr = prMap[parts.PR as keyof typeof prMap];
+  const ui = UI[parts.UI as keyof typeof UI];
+  const c = IMPACT[parts.C as keyof typeof IMPACT];
+  const i = IMPACT[parts.I as keyof typeof IMPACT];
+  const a = IMPACT[parts.A as keyof typeof IMPACT];
+
+  if ([av, ac, pr, ui, c, i, a].some((x) => x == null)) return null;
+
+  const iscBase = 1 - (1 - c) * (1 - i) * (1 - a);
+  const impact = scopeChanged
+    ? 7.52 * (iscBase - 0.029) - 3.25 * (iscBase - 0.02) ** 15
+    : 6.42 * iscBase;
+  const exploitability = 8.22 * av * ac * pr * ui;
+
+  if (impact <= 0) return 0;
+  const raw = scopeChanged
+    ? 1.08 * (impact + exploitability)
+    : impact + exploitability;
+  return roundUp(Math.min(raw, 10));
+}