itworksbut 0.4.0 → 0.6.0

package/README.md

@@ -6,7 +6,19 @@ It focuses on common "it works, but..." risks often found in AI-generated or rus
 
 For every finding, ItWorksBut gives you a copy-ready fix prompt you can paste into your coding agent. It does not just say what is wrong; it tells your AI exactly what to inspect, what to change, and what not to leak.
 
-It only reads files and reports findings. It does not call external APIs, does not send telemetry, and does not modify the scanned project unless you explicitly ask it to write `todo.md` with `--todo`.
+It mostly reads files and reports findings. It does not send telemetry. The outdated-package check may invoke your local package manager, and the CLI only writes files when you explicitly ask for `todo.md` with `--todo` or `report.md` with `--report`.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Options](#options)
+- [Terminal Experience](#terminal-experience)
+- [GitHub Actions](#github-actions)
+- [Configuration](#configuration)
+- [Example Output](#example-output)
+- [What It Detects](#what-it-detects)
+- [What It Does Not Guarantee](#what-it-does-not-guarantee)
 
 ## Installation
 
@@ -41,6 +53,7 @@ itworksbut scan --fail-on high
 itworksbut scan --json
 itworksbut scan --sarif > itworksbut.sarif
 itworksbut scan --todo
+itworksbut scan --report
 itworksbut scan --config itworksbut.config.json
 itworksbut scan --verbose
 itworksbut --version
@@ -58,6 +71,7 @@ itworksbut scan [options]
 - `--json`: Print machine-readable JSON only. No banner, colors, spinner, table, or extra text.
 - `--sarif`: Print SARIF JSON for GitHub Code Scanning. No banner, colors, spinner, table, or extra text.
 - `--todo`: Write an AI-ready `todo.md` into the scanned project with prioritized findings, fix prompts, and acceptance criteria.
+- `--report`: Write a Markdown `report.md` into the current working directory.
 - `--verbose`: Include scanner warnings and extra metadata in console output.
 - `--quiet`: Print only the summary.
 - `--no-color`: Disable colored output.
@@ -97,6 +111,14 @@ itworksbut scan --todo
 
 This writes `todo.md` to the scanned project. The file is ordered by severity and includes agent rules, exact fix prompts, locations, recommendations, and final verification checkboxes.
 
+To create a Markdown scan report:
+
+```sh
+itworksbut scan --report
+```
+
+This writes `report.md` to the current working directory with check statuses, summaries, details, and recommendations.
+
 ## GitHub Actions
 
 ```yaml
@@ -166,38 +188,10 @@ release/**
 ## Example Output
 
 ![screenshot of an example output](/assets/medium_problems.webp)
-✖ CRITICAL It works, but your .env is tracked.
-✔ Check: env.env-file-tracked
-📁 File: .env
-🤔 Why: .env appears to be tracked by git. Secrets may be exposed.
-🤖 prompt: You are a senior security engineer working in this repository. Fix the ItWorksBut finding env.env-file-tracked at .env. Treat this as a concrete finding. Problem: .env appears to be tracked by git. Secrets may be exposed. Required change: Remove tracked env files from git, add safe examples such as .env.example, and make sure any exposed credentials are treated as compromised. Do not print, log, or preserve raw secret values; use placeholders only. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
-
-▲ HIGH It works, but your SQL query is one template string away from pain.
-✔ Check: database.raw-sql-interpolation
-📁 File: src/db.js:12
-🤔 Why: Possible SQL injection risk: raw SQL appears to be built with template string interpolation.
-🤖 prompt: You are a senior security engineer working in this repository. Fix the ItWorksBut finding database.raw-sql-interpolation at src/db.js:12. This finding is heuristic, so inspect the code first and only change behavior when the risk is real. Problem: Possible SQL injection risk: raw SQL appears to be built with template string interpolation. Required change: Replace SQL string interpolation or concatenation with parameterized queries, prepared statements, or a safe ORM query builder. Keep existing behavior intact where possible, add or update focused tests when useful, and do not silence the check unless the underlying risk is actually fixed.
-
-SUMMARY
-
-- ship status: DO NOT SHIP
-- Fix the red stuff before production.
-- total findings: 2
-- critical: 1
-- high: 1
-- medium: 0
-- low: 0
-- info: 0
-- fail-on: high
-- exit decision: 1
-
-```
-
-Secret-like findings never print the full secret value. Findings report the file, line, and secret type where possible.
 
 ## What It Detects
 
-The baseline includes 40 modular checks:
+The baseline includes 51 modular checks:
 
 - `git.gitignore-missing`
 - `git.gitignore-incomplete`
@@ -211,6 +205,7 @@ The baseline includes 40 modular checks:
 - `dependencies.multiple-lockfiles`
 - `dependencies.install-scripts-risk`
 - `dependencies.audit-script-missing`
+- `dependencies.outdated-packages`
 - `package.scripts-missing`
 - `ci.no-ci-config`
 - `ci.npm-install-instead-of-npm-ci`
@@ -228,6 +223,10 @@ The baseline includes 40 modular checks:
 - `api.idor-risk`
 - `auth.jwt-secret-weak-or-fallback`
 - `auth.password-hashing-missing`
+- `auth.missing-csrf-protection`
+- `api.missing-method-guard`
+- `api.mass-assignment-risk`
+- `api.no-schema-validation`
 - `database.raw-sql-interpolation`
 - `database.no-migrations`
 - `cookies.insecure-session-cookie`
@@ -235,10 +234,16 @@ The baseline includes 40 modular checks:
 - `webhooks.missing-raw-body`
 - `llm.prompt-injection-risk`
 - `frontend.sourcemaps-production`
+- `frontend.localstorage-token`
+- `files.path-traversal-risk`
+- `ssrf.user-controlled-fetch`
+- `next.public-server-code-risk`
 - `config.debug-production`
 - `electron.node-integration-enabled`
 - `electron.context-isolation-disabled`
+- `electron.remote-content-with-node`
 - `tauri.dangerous-allowlist-or-capabilities`
+- `tauri.remote-url-permissions-risk`
 
 Each check is a plain ESM module with an `id`, metadata, and async `run(context)` function. Add new checks under `src/checks/` and register them in `src/checks/index.js`.
 
@@ -247,4 +252,3 @@ Each check is a plain ESM module with an `id`, metadata, and async `run(context)
 ItWorksBut is a static heuristic scanner, not a pentest, SAST replacement, dependency vulnerability database, or runtime security monitor. Findings intentionally use wording such as "possible", "potential", and "appears to" when a check is heuristic.
 
 Use it as a CI guardrail for common project hygiene and security mistakes. For production systems, combine it with code review, tests, dependency scanning, secrets scanning, threat modeling, and focused security assessment.
-```

package/bin/itworksbut.js

@@ -10,6 +10,7 @@ import { reportConsole } from '../src/reporters/consoleReporter.js';
 import { reportJson } from '../src/reporters/jsonReporter.js';
 import { reportSarif } from '../src/reporters/sarifReporter.js';
 import { writeTodoReport } from '../src/reporters/todoReporter.js';
+import { writeMarkdownReport } from '../src/reporters/markdownReport.js';
 
 async function main() {
     const args = parseArgs(process.argv.slice(2));
@@ -59,6 +60,14 @@ async function main() {
         reportConsole(result, args);
     }
 
+    if (args.report) {
+        const report = await writeMarkdownReport(result);
+        if (!args.json && !args.sarif) {
+            const verb = report.overwritten ? 'Overwrote' : 'Wrote';
+            process.stdout.write(`${verb} scan report: ${report.filePath}\n`);
+        }
+    }
+
     return getExitCode(result.findings, result.config.failOn);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "itworksbut",
-    "version": "0.4.0",
+    "version": "0.6.0",
     "description": "Static CI checks for common security, repo, dependency, build, and deployment risks in JavaScript vibe coding projects.",
     "type": "module",
     "bin": {

package/src/checks/api/mass-assignment-risk.js

@@ -0,0 +1,81 @@
+import { isCodeLikeFile, isEnvExampleFile, isLockfile, lineFromOffset, readNearby } from "../helpers.js";
+
+const MASS_ASSIGNMENT_PATTERNS = [
+  {
+    regex: /\b(?:prisma\.\w+\.)?(?:create|update|upsert)\s*\(\s*{[\s\S]{0,600}?\bdata\s*:\s*(?:req\.body|body|input)\b/g,
+    label: "direct data object",
+    severity: "high"
+  },
+  {
+    regex: /\b(?:db|database|collection|\w+)\.(?:update|updateOne|updateMany|findOneAndUpdate)\s*\([\s\S]{0,300}?(?:req\.body|body|input)\b/g,
+    label: "direct update payload",
+    severity: "high"
+  },
+  {
+    regex: /\b(?:User|Account|Profile|Model|model|\w+)\.(?:create|update)\s*\(\s*(?:req\.body|body|input)\b/g,
+    label: "model create/update payload",
+    severity: "high"
+  },
+  {
+    regex: /\$set\s*:\s*(?:req\.body|body|input)\b/g,
+    label: "mongodb set payload",
+    severity: "high"
+  },
+  {
+    regex: /Object\.assign\s*\(\s*(?:user|entity|account|profile|record|model)[\w$]*\s*,\s*(?:req\.body|body|input)\b/g,
+    label: "object assign from request input",
+    severity: "medium"
+  },
+  {
+    regex: /\{\s*\.\.\.(?:req\.body|body)\s*}/g,
+    label: "spread request body",
+    severity: "medium",
+    requiresCreateOrUpdateContext: true
+  }
+];
+
+const SAFE_FIELD_RE =
+  /\b(?:pick|omit|allowedFields|allowlist|whitelist|safeData|validatedData|schema\.parse|schema\.safeParse|safeParse|zod|Joi|joi|yup|valibot)\b/i;
+const RISKY_FIELD_RE =
+  /\b(?:role|isAdmin|admin|plan|verified|emailVerified|ownerId|userId|tenantId|accountId|permissions|credits|balance|price|status)\b/i;
+const CREATE_OR_UPDATE_RE = /\b(?:create|update|upsert|insert|save|data\s*:|\$set)\b/i;
+
+export default {
+  id: "api.mass-assignment-risk",
+  title: "Create and update operations should not trust raw request bodies",
+  category: "api",
+  severity: "high",
+  tags: ["api", "database", "mass-assignment", "heuristic"],
+  run: async (context) => {
+    const findings = [];
+
+    for (const file of context.textFiles) {
+      if (isLockfile(file) || isEnvExampleFile(file) || !isCodeLikeFile(file)) continue;
+      const content = await context.readFileSafe(file);
+      if (!content || !/\b(?:req\.body|body|input|Object\.assign|\$set)\b/.test(content)) continue;
+
+      for (const pattern of MASS_ASSIGNMENT_PATTERNS) {
+        pattern.regex.lastIndex = 0;
+        let match;
+        while ((match = pattern.regex.exec(content)) !== null) {
+          const line = lineFromOffset(content, match.index);
+          const nearby = await readNearby(context, file, line, 8);
+          if (pattern.requiresCreateOrUpdateContext && !CREATE_OR_UPDATE_RE.test(nearby)) continue;
+          if (SAFE_FIELD_RE.test(nearby)) continue;
+
+          findings.push({
+            severity: RISKY_FIELD_RE.test(nearby) ? "high" : pattern.severity === "high" ? "high" : "medium",
+            message: "User-controlled input appears to be passed directly into a create or update operation.",
+            file,
+            line,
+            recommendation: "Whitelist allowed fields explicitly. Never pass req.body directly into database create/update calls.",
+            heuristic: true,
+            metadata: { pattern: pattern.label }
+          });
+        }
+      }
+    }
+
+    return findings.slice(0, 100);
+  }
+};

package/src/checks/api/missing-method-guard.js

@@ -0,0 +1,68 @@
+import { isServerOrApiFile, lineFromOffset, readNearby } from "../helpers.js";
+
+const ALL_ROUTE_RE = /\b(?:app|router|server)\.all\s*\(/g;
+const NEXT_PAGES_HANDLER_RE = /\bexport\s+default\s+(?:async\s+)?function\s+\w*\s*\(\s*(?:req|request)\s*,\s*(?:res|response)\s*\)/g;
+const NAMED_HANDLER_RE = /\bexport\s+(?:async\s+)?function\s+handler\s*\(\s*(?:req|request)\s*,\s*(?:res|response)\s*\)/g;
+const METHOD_GUARD_RE =
+  /\b(?:req|request)\.method\b|\bswitch\s*\(\s*(?:req|request)\.method\s*\)|\ballowedMethods\b|\bmethodNotAllowed\b|\breturn\s+new\s+Response\s*\([^)]*405|\bstatus\s*\(\s*405\s*\)/i;
+const METHOD_EXPORT_RE = /\bexport\s+(?:async\s+)?function\s+(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(/;
+
+export default {
+  id: "api.missing-method-guard",
+  title: "API handlers should restrict HTTP methods",
+  category: "api",
+  severity: "medium",
+  tags: ["api", "http-methods", "heuristic"],
+  run: async (context) => {
+    const findings = [];
+
+    for (const file of context.textFiles) {
+      if (!isApiCandidate(file)) continue;
+      const content = await context.readFileSafe(file);
+      if (!content) continue;
+
+      ALL_ROUTE_RE.lastIndex = 0;
+      let allMatch;
+      while ((allMatch = ALL_ROUTE_RE.exec(content)) !== null) {
+        const line = lineFromOffset(content, allMatch.index);
+        const nearby = await readNearby(context, file, line, 8);
+        if (/\b(?:allowedMethods|methodNotAllowed|405)\b/i.test(nearby)) continue;
+        findings.push(methodFinding(file, line, "app-router-all"));
+      }
+
+      if (METHOD_EXPORT_RE.test(content) || METHOD_GUARD_RE.test(content)) continue;
+
+      for (const pattern of [NEXT_PAGES_HANDLER_RE, NAMED_HANDLER_RE]) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+          findings.push(methodFinding(file, lineFromOffset(content, match.index), "handler-without-method-guard"));
+        }
+      }
+    }
+
+    return findings.slice(0, 100);
+  }
+};
+
+function isApiCandidate(file) {
+  return (
+    /\.[cm]?[jt]sx?$/.test(file) &&
+    (isServerOrApiFile(file) ||
+      file.startsWith("routes/") ||
+      file.startsWith("api/") ||
+      file.includes("/controllers/") ||
+      file.includes("/handlers/"))
+  );
+}
+
+function methodFinding(file, line, pattern) {
+  return {
+    message: "This API handler appears to process requests without an explicit HTTP method guard.",
+    file,
+    line,
+    recommendation: "Restrict API routes to the intended HTTP methods and return 405 Method Not Allowed for unsupported methods.",
+    heuristic: true,
+    metadata: { pattern }
+  };
+}

package/src/checks/api/no-schema-validation.js

@@ -0,0 +1,68 @@
+import { isServerOrApiFile, lineFromOffset, readNearby } from "../helpers.js";
+
+const REQUEST_INPUT_RE =
+  /\breq\.(?:body|query|params)\b|\brequest\.json\s*\(|\bsearchParams\.get\s*\(|\bnew\s+URL\s*\(\s*(?:req|request)\.url\s*\)\.searchParams\b|\bformData\s*\(|\bctx\.request\.body\b/g;
+const VALIDATION_RE =
+  /\b(?:zod|Joi|joi|yup|valibot|ajv|superstruct|TypeBox|validator|validatedData)\b|\.safeParse\s*\(|\.parse\s*\(\s*(?:req\.body|body|input|payload|data)|\.validate\s*\(\s*(?:req\.body|body|input|payload|data)|\bschema\.(?:validate|parse|safeParse)\b/i;
+const GLOBAL_VALIDATION_RE = /\b(?:app|router|server)\.use\s*\([^)]*(?:validate|validator|schema|zod|joi|yup|ajv|valibot)/i;
+
+export default {
+  id: "api.no-schema-validation",
+  title: "API request input should be schema validated",
+  category: "api",
+  severity: "high",
+  tags: ["api", "validation", "heuristic"],
+  run: async (context) => {
+    const findings = [];
+    const globalValidationSeen = await hasGlobalValidationMiddleware(context);
+    if (globalValidationSeen) return [];
+
+    for (const file of context.textFiles) {
+      if (!isApiFile(file)) continue;
+      const content = await context.readFileSafe(file);
+      if (!content) continue;
+      if (VALIDATION_RE.test(content)) continue;
+
+      REQUEST_INPUT_RE.lastIndex = 0;
+      const match = REQUEST_INPUT_RE.exec(content);
+      if (!match) continue;
+
+      const line = lineFromOffset(content, match.index);
+      const nearby = await readNearby(context, file, line, 10);
+      if (VALIDATION_RE.test(nearby)) continue;
+
+      findings.push({
+        message: "This API route appears to consume request input without an obvious schema validation step.",
+        file,
+        line,
+        recommendation: "Validate request body, query and params with a schema library such as Zod, Joi, Valibot, AJV or equivalent.",
+        heuristic: true,
+        metadata: { pattern: "request-input-without-schema-validation" }
+      });
+    }
+
+    return findings.slice(0, 100);
+  }
+};
+
+function isApiFile(file) {
+  return (
+    /\.[cm]?[jt]sx?$/.test(file) &&
+    (isServerOrApiFile(file) ||
+      file.startsWith("api/") ||
+      file.startsWith("routes/") ||
+      file.startsWith("handlers/") ||
+      file.startsWith("controllers/") ||
+      file.includes("/handlers/") ||
+      file.includes("/controllers/"))
+  );
+}
+
+async function hasGlobalValidationMiddleware(context) {
+  for (const file of context.textFiles) {
+    if (!/\.[cm]?[jt]sx?$/.test(file) || !isServerOrApiFile(file)) continue;
+    const content = await context.readFileSafe(file);
+    if (content && GLOBAL_VALIDATION_RE.test(content)) return true;
+  }
+  return false;
+}

package/src/checks/auth/missing-csrf-protection.js

@@ -0,0 +1,75 @@
+import { isCodeLikeFile, isEnvExampleFile, isLockfile, lineFromOffset } from "../helpers.js";
+
+const COOKIE_AUTH_RE =
+  /\b(?:res\.cookie|cookies\(\)\.set|response\.cookies\.set|setCookie|serialize)\s*\(\s*["'`](?:session|token|auth|jwt)["'`]|cookieSession\s*\(|express-session|\bsession\s*\(|credentials\s*:\s*["'`]include["'`]|withCredentials\s*:\s*true/gi;
+const CSRF_PROTECTION_RE =
+  /\b(?:csrf|csurf|csrfToken|anti-csrf|verifyCsrf|validateCsrf|csrfProtection)\b|double\s+submit|\bsameSite\s*:\s*["'`]?(?:strict|lax)["'`]?\b/gi;
+const STATE_CHANGING_ROUTE_RE =
+  /\b(?:app|router|server)\.(?:post|put|patch|delete)\s*\(|\bmethod\s*:\s*["'`](?:POST|PUT|PATCH|DELETE)["'`]|\breq\.method\s*={0,3}\s*["'`](?:POST|PUT|PATCH|DELETE)["'`]|\bexport\s+async\s+function\s+(?:POST|PUT|PATCH|DELETE)\s*\(/g;
+
+export default {
+  id: "auth.missing-csrf-protection",
+  title: "Cookie-based authentication should include CSRF protection",
+  category: "auth",
+  severity: "high",
+  tags: ["auth", "csrf", "cookies", "heuristic"],
+  run: async (context) => {
+    const cookieMatches = [];
+    const stateChangingRoutes = [];
+    let csrfProtectionSeen = false;
+
+    for (const file of context.textFiles) {
+      if (isLockfile(file) || isEnvExampleFile(file) || !isCodeLikeFile(file)) continue;
+      const content = await context.readFileSafe(file);
+      if (!content) continue;
+
+      CSRF_PROTECTION_RE.lastIndex = 0;
+      if (CSRF_PROTECTION_RE.test(content)) {
+        csrfProtectionSeen = true;
+        break;
+      }
+
+      COOKIE_AUTH_RE.lastIndex = 0;
+      let cookieMatch;
+      while ((cookieMatch = COOKIE_AUTH_RE.exec(content)) !== null) {
+        cookieMatches.push({
+          file,
+          line: lineFromOffset(content, cookieMatch.index),
+          pattern: normalizePattern(cookieMatch[0])
+        });
+        if (cookieMatches.length >= 25) break;
+      }
+
+      STATE_CHANGING_ROUTE_RE.lastIndex = 0;
+      let routeMatch;
+      while ((routeMatch = STATE_CHANGING_ROUTE_RE.exec(content)) !== null) {
+        stateChangingRoutes.push({
+          file,
+          line: lineFromOffset(content, routeMatch.index),
+          pattern: normalizePattern(routeMatch[0])
+        });
+        if (stateChangingRoutes.length >= 25) break;
+      }
+    }
+
+    if (csrfProtectionSeen || cookieMatches.length === 0 || stateChangingRoutes.length === 0) return [];
+
+    const primaryCookie = cookieMatches[0];
+    return stateChangingRoutes.slice(0, 25).map((route) => ({
+      message: "Cookie-based authentication appears to be used without an obvious CSRF protection mechanism.",
+      file: route.file,
+      line: route.line,
+      recommendation: "Use SameSite cookies, CSRF tokens or another explicit CSRF mitigation for state-changing routes.",
+      heuristic: true,
+      metadata: {
+        pattern: "cookie-auth-with-state-changing-route",
+        cookieFile: primaryCookie.file,
+        cookieLine: primaryCookie.line
+      }
+    }));
+  }
+};
+
+function normalizePattern(value) {
+  return String(value || "").replace(/\s+/g, " ").slice(0, 80);
+}