jaku.sh 1.0.2 → 1.2.0

package/src/reporting/sarif-generator.js

@@ -1,5 +1,7 @@
 import fs from 'fs';
 import path from 'path';
+import crypto from 'crypto';
+import { getVersion } from '../utils/version.js';
 
 /**
  * SARIF Generator — Generates Static Analysis Results Interchange Format (SARIF) v2.1.0
@@ -89,6 +91,11 @@ export function generateSARIF(findings, meta = {}) {
             rules.push(rule);
         }
 
+        // Represent the affected surface as a proper absolute web URI rather
+        // than anchoring it to the source tree (no %SRCROOT%), so GitHub does
+        // not try to map DAST URLs to repository files.
+        const webUri = _toWebUri(finding.affected_surface || meta.target);
+
         // Build result
         const result = {
             ruleId,
@@ -98,19 +105,31 @@ export function generateSARIF(findings, meta = {}) {
             locations: [{
                 physicalLocation: {
                     artifactLocation: {
-                        uri: finding.affected_surface || meta.target || 'unknown',
-                        uriBaseId: '%SRCROOT%',
+                        uri: webUri,
                     },
                 },
             }],
+            // Stable per-result fingerprint so GitHub can track findings across
+            // runs (derived from module + normalized title + affected surface).
+            partialFingerprints: {
+                'jakuFindingHash/v1': _fingerprint(finding),
+            },
             properties: {
                 severity: finding.severity,
                 module: finding.module,
                 status: finding.status || 'open',
                 timestamp: finding.timestamp || new Date().toISOString(),
+                affectedUrl: finding.affected_surface || meta.target || null,
             },
         };
 
+        // Describe the tested surface as a SARIF webRequest where we can, which
+        // signals to consumers that this is a dynamic (DAST) finding.
+        const webRequest = _toWebRequest(finding.affected_surface || meta.target);
+        if (webRequest) {
+            result.webRequest = webRequest;
+        }
+
         if (finding.remediation) {
             result.fixes = [{ description: { text: finding.remediation } }];
         }
@@ -123,7 +142,7 @@ export function generateSARIF(findings, meta = {}) {
                         location: {
                             message: { text: typeof finding.evidence === 'string' ? finding.evidence : JSON.stringify(finding.evidence) },
                             physicalLocation: {
-                                artifactLocation: { uri: finding.affected_surface || 'unknown' },
+                                artifactLocation: { uri: webUri },
                             },
                         },
                     }],
@@ -141,8 +160,8 @@ export function generateSARIF(findings, meta = {}) {
             tool: {
                 driver: {
                     name: 'JAKU',
-                    version: meta.version || '1.0.2',
-                    semanticVersion: meta.version || '1.0.2',
+                    version: meta.version || getVersion(),
+                    semanticVersion: meta.version || getVersion(),
                     informationUri: 'https://github.com/jaku-security',
                     rules,
                 },
@@ -168,6 +187,63 @@ export function writeSARIF(findings, outputDir, meta = {}) {
     return sarifPath;
 }
 
+/**
+ * Normalize an affected surface into a clean absolute web URI.
+ * Falls back to a stable placeholder when it isn't a parseable URL.
+ */
+function _toWebUri(surface) {
+    if (!surface) return 'urn:jaku:unknown-surface';
+    try {
+        const u = new URL(surface);
+        return u.toString();
+    } catch {
+        // Not a URL (e.g. a file path or descriptive surface) — keep it as a
+        // logical identifier so GitHub doesn't treat it as a source artifact.
+        return `urn:jaku:surface:${encodeURIComponent(String(surface))}`;
+    }
+}
+
+/**
+ * Build a minimal SARIF webRequest object for a tested URL, when possible.
+ */
+function _toWebRequest(surface) {
+    if (!surface) return null;
+    try {
+        const u = new URL(surface);
+        return {
+            protocol: u.protocol.replace(':', ''),
+            target: u.toString(),
+            method: 'GET',
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Derive a stable fingerprint for cross-run finding tracking.
+ * Based on module + normalized title + affected surface (host + path only,
+ * so transient query values don't churn the hash between runs).
+ */
+function _fingerprint(finding) {
+    const module = (finding.module || 'security').toLowerCase();
+    const title = (finding.title || '')
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .trim();
+
+    let surface = finding.affected_surface || '';
+    try {
+        const u = new URL(surface);
+        surface = `${u.origin}${u.pathname}`;
+    } catch {
+        // leave non-URL surfaces as-is
+    }
+
+    const basis = `${module}|${title}|${surface.toLowerCase()}`;
+    return crypto.createHash('sha256').update(basis).digest('hex');
+}
+
 /**
  * Match a finding to a CWE based on title/description patterns.
  */

package/src/utils/config.js

@@ -1,6 +1,20 @@
 import fs from 'fs';
 import path from 'path';
 
+/**
+ * Safety mode tiers control how aggressive JAKU is allowed to be.
+ *
+ *   passive     — recon/observation + static analysis only. No probing requests
+ *                 that send attack payloads, no state-changing requests.
+ *   safe-active — (default) active but non-destructive probing (XSS/SQLi probes,
+ *                 enumeration checks, etc.). Never issues state-changing/mutating
+ *                 requests. Destructive logic tests are skipped.
+ *   aggressive  — everything, including destructive/state-changing tests
+ *                 (race conditions, pricing/checkout mutation, etc.).
+ */
+export const SAFETY_MODES = ['passive', 'safe-active', 'aggressive'];
+export const DEFAULT_SAFETY_MODE = 'safe-active';
+
 const DEFAULTS = {
     target_url: null,
     credentials: [],
@@ -8,11 +22,24 @@ const DEFAULTS = {
     severity_threshold: 'low',
     halt_on_critical: false,
     notify_webhook: null,
+    safety_mode: DEFAULT_SAFETY_MODE,
+    // LLM augmentation is OFF by default and strictly additive. The API key is
+    // NEVER stored here — it is read from the environment at runtime only.
+    llm: {
+        enabled: false,
+        provider: 'openai',          // openai | anthropic
+        model: null,                 // null → provider default (cheap model)
+        max_tokens: 1024,            // per-call output cap
+        max_calls: 50,               // per-scan call budget
+        token_budget: 100000,        // per-scan total token budget
+        timeout_seconds: 30,
+        consent: false,              // must be true before any data egress
+        base_url: null,              // optional override (self-hosted/proxy)
+    },
     crawler: {
         max_depth: 5,
         max_pages: 50,
         timeout: 30000,
-        respect_robots_txt: true,
         concurrency: 4,
     },
     viewports: {
@@ -45,6 +72,164 @@ const SCAN_PROFILES = {
     },
 };
 
+// ── Lightweight config schema (for validation) ──────────────
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+    'target_url', 'credentials', 'modules_enabled', 'severity_threshold',
+    'halt_on_critical', 'prod_safe', 'notify_webhook', 'safety_mode',
+    'crawler', 'viewports', 'auth', 'business_context', 'output_dir',
+    'llm', '_profile', '_authManager',
+]);
+const KNOWN_CRAWLER_KEYS = new Set(['max_depth', 'max_pages', 'timeout', 'concurrency']);
+const KNOWN_LLM_KEYS = new Set([
+    'enabled', 'provider', 'model', 'max_tokens', 'max_calls',
+    'token_budget', 'timeout_seconds', 'consent', 'base_url',
+]);
+// Secret-bearing keys must NEVER live in the config file.
+const LLM_SECRET_KEYS = new Set(['api_key', 'apiKey', 'key', 'openai_api_key', 'anthropic_api_key', 'token']);
+const VALID_LLM_PROVIDERS = new Set(['openai', 'anthropic']);
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info']);
+
+// Keys that have been removed/deprecated. Mapped to a short reason so we can
+// warn and drop them cleanly rather than silently honoring drifted config.
+const DEPRECATED_KEYS = {
+    respect_robots: 'JAKU is a security scanner and intentionally does not honor robots.txt',
+    respect_robots_txt: 'JAKU is a security scanner and intentionally does not honor robots.txt',
+};
+
+/**
+ * Validate a parsed jaku.config.json. Warns (does not throw) on unknown keys,
+ * bad types, and deprecated keys, and returns a cleaned copy.
+ */
+export function validateConfig(fileConfig) {
+    const warnings = [];
+    const cfg = { ...fileConfig };
+
+    // Alias drift: README historically documented `modules`; canonical is `modules_enabled`.
+    if (cfg.modules !== undefined && cfg.modules_enabled === undefined) {
+        cfg.modules_enabled = cfg.modules;
+        warnings.push('Config key "modules" is deprecated — use "modules_enabled". Aliased for now.');
+    }
+    delete cfg.modules;
+
+    // Top-level deprecated keys (e.g. respect_robots).
+    for (const key of Object.keys(DEPRECATED_KEYS)) {
+        if (cfg[key] !== undefined) {
+            warnings.push(`Config key "${key}" is no longer supported (${DEPRECATED_KEYS[key]}). Ignoring it.`);
+            delete cfg[key];
+        }
+    }
+
+    // Unknown top-level keys.
+    for (const key of Object.keys(cfg)) {
+        if (!KNOWN_TOP_LEVEL_KEYS.has(key) && key !== 'modules') {
+            warnings.push(`Unknown config key "${key}" — ignoring.`);
+        }
+    }
+
+    // Type checks (light).
+    if (cfg.severity_threshold !== undefined && !VALID_SEVERITIES.has(cfg.severity_threshold)) {
+        warnings.push(`Invalid severity_threshold "${cfg.severity_threshold}" — expected one of ${[...VALID_SEVERITIES].join(', ')}.`);
+    }
+    if (cfg.safety_mode !== undefined && !SAFETY_MODES.includes(cfg.safety_mode)) {
+        warnings.push(`Invalid safety_mode "${cfg.safety_mode}" — expected one of ${SAFETY_MODES.join(', ')}. Falling back to "${DEFAULT_SAFETY_MODE}".`);
+        delete cfg.safety_mode;
+    }
+    if (cfg.halt_on_critical !== undefined && typeof cfg.halt_on_critical !== 'boolean') {
+        warnings.push('Config key "halt_on_critical" should be a boolean.');
+    }
+    if (cfg.modules_enabled !== undefined && !Array.isArray(cfg.modules_enabled)) {
+        warnings.push('Config key "modules_enabled" should be an array of module names.');
+    }
+
+    // Crawler sub-keys.
+    if (cfg.crawler !== undefined) {
+        if (typeof cfg.crawler !== 'object' || cfg.crawler === null) {
+            warnings.push('Config key "crawler" should be an object.');
+        } else {
+            for (const key of Object.keys(cfg.crawler)) {
+                if (key in DEPRECATED_KEYS) {
+                    warnings.push(`Config key "crawler.${key}" is no longer supported (${DEPRECATED_KEYS[key]}). Ignoring it.`);
+                    delete cfg.crawler[key];
+                } else if (!KNOWN_CRAWLER_KEYS.has(key)) {
+                    warnings.push(`Unknown crawler config key "crawler.${key}" — ignoring.`);
+                }
+            }
+        }
+    }
+
+    // LLM sub-keys.
+    if (cfg.llm !== undefined) {
+        if (typeof cfg.llm !== 'object' || cfg.llm === null) {
+            warnings.push('Config key "llm" should be an object.');
+            delete cfg.llm;
+        } else {
+            cfg.llm = { ...cfg.llm };
+            // SECURITY: warn-and-drop any API key placed in the config file.
+            for (const key of Object.keys(cfg.llm)) {
+                if (LLM_SECRET_KEYS.has(key)) {
+                    warnings.push(`Config key "llm.${key}" is not allowed — API keys must come from the environment (OPENAI_API_KEY / ANTHROPIC_API_KEY), never the config file. Dropping it.`);
+                    delete cfg.llm[key];
+                } else if (!KNOWN_LLM_KEYS.has(key)) {
+                    warnings.push(`Unknown llm config key "llm.${key}" — ignoring.`);
+                }
+            }
+            if (cfg.llm.enabled !== undefined && typeof cfg.llm.enabled !== 'boolean') {
+                warnings.push('Config key "llm.enabled" should be a boolean.');
+            }
+            if (cfg.llm.consent !== undefined && typeof cfg.llm.consent !== 'boolean') {
+                warnings.push('Config key "llm.consent" should be a boolean.');
+            }
+            if (cfg.llm.provider !== undefined && !VALID_LLM_PROVIDERS.has(cfg.llm.provider)) {
+                warnings.push(`Invalid llm.provider "${cfg.llm.provider}" — expected one of ${[...VALID_LLM_PROVIDERS].join(', ')}.`);
+            }
+            for (const numKey of ['max_tokens', 'max_calls', 'token_budget', 'timeout_seconds']) {
+                if (cfg.llm[numKey] !== undefined && (typeof cfg.llm[numKey] !== 'number' || cfg.llm[numKey] <= 0)) {
+                    warnings.push(`Config key "llm.${numKey}" should be a positive number.`);
+                }
+            }
+        }
+    }
+
+    for (const w of warnings) {
+        console.warn(`⚠ JAKU config: ${w}`);
+    }
+
+    return cfg;
+}
+
+/**
+ * Resolve the safety mode from CLI flags / file config / default.
+ * Precedence: explicit CLI flag > config file > default (safe-active).
+ */
+/**
+ * Resolve LLM settings. Precedence: CLI flags > config file > defaults.
+ * NOTE: the API key is NEVER part of this object — it is read from env at
+ * runtime by LLMClient. Any stray secret keys are stripped for defense in depth.
+ */
+function resolveLLM(cliOptions, fileLLM) {
+    const llm = { ...DEFAULTS.llm, ...(fileLLM || {}) };
+
+    if (cliOptions.llm) llm.enabled = true;
+    if (cliOptions.llmProvider) llm.provider = cliOptions.llmProvider;
+    if (cliOptions.llmModel) llm.model = cliOptions.llmModel;
+    if (cliOptions.llmConsent) llm.consent = true;
+
+    // Defense in depth: never let a secret survive into the merged config.
+    for (const key of Object.keys(llm)) {
+        if (LLM_SECRET_KEYS.has(key)) delete llm[key];
+    }
+    return llm;
+}
+
+function resolveSafetyMode(cliOptions, fileMode) {
+    if (cliOptions.aggressive) return 'aggressive';
+    if (cliOptions.passive) return 'passive';
+    if (cliOptions.safeActive) return 'safe-active';
+    if (cliOptions.safety && SAFETY_MODES.includes(cliOptions.safety)) return cliOptions.safety;
+    if (fileMode && SAFETY_MODES.includes(fileMode)) return fileMode;
+    return DEFAULT_SAFETY_MODE;
+}
+
 export function loadConfig(cliOptions = {}) {
     let fileConfig = {};
 
@@ -59,12 +244,16 @@ export function loadConfig(cliOptions = {}) {
         }
     }
 
+    // Validate + clean file config (warn on unknown/deprecated/bad-typed keys)
+    fileConfig = validateConfig(fileConfig);
+
     // Merge: defaults < file config < CLI options
     const config = {
         ...DEFAULTS,
         ...fileConfig,
         crawler: { ...DEFAULTS.crawler, ...(fileConfig.crawler || {}) },
         viewports: { ...DEFAULTS.viewports, ...(fileConfig.viewports || {}) },
+        llm: { ...DEFAULTS.llm, ...(fileConfig.llm || {}) },
     };
 
     // Apply scan profile (overrides default settings)
@@ -93,9 +282,14 @@ export function loadConfig(cliOptions = {}) {
     if (cliOptions.maxPages) config.crawler.max_pages = parseInt(cliOptions.maxPages);
     if (cliOptions.maxDepth) config.crawler.max_depth = parseInt(cliOptions.maxDepth);
 
+    // Resolve safety mode (CLI flag > file > default)
+    config.safety_mode = resolveSafetyMode(cliOptions, config.safety_mode);
+
+    // Resolve LLM settings (CLI flag > file > default). Key stays in env only.
+    config.llm = resolveLLM(cliOptions, config.llm);
+
     return config;
 }
 
 export { SCAN_PROFILES };
 export default loadConfig;
-

package/src/utils/finding.js

@@ -18,6 +18,7 @@ export function createFinding({
     remediation = '',
     references = [],
     status = 'open',
+    source = null,
 }) {
     const prefix = module.toUpperCase();
     const shortId = nanoid(6);
@@ -35,6 +36,8 @@ export function createFinding({
         references,
         status,
         timestamp: new Date().toISOString(),
+        // Provenance: 'llm' marks AI-generated/augmented findings; null = deterministic.
+        ...(source ? { source } : {}),
     };
 
     // Auto-tag with OWASP Top 10 classification

package/src/utils/logger.js

@@ -4,6 +4,38 @@ import fs from 'fs';
 
 const LOG_DIR = path.join(process.cwd(), 'jaku-reports', 'logs');
 
+// Patterns for secrets that must never reach any transport (file or console).
+const SECRET_PATTERNS = [
+  /\bsk-[A-Za-z0-9_-]{8,}\b/g,                 // OpenAI-style keys
+  /\bsk-ant-[A-Za-z0-9_-]{8,}\b/g,            // Anthropic-style keys
+  /(Bearer\s+)[A-Za-z0-9._-]{8,}/gi,          // Authorization: Bearer <token>
+  /(x-api-key["']?\s*[:=]\s*["']?)[A-Za-z0-9._-]{8,}/gi, // x-api-key headers
+  /((?:api[_-]?key|apikey|token)["']?\s*[:=]\s*["']?)[A-Za-z0-9._-]{8,}/gi,
+];
+
+/** Replace any secret-looking substrings with [REDACTED]. */
+export function redactSecrets(value) {
+  if (value == null) return value;
+  let str = typeof value === 'string' ? value : String(value);
+  for (const re of SECRET_PATTERNS) {
+    str = str.replace(re, (m, prefix) => (prefix ? `${prefix}[REDACTED]` : '[REDACTED]'));
+  }
+  return str;
+}
+
+// Winston format that scrubs secrets from message + meta before transports.
+const redactionFormat = winston.format((info) => {
+  if (typeof info.message === 'string') {
+    info.message = redactSecrets(info.message);
+  }
+  for (const key of Object.keys(info)) {
+    if (key === 'level' || key === 'message' || key === 'timestamp') continue;
+    const v = info[key];
+    if (typeof v === 'string') info[key] = redactSecrets(v);
+  }
+  return info;
+});
+
 export function createLogger(options = {}) {
   const { verbose = false, logDir = LOG_DIR } = options;
 
@@ -14,6 +46,7 @@ export function createLogger(options = {}) {
   const logger = winston.createLogger({
     level: verbose ? 'debug' : 'info',
     format: winston.format.combine(
+      redactionFormat(),
       winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
       winston.format.errors({ stack: true }),
       winston.format.json()

package/src/utils/param-discovery.js

@@ -0,0 +1,93 @@
+/**
+ * Parameter discovery helpers.
+ *
+ * Derives real, application-specific parameter names from a SurfaceInventory so
+ * injection scanners can test what the app actually uses instead of relying on
+ * a fixed guess-list. Sources:
+ *   - form fields (per-page forms and the global forms list)
+ *   - query-string params on discovered page URLs and links
+ *   - query-string params on intercepted API endpoint URLs
+ */
+
+function _addUrlParams(url, set) {
+    if (!url || typeof url !== 'string') return;
+    try {
+        const u = new URL(url);
+        for (const key of u.searchParams.keys()) {
+            if (key) set.add(key);
+        }
+    } catch {
+        // not a parseable URL — ignore
+    }
+}
+
+function _addFormFields(form, set) {
+    for (const field of (form?.fields || [])) {
+        const name = field?.name || field?.id;
+        if (name) set.add(name);
+    }
+}
+
+/**
+ * Collect a de-duplicated list of candidate parameter names from an inventory.
+ * @param {object} inventory - SurfaceInventory ({ pages, forms, apiEndpoints })
+ * @returns {string[]} discovered parameter names
+ */
+export function collectParamNames(inventory) {
+    const names = new Set();
+    if (!inventory) return [];
+
+    for (const page of (inventory.pages || [])) {
+        _addUrlParams(page?.url || page, names);
+        for (const link of (page?.links || [])) {
+            _addUrlParams(link, names);
+        }
+        for (const form of (page?.forms || [])) {
+            _addFormFields(form, names);
+        }
+    }
+
+    for (const form of (inventory.forms || [])) {
+        _addFormFields(form, names);
+    }
+
+    for (const api of (inventory.apiEndpoints || [])) {
+        _addUrlParams(api?.url || api, names);
+    }
+
+    return [...names];
+}
+
+/**
+ * Collect, per discovered page/link/api URL, the set of query params that
+ * already appear on that exact URL. Useful for scanners that want to test the
+ * parameters that a given endpoint genuinely accepts.
+ * @returns {Map<string, string[]>} url → param names present on that url
+ */
+export function collectUrlParamMap(inventory) {
+    const map = new Map();
+    if (!inventory) return map;
+
+    const record = (url) => {
+        if (!url || typeof url !== 'string') return;
+        try {
+            const u = new URL(url);
+            const keys = [...u.searchParams.keys()].filter(Boolean);
+            if (keys.length > 0) map.set(url, keys);
+        } catch {
+            /* ignore */
+        }
+    };
+
+    for (const page of (inventory.pages || [])) {
+        record(page?.url || page);
+        for (const link of (page?.links || [])) record(link);
+    }
+    for (const api of (inventory.apiEndpoints || [])) {
+        record(api?.url || api);
+    }
+
+    return map;
+}
+
+export default { collectParamNames, collectUrlParamMap };

package/src/utils/safety.js

@@ -0,0 +1,44 @@
+import { DEFAULT_SAFETY_MODE, SAFETY_MODES } from './config.js';
+
+/**
+ * Safety tier helpers.
+ *
+ * Tiers are ordered: passive < safe-active < aggressive.
+ * A test declares the MINIMUM tier it requires to run; it runs only when the
+ * active safety mode is at least that tier.
+ *
+ *   passive     — no attack/probing requests, no state-changing requests
+ *   safe-active — active but non-destructive probing (default)
+ *   aggressive  — destructive/state-changing tests allowed
+ */
+const TIER_RANK = {
+    passive: 0,
+    'safe-active': 1,
+    aggressive: 2,
+};
+
+/** Resolve the active safety mode from a config object. */
+export function getSafetyMode(config) {
+    const mode = config?.safety_mode;
+    return SAFETY_MODES.includes(mode) ? mode : DEFAULT_SAFETY_MODE;
+}
+
+/**
+ * Returns true if the active safety mode permits a test that requires
+ * `requiredTier` (one of 'passive' | 'safe-active' | 'aggressive').
+ */
+export function allows(config, requiredTier) {
+    const current = TIER_RANK[getSafetyMode(config)] ?? TIER_RANK[DEFAULT_SAFETY_MODE];
+    const required = TIER_RANK[requiredTier] ?? TIER_RANK['safe-active'];
+    return current >= required;
+}
+
+export function isPassive(config) {
+    return getSafetyMode(config) === 'passive';
+}
+
+export function isAggressive(config) {
+    return getSafetyMode(config) === 'aggressive';
+}
+
+export { SAFETY_MODES };

package/src/utils/version.js

@@ -0,0 +1,30 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Centralized version resolver.
+ *
+ * Reads the version from package.json once and caches it, so the version
+ * string is never duplicated/hardcoded across the codebase. Use getVersion()
+ * everywhere a version is needed (CLI banner, reports, SARIF, webhooks, etc.).
+ */
+let _cachedVersion = null;
+
+export function getVersion() {
+    if (_cachedVersion) return _cachedVersion;
+
+    try {
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        // src/utils/version.js → ../../package.json
+        const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        _cachedVersion = pkg.version || '0.0.0';
+    } catch {
+        _cachedVersion = '0.0.0';
+    }
+
+    return _cachedVersion;
+}
+
+export default getVersion;