pentesting 0.73.14 → 0.90.1

package/README.md

@@ -1,79 +1,150 @@
-<div align="center">
+# pentesting
 
-<a href="https://agnusdei1207.github.io/brainscience/pentesting/">
-  <img src="https://api.iconify.design/game-icons:fizzing-flask.svg?color=%232496ED" width="80" height="80" alt="Pentesting Agent" />
-</a>
+`pentesting` is the public npm facade for the Builder runtime.
 
-# pentesting
-> **Autonomous Offensive Security AI Agent**
+- Installs the `pentesting` CLI.
+- Keeps `builder` as a temporary compatibility alias.
+- Downloads the matching Builder binary from `agnusdei1207/builder` releases for the current OS/CPU.
+- Performs only minimal wrapping before delegating execution to the Rust Builder binary.
+- Does not ship a second JavaScript or TypeScript runtime.
 
-[![npm](https://img.shields.io/badge/npm-pentesting-CB3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/pentesting)
-[![docker](https://img.shields.io/badge/docker-pentesting-2496ED?style=flat-square&logo=docker&logoColor=white)](https://hub.docker.com/r/agnusdei1207/pentesting)
-[![docs](https://img.shields.io/badge/docs-brainscience-10B981?style=flat-square&logo=readthedocs&logoColor=white)](https://agnusdei1207.github.io/brainscience/pentesting/)
+## Install
 
-</div>
+```bash
+npm install -g pentesting
+pentesting
+builder --version
+```
 
----
+## Quick commands
 
-## TUI Demo
+```bash
+pentesting
+pentesting run "Enumerate the target web application and summarize the next actions."
+pentesting scan 10.10.10.10
+builder --version
+```
 
-![TUI Demo](https://raw.githubusercontent.com/agnusdei1207/public/main/tui-demo.webp)
+Inside the interactive TUI:
 
-## Screenshots
+```text
+/goal harden the npm release flow and verify Docker startup
+/auto
+```
 
-| Recon | Exploit |
-|-------|---------|
-| ![Recon](https://raw.githubusercontent.com/agnusdei1207/public/main/01-recon.png) | ![Exploit](https://raw.githubusercontent.com/agnusdei1207/public/main/02-exploit.png) |
+- `/goal <objective>` sets the active goal only.
+- `/goal` with no text clears the goal and disables auto mode.
+- `/auto` toggles auto mode for the current goal.
+- `/auto` requires an existing goal and will not infer one from the transcript.
+- `/auto <text>` is rejected with usage guidance; use `/goal <objective>` first, then `/auto`.
 
-| Privesc | Lateral Movement |
-|---------|-----------------|
-| ![Privesc](https://raw.githubusercontent.com/agnusdei1207/public/main/03-privesc.png) | ![Lateral](https://raw.githubusercontent.com/agnusdei1207/public/main/04-lateral.png) |
+## What npm installs
 
----
+`npm install -g pentesting` installs a thin wrapper package and then runs `postinstall`:
+
+- if `BUILDER_BIN` is already set, the wrapper reuses that Builder executable
+- if `BUILDER_SKIP_DOWNLOAD=true`, the wrapper skips managed download entirely
+- otherwise it downloads the matching public Builder release asset into the package-local managed binary directory and executes that binary on launch
+
+This means the outside package name is `pentesting`, but the actual runtime engine is Builder.
+
+## Thin-wrapper design
+
+The npm package is intentionally narrow.
+
+- it installs a launcher, not a second agent runtime
+- it resolves or downloads the correct Builder release asset
+- it forwards execution into the Rust Builder binary
+- it keeps only minimal compatibility translation for legacy `interactive`, `run`, and `scan` entrypoints
 
-## Purpose
+If a change would add orchestration, memory, monitoring, or prompt-management logic directly into the npm layer, that change belongs upstream in Builder instead.
 
-Autonomous network penetration testing and CTF assistant. Supports offensive security workflows including recon, exploit, and post-exploitation.
+## Runtime strengths exposed through pentesting
 
-## Quick Start
+Because `pentesting` delegates to the Rust Builder runtime, it inherits the same core capabilities:
 
-### 🐳 Docker (Recommended)
+- goal-aware TUI sessions through `/goal`
+- explicit auto-mode toggling through `/auto`
+- post-turn self-review and persistent local memory files
+- context compression for long-running sessions
+- workflow status, budget, proof, and verification signals in the TUI
+- Docker and npm entrypoints that share one runtime instead of diverging implementations
+
+## Docker and compose alternative
+
+If you do not want a managed local binary, use Builder directly through Docker:
 
 ```bash
 docker run -it --rm \
-  -e PENTEST_API_KEY="your_key" \
-  -e PENTEST_BASE_URL="https://api.z.ai/api/anthropic" \
-  -e PENTEST_MODEL="glm-4.7" \
-  -v pentesting-data:/tmp/.pentesting \
-  agnusdei1207/pentesting
+  -v "$(pwd):/workspace" \
+  -w /workspace \
+  agnusdei1207/builder:latest
 ```
 
-Docker stores workspace state under `/tmp/.pentesting` inside the container.
-The entrypoint resets that directory on each fresh container start to avoid mixing stale state into a new run.
-Mount that path if you want access to `.pentesting/turns`, `.pentesting/sessions`, `.pentesting/memory`, and workspace artifacts after an OOM or while the same container is still alive.
-
-### 🐉 Kali Linux (Native)
+For a PostgreSQL-backed compose path, use the public `compose.yaml` facade from the public repo or mirrored docs:
 
 ```bash
-npm install -g pentesting
-export PENTEST_API_KEY="your_key"
-pentesting
+docker compose up -d postgres
+PENTESTING_PROJECT_DIR=/path/to/project docker compose run pentesting
 ```
 
-### Environment Variables
+## Supported runtime targets
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `PENTEST_API_KEY` | ✅ | LLM API key |
-| `PENTEST_BASE_URL` | ❌ | API endpoint (z.ai auto-enables web search) |
-| `PENTEST_MODEL` | ❌ | Model (default: `glm-4.7`) |
-| `SEARCH_API_KEY` | ❌ | External search key (not needed for z.ai) |
-| `PENTEST_TOR` | ❌ | Enable Tor (`true`, Docker only) |
----
+| OS | CPU | Release asset |
+| --- | --- | --- |
+| Linux | x64 | `builder-x86_64-unknown-linux-musl` |
+| Linux | arm64 | `builder-aarch64-unknown-linux-musl` |
+| macOS | x64 | `builder-x86_64-apple-darwin` |
+| macOS | arm64 | `builder-aarch64-apple-darwin` |
+| Windows | x64 | `builder-x86_64-pc-windows-msvc.exe` |
+| Windows | arm64 | `builder-aarch64-pc-windows-msvc.exe` |
+| Android | arm64 | `builder-aarch64-linux-android` |
+
+## Environment variables
+
+| Variable | Description |
+| --- | --- |
+| `BUILDER_BIN` | Use an already-installed Builder binary instead of the managed download. |
+| `BUILDER_REPO` | Override the public release repo used for binary downloads. Defaults to `agnusdei1207/builder`. |
+| `BUILDER_SKIP_DOWNLOAD` | Skip the postinstall binary download. Useful in CI or when `BUILDER_BIN` will be provided later. |
+
+## Compatibility wrappers
+
+- `pentesting` / `pentesting interactive` starts Builder interactive mode.
+- `pentesting run "<objective>"` becomes a Builder prompt tailored for the objective.
+- `pentesting scan <target>` becomes a Builder prompt tailored for recon and pentest scanning.
+- `builder` remains available as a compatibility alias during the naming transition.
+
+## Runtime behavior notes
+
+- `pentesting` with no extra arguments starts the Builder interactive/default flow.
+- `builder` and `pentesting` share the same wrapper entrypoint in the public package.
+- Docker and npm both end up delegating to the same upstream Builder runtime, so differences are usually install/configuration problems rather than different products.
+
+## Runtime cautions
+
+- `BUILDER_SKIP_DOWNLOAD=true` is only safe when you intentionally plan to provide `BUILDER_BIN` later or reinstall after provisioning access to the Builder release asset.
+- The npm package does not publish Docker images itself. Docker users should treat `agnusdei1207/builder:latest` as the runtime image and `pentesting` as the public command/package facade.
+- Unsupported OS/CPU pairs fail during release asset resolution before download.
+- If the managed binary is missing at runtime, reinstall the package or set `BUILDER_BIN` explicitly.
+
+## Development and release from source
+
+If you maintain this npm facade from the private source repository, use the root `builder-private` commands rather than adding more logic inside this package:
+
+```bash
+npm run pentesting:status
+npm run pentesting:verify
+npm run pentesting:pack:dry-run
+npm run pentesting:release:patch:dry-run
+NPM_TOKEN=... npm run pentesting:publish -- 0.90.1
+```
 
-## Issue
+## Further reading
 
-email: agnusdei1207@gmail.com
+- public Builder runtime docs and Docker guidance
+- the mirrored public `compose.yaml` facade for PostgreSQL-backed sessions
+- the Builder release asset matching your OS/CPU target
 
 ---
 

package/bin/pentesting.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+
+import { resolveBuilderBinary, translateBuilderInvocation } from "../lib/runtime.mjs";
+
+async function main() {
+  const invocation = translateBuilderInvocation(process.argv.slice(2));
+  for (const warning of invocation.warnings) {
+    console.warn(`[pentesting] ${warning}`);
+  }
+
+  const builderBinary = await resolveBuilderBinary({ downloadIfMissing: true });
+  const result = spawnSync(builderBinary, invocation.builderArgs, {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  if (result.error) {
+    console.error(
+      `pentesting could not start Builder (${result.error.message}). Set BUILDER_BIN or reinstall the pentesting package.`,
+    );
+    process.exit(127);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+main().catch((error) => {
+  console.error(`[pentesting] ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/lib/runtime.mjs

@@ -0,0 +1,419 @@
+import { createWriteStream, readFileSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE_JSON = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+const MANAGED_BINARY_DIR = path.join(PACKAGE_ROOT, "vendor");
+const MANAGED_BINARY_MANIFEST = path.join(MANAGED_BINARY_DIR, "builder-manifest.json");
+const BUILDER_COMMANDS = new Set([
+  "agent",
+  "banner",
+  "cmd",
+  "commit",
+  "config",
+  "conversation",
+  "data",
+  "doctor",
+  "info",
+  "list",
+  "mcp",
+  "provider",
+  "setup",
+  "suggest",
+  "update",
+  "vscode",
+  "workspace",
+  "zsh",
+]);
+
+const RELEASE_TARGETS = {
+  "android:arm64": {
+    assetName: "builder-aarch64-linux-android",
+    binaryFileName: "builder",
+    label: "android-arm64",
+  },
+  "darwin:arm64": {
+    assetName: "builder-aarch64-apple-darwin",
+    binaryFileName: "builder",
+    label: "macos-arm64",
+  },
+  "darwin:x64": {
+    assetName: "builder-x86_64-apple-darwin",
+    binaryFileName: "builder",
+    label: "macos-x64",
+  },
+  "linux:arm64": {
+    assetName: "builder-aarch64-unknown-linux-musl",
+    binaryFileName: "builder",
+    label: "linux-arm64",
+  },
+  "linux:x64": {
+    assetName: "builder-x86_64-unknown-linux-musl",
+    binaryFileName: "builder",
+    label: "linux-x64",
+  },
+  "win32:arm64": {
+    assetName: "builder-aarch64-pc-windows-msvc.exe",
+    binaryFileName: "builder.exe",
+    label: "windows-arm64",
+  },
+  "win32:x64": {
+    assetName: "builder-x86_64-pc-windows-msvc.exe",
+    binaryFileName: "builder.exe",
+    label: "windows-x64",
+  },
+};
+
+function parseLegacyFlags(argv) {
+  const passthrough = [];
+  const warnings = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+
+    if (current === "--dangerously-skip-permissions") {
+      warnings.push(
+        "Legacy '--dangerously-skip-permissions' is ignored. Builder owns approval handling inside its runtime.",
+      );
+      continue;
+    }
+
+    if (current === "--target" || current === "-t") {
+      const target = argv[index + 1];
+      if (target) {
+        warnings.push(
+          `Legacy target '${target}' is not auto-injected into Builder interactive mode. Paste it as your first prompt after startup.`,
+        );
+        index += 1;
+      } else {
+        warnings.push("Legacy '--target' was provided without a value and was ignored.");
+      }
+      continue;
+    }
+
+    passthrough.push(current);
+  }
+
+  return { passthrough, warnings };
+}
+
+function parseOptionValue(argv, index, option) {
+  if (index + 1 >= argv.length) {
+    throw new Error(`Missing value for ${option}.`);
+  }
+  return argv[index + 1];
+}
+
+function buildRunPrompt(objective, options) {
+  const lines = [`Objective: ${objective}`];
+
+  if (options.target) {
+    lines.push(`Primary target: ${options.target}`);
+  }
+
+  lines.push("");
+  lines.push("Use Builder to execute the task.");
+
+  if (options.maxSteps) {
+    lines.push(
+      `Keep the workflow within roughly ${options.maxSteps} meaningful tool steps when it does not reduce quality.`,
+    );
+  }
+
+  if (options.output) {
+    lines.push(`Write the final deliverable to ${options.output}.`);
+  }
+
+  return lines.join("\n");
+}
+
+function buildScanPrompt(target, options) {
+  const lines = [`Perform a reconnaissance scan against ${target}.`];
+  lines.push(`Focus mode: ${options.scanType}.`);
+
+  if (options.ports) {
+    lines.push(`Prioritize ports: ${options.ports}.`);
+  }
+
+  if (options.output) {
+    lines.push(`Write the final deliverable to ${options.output}.`);
+  }
+
+  lines.push("Prefer Builder-native tool selection and summarize the most actionable findings first.");
+  return lines.join("\n");
+}
+
+function translateRun(argv) {
+  const warnings = [];
+  const options = {};
+  const objectiveParts = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+
+    if (current === "--output" || current === "-o") {
+      options.output = parseOptionValue(argv, index, current);
+      index += 1;
+      continue;
+    }
+
+    if (current === "--max-steps") {
+      options.maxSteps = parseOptionValue(argv, index, current);
+      index += 1;
+      continue;
+    }
+
+    if (current === "--target" || current === "-t") {
+      options.target = parseOptionValue(argv, index, current);
+      index += 1;
+      continue;
+    }
+
+    if (current === "--dangerously-skip-permissions") {
+      warnings.push(
+        "Legacy '--dangerously-skip-permissions' is ignored. Builder owns approval handling inside its runtime.",
+      );
+      continue;
+    }
+
+    objectiveParts.push(current);
+  }
+
+  const objective = objectiveParts.join(" ").trim();
+  if (!objective) {
+    throw new Error("pentesting run requires an objective.");
+  }
+
+  return {
+    builderArgs: ["--prompt", buildRunPrompt(objective, options)],
+    warnings,
+  };
+}
+
+function translateScan(argv) {
+  const warnings = [];
+  const options = { scanType: "service" };
+  let target = "";
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+
+    if (current === "--scan-type" || current === "-s") {
+      options.scanType = parseOptionValue(argv, index, current);
+      index += 1;
+      continue;
+    }
+
+    if (current === "--ports" || current === "-p") {
+      options.ports = parseOptionValue(argv, index, current);
+      index += 1;
+      continue;
+    }
+
+    if (current === "--output" || current === "-o") {
+      options.output = parseOptionValue(argv, index, current);
+      index += 1;
+      continue;
+    }
+
+    if (current === "--dangerously-skip-permissions") {
+      warnings.push(
+        "Legacy '--dangerously-skip-permissions' is ignored. Builder owns approval handling inside its runtime.",
+      );
+      continue;
+    }
+
+    if (!target) {
+      target = current;
+      continue;
+    }
+
+    warnings.push(`Extra scan argument '${current}' was folded into the Builder prompt.`);
+    target = `${target} ${current}`;
+  }
+
+  if (!target) {
+    throw new Error("pentesting scan requires a target.");
+  }
+
+  return {
+    builderArgs: ["--prompt", buildScanPrompt(target, options)],
+    warnings,
+  };
+}
+
+export function packageVersion() {
+  return PACKAGE_JSON.version;
+}
+
+export function releaseRepository() {
+  return process.env.BUILDER_REPO || "agnusdei1207/builder";
+}
+
+export function defaultReleaseTag(version = packageVersion()) {
+  return /^\d+\.\d+\.\d+(?:[-+].+)?$/.test(version) ? `v${version}` : "latest";
+}
+
+export function resolveReleaseAsset(platform = process.platform, arch = process.arch) {
+  const target = RELEASE_TARGETS[`${platform}:${arch}`];
+  if (!target) {
+    const supported = Object.keys(RELEASE_TARGETS).join(", ");
+    throw new Error(
+      `Unsupported platform '${platform}/${arch}'. Supported builder targets: ${supported}.`,
+    );
+  }
+  return target;
+}
+
+export function releaseAssetUrl(assetName, options = {}) {
+  const repo = options.repo || releaseRepository();
+  const releaseTag = options.releaseTag || defaultReleaseTag();
+  if (releaseTag === "latest") {
+    return `https://github.com/${repo}/releases/latest/download/${assetName}`;
+  }
+  return `https://github.com/${repo}/releases/download/${releaseTag}/${assetName}`;
+}
+
+async function pathExists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function manifestMatches(expected) {
+  try {
+    const raw = JSON.parse(await readFile(MANAGED_BINARY_MANIFEST, "utf8"));
+    return (
+      raw.assetName === expected.assetName &&
+      raw.releaseTag === expected.releaseTag &&
+      raw.repo === expected.repo
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function installManagedBuilder(options = {}) {
+  if (process.env.BUILDER_BIN) {
+    return { binaryPath: process.env.BUILDER_BIN, source: "external" };
+  }
+
+  const target = resolveReleaseAsset();
+  const repo = options.repo || releaseRepository();
+  const releaseTag = options.releaseTag || defaultReleaseTag();
+  const binaryPath = path.join(MANAGED_BINARY_DIR, target.binaryFileName);
+  const manifest = { assetName: target.assetName, releaseTag, repo };
+
+  if (!options.force && (await pathExists(binaryPath)) && (await manifestMatches(manifest))) {
+    return { binaryPath, source: "cached", ...manifest };
+  }
+
+  if (process.env.BUILDER_SKIP_DOWNLOAD === "true") {
+    return { binaryPath, source: "skipped", ...manifest };
+  }
+
+  await mkdir(MANAGED_BINARY_DIR, { recursive: true });
+  const downloadUrl = releaseAssetUrl(target.assetName, { repo, releaseTag });
+  const response = await fetch(downloadUrl, {
+    headers: {
+      "user-agent": `pentesting-npm/${packageVersion()}`,
+    },
+  });
+
+  if (!response.ok || !response.body) {
+    throw new Error(
+      `Failed to download ${target.assetName} from ${downloadUrl} (${response.status} ${response.statusText}).`,
+    );
+  }
+
+  const tempPath = path.join(MANAGED_BINARY_DIR, `${target.binaryFileName}.download`);
+  await rm(tempPath, { force: true });
+  await pipeline(Readable.fromWeb(response.body), createWriteStream(tempPath));
+  if (process.platform !== "win32") {
+    await chmod(tempPath, 0o755);
+  }
+  await rm(binaryPath, { force: true });
+  await rename(tempPath, binaryPath);
+  await writeFile(
+    MANAGED_BINARY_MANIFEST,
+    JSON.stringify(
+      {
+        ...manifest,
+        downloadedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+
+  return { binaryPath, source: "downloaded", ...manifest };
+}
+
+export async function resolveBuilderBinary(options = {}) {
+  if (process.env.BUILDER_BIN) {
+    return process.env.BUILDER_BIN;
+  }
+
+  const target = resolveReleaseAsset();
+  const binaryPath = path.join(MANAGED_BINARY_DIR, target.binaryFileName);
+  if (await pathExists(binaryPath)) {
+    return binaryPath;
+  }
+
+  if (options.downloadIfMissing) {
+    const install = await installManagedBuilder();
+    if (install.source === "skipped") {
+      throw new Error(
+        "Managed Builder download was skipped and no BUILDER_BIN override was provided.",
+      );
+    }
+    return install.binaryPath;
+  }
+
+  throw new Error(
+    "No managed Builder binary is available. Reinstall the pentesting package or set BUILDER_BIN.",
+  );
+}
+
+export function translateBuilderInvocation(argv) {
+  if (argv.length === 0) {
+    return { builderArgs: [], warnings: [] };
+  }
+
+  const [command, ...rest] = argv;
+
+  if (command === "interactive" || command === "i") {
+    const parsed = parseLegacyFlags(rest);
+    return { builderArgs: parsed.passthrough, warnings: parsed.warnings };
+  }
+
+  if (command === "run" || command === "r") {
+    return translateRun(rest);
+  }
+
+  if (command === "scan") {
+    return translateScan(rest);
+  }
+
+  if (command.startsWith("-")) {
+    const parsed = parseLegacyFlags(argv);
+    return { builderArgs: parsed.passthrough, warnings: parsed.warnings };
+  }
+
+  if (BUILDER_COMMANDS.has(command)) {
+    return { builderArgs: argv, warnings: [] };
+  }
+
+  return { builderArgs: argv, warnings: [] };
+}