@stsepelin/checktrail 0.1.0-alpha.1

package/dist/src/fastapi-runner.js

@@ -0,0 +1,84 @@
+export const fastapiRunner = String.raw `
+import asyncio, contextlib, importlib, json, sys
+from datetime import datetime, timezone
+from importlib.metadata import version, PackageNotFoundError
+
+def identity(value):
+    module = getattr(value, '__module__', None)
+    name = getattr(value, '__qualname__', None)
+    if not isinstance(module, str) or not isinstance(name, str):
+        raise ValueError('Unsupported callable identity')
+    return module + '.' + name
+
+async def capture(config):
+    from fastapi import FastAPI
+    from fastapi.routing import APIRoute, APIWebSocketRoute
+    from starlette.routing import Route, WebSocketRoute
+    app = getattr(importlib.import_module(config['module']), config['attribute'])
+    if not isinstance(app, FastAPI):
+        raise ValueError('Configured object is not a FastAPI application')
+    async with app.router.lifespan_context(app):
+        entries = []
+        indices = []
+        supported = 0
+        application = 0
+        for index, route in enumerate(app.routes):
+            if type(route) not in (APIRoute, APIWebSocketRoute, Route, WebSocketRoute):
+                continue
+            methods = sorted(route.methods) if isinstance(route, Route) else ['WEBSOCKET']
+            protocol = 'http' if isinstance(route, Route) else 'websocket'
+            if not methods:
+                continue
+            dependencies = []
+            if isinstance(route, (APIRoute, APIWebSocketRoute)):
+                application += 1
+                pending = list(route.dependant.dependencies)
+                visited = 0
+                while pending:
+                    dependency = pending.pop(0)
+                    visited += 1
+                    if visited > 1000:
+                        raise ValueError('Dependency inventory exceeds limit')
+                    dependencies.append(identity(dependency.call))
+                    pending[0:0] = dependency.dependencies
+            for method in methods:
+                indices.append(index)
+                key = 'HTTP ' + method + ' ' + route.path if protocol == 'http' else 'WEBSOCKET ' + route.path
+                entries.append({'key': key, 'attributes': {
+                    'protocol': protocol, 'method': method, 'path': route.path, 'handler': identity(route.endpoint),
+                    'name': route.name, 'dependencies': dependencies,
+                    'includeInSchema': bool(getattr(route, 'include_in_schema', False))
+                }})
+            supported += 1
+            if len(entries) > 20000:
+                raise ValueError('Route inventory exceeds limit')
+        return entries, indices, len(app.routes), supported, application
+
+try:
+    try:
+        versions = {'fastapi': version('fastapi'), 'starlette': version('starlette')}
+    except PackageNotFoundError:
+        json.dump({'unavailable': 'fastapi-runtime', 'reason': 'missing-package'}, sys.stdout)
+        sys.exit(3)
+    if versions != {'fastapi': '0.141.1', 'starlette': '1.6.0'}:
+        json.dump({'unavailable': 'fastapi-runtime', 'reason': 'unsupported-version'}, sys.stdout)
+        sys.exit(3)
+    config = json.loads(sys.argv[1])
+    with contextlib.redirect_stdout(sys.stderr):
+        entries, indices, total, supported, application = asyncio.run(capture(config))
+    json.dump({
+        'version': 1, 'versions': versions, 'totalRoutes': total, 'supportedRoutes': supported,
+        'applicationRoutes': application,
+        'entryRouteIndices': indices,
+        'runtime': {
+            'schemaVersion': 1, 'format': 'runtime-inventory',
+            'producer': {'name': 'checktrail.fastapi-routes', 'version': '1.0.0'},
+            'assembly': {'name': config['assembly'], 'environment': config['environment']},
+            'sourceFingerprint': sys.argv[2], 'capturedAt': datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z'),
+            'collections': [{'kind': 'routes', 'complete': supported == total, 'ordered': True, 'entries': entries}]
+        }
+    }, sys.stdout)
+except Exception as error:
+    print(type(error).__name__ + ': ' + str(error), file=sys.stderr)
+    sys.exit(2)
+`;

package/dist/src/fastapi.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { Check, Inventory, Project } from "./types.js";
+export declare const fastapiConfigSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    module: z.ZodString;
+    attribute: z.ZodString;
+    assembly: z.ZodString;
+    environment: z.ZodString;
+}, z.core.$strict>;
+export declare function fastapiCheck(source: Inventory, project: Project): Promise<Check>;

package/dist/src/fastapi.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { z } from "zod";
+import { readProjectFile } from "./inventory.js";
+import { fastapiRunner } from "./fastapi-runner.js";
+export const fastapiConfigSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    module: z
+        .string()
+        .regex(/^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$/)
+        .max(256),
+    attribute: z
+        .string()
+        .regex(/^[A-Za-z_]\w*$/)
+        .max(128),
+    assembly: z.string().min(1).max(256),
+    environment: z.string().min(1).max(256),
+});
+export async function fastapiCheck(source, project) {
+    const check = {
+        id: "python.fastapi-routes",
+        adapter: project.adapter,
+        project: project.path,
+        kind: "analysis",
+        parser: "fastapi-json",
+        scope: [],
+        commands: [],
+        reason: "Capture the configured FastAPI application's flat native route table after lifespan startup and reject exact duplicate HTTP/WebSocket routes.",
+    };
+    if (!project.files.includes("checktrail.fastapi.json")) {
+        check.unavailableReason =
+            "FastAPI route validation requires an explicit checktrail.fastapi.json application profile.";
+        return check;
+    }
+    const config = fastapiConfigSchema.parse(JSON.parse(await readProjectFile(source.root, path.posix.join(project.path, "checktrail.fastapi.json"))));
+    const modulePath = config.module.replaceAll(".", "/");
+    const candidates = [`${modulePath}.py`, `${modulePath}/__init__.py`].filter((file) => project.files.includes(file));
+    if (candidates.length !== 1) {
+        check.unavailableReason =
+            "FastAPI import entry must resolve to one inventoried local Python module or package.";
+        return check;
+    }
+    check.scope = candidates;
+    check.commands = [
+        {
+            executable: "python3",
+            args: ["-c", fastapiRunner, JSON.stringify(config), source.fingerprint],
+            cwd: project.path,
+            env: { PYTHONDONTWRITEBYTECODE: "1" },
+        },
+    ];
+    return check;
+}

package/dist/src/fetch-pack.d.ts

@@ -0,0 +1,16 @@
+import { type PackReference } from "./policy-pack.js";
+export interface FetchPackOptions {
+    url: string;
+    sha256: string;
+    output: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface FetchedPack {
+    schemaVersion: 1;
+    id: string;
+    version: string;
+    bytes: number;
+    reference: PackReference;
+}
+export declare function fetchPolicyPack(root: string, input: FetchPackOptions): Promise<FetchedPack>;

package/dist/src/fetch-pack.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { link, lstat, mkdtemp, open, realpath, rm } from "node:fs/promises";
+import { request } from "node:https";
+import path from "node:path";
+import { z } from "zod";
+import { withinRoot } from "./inventory.js";
+import { parsePolicyPack } from "./policy-pack.js";
+const optionsSchema = z.strictObject({
+    url: z.string().min(1).max(8192),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    output: z.string().min(1).max(4096),
+    timeoutMs: z.number().int().min(1).max(120_000).default(30_000),
+});
+async function download(url, timeoutMs, signal) {
+    if (signal?.aborted)
+        throw new Error("Policy pack download cancelled");
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
+            if (error) {
+                req.destroy();
+                reject(error);
+            }
+            else
+                resolve(Buffer.concat(chunks));
+        };
+        const cancel = () => finish(new Error("Policy pack download cancelled"));
+        const req = request(url, {
+            method: "GET",
+            agent: false,
+            rejectUnauthorized: true,
+            maxHeaderSize: 16 * 1024,
+            headers: { Accept: "application/json", "Accept-Encoding": "identity" },
+        }, (response) => {
+            response.on("error", () => finish(new Error("Policy pack transfer failed")));
+            if (response.statusCode !== 200) {
+                finish(new Error("Policy pack endpoint must return HTTP 200; redirects are not followed"));
+                return;
+            }
+            const length = response.headers["content-length"];
+            if ((length && (!/^\d+$/.test(length) || Number(length) > 64 * 1024)) ||
+                (response.headers["content-encoding"] &&
+                    response.headers["content-encoding"] !== "identity")) {
+                finish(new Error("Policy pack response exceeds limits or uses content encoding"));
+                return;
+            }
+            response.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > 64 * 1024)
+                    finish(new Error("Policy pack exceeds 64 KiB limit"));
+                else
+                    chunks.push(chunk);
+            });
+            response.on("end", () => {
+                if (!response.complete)
+                    finish(new Error("Policy pack transfer is incomplete"));
+                else
+                    finish();
+            });
+        });
+        const timer = setTimeout(() => finish(new Error("Policy pack download timed out")), timeoutMs);
+        req.on("error", () => finish(new Error("Policy pack HTTPS connection failed")));
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            cancel();
+        else
+            req.end();
+    });
+}
+export async function fetchPolicyPack(root, input) {
+    const { signal, ...provided } = input;
+    const parsed = optionsSchema.safeParse(provided);
+    if (!parsed.success)
+        throw new Error("Invalid policy pack download options");
+    const options = parsed.data;
+    let url;
+    try {
+        url = new URL(options.url);
+    }
+    catch {
+        throw new Error("Policy pack endpoint must be an absolute HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash)
+        throw new Error("Policy pack endpoint requires HTTPS without user information or a fragment");
+    const output = options.output;
+    if (path.isAbsolute(output) ||
+        path.posix.normalize(output) !== output ||
+        output.startsWith("../") ||
+        output === ".." ||
+        output === "." ||
+        !output.endsWith(".json") ||
+        [...output].some((character) => character === "\\" ||
+            character.charCodeAt(0) < 32 ||
+            character.charCodeAt(0) === 127))
+        throw new Error("Policy pack output must be a normalized relative JSON path");
+    const canonicalRoot = await realpath(root);
+    const parent = await withinRoot(canonicalRoot, path.dirname(output));
+    if (parent !== path.resolve(canonicalRoot, path.dirname(output)))
+        throw new Error("Policy pack output directories must not traverse symbolic links");
+    const destination = path.join(parent, path.basename(output));
+    try {
+        await lstat(destination);
+        throw new Error("Policy pack output already exists");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const bytes = await download(url, options.timeoutMs, signal);
+    if (createHash("sha256").update(bytes).digest("hex") !== options.sha256)
+        throw new Error("Policy pack integrity mismatch");
+    let pack;
+    try {
+        pack = parsePolicyPack(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes));
+    }
+    catch {
+        throw new Error("Downloaded policy pack is not valid UTF-8 policy JSON");
+    }
+    if (signal?.aborted)
+        throw new Error("Policy pack download cancelled");
+    const temporary = await mkdtemp(path.join(parent, ".checktrail-pack-"));
+    try {
+        const staged = path.join(temporary, "pack.json");
+        const handle = await open(staged, "wx", 0o600);
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (signal?.aborted)
+            throw new Error("Policy pack download cancelled");
+        // A hard link publishes complete bytes without replacing a concurrently created destination.
+        await link(staged, destination);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return {
+        schemaVersion: 1,
+        id: pack.id,
+        version: pack.version,
+        bytes: bytes.length,
+        reference: { path: output, sha256: options.sha256 },
+    };
+}

package/dist/src/finding-policy-schema.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+export declare const findingKeySchema: z.ZodObject<{
+    checkId: z.ZodString;
+    project: z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>;
+    ruleId: z.ZodString;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    level: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        note: "note";
+    }>;
+    messageHash: z.ZodString;
+}, z.core.$strict>;
+export declare const findingBaselineEntrySchema: z.ZodObject<{
+    checkId: z.ZodString;
+    project: z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>;
+    ruleId: z.ZodString;
+    file: z.ZodString;
+    line: z.ZodNumber;
+    level: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        note: "note";
+    }>;
+    messageHash: z.ZodString;
+    id: z.ZodString;
+    occurrences: z.ZodNumber;
+    kind: z.ZodEnum<{
+        baseline: "baseline";
+        exception: "exception";
+    }>;
+    owner: z.ZodString;
+    reason: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+export declare const findingBaselineSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    createdFrom: z.ZodObject<{
+        runId: z.ZodString;
+        sourceFingerprint: z.ZodString;
+        policyFingerprint: z.ZodString;
+    }, z.core.$strict>;
+    limits: z.ZodObject<{
+        maxEntries: z.ZodNumber;
+        maxExceptions: z.ZodNumber;
+    }, z.core.$strict>;
+    entries: z.ZodArray<z.ZodObject<{
+        checkId: z.ZodString;
+        project: z.ZodUnion<readonly [z.ZodLiteral<".">, z.ZodString]>;
+        ruleId: z.ZodString;
+        file: z.ZodString;
+        line: z.ZodNumber;
+        level: z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            note: "note";
+        }>;
+        messageHash: z.ZodString;
+        id: z.ZodString;
+        occurrences: z.ZodNumber;
+        kind: z.ZodEnum<{
+            baseline: "baseline";
+            exception: "exception";
+        }>;
+        owner: z.ZodString;
+        reason: z.ZodString;
+        expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type FindingBaseline = z.infer<typeof findingBaselineSchema>;
+export declare const findingComparisonSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    engineVersion: z.ZodString;
+    provenance: z.ZodLiteral<"finding-comparison">;
+    outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    validationOutcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    reason: z.ZodString;
+    sourceVerified: z.ZodBoolean;
+    baselineFingerprint: z.ZodString;
+    counts: z.ZodObject<{
+        current: z.ZodNumber;
+        new: z.ZodNumber;
+        matched: z.ZodNumber;
+        stale: z.ZodNumber;
+        expired: z.ZodNumber;
+        changed: z.ZodNumber;
+        unverified: z.ZodNumber;
+        expanded: z.ZodNumber;
+        modified: z.ZodNumber;
+    }, z.core.$strict>;
+    limitExceeded: z.ZodBoolean;
+    unaccountedFailures: z.ZodNumber;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            unverified: "unverified";
+            changed: "changed";
+            matched: "matched";
+            stale: "stale";
+            expired: "expired";
+        }>;
+        occurrences: z.ZodNumber;
+    }, z.core.$strict>>;
+    newFindingIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type FindingComparison = z.infer<typeof findingComparisonSchema>;
+export declare const findingComparisonSummarySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    engineVersion: z.ZodString;
+    provenance: z.ZodLiteral<"finding-comparison">;
+    outcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    reason: z.ZodString;
+    counts: z.ZodObject<{
+        current: z.ZodNumber;
+        new: z.ZodNumber;
+        matched: z.ZodNumber;
+        stale: z.ZodNumber;
+        expired: z.ZodNumber;
+        changed: z.ZodNumber;
+        unverified: z.ZodNumber;
+        expanded: z.ZodNumber;
+        modified: z.ZodNumber;
+    }, z.core.$strict>;
+    validationOutcome: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        incomplete: "incomplete";
+    }>;
+    sourceVerified: z.ZodBoolean;
+    baselineFingerprint: z.ZodString;
+    limitExceeded: z.ZodBoolean;
+    unaccountedFailures: z.ZodNumber;
+}, z.core.$strict>;

package/dist/src/finding-policy-schema.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+const hash = z.string().regex(/^[a-f0-9]{64}$/);
+const relative = z
+    .string()
+    .min(1)
+    .max(4096)
+    .regex(/^(?![A-Za-z]:)(?:(?!\.{1,2}\/)[^/\\\0]+\/)*(?!\.{1,2}$)[^/\\\0]+$/, "Expected a normalized relative file path");
+export const findingKeySchema = z.strictObject({
+    checkId: z.string().min(1).max(256),
+    project: z.union([z.literal("."), relative]),
+    ruleId: z.string().min(1).max(256),
+    file: relative,
+    line: z.number().int().positive(),
+    level: z.enum(["error", "warning", "note"]),
+    messageHash: hash,
+});
+export const findingBaselineEntrySchema = findingKeySchema.extend({
+    id: hash,
+    occurrences: z.number().int().positive().max(100_000),
+    kind: z.enum(["baseline", "exception"]),
+    owner: z.string().trim().min(1).max(256),
+    reason: z.string().trim().min(1).max(4096),
+    expiresAt: z.iso.datetime().optional(),
+});
+export const findingBaselineSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    createdFrom: z.strictObject({
+        runId: z.string(),
+        sourceFingerprint: z.string(),
+        policyFingerprint: z.string(),
+    }),
+    limits: z.strictObject({
+        maxEntries: z.number().int().nonnegative().max(10_000),
+        maxExceptions: z.number().int().nonnegative().max(10_000),
+    }),
+    entries: z.array(findingBaselineEntrySchema).max(10_000),
+});
+export const findingComparisonSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    engineVersion: z.string(),
+    provenance: z.literal("finding-comparison"),
+    outcome: z.enum(["passed", "failed", "incomplete"]),
+    validationOutcome: z.enum(["passed", "failed", "incomplete"]),
+    reason: z.string(),
+    sourceVerified: z.boolean(),
+    baselineFingerprint: hash,
+    counts: z.strictObject({
+        current: z.number().int().nonnegative(),
+        new: z.number().int().nonnegative(),
+        matched: z.number().int().nonnegative(),
+        stale: z.number().int().nonnegative(),
+        expired: z.number().int().nonnegative(),
+        changed: z.number().int().nonnegative(),
+        unverified: z.number().int().nonnegative(),
+        expanded: z.number().int().nonnegative(),
+        modified: z.number().int().nonnegative(),
+    }),
+    limitExceeded: z.boolean(),
+    unaccountedFailures: z.number().int().nonnegative(),
+    entries: z.array(z.strictObject({
+        id: hash,
+        status: z.enum(["matched", "stale", "expired", "changed", "unverified"]),
+        occurrences: z.number().int().nonnegative(),
+    })),
+    newFindingIds: z.array(hash),
+});
+export const findingComparisonSummarySchema = findingComparisonSchema.omit({
+    entries: true,
+    newFindingIds: true,
+});

package/dist/src/finding-policy.d.ts

@@ -0,0 +1,62 @@
+import { type FindingBaseline, type FindingComparison } from "./finding-policy-schema.js";
+export declare function projectFindingComparison(result: FindingComparison, detailed: boolean): {
+    schemaVersion: 1;
+    engineVersion: string;
+    provenance: "finding-comparison";
+    outcome: "passed" | "failed" | "incomplete";
+    validationOutcome: "passed" | "failed" | "incomplete";
+    reason: string;
+    sourceVerified: boolean;
+    baselineFingerprint: string;
+    counts: {
+        current: number;
+        new: number;
+        matched: number;
+        stale: number;
+        expired: number;
+        changed: number;
+        unverified: number;
+        expanded: number;
+        modified: number;
+    };
+    limitExceeded: boolean;
+    unaccountedFailures: number;
+    entries: {
+        id: string;
+        status: "unverified" | "changed" | "matched" | "stale" | "expired";
+        occurrences: number;
+    }[];
+    newFindingIds: string[];
+} | {
+    schemaVersion: 1;
+    engineVersion: string;
+    provenance: "finding-comparison";
+    outcome: "passed" | "failed" | "incomplete";
+    validationOutcome: "passed" | "failed" | "incomplete";
+    reason: string;
+    sourceVerified: boolean;
+    baselineFingerprint: string;
+    counts: {
+        current: number;
+        new: number;
+        matched: number;
+        stale: number;
+        expired: number;
+        changed: number;
+        unverified: number;
+        expanded: number;
+        modified: number;
+    };
+    limitExceeded: boolean;
+    unaccountedFailures: number;
+};
+export declare function createFindingBaseline(input: unknown, options: {
+    owner: string;
+    reason: string;
+    kind?: "baseline" | "exception";
+    expiresAt?: string;
+}): FindingBaseline;
+export declare function compareFindings(input: unknown, baselineInput: unknown, options?: {
+    now?: string;
+    previousBaseline?: unknown;
+}): FindingComparison;