middlebrick 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# middlebrick
+
+CLI for [middleBrick](https://middlebrick.com) API security scanning. Scan APIs from your terminal, get risk scores, and gate CI/CD pipelines.
+
+## Install
+
+```bash
+npm install -g middlebrick
+```
+
+## Quick Start
+
+```bash
+# Set up your API key
+middlebrick configure
+
+# Scan an API
+middlebrick scan https://api.example.com/v1/users
+
+# JSON output for CI
+middlebrick scan https://api.example.com/v1/users --format json
+
+# Fail if score < 80
+middlebrick scan https://api.example.com/v1/users --threshold 80
+```
+
+## Commands
+
+### `middlebrick scan <url>`
+
+Scan an API endpoint and display security results.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--method <METHOD>` | HTTP method | `GET` |
+| `--format <FORMAT>` | Output: `summary`, `json`, `table` | `summary` |
+| `--threshold <score>` | Exit code 1 if score below threshold | — |
+| `--no-wait` | Return scanId immediately | — |
+
+### `middlebrick results <scanId>`
+
+Fetch results of a previous scan.
+
+### `middlebrick configure`
+
+Interactively set up your API key. Saves to `~/.middlebrick/config.json`.
+
+## Authentication
+
+| Priority | Source |
+|----------|--------|
+| 1 | `--api-key` flag |
+| 2 | `MIDDLEBRICK_API_KEY` env var |
+| 3 | `~/.middlebrick/config.json` |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Scan failed or score below threshold |
+| 2 | Auth/config error |
+
+## CI/CD
+
+```yaml
+# GitHub Actions
+- name: API Security Gate
+  run: npx middlebrick scan ${{ env.API_URL }} --threshold 75 --api-key ${{ secrets.MIDDLEBRICK_API_KEY }}
+```
+
+## License
+
+MIT — [Zevlat Intelligence](https://zev.lat)

package/dist/commands/configure.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const configureCommand: Command;

package/dist/commands/configure.js

@@ -0,0 +1,33 @@
+import { Command } from "commander";
+import { createInterface } from "node:readline";
+import { saveConfig, loadConfig } from "../config.js";
+export const configureCommand = new Command("configure")
+    .description("Set up your middleBrick API key")
+    .action(async () => {
+    const existing = loadConfig();
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const prompt = existing.apiKey
+        ? `API key [${existing.apiKey.slice(0, 6)}...]: `
+        : "API key: ";
+    const apiKey = await new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+    if (!apiKey) {
+        if (existing.apiKey) {
+            console.log("Keeping existing key.");
+        }
+        else {
+            console.error("No key provided. Get one at https://middlebrick.com/dashboard");
+            process.exit(2);
+        }
+        return;
+    }
+    saveConfig({ apiKey });
+    console.log("API key saved to ~/.middlebrick/config.json");
+});

package/dist/commands/results.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const resultsCommand: Command;

package/dist/commands/results.js

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import { MiddleBrickClient, MiddleBrickError } from "@middlebrick/api-client";
+import { resolveApiKey } from "../config.js";
+import { formatSummary } from "../formatters/summary.js";
+import { formatJson } from "../formatters/json.js";
+import { formatTable } from "../formatters/table.js";
+export const resultsCommand = new Command("results")
+    .description("Fetch results of a previous scan")
+    .argument("<scanId>", "Scan ID to retrieve")
+    .option("--format <FORMAT>", "Output format: summary | json | table", "summary")
+    .action(async (scanId, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    let apiKey;
+    try {
+        apiKey = resolveApiKey(globalOpts);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(2);
+    }
+    const client = new MiddleBrickClient({
+        apiKey,
+        baseUrl: globalOpts.baseUrl,
+    });
+    try {
+        const result = await client.getScan(scanId);
+        switch (opts.format) {
+            case "json":
+                console.log(formatJson(result));
+                break;
+            case "table":
+                console.log(formatTable(result));
+                break;
+            case "summary":
+            default:
+                console.log(formatSummary(result));
+                break;
+        }
+    }
+    catch (err) {
+        if (err instanceof MiddleBrickError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(err.statusCode === 401 || err.statusCode === 403 ? 2 : 1);
+        }
+        throw err;
+    }
+});

package/dist/commands/scan.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const scanCommand: Command;

package/dist/commands/scan.js

@@ -0,0 +1,103 @@
+import { Command } from "commander";
+import { MiddleBrickClient, MiddleBrickError } from "@middlebrick/api-client";
+import { resolveApiKey } from "../config.js";
+import { formatSummary } from "../formatters/summary.js";
+import { formatJson } from "../formatters/json.js";
+import { formatTable } from "../formatters/table.js";
+export const scanCommand = new Command("scan")
+    .description("Scan an API endpoint for security risks")
+    .argument("<url>", "API endpoint URL to scan")
+    .option("--method <METHOD>", "HTTP method", "GET")
+    .option("--format <FORMAT>", "Output format: summary | json | table", "summary")
+    .option("--threshold <score>", "Exit code 1 if overall score < threshold", parseFloat)
+    .option("--no-wait", "Return scanId immediately, don't poll")
+    .action(async (url, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    let apiKey;
+    try {
+        apiKey = resolveApiKey(globalOpts);
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(2);
+    }
+    const client = new MiddleBrickClient({
+        apiKey,
+        baseUrl: globalOpts.baseUrl,
+    });
+    let result;
+    try {
+        if (opts.wait === false) {
+            if (opts.threshold !== undefined) {
+                console.error("Warning: --threshold is ignored with --no-wait");
+            }
+            const { scanId } = await client.scanApi({
+                apiUrl: url,
+                method: opts.method,
+            });
+            console.log(scanId);
+            return;
+        }
+        // Show spinner while waiting
+        const spinner = createSpinner("Scanning...");
+        spinner.start();
+        try {
+            result = await client.scanAndWait({
+                apiUrl: url,
+                method: opts.method,
+            });
+        }
+        finally {
+            spinner.stop();
+        }
+    }
+    catch (err) {
+        if (err instanceof MiddleBrickError) {
+            console.error(`Error: ${err.message}`);
+            process.exit(err.statusCode === 401 || err.statusCode === 403 ? 2 : 1);
+        }
+        throw err;
+    }
+    // Format output
+    const output = formatOutput(result, opts.format, opts.threshold);
+    console.log(output);
+    // Threshold check
+    if (opts.threshold !== undefined &&
+        result.overall !== undefined &&
+        result.overall < opts.threshold) {
+        process.exit(1);
+    }
+    if (result.status === "failed") {
+        process.exit(1);
+    }
+});
+function formatOutput(result, format, threshold) {
+    switch (format) {
+        case "json":
+            return formatJson(result);
+        case "table":
+            return formatTable(result);
+        case "summary":
+        default:
+            return formatSummary(result, threshold);
+    }
+}
+function createSpinner(message) {
+    let interval = null;
+    let dots = 0;
+    return {
+        start() {
+            process.stdout.write(message);
+            interval = setInterval(() => {
+                dots = (dots + 1) % 4;
+                process.stdout.write(`\r${message}${".".repeat(dots)}${"   ".slice(dots)}`);
+            }, 300);
+        },
+        stop() {
+            if (interval) {
+                clearInterval(interval);
+                process.stdout.write("\r" + " ".repeat(message.length + 4) + "\r");
+            }
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+interface Config {
+    apiKey?: string;
+}
+declare const CONFIG_DIR: string;
+declare const CONFIG_FILE: string;
+export declare function resolveApiKey(opts: {
+    apiKey?: string;
+}): string;
+export declare function loadConfig(): Config;
+export declare function saveConfig(config: Config): void;
+export { CONFIG_DIR, CONFIG_FILE };

package/dist/config.js

@@ -0,0 +1,41 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CONFIG_DIR = join(homedir(), ".middlebrick");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+export function resolveApiKey(opts) {
+    // 1. CLI flag
+    if (opts.apiKey)
+        return opts.apiKey;
+    // 2. Environment variable
+    const envKey = process.env.MIDDLEBRICK_API_KEY;
+    if (envKey)
+        return envKey;
+    // 3. Config file
+    const config = loadConfig();
+    if (config.apiKey)
+        return config.apiKey;
+    throw new Error([
+        "No API key found. Set one with:",
+        "",
+        "  middlebrick configure",
+        "  --api-key <key>",
+        "  MIDDLEBRICK_API_KEY=mb_... middlebrick scan <url>",
+        "",
+        "Get your API key at https://middlebrick.com/dashboard",
+    ].join("\n"));
+}
+export function loadConfig() {
+    try {
+        const raw = readFileSync(CONFIG_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(config) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+export { CONFIG_DIR, CONFIG_FILE };

package/dist/formatters/json.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "@middlebrick/api-client";
+export declare function formatJson(result: ScanResult): string;

package/dist/formatters/json.js

@@ -0,0 +1,3 @@
+export function formatJson(result) {
+    return JSON.stringify(result, null, 2);
+}

package/dist/formatters/summary.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "@middlebrick/api-client";
+export declare function formatSummary(result: ScanResult, threshold?: number): string;

package/dist/formatters/summary.js

@@ -0,0 +1,97 @@
+import chalk from "chalk";
+function scoreBar(score) {
+    const filled = Math.round(score / 10);
+    const empty = 10 - filled;
+    return chalk.green("█".repeat(filled)) + chalk.gray("░".repeat(empty));
+}
+function gradeColor(grade) {
+    switch (grade) {
+        case "A":
+            return chalk.green(grade);
+        case "B":
+            return chalk.cyan(grade);
+        case "C":
+            return chalk.yellow(grade);
+        case "D":
+            return chalk.hex("#FF8800")(grade);
+        case "F":
+            return chalk.red(grade);
+        default:
+            return grade;
+    }
+}
+function severityIcon(severity) {
+    switch (severity) {
+        case "critical":
+        case "high":
+        case "medium":
+            return chalk.red("✗");
+        case "low":
+            return chalk.yellow("!");
+        case "info":
+            return chalk.green("✓");
+        default:
+            return " ";
+    }
+}
+function severityLabel(severity) {
+    const upper = severity.toUpperCase();
+    switch (severity) {
+        case "critical":
+            return chalk.bgRed.white(` ${upper} `);
+        case "high":
+            return chalk.red(`[${upper}]`);
+        case "medium":
+            return chalk.yellow(`[${upper}]`);
+        case "low":
+            return chalk.cyan(`[${upper}]`);
+        case "info":
+            return chalk.gray(`[${upper}]`);
+        default:
+            return `[${upper}]`;
+    }
+}
+export function formatSummary(result, threshold) {
+    const lines = [];
+    lines.push("");
+    lines.push(chalk.bold("  middleBrick API Security Scan"));
+    lines.push("");
+    lines.push(`  URL:    ${result.apiUrl}`);
+    lines.push(`  Method: ${result.method}`);
+    if (result.status === "failed") {
+        lines.push("");
+        lines.push(chalk.red(`  Scan failed: ${result.errorMessage || "Unknown error"}`));
+        lines.push("");
+        return lines.join("\n");
+    }
+    if (result.overall !== undefined && result.letterGrade) {
+        lines.push(`  Score:  ${result.overall}/100 (${gradeColor(result.letterGrade)})`);
+    }
+    if (result.categories && Object.keys(result.categories).length > 0) {
+        lines.push("");
+        lines.push(chalk.bold("  Categories:"));
+        for (const [name, score] of Object.entries(result.categories)) {
+            const label = name.padEnd(20);
+            lines.push(`    ${label} ${scoreBar(score)}  ${score}`);
+        }
+    }
+    const findings = result.findings || [];
+    if (findings.length > 0) {
+        lines.push("");
+        lines.push(chalk.bold(`  Findings (${findings.length}):`));
+        for (const f of findings) {
+            lines.push(`    ${severityIcon(f.severity)} ${severityLabel(f.severity)} ${f.title}`);
+            lines.push(`      ${chalk.gray(f.description)}`);
+        }
+    }
+    if (threshold !== undefined && result.overall !== undefined) {
+        lines.push("");
+        const passed = result.overall >= threshold;
+        const status = passed
+            ? chalk.green("PASS ✓")
+            : chalk.red("FAIL ✗");
+        lines.push(`  Threshold: ${threshold} → ${status}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/formatters/table.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from "@middlebrick/api-client";
+export declare function formatTable(result: ScanResult): string;

package/dist/formatters/table.js

@@ -0,0 +1,9 @@
+export function formatTable(result) {
+    const findings = result.findings || [];
+    if (findings.length === 0) {
+        return "No findings.";
+    }
+    const header = "SEVERITY\tCATEGORY\tTITLE";
+    const rows = findings.map((f) => `${f.severity.toUpperCase()}\t${f.category}\t${f.title}`);
+    return [header, ...rows].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { scanCommand } from "./commands/scan.js";
+import { resultsCommand } from "./commands/results.js";
+import { configureCommand } from "./commands/configure.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const program = new Command()
+    .name("middlebrick")
+    .description("middleBrick — API security scanning from your terminal")
+    .version(pkg.version)
+    .option("--api-key <key>", "API key (overrides env/config)")
+    .option("--base-url <url>", "API base URL override");
+program.addCommand(scanCommand);
+program.addCommand(resultsCommand);
+program.addCommand(configureCommand);
+program.parse();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "middlebrick",
+  "version": "0.1.0",
+  "description": "middleBrick CLI — API security scanning from your terminal",
+  "type": "module",
+  "bin": {
+    "middlebrick": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@middlebrick/api-client": "^0.1.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}