bandit-cli 1.0.0

package/dist/core/context.js

@@ -0,0 +1,7 @@
+import path from "node:path";
+export function makeContext(projectPath) {
+    return {
+        projectPath,
+        packageJsonPath: path.join(projectPath, "package.json"),
+    };
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runAudit } from "./core/auditor.js";
+import { printHuman } from "./cli/output.js";
+const program = new Command();
+program
+    .name("bandit")
+    .description("The Swiss Army Knife for Backend Developers");
+// Subcommand: audit (original behavior)
+program
+    .command("audit")
+    .description("Audit a backend project directory for basic best-practices")
+    .argument("[path]", "Path to the project", ".")
+    .option("--json", "Print results as JSON")
+    .option("--fail-on-warn", "Exit with code 1 if warnings exist")
+    .action(async (projectPath, opts) => {
+    const results = await runAudit(projectPath);
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(results, null, 2) + "\n");
+    }
+    else {
+        printHuman(results);
+    }
+    const hasErrors = results.items.some((r) => r.status === "fail" && r.severity === "error");
+    const hasWarnings = results.items.some((r) => r.status === "fail" && r.severity === "warn");
+    if (hasErrors)
+        process.exit(1);
+    if (opts.failOnWarn && hasWarnings)
+        process.exit(1);
+});
+// Subcommand: ports
+program
+    .command("ports")
+    .description("Scan active listening ports and interactively terminate locked processes")
+    .action(async () => {
+    const { runPortsCommand } = await import("./cli/ports.js");
+    await runPortsCommand();
+});
+// Subcommand: env
+program
+    .command("env")
+    .description("Audit local .env configurations against .env.example")
+    .argument("[path]", "Path to the project", ".")
+    .action(async (projectPath) => {
+    const { runEnvCommand } = await import("./cli/env.js");
+    await runEnvCommand(projectPath);
+});
+// Subcommand: doctor
+program
+    .command("doctor")
+    .description("Actively audit a running local server for header security, error leakage, and payload crashes")
+    .argument("[url]", "URL of the running server", "http://localhost:3000")
+    .action(async (url) => {
+    const { runDoctorCommand } = await import("./cli/doctor.js");
+    await runDoctorCommand(url);
+});
+// Subcommand: api
+program
+    .command("api")
+    .description("Interactive API playfield: scan codebase routes and send test requests")
+    .argument("[path]", "Path to the project", ".")
+    .action(async (projectPath) => {
+    const { runApiCommand } = await import("./cli/api.js");
+    await runApiCommand(projectPath);
+});
+// Subcommand: bench
+program
+    .command("bench")
+    .description("Benchmark an HTTP endpoint with concurrent connections load testing")
+    .argument("<url>", "Target URL to load test")
+    .option("-c, --connections <number>", "Number of concurrent connections", "10")
+    .option("-r, --requests <number>", "Total number of requests to execute", "200")
+    .action(async (url, opts) => {
+    const connections = parseInt(opts.connections, 10);
+    const requests = parseInt(opts.requests, 10);
+    if (isNaN(connections) || connections <= 0) {
+        console.error("Error: connections must be a positive integer.");
+        process.exit(1);
+    }
+    if (isNaN(requests) || requests <= 0) {
+        console.error("Error: requests must be a positive integer.");
+        process.exit(1);
+    }
+    const { runBenchCommand } = await import("./cli/bench.js");
+    await runBenchCommand(url, { connections, requests });
+});
+// Default to help if no command specified
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+    process.exit(0);
+}
+program.parse(process.argv);

package/dist/rules/index.js

@@ -0,0 +1,28 @@
+import { rulePackageJsonExists } from "./mvp.rules.js";
+import { ruleEnvExists } from "./mvp.rules.js";
+import { ruleEnvExampleExists } from "./mvp.rules.js";
+import { ruleEnvInGitignore } from "./mvp.rules.js";
+import { ruleDockerfileExists } from "./mvp.rules.js";
+import { ruleHasTestScript } from "./mvp.rules.js";
+import { ruleSrcFolderExists, ruleDetectFramework, ruleSecurityDeps, ruleGlobalErrorHandler, } from "./phase2.rules.js";
+import { ruleLoggingSetup, ruleEnvValidation, ruleDatabaseSetup, ruleTypeScriptStrict, ruleProductionDeps, } from "./phase3.rules.js";
+export const rules = [
+    // Phase 1 - MVP checks
+    rulePackageJsonExists,
+    ruleEnvExists,
+    ruleEnvExampleExists,
+    ruleEnvInGitignore,
+    ruleDockerfileExists,
+    ruleHasTestScript,
+    // Phase 2 - Structure + detection + security
+    ruleSrcFolderExists,
+    ruleDetectFramework,
+    ruleSecurityDeps,
+    ruleGlobalErrorHandler,
+    // Phase 3 - Production readiness
+    ruleLoggingSetup,
+    ruleEnvValidation,
+    ruleDatabaseSetup,
+    ruleTypeScriptStrict,
+    ruleProductionDeps,
+];

package/dist/rules/mvp.rules.js

@@ -0,0 +1,138 @@
+// File: src/rules/mvp.rules.ts
+import path from "node:path";
+import { exists, readText } from "../utils/fs.js";
+import { readPackageJson, hasScript } from "../utils/packageJson.js";
+export const rulePackageJsonExists = {
+    id: "pkg-json-exists",
+    title: "package.json exists",
+    severity: "error",
+    async run(ctx) {
+        const ok = exists(ctx.packageJsonPath);
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : "package.json not found.",
+            suggestion: ok ? undefined : "Run `npm init -y` in the project root.",
+        };
+    },
+};
+export const ruleEnvExists = {
+    id: "env-exists",
+    title: ".env exists",
+    severity: "warn",
+    async run(ctx) {
+        const envPath = path.join(ctx.projectPath, ".env");
+        const ok = exists(envPath);
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : ".env not found.",
+            suggestion: ok ? undefined : "Create a local .env file for development.",
+        };
+    },
+};
+export const ruleEnvExampleExists = {
+    id: "env-example-exists",
+    title: ".env.example exists",
+    severity: "info",
+    async run(ctx) {
+        const envExamplePath = path.join(ctx.projectPath, ".env.example");
+        const ok = exists(envExamplePath);
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : ".env.example not found.",
+            suggestion: ok
+                ? undefined
+                : "Create .env.example listing all required env keys (without real secrets).",
+        };
+    },
+};
+export const ruleEnvInGitignore = {
+    id: "env-in-gitignore",
+    title: ".env is ignored in .gitignore",
+    severity: "error",
+    async run(ctx) {
+        const gitignorePath = path.join(ctx.projectPath, ".gitignore");
+        const gitignore = readText(gitignorePath);
+        if (!gitignore) {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "fail",
+                details: ".gitignore not found.",
+                suggestion: "Create a .gitignore and add `.env` to it.",
+            };
+        }
+        const lines = gitignore
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l && !l.startsWith("#"));
+        const ok = lines.includes(".env") || lines.includes(".env*");
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : "`.env` is not ignored.",
+            suggestion: ok
+                ? undefined
+                : "Add `.env` to .gitignore to avoid leaking secrets.",
+        };
+    },
+};
+export const ruleDockerfileExists = {
+    id: "dockerfile-exists",
+    title: "Dockerfile exists",
+    severity: "info",
+    async run(ctx) {
+        const dockerfilePath = path.join(ctx.projectPath, "Dockerfile");
+        const ok = exists(dockerfilePath);
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : "Dockerfile not found.",
+            suggestion: ok
+                ? undefined
+                : "If you plan to containerize this backend, add a Dockerfile.",
+        };
+    },
+};
+export const ruleHasTestScript = {
+    id: "test-script-exists",
+    title: "package.json contains a test script",
+    severity: "warn",
+    async run(ctx) {
+        const pkg = readPackageJson(ctx.packageJsonPath);
+        if (!pkg) {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "skip",
+                details: "Could not read/parse package.json.",
+                suggestion: "Fix package.json JSON syntax.",
+            };
+        }
+        const ok = hasScript(pkg, "test");
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : "No `test` script found.",
+            suggestion: ok
+                ? undefined
+                : "Add a test runner (jest/vitest) and a `test` script.",
+        };
+    },
+};

package/dist/rules/phase2.rules.js

@@ -0,0 +1,233 @@
+// File: src/rules/phase2.rules.ts
+import path from "node:path";
+import { exists } from "../utils/fs.js";
+import { readPackageJson, hasDependency, detectFramework, } from "../utils/packageJson.js";
+import { scanForErrorHandler } from "../utils/codeScanner.js";
+// Rule 7: src/ folder exists
+export const ruleSrcFolderExists = {
+    id: "src-folder-exists",
+    title: "src/ folder exists",
+    severity: "warn",
+    async run(ctx) {
+        const srcPath = path.join(ctx.projectPath, "src");
+        const ok = exists(srcPath);
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: ok ? "pass" : "fail",
+            details: ok ? undefined : "src/ folder not found.",
+            suggestion: ok
+                ? undefined
+                : "Create a src/ folder to organize your backend code.",
+        };
+    },
+};
+// Rule 8: Detect backend framework
+export const ruleDetectFramework = {
+    id: "detect-framework",
+    title: "Detect backend framework",
+    severity: "info",
+    async run(ctx) {
+        const pkg = readPackageJson(ctx.packageJsonPath);
+        if (!pkg) {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "skip",
+                details: "Could not read package.json.",
+                suggestion: "Fix package.json JSON syntax.",
+            };
+        }
+        const framework = detectFramework(pkg);
+        // Update context with detected framework for subsequent rules
+        ctx.framework = framework;
+        if (framework === "unknown") {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "fail",
+                details: "No known backend framework detected.",
+                suggestion: "Consider using a popular framework like Express, Fastify, NestJS, or Hono.",
+            };
+        }
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: "pass",
+            details: `Detected framework: ${framework}`,
+        };
+    },
+};
+// Rule 9: Security dependencies check (framework-dependent)
+export const ruleSecurityDeps = {
+    id: "security-deps",
+    title: "Security dependencies check",
+    severity: "warn",
+    async run(ctx) {
+        const pkg = readPackageJson(ctx.packageJsonPath);
+        if (!pkg) {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "skip",
+                details: "Could not read package.json.",
+            };
+        }
+        const framework = ctx.framework || detectFramework(pkg);
+        // For Express, check helmet and cors
+        if (framework === "express") {
+            const hasHelmet = hasDependency(pkg, "helmet");
+            const hasCors = hasDependency(pkg, "cors");
+            if (!hasHelmet && !hasCors) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "Missing security dependencies: helmet and cors not found.",
+                    suggestion: "Install: `npm install helmet cors`",
+                };
+            }
+            if (!hasHelmet) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "helmet is not installed.",
+                    suggestion: "Install: `npm install helmet`",
+                };
+            }
+            if (!hasCors) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "cors is not installed.",
+                    suggestion: "Install: `npm install cors`",
+                };
+            }
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "pass",
+                details: "helmet and cors are installed.",
+            };
+        }
+        // For Fastify
+        if (framework === "fastify") {
+            const hasHelmet = hasDependency(pkg, "@fastify/helmet");
+            const hasCors = hasDependency(pkg, "@fastify/cors");
+            if (!hasHelmet && !hasCors) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "Missing security dependencies: @fastify/helmet and @fastify/cors not found.",
+                    suggestion: "Install: `npm install @fastify/helmet @fastify/cors`",
+                };
+            }
+            if (!hasHelmet) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "@fastify/helmet is not installed.",
+                    suggestion: "Install: `npm install @fastify/helmet`",
+                };
+            }
+            if (!hasCors) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "@fastify/cors is not installed.",
+                    suggestion: "Install: `npm install @fastify/cors`",
+                };
+            }
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "pass",
+                details: "@fastify/helmet and @fastify/cors are installed.",
+            };
+        }
+        // For NestJS, security is built-in but can check helmet
+        if (framework === "nest") {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "pass",
+                details: "NestJS has built-in security features. Consider adding helmet.",
+            };
+        }
+        // For other frameworks or unknown
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: "skip",
+            details: `Security checks not defined for framework: ${framework}`,
+        };
+    },
+};
+// Rule 10: Global error handler present
+export const ruleGlobalErrorHandler = {
+    id: "global-error-handler",
+    title: "Global error handler present",
+    severity: "warn",
+    async run(ctx) {
+        const srcPath = path.join(ctx.projectPath, "src");
+        if (!exists(srcPath)) {
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "skip",
+                details: "src/ folder not found, skipping code scan.",
+            };
+        }
+        const framework = ctx.framework || "unknown";
+        // For Express, look for error handler middleware pattern
+        if (framework === "express") {
+            const found = await scanForErrorHandler(srcPath);
+            if (!found) {
+                return {
+                    id: this.id,
+                    title: this.title,
+                    severity: this.severity,
+                    status: "fail",
+                    details: "No global error handler middleware found.",
+                    suggestion: "Add app.use((err, req, res, next) => {...}) after all routes.",
+                };
+            }
+            return {
+                id: this.id,
+                title: this.title,
+                severity: this.severity,
+                status: "pass",
+                details: "Global error handler detected.",
+            };
+        }
+        // For other frameworks, skip for now
+        return {
+            id: this.id,
+            title: this.title,
+            severity: this.severity,
+            status: "skip",
+            details: `Error handler check not implemented for framework: ${framework}`,
+        };
+    },
+};