penthera 1.1.0

package/lib/whitebox/sbom.js

@@ -0,0 +1,144 @@
+/**
+ * Software Bill of Materials (CycloneDX) generator.
+ *
+ * Parses a repo's dependency manifests offline (no network, no API keys) and
+ * emits a CycloneDX 1.5 SBOM, the artifact enterprises increasingly demand of
+ * their suppliers, and direct evidence for NIS2 supply-chain security (d).
+ *
+ * Supports npm (package-lock.json, then package.json) and Python
+ * (requirements.txt). Resolved lockfile versions are preferred; where only a
+ * range is known it is recorded as-is and marked.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+function cleanRange(range) {
+  // Strip a leading range operator for a best-effort version; keep the rest.
+  return String(range).replace(/^[\^~>=<\s]+/, "").trim() || String(range);
+}
+
+function purl(ecosystem, name, version) {
+  return `pkg:${ecosystem}/${encodeURIComponent(name)}@${encodeURIComponent(version)}`;
+}
+
+function parseNpmLock(lock) {
+  const comps = [];
+  if (lock.packages) { // lockfile v2/v3
+    for (const [k, v] of Object.entries(lock.packages)) {
+      if (k === "" || !v || !v.version) continue; // "" is the root project
+      const name = k.split("node_modules/").pop();
+      if (!name) continue;
+      comps.push({ name, version: v.version, scope: v.dev ? "optional" : "required", resolved: true });
+    }
+  } else if (lock.dependencies) { // lockfile v1
+    const walk = (deps) => {
+      for (const [name, v] of Object.entries(deps)) {
+        if (v?.version) comps.push({ name, version: v.version, scope: v.dev ? "optional" : "required", resolved: true });
+        if (v?.dependencies) walk(v.dependencies);
+      }
+    };
+    walk(lock.dependencies);
+  }
+  return comps;
+}
+
+function parsePackageJson(pkg) {
+  const comps = [];
+  for (const [name, range] of Object.entries(pkg.dependencies || {})) {
+    comps.push({ name, version: cleanRange(range), scope: "required", resolved: false });
+  }
+  for (const [name, range] of Object.entries(pkg.devDependencies || {})) {
+    comps.push({ name, version: cleanRange(range), scope: "optional", resolved: false });
+  }
+  return comps;
+}
+
+function parseRequirements(text) {
+  const comps = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#") || line.startsWith("-")) continue;
+    const m = line.match(/^([A-Za-z0-9._-]+)\s*(?:==|>=|~=|<=|!=)?\s*([\w.*+!-]+)?/);
+    if (!m) continue;
+    comps.push({ name: m[1], version: m[2] || "unknown", scope: "required", resolved: !!m[2] && line.includes("=="), ecosystem: "pypi" });
+  }
+  return comps;
+}
+
+function dedupe(comps) {
+  const seen = new Set();
+  return comps.filter((c) => {
+    const key = `${c.ecosystem || "npm"}:${c.name}@${c.version}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Build a CycloneDX SBOM for a repo. Returns null if no manifest is found.
+ * @param {string} repoPath
+ * @param {object} opts - { serialNumber, timestamp } (injected for reproducibility/testing)
+ */
+export function buildSbom(repoPath, opts = {}) {
+  let components = [];
+  let rootName = "application";
+  let rootVersion = "0.0.0";
+  const sources = [];
+
+  const pkgJsonPath = join(repoPath, "package.json");
+  const lockPath = join(repoPath, "package-lock.json");
+  const reqPath = join(repoPath, "requirements.txt");
+
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+      rootName = pkg.name || rootName;
+      rootVersion = pkg.version || rootVersion;
+    } catch { /* ignore malformed */ }
+  }
+
+  if (existsSync(lockPath)) {
+    try {
+      const npm = parseNpmLock(JSON.parse(readFileSync(lockPath, "utf-8"))).map((c) => ({ ...c, ecosystem: "npm" }));
+      if (npm.length) { components.push(...npm); sources.push("package-lock.json"); }
+    } catch { /* ignore */ }
+  }
+  if (components.length === 0 && existsSync(pkgJsonPath)) {
+    try {
+      const npm = parsePackageJson(JSON.parse(readFileSync(pkgJsonPath, "utf-8"))).map((c) => ({ ...c, ecosystem: "npm" }));
+      if (npm.length) { components.push(...npm); sources.push("package.json"); }
+    } catch { /* ignore */ }
+  }
+  if (existsSync(reqPath)) {
+    try {
+      const py = parseRequirements(readFileSync(reqPath, "utf-8"));
+      if (py.length) { components.push(...py); sources.push("requirements.txt"); }
+    } catch { /* ignore */ }
+  }
+
+  if (sources.length === 0) return null;
+
+  components = dedupe(components);
+
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: "1.5",
+    serialNumber: opts.serialNumber || undefined,
+    version: 1,
+    metadata: {
+      timestamp: opts.timestamp || undefined,
+      tools: [{ vendor: "Penthera", name: "penthera", components: [] }],
+      component: { type: "application", name: rootName, version: rootVersion },
+      properties: [{ name: "penthera:sources", value: sources.join(", ") }],
+    },
+    components: components.map((c) => ({
+      type: "library",
+      name: c.name,
+      version: c.version,
+      scope: c.scope,
+      purl: purl(c.ecosystem || "npm", c.name, c.version),
+      properties: c.resolved ? undefined : [{ name: "penthera:version-note", value: "declared range, not a resolved version" }],
+    })),
+  };
+}

package/lib/whitebox/secrets.js

@@ -0,0 +1,111 @@
+/**
+ * Scan repository source for hardcoded secrets.
+ */
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", "coverage",
+  "reports", ".security-results", "vendor",
+]);
+
+const SKIP_FILES = /\.(png|jpg|jpeg|gif|webp|ico|woff|woff2|ttf|eot|zip|tar|gz|pdf|lock)$/i;
+
+// Values that clearly aren't real secrets: placeholders, redactions, and the
+// dummy/probe credentials that security tooling (Penthera included) hardcodes
+// to test login endpoints, e.g. `password: "invalid-password-12345"`. Matched
+// against the assigned value only, with word boundaries so a real secret that
+// merely contains one of these substrings isn't suppressed.
+const TEST_VALUE = /\b(?:placeholder|example|changeme|dummy|sample|redacted|invalid|fake|test|your)\b|xxx|\*{3,}/i;
+
+const SECRET_PATTERNS = [
+  { name: "AWS access key", pattern: /AKIA[0-9A-Z]{16}/, severity: "critical" },
+  { name: "GitHub token", pattern: /ghp_[a-zA-Z0-9]{36,}/, severity: "critical" },
+  { name: "OpenAI API key", pattern: /sk-[a-zA-Z0-9]{20,}/, severity: "critical" },
+  { name: "Stripe secret key", pattern: /sk_live_[a-zA-Z0-9]{20,}/, severity: "critical" },
+  {
+    name: "Generic API key assignment",
+    pattern: /(?:api[_-]?key|apikey|secret[_-]?key)\s*[:=]\s*['"][^'"\s]{8,}['"]/i,
+    severity: "high",
+    skipIf: TEST_VALUE,
+  },
+  {
+    name: "Hardcoded password",
+    pattern: /(?:password|passwd|pwd)\s*[:=]\s*['"][^'"\s]{4,}['"]/i,
+    severity: "high",
+    skipIf: TEST_VALUE,
+  },
+  { name: "Private key block", pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/, severity: "critical" },
+  { name: "GCP/Firebase service account", pattern: /"private_key"\s*:\s*"-----BEGIN/, severity: "critical" },
+  {
+    name: "JWT secret assignment",
+    pattern: /(?:jwt[_-]?secret|session[_-]?secret)\s*[:=]\s*['"][^'"\s]{8,}['"]/i,
+    severity: "high",
+    skipIf: TEST_VALUE,
+  },
+];
+
+const SCAN_EXTENSIONS = new Set([
+  ".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs", ".py", ".rb", ".go", ".java",
+  ".env", ".yaml", ".yml", ".json", ".toml", ".cfg", ".ini", ".sh",
+]);
+
+function walkFiles(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      walkFiles(full, files);
+    } else if (!SKIP_FILES.test(entry)) {
+      const ext = entry.includes(".") ? entry.slice(entry.lastIndexOf(".")) : "";
+      if (SCAN_EXTENSIONS.has(ext) || entry.startsWith(".env")) files.push(full);
+    }
+  }
+  return files;
+}
+
+function maskMatch(match) {
+  return match.length <= 8 ? "***" : match.slice(0, 4) + "…" + match.slice(-4);
+}
+
+export function scanSecrets(repoPath) {
+  const findings = [];
+  const seen = new Set();
+
+  for (const filePath of walkFiles(repoPath)) {
+    let content;
+    try {
+      content = readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const rel = relative(repoPath, filePath);
+
+    for (const rule of SECRET_PATTERNS) {
+      const match = content.match(rule.pattern);
+      if (!match) continue;
+      // For assignment-style rules, test the placeholder/dummy filter against
+      // the assigned value only (not the whole `key = "value"` match), so a
+      // variable named e.g. `testToken` can't mask a real secret.
+      const value = (match[0].match(/['"]([^'"]+)['"]/) || [, match[0]])[1];
+      if (rule.skipIf && rule.skipIf.test(value)) continue;
+
+      const key = `${rel}::${rule.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      findings.push({
+        severity: rule.severity,
+        title: `${rule.name} in source`,
+        description: `Possible secret in \`${rel}\`: \`${maskMatch(match[0])}\``,
+        url: rel,
+        category: "secrets",
+        source: "secret-scan",
+      });
+    }
+  }
+
+  return findings;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "penthera",
+  "version": "1.1.0",
+  "type": "module",
+  "description": "Lightweight security scanner for web apps — scan URLs or repos from the CLI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danoszz/penthera.git"
+  },
+  "homepage": "https://github.com/danoszz/penthera#readme",
+  "bugs": {
+    "url": "https://github.com/danoszz/penthera/issues"
+  },
+  "bin": {
+    "penthera": "./bin/penthera.js",
+    "penthera-scan": "./bin/scan.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "lib",
+    "skills",
+    "docs",
+    "scripts/package-skill.sh",
+    "pentest.config.example.js",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "exports": {
+    "./plugins": "./lib/plugins.js",
+    "./adaptive": "./lib/blackbox/adaptive-scan.js",
+    "./wstg": "./lib/owasp-wstg.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run --reporter=verbose",
+    "scan": "node bin/penthera.js",
+    "scan:full": "node bin/scan.js",
+    "pentest": "vitest run --reporter=verbose",
+    "pentest:watch": "vitest --reporter=verbose",
+    "pentest:static": "vitest run tests/pentest-static.test.js --reporter=verbose",
+    "pentest:live": "vitest run tests/pentest-live.test.js --reporter=verbose",
+    "pentest:adaptive": "vitest run tests/pentest-adaptive.test.js --reporter=verbose",
+    "pentest:recon": "vitest run tests/pentest-recon.test.js --reporter=verbose",
+    "pentest:mock": "vitest run tests/pentest-mock.test.js --reporter=verbose",
+    "pentest:wstg": "vitest run tests/owasp-wstg.test.js --reporter=verbose",
+    "validate:report": "node skills/penthera/scripts/validate-report.mjs",
+    "package:skill": "bash scripts/package-skill.sh",
+    "prepack": "npm test",
+    "mock-server": "node tests/fixtures/mock-server.js"
+  },
+  "keywords": [
+    "security",
+    "scanner",
+    "pentest",
+    "vulnerability",
+    "recon",
+    "cli",
+    "agent-skills",
+    "cursor",
+    "claude-code",
+    "owasp",
+    "sarif"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3"
+  }
+}

package/pentest.config.example.js

@@ -0,0 +1,82 @@
+/**
+ * Penthera — Live test configuration (example)
+ *
+ * Copy to pentest.config.js and customize for your app:
+ *   cp pentest.config.example.js pentest.config.js
+ *
+ * Or override the target URL without editing this file:
+ *   PENTEST_BASE_URL=https://staging.myapp.com npm run pentest:live
+ */
+
+// ── Target ────────────────────────────────────────────────────────────────
+export const BASE_URL = process.env.PENTEST_BASE_URL || "http://localhost:3000";
+
+// ── Allowed CORS Origins ──────────────────────────────────────────────────
+export const ALLOWED_ORIGINS = [
+  "http://localhost:3000",
+  "http://localhost:5173",
+  "https://staging.myapp.com",
+];
+
+// ── Route Definitions ─────────────────────────────────────────────────────
+// Group routes by auth level. Penthera verifies each group behaves correctly.
+
+export const PUBLIC_ROUTES = [
+  { method: "GET", path: "/api/health" },
+  // { method: "POST", path: "/api/contact", body: { email: "test@example.com" } },
+];
+
+export const USER_ROUTES = [
+  // Should return 401 without a valid Bearer token
+  // { method: "GET", path: "/api/user/profile" },
+  // { method: "POST", path: "/api/projects/create", body: { name: "test" } },
+];
+
+export const ADMIN_ROUTES = [
+  // Should return 401/403 for non-admin tokens
+  // { method: "GET", path: "/api/admin/users" },
+];
+
+export const CRON_ROUTES = [
+  // Should reject requests without the correct CRON_SECRET header
+  // { method: "GET", path: "/api/cron/cleanup" },
+];
+
+// ── Input Validation Endpoints ────────────────────────────────────────────
+export const INPUT_VALIDATION_ROUTES = [
+  // {
+  //   method: "POST",
+  //   path: "/api/leads/capture",
+  //   fields: {
+  //     email: "sectest@example.com",
+  //     name: '<script>alert("xss")</script>',
+  //   },
+  //   emailField: "email",
+  // },
+];
+
+// ── Stripe / Payment Routes ───────────────────────────────────────────────
+export const PAYMENT_ROUTES = [
+  // { method: "POST", path: "/api/stripe/checkout", body: {} },
+];
+
+// ── Rate Limited Routes ───────────────────────────────────────────────────
+export const RATE_LIMITED_ROUTES = [
+  // { method: "POST", path: "/api/contact", concurrency: 20, body: { message: "test" } },
+];
+
+// ── Filesystem Discovery ──────────────────────────────────────────────────
+// Point to your Next.js app/api directory for adaptive white-box tests.
+export const API_ROOT_PATH = null;
+// export const API_ROOT_PATH = "/Users/you/project/app/api";
+
+// ── Authenticated scanning (optional) ─────────────────────────────────────
+// Used by CLI: --auth-cookie / --auth-bearer or env vars PENTHERA_COOKIE / PENTHERA_BEARER
+export const SESSION_COOKIE = process.env.PENTHERA_COOKIE || null;
+export const BEARER_TOKEN = process.env.PENTHERA_BEARER || null;
+
+// Route to test JWT alg:none bypass (must require auth)
+export const AUTH_TEST_PATH = "/api/user/profile";
+
+// ── Health Check ────────────────────────────────────────────────────────────
+export const HEALTH_ENDPOINT = "/api/health";

package/scripts/package-skill.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Package the Agent Skill for Claude.ai upload or GitHub Releases.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUT="$ROOT/dist"
+ZIP="$OUT/penthera-skill.zip"
+
+mkdir -p "$OUT"
+rm -f "$ZIP"
+
+cd "$ROOT/skills"
+zip -r "$ZIP" penthera/ -x "*.DS_Store"
+
+echo "Created $ZIP"
+ls -lh "$ZIP"