evershield 0.0.0-stage → 0.2.0

package/dist/audit/run.js

@@ -0,0 +1,62 @@
+import { VERSION } from "../index.js";
+import { sortFindings } from "../scan/artifact.js";
+import { requestEndpoint } from "./http.js";
+import { RESPONSE_RULES } from "./rules.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Layer 2: call each endpoint as each identity, least privileged first, and
+ * run the response rules over what came back. Requests are sequential: an
+ * audit is a handful of calls, and it should never look like load.
+ */
+export async function runAudit(config, options = {}) {
+    const startedAt = new Date().toISOString();
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const findings = [];
+    const warnings = [];
+    let responsesEvaluated = 0;
+    for (const endpoint of config.endpoints) {
+        const label = `${endpoint.method} ${endpoint.path}`;
+        const observation = { endpoint, label, tiers: config.tiers, responses: new Map() };
+        for (const identityName of config.tiers) {
+            const identity = config.identities[identityName];
+            if (identity === undefined) {
+                warnings.push(`${label}: identity "${identityName}" is not defined`);
+                continue;
+            }
+            const requestOptions = { baseUrl: config.baseUrl, endpoint, identityName, identity, timeoutMs };
+            const response = await requestEndpoint({
+                ...requestOptions,
+                ...(options.env === undefined ? {} : { env: options.env }),
+                ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+            });
+            observation.responses.set(identityName, response);
+            if (response.error !== undefined) {
+                warnings.push(`${label} as ${identityName}: request failed (${response.error})`);
+            }
+            else if (response.status < 200 || response.status >= 300) {
+                warnings.push(`${label} as ${identityName}: HTTP ${response.status}, not evaluated`);
+            }
+            else if (!response.isJson) {
+                warnings.push(`${label} as ${identityName}: response is not JSON (${response.contentType ?? "no content-type"}), not evaluated`);
+            }
+            else {
+                responsesEvaluated += 1;
+            }
+        }
+        for (const rule of RESPONSE_RULES)
+            findings.push(...rule.check(observation));
+    }
+    return {
+        version: VERSION,
+        layer: "response",
+        target: config.baseUrl,
+        identities: [...config.tiers],
+        endpointsAudited: config.endpoints.length,
+        responsesEvaluated,
+        ignored: 0,
+        warnings,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        findings: sortFindings(findings),
+    };
+}

package/dist/audit/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Layer 2: privilege-differential response audit.
+ *
+ * The operator declares identities (anonymous, free, pro, admin, …) whose
+ * credentials live in environment variables, an ordered list of tiers from
+ * least to most privileged, and endpoints to call as each identity. The
+ * audit compares what each identity receives and reports fields that a
+ * lower tier should not have.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface IdentityConfig {
+    /** Header values may reference env vars as `${NAME}`; credential headers must. */
+    headers?: Record<string, string>;
+}
+export interface EndpointExpectation {
+    /** JSON paths (dot notation, `[]` for arrays) that must be absent or null for this identity. */
+    absent?: string[];
+}
+export interface EndpointConfig {
+    method: HttpMethod;
+    /** Path relative to `baseUrl`, starting with `/`. */
+    path: string;
+    headers?: Record<string, string>;
+    /** JSON body for POST/PUT/PATCH. String values may reference env vars. */
+    body?: unknown;
+    /** The endpoint is supposed to answer differently per tier. */
+    tiered?: boolean;
+    /** Per-identity expectations, keyed by identity name. */
+    expect?: Record<string, EndpointExpectation>;
+}
+export interface AuditConfig {
+    /** Origin the audit is allowed to talk to. Endpoints are relative to it. */
+    baseUrl: string;
+    /** Identity names ordered from least to most privileged. */
+    tiers: string[];
+    identities: Record<string, IdentityConfig>;
+    endpoints: EndpointConfig[];
+    timeoutMs?: number;
+}
+export interface ResponseObservation {
+    identity: string;
+    status: number;
+    contentType: string | null;
+    /** Parsed JSON body, or undefined when the body was not JSON. */
+    json: unknown;
+    isJson: boolean;
+    /** Transport-level failure, when the request did not complete. */
+    error?: string;
+}
+export interface EndpointObservation {
+    endpoint: EndpointConfig;
+    /** "POST /api/analyze" */
+    label: string;
+    /** Identity names, least privileged first. */
+    tiers: string[];
+    responses: Map<string, ResponseObservation>;
+}

package/dist/audit/types.js

@@ -0,0 +1,10 @@
+/**
+ * Layer 2: privilege-differential response audit.
+ *
+ * The operator declares identities (anonymous, free, pro, admin, …) whose
+ * credentials live in environment variables, an ordered list of tiers from
+ * least to most privileged, and endpoints to call as each identity. The
+ * audit compares what each identity receives and reports fields that a
+ * lower tier should not have.
+ */
+export {};

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+const result = await run(process.argv.slice(2));
+if (result.stdout)
+    process.stdout.write(result.stdout);
+if (result.stderr)
+    process.stderr.write(result.stderr);
+process.exitCode = result.code;

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+export interface CliResult {
+    /** Process exit code. 0 clean, 1 blocking findings, 2 usage or runtime error. */
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Entry point without process side effects beyond the optional --output
+ * file: takes argv (minus node and the script path), returns what to print
+ * and the exit code.
+ */
+export declare function run(argv: readonly string[]): Promise<CliResult>;

package/dist/cli.js

@@ -0,0 +1,213 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { runAudit } from "./audit/run.js";
+import { applyIgnores, ConfigError, loadConfig } from "./config.js";
+import { runInit } from "./init.js";
+import { runSurface } from "./surface/run.js";
+import { VERSION } from "./index.js";
+import { CONFIDENCES, DEFAULT_GATE, isBlocking, renderJson, renderText, SEVERITIES } from "./report/index.js";
+import { renderSarif } from "./report/sarif.js";
+import { scanArtifact } from "./scan/artifact.js";
+import { ADAPTERS } from "./scan/adapters.js";
+const HELP = `evershield ${VERSION}
+Shield everything, everywhere.
+
+Usage:
+  evershield init [--force]         Detect your framework and write evershield.config.json
+                                    and a GitHub workflow that scans every pull request
+  evershield scan <dir> [options]   Layer 1: scan a built web artifact directory
+  evershield audit [options]        Layer 2: call configured endpoints as each identity
+                                    and compare what they receive (needs config "audit")
+  evershield surface [options]      Layer 3: open configured pages as each identity in a
+                                    headless browser and find content that is present but
+                                    hidden (needs config "surface" and Playwright)
+  evershield --version              Print version
+  evershield --help                 Show this help
+
+Options (scan, audit, surface):
+  --format <text|json|sarif>        Output format (default: text)
+  --output <file>                   Write the report to a file; stdout gets a one-line summary
+  --config <file>                   Config file (default: ./evershield.config.json if present)
+  --fail-on <severity|none>         Fail on findings at this severity or worse
+                                    (critical|high|medium|low|info|none; default: high)
+  --min-confidence <level>          Findings below this confidence never fail the build
+                                    (high|medium|low; default: medium)
+
+Scan options:
+  --adapter <nextjs|plain>          Force an adapter instead of detecting one
+
+Exit codes: 0 clean · 1 blocking findings · 2 usage or runtime error
+Documentation: https://github.com/inviy/evershield
+`;
+function usageError(message) {
+    return { code: 2, stdout: "", stderr: `evershield: ${message}\n\n${HELP}` };
+}
+function isOneOf(value, allowed) {
+    return allowed.includes(value);
+}
+function parseCommonOptions(rest) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...rest],
+            allowPositionals: true,
+            options: {
+                format: { type: "string", default: "text" },
+                output: { type: "string" },
+                config: { type: "string" },
+                "fail-on": { type: "string" },
+                "min-confidence": { type: "string" },
+                adapter: { type: "string" },
+            },
+        });
+    }
+    catch (error) {
+        return usageError(error instanceof Error ? error.message : String(error));
+    }
+    const format = String(parsed.values.format);
+    if (!isOneOf(format, ["text", "json", "sarif"]))
+        return usageError(`unknown --format "${format}"`);
+    const failOn = parsed.values["fail-on"] === undefined ? undefined : String(parsed.values["fail-on"]);
+    if (failOn !== undefined && !isOneOf(failOn, [...SEVERITIES, "none"]))
+        return usageError(`unknown --fail-on "${failOn}"`);
+    const minConfidence = parsed.values["min-confidence"] === undefined ? undefined : String(parsed.values["min-confidence"]);
+    if (minConfidence !== undefined && !isOneOf(minConfidence, CONFIDENCES))
+        return usageError(`unknown --min-confidence "${minConfidence}"`);
+    const adapter = parsed.values.adapter === undefined ? undefined : String(parsed.values.adapter);
+    if (adapter !== undefined && !isOneOf(adapter, Object.keys(ADAPTERS))) {
+        return usageError(`unknown --adapter "${adapter}"`);
+    }
+    return {
+        positionals: parsed.positionals,
+        format,
+        outputPath: parsed.values.output === undefined ? undefined : String(parsed.values.output),
+        configPath: parsed.values.config === undefined ? undefined : String(parsed.values.config),
+        failOn,
+        minConfidence,
+        adapter,
+    };
+}
+function gateFor(options, config) {
+    // Precedence: CLI flag, then config file, then defaults.
+    return {
+        failOn: options.failOn ?? config.gate?.failOn ?? DEFAULT_GATE.failOn,
+        minConfidence: options.minConfidence ?? config.gate?.minConfidence ?? DEFAULT_GATE.minConfidence,
+    };
+}
+async function finish(report, gate, options) {
+    const blocking = report.findings.filter((finding) => isBlocking(finding, gate)).length;
+    const rendered = options.format === "json" ? renderJson(report, gate) : options.format === "sarif" ? renderSarif(report, gate) : renderText(report, gate);
+    const code = blocking > 0 ? 1 : 0;
+    if (options.outputPath === undefined)
+        return { code, stdout: rendered, stderr: "" };
+    await writeFile(path.resolve(options.outputPath), rendered);
+    const summary = `evershield: ${report.findings.length} finding(s), ${blocking} blocking, ${report.ignored} ignored · ${options.format} report written to ${options.outputPath}\n`;
+    return { code, stdout: summary, stderr: "" };
+}
+function failure(command, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const prefix = error instanceof ConfigError ? "evershield config" : `evershield ${command}`;
+    return { code: 2, stdout: "", stderr: `${prefix}: ${message}\n` };
+}
+/**
+ * Entry point without process side effects beyond the optional --output
+ * file: takes argv (minus node and the script path), returns what to print
+ * and the exit code.
+ */
+export async function run(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+        return { code: 0, stdout: HELP, stderr: "" };
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        return { code: 0, stdout: `${VERSION}\n`, stderr: "" };
+    }
+    if (command === "init") {
+        const unknown = rest.filter((arg) => arg !== "--force");
+        if (unknown.length > 0)
+            return usageError(`init: unexpected argument "${unknown[0]}"`);
+        try {
+            const { detection, written, skipped } = await runInit(process.cwd(), { force: rest.includes("--force") });
+            const lines = [
+                `evershield init · detected ${detection.framework} · build output ${detection.buildDir} · ${detection.packageManager}`,
+                ...written.map((file) => `  created  ${file}`),
+                ...skipped.map((file) => `  skipped  ${file} (exists; use --force to overwrite)`),
+                "",
+                "Next:",
+                `  1. Build, then try it locally:  npx evershield scan ${detection.buildDir}`,
+                "  2. Commit the workflow; every pull request is scanned and findings appear in the Security tab.",
+                "  3. Known-safe matches go in evershield.config.json under \"ignore\", each with a reason.",
+            ];
+            if (detection.framework === "unknown") {
+                lines.push("", `Could not detect a framework; edit the build step and path in .github/workflows/evershield.yml.`);
+            }
+            return { code: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+        }
+        catch (error) {
+            return failure("init", error);
+        }
+    }
+    if (command !== "scan" && command !== "audit" && command !== "surface") {
+        return usageError(`unknown command "${command}"`);
+    }
+    const options = parseCommonOptions(rest);
+    if ("code" in options)
+        return options;
+    if (command === "scan") {
+        const target = options.positionals[0];
+        if (target === undefined)
+            return usageError("scan: missing <dir>");
+        try {
+            const { config } = await loadConfig(options.configPath);
+            const gate = gateFor(options, config);
+            const scanned = await scanArtifact(target, options.adapter === undefined ? {} : { adapter: options.adapter });
+            const { kept, ignored } = applyIgnores(scanned.findings, config.ignore);
+            return await finish({ ...scanned, findings: kept, ignored: ignored.length }, gate, options);
+        }
+        catch (error) {
+            return failure("scan", error);
+        }
+    }
+    if (options.positionals.length > 0)
+        return usageError(`${command}: unexpected argument "${options.positionals[0]}"`);
+    if (command === "surface") {
+        try {
+            const { config, source } = await loadConfig(options.configPath);
+            if (config.surface === undefined) {
+                throw new ConfigError(source === null
+                    ? "surface needs a config file with a \"surface\" block (see docs/configuration.md)"
+                    : `${source} has no "surface" block (see docs/configuration.md)`);
+            }
+            const gate = gateFor(options, config);
+            const surfaced = await runSurface(config.surface);
+            if (surfaced.snapshotsEvaluated === 0) {
+                throw new Error(`no page could be evaluated, so nothing was audited:\n  ${surfaced.warnings.join("\n  ")}`);
+            }
+            const { kept, ignored } = applyIgnores(surfaced.findings, config.ignore);
+            return await finish({ ...surfaced, findings: kept, ignored: ignored.length }, gate, options);
+        }
+        catch (error) {
+            return failure("surface", error);
+        }
+    }
+    try {
+        const { config, source } = await loadConfig(options.configPath);
+        if (config.audit === undefined) {
+            throw new ConfigError(source === null
+                ? "audit needs a config file with an \"audit\" block (see docs/configuration.md)"
+                : `${source} has no "audit" block (see docs/configuration.md)`);
+        }
+        const gate = gateFor(options, config);
+        const audited = await runAudit(config.audit);
+        if (audited.responsesEvaluated === 0) {
+            // "No findings" would be a lie: nothing was looked at. Fail loudly.
+            throw new Error(`no response could be evaluated, so nothing was audited:\n  ${audited.warnings.join("\n  ")}`);
+        }
+        const { kept, ignored } = applyIgnores(audited.findings, config.ignore);
+        return await finish({ ...audited, findings: kept, ignored: ignored.length }, gate, options);
+    }
+    catch (error) {
+        return failure("audit", error);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+import type { AuditConfig } from "./audit/types.ts";
+import type { Finding } from "./index.ts";
+import type { SurfaceConfig } from "./surface/types.ts";
+import { type Gate } from "./report/index.ts";
+export interface IgnoreRule {
+    /** Rule id to ignore, or "*" for any rule. */
+    ruleId: string;
+    /** Glob over the evidence path, relative to the scan target. */
+    path?: string;
+    /** Substring that must appear in the finding's message or excerpt. */
+    match?: string;
+    /** Why this is safe. Required. */
+    reason: string;
+}
+export interface Config {
+    gate?: Partial<Gate>;
+    ignore: IgnoreRule[];
+    /** Layer 2 settings; `evershield audit` requires this block. */
+    audit?: AuditConfig;
+    /** Layer 3 settings; `evershield surface` requires this block. */
+    surface?: SurfaceConfig;
+}
+export declare const DEFAULT_CONFIG_FILE = "evershield.config.json";
+export declare class ConfigError extends Error {
+}
+/** Validate a parsed JSON value into a Config, with messages a human can act on. */
+export declare function parseConfig(raw: unknown, source: string): Config;
+/**
+ * Load the config file. An explicit path must exist; the default file is
+ * optional. Returns the source path alongside, for messages.
+ */
+export declare function loadConfig(explicitPath?: string): Promise<{
+    config: Config;
+    source: string | null;
+}>;
+/** Minimal glob: `**` spans directories, `*` and `?` stay within one segment. */
+export declare function globToRegExp(pattern: string): RegExp;
+/** Split findings into those kept and those an ignore rule accounts for. */
+export declare function applyIgnores(findings: Finding[], ignore: IgnoreRule[]): {
+    kept: Finding[];
+    ignored: Finding[];
+};