@aimarket/warden 0.8.2 → 0.13.0

package/dist/scan.d.ts

@@ -0,0 +1,177 @@
+import { type ClientKind, type ConfiguredServer, type DiscoveryEnv } from './scan-config.js';
+import { type FetchedServer } from './mcp-client.js';
+import { type HistorCheck } from './histor.js';
+import { type ToxicFlow } from './toxic-flow.js';
+import { type ClassifierOptions } from './classifier.js';
+import { type ToolChange } from './scan-lock.js';
+import type { Severity, ToolDef, WardenFinding, WardenPolicy, RulesetRef } from './types.js';
+export declare const SEVERITIES: Severity[];
+export interface ScanOptions {
+    configs: string[];
+    project: boolean;
+    clients?: ClientKind[];
+    cwd: string;
+    launch: boolean;
+    publicOnly: boolean;
+    timeoutMs: number;
+    concurrency: number;
+    policy: WardenPolicy;
+    lock?: string;
+    updateLock: boolean;
+    stateDir: string;
+    feed?: string;
+    feedKey?: string;
+    histor: boolean;
+    historUrl: string;
+    /** Opt-in meaning-based check; absent unless both --classifier-url and --classifier-model are given. */
+    classifier?: ClassifierOptions & {
+        blocks: boolean;
+    };
+    format: 'table' | 'json';
+    sarif?: string;
+    markdown?: string;
+    jsonFile?: string;
+    failOnError: boolean;
+    color: boolean;
+}
+export type ServerStatus = 'scanned' | 'launch-only' | 'blocked-at-launch' | 'error' | 'skipped';
+export interface HistorSummary {
+    /** What was asked about: an endpoint, or a stdio server's `npm:`/`pypi:` package. */
+    package?: string;
+    /** The package version HISTOR last observed in its sandbox. */
+    packageVersion?: string;
+    /** HISTOR's id for the server: what its feed takes in `watch=`. */
+    targetId?: string;
+    match?: string;
+    note?: string;
+    page?: string;
+    unchangedSince?: string;
+    changes?: number;
+    error?: string;
+    notSent?: string;
+}
+export interface ScanServerResult {
+    id: string;
+    key: string;
+    client: ClientKind;
+    source: string;
+    scope: 'user' | 'project';
+    transport: 'stdio' | 'sse' | 'http';
+    wrapped: boolean;
+    /** Display form of the launch: secrets in args and URLs are redacted. */
+    launch: string;
+    status: ServerStatus;
+    allow: boolean | null;
+    score?: number;
+    decidedBy?: string;
+    findings: WardenFinding[];
+    allowedTools: string[];
+    blockedTools: string[];
+    toolCount?: number;
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+    error?: string;
+    skipped?: string;
+    mtlDigest?: string;
+    mtlError?: string;
+    histor?: HistorSummary;
+    classifier?: {
+        model: string;
+        flagged: number;
+        error?: string;
+        incompleteTools?: string[];
+        retried?: number;
+    };
+    lock?: {
+        state: 'match' | 'drift' | 'missing' | 'updated' | 'unchanged' | 'refused';
+        changes?: ToolChange[];
+    };
+    /** The fetched definitions; kept for the Markdown diff and --update-lock, not printed in JSON. */
+    tools?: ToolDef[];
+}
+export interface ScanReport {
+    tool: 'warden-scan';
+    version: string;
+    scannedAt: string;
+    ruleset: RulesetRef;
+    policy: WardenPolicy;
+    launch: boolean;
+    sources: Array<{
+        path: string;
+        client: ClientKind;
+        scope: 'user' | 'project';
+        servers: number;
+        error?: string;
+    }>;
+    servers: ScanServerResult[];
+    lock?: {
+        path: string;
+        stale: string[];
+        written: boolean;
+    };
+    /**
+     * Per client: private data, outside text and an outbound channel among the servers it starts
+     * (toxic-flow.ts). Advisory: a flow never blocks and never changes the exit code.
+     */
+    flows: ToxicFlow[];
+    /** With --histor: a feed of changes to the servers HISTOR knows among these, for any feed reader. */
+    historWatch?: string;
+    summary: {
+        servers: number;
+        scanned: number;
+        allowed: number;
+        blocked: number;
+        errors: number;
+        skipped: number;
+        launchOnly: number;
+    };
+}
+export declare const SCAN_USAGE: string;
+export declare function parseScanArgs(argv: string[], env?: NodeJS.ProcessEnv): Promise<ScanOptions>;
+export declare class UsageRequested extends Error {
+    constructor();
+}
+/** A path segment or argument that looks like it carries a credential. */
+export declare function looksSecret(text: string): boolean;
+/** The launch line with credentials replaced, for terminals, reports and SARIF. */
+export declare function redactLaunch(server: ConfiguredServer): string;
+export declare function redactUrl(raw: string): string;
+/** The endpoint HISTOR may be asked about, or why it is not sent. */
+export declare function historEndpoint(raw: string): {
+    endpoint?: string;
+    reason?: string;
+};
+/**
+ * The npm or PyPI package a stdio launch runs, as HISTOR names it (`npm:<name>`,
+ * `pypi:<normalised name>`), or why it is not sent. Only a package from the public
+ * registry is named: a local path, a git or tarball URL, or a private registry
+ * (`--registry`, `--index-url`) stays on this machine. The version is not sent —
+ * the digest already tells HISTOR which of the versions it observed you run.
+ */
+export declare function historPackage(command: string, args: readonly string[]): {
+    package?: string;
+    reason?: string;
+};
+/**
+ * What HISTOR knows about a package beyond its tools: a name made to be taken for a popular one,
+ * and the marks of a stolen publishing token on the version it observed. All advisory.
+ */
+export declare function packageFindings(answer: HistorCheck): WardenFinding[];
+/**
+ * What the package did in HISTOR's sandbox (gVisor's own trace, decoy credentials, canary tool
+ * calls). Reading a decoy or writing where it would persist is the loud part; contacting its own
+ * API during a call is what API servers do and is not a finding, nor is loading .env from the
+ * working directory, which dotenv does for half the ecosystem.
+ */
+export declare function behaviourFindings(behaviour: Record<string, unknown> | undefined, version: string): WardenFinding[];
+export interface ScanDeps {
+    fetch?: (server: ConfiguredServer, opts: ScanOptions) => Promise<FetchedServer>;
+    historFetch?: typeof fetch;
+    now?: () => Date;
+    discovery?: Partial<DiscoveryEnv>;
+}
+export declare function runScan(opts: ScanOptions, deps?: ScanDeps): Promise<ScanReport>;
+export declare function exitCode(report: ScanReport, opts: Pick<ScanOptions, 'failOnError'>): number;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"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"}