@securitychecks/cli 0.1.1-rc.1

package/dist/lib.d.ts

@@ -0,0 +1,908 @@
+import { AuditResult, Finding, CollectorArtifact, Severity, CheckResult, Artifact } from '@securitychecks/collector';
+
+/**
+ * Audit API - Programmatic interface for running the staff check
+ *
+ * This module provides the core audit functionality that can be used by:
+ * - CLI commands
+ * - MCP server
+ * - Programmatic integration
+ *
+ * SECURITY NOTE: All audit functions require cloud API authentication.
+ * Detection logic runs server-side to protect IP.
+ * See: docs/POST_MORTEM_001_ENGINE_EXPOSURE.md
+ */
+
+interface AuditOptions {
+    /** Target path to audit (default: current directory) */
+    targetPath?: string;
+    /** Only run specific invariant checks by ID */
+    only?: string[];
+    /** Skip specific invariant checks by ID */
+    skip?: string[];
+}
+/**
+ * Run the full staff check audit
+ *
+ * This is the main programmatic API for running the staff check.
+ * It performs two steps:
+ * 1. Collect artifacts from the target codebase (facts)
+ * 2. Send to cloud API for evaluation (findings)
+ *
+ * SECURITY: Detection logic runs server-side to protect IP.
+ * An API key is required. Get one at https://securitychecks.ai/dashboard/settings/api-keys
+ *
+ * @example
+ * ```ts
+ * import { audit } from '@securitychecks/cli';
+ *
+ * // Requires SECURITYCHECKS_API_KEY environment variable
+ * const result = await audit({
+ *   targetPath: '/path/to/codebase',
+ *   only: ['WEBHOOK.IDEMPOTENT'],
+ * });
+ *
+ * console.log(result.summary);
+ * ```
+ */
+declare function audit(options?: AuditOptions): Promise<AuditResult>;
+
+/**
+ * Schema Version Compatibility
+ *
+ * Ensures CLI can consume artifacts from compatible collector versions.
+ *
+ * The schema version follows semver:
+ * - MAJOR: Breaking changes (fields removed, types changed)
+ * - MINOR: Additive changes (new optional fields)
+ * - PATCH: Bug fixes, clarifications
+ *
+ * CLI declares a supported range, collector emits current version.
+ */
+/**
+ * The schema version range this CLI version supports.
+ *
+ * Format: "^MAJOR.MINOR.x" - compatible with any version that has:
+ * - Same MAJOR version (no breaking changes)
+ * - Same or higher MINOR version (may have new optional fields)
+ *
+ * When updating:
+ * - Bump MINOR when CLI starts using new optional fields
+ * - Bump MAJOR when CLI requires breaking schema changes
+ */
+declare const SUPPORTED_SCHEMA_RANGE: {
+    minMajor: number;
+    minMinor: number;
+    maxMajor: number;
+};
+interface SchemaValidationResult {
+    valid: boolean;
+    artifactVersion: string;
+    currentVersion: string;
+    error?: string;
+    remediation?: string;
+}
+/**
+ * Validate that an artifact's schema version is compatible with this CLI.
+ *
+ * Compatibility rules:
+ * - Artifact MAJOR must equal CLI's supported MAJOR (breaking changes)
+ * - Artifact MINOR must be >= CLI's minMinor (additive features)
+ * - Pre-1.0.0 artifacts (missing schemaVersion) are assumed "1.0.0"
+ */
+declare function validateSchemaVersion(artifactSchemaVersion?: string): SchemaValidationResult;
+/**
+ * Get the current collector schema version
+ */
+declare function getCurrentSchemaVersion(): string;
+
+/**
+ * Deterministic Error Codes for SecurityChecks CLI
+ *
+ * Format: SC_<CATEGORY>_<NUMBER>
+ *
+ * Categories:
+ * - CONFIG: Configuration errors
+ * - PARSE: Parsing/syntax errors
+ * - CHECK: Checker execution errors
+ * - IO: File system / network errors
+ * - CLI: Command line argument errors
+ */
+declare const ErrorCodes: {
+    readonly CONFIG_NOT_FOUND: "SC_CONFIG_001";
+    readonly CONFIG_INVALID: "SC_CONFIG_002";
+    readonly CONFIG_SCHEMA_ERROR: "SC_CONFIG_003";
+    readonly PARSE_TYPESCRIPT_ERROR: "SC_PARSE_101";
+    readonly PARSE_FILE_NOT_FOUND: "SC_PARSE_102";
+    readonly PARSE_UNSUPPORTED_SYNTAX: "SC_PARSE_103";
+    readonly CHECK_EXECUTION_ERROR: "SC_CHECK_201";
+    readonly CHECK_TIMEOUT: "SC_CHECK_202";
+    readonly CHECK_INVARIANT_NOT_FOUND: "SC_CHECK_203";
+    readonly IO_READ_ERROR: "SC_IO_301";
+    readonly IO_WRITE_ERROR: "SC_IO_302";
+    readonly IO_PERMISSION_DENIED: "SC_IO_303";
+    readonly IO_PATH_NOT_FOUND: "SC_IO_304";
+    readonly CLI_INVALID_ARGUMENT: "SC_CLI_401";
+    readonly CLI_MISSING_ARGUMENT: "SC_CLI_402";
+    readonly CLI_UNKNOWN_COMMAND: "SC_CLI_403";
+    readonly ARTIFACT_NOT_FOUND: "SC_ARTIFACT_501";
+    readonly ARTIFACT_INVALID: "SC_ARTIFACT_502";
+    readonly ARTIFACT_VERSION_MISMATCH: "SC_ARTIFACT_503";
+    readonly CLOUD_AUTH_FAILED: "SC_CLOUD_601";
+    readonly CLOUD_PERMISSION_DENIED: "SC_CLOUD_602";
+    readonly CLOUD_NOT_FOUND: "SC_CLOUD_603";
+    readonly CLOUD_RATE_LIMITED: "SC_CLOUD_604";
+    readonly CLOUD_API_ERROR: "SC_CLOUD_605";
+    readonly CLOUD_NETWORK_ERROR: "SC_CLOUD_606";
+    readonly CLOUD_INVALID_API_KEY: "SC_CLOUD_607";
+    readonly AUTH_REQUIRED: "SC_CLOUD_608";
+    readonly OFFLINE_NOT_SUPPORTED: "SC_CLOUD_609";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * User-friendly error messages for each error code
+ */
+declare const ErrorMessages: Record<ErrorCode, string>;
+/**
+ * Remediation guidance for each error code
+ * Helps users understand what to do when they encounter an error.
+ */
+declare const ErrorRemediation: Record<ErrorCode, string>;
+/**
+ * Structured CLI Error with deterministic error code
+ */
+declare class CLIError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: unknown;
+    readonly cause?: Error;
+    constructor(code: ErrorCode, message?: string, options?: {
+        details?: unknown;
+        cause?: Error;
+    });
+    /**
+     * Get remediation guidance for this error
+     */
+    getRemediation(): string;
+    /**
+     * Format error for user display
+     */
+    toUserString(verbose?: boolean): string;
+    /**
+     * Format error with remediation for user display
+     */
+    toUserStringWithRemediation(): string;
+    /**
+     * Format error for JSON output
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Check if an error is a CLIError
+ */
+declare function isCLIError(error: unknown): error is CLIError;
+/**
+ * Wrap an unknown error in a CLIError
+ */
+declare function wrapError(error: unknown, code: ErrorCode, message?: string): CLIError;
+
+/**
+ * CI Environment Detection
+ *
+ * Detects CI/CD environment and extracts relevant context
+ * (branch, commit SHA, PR number) for proper scan association.
+ */
+interface CIContext {
+    /** CI provider name */
+    provider: 'github-actions' | 'gitlab-ci' | 'circleci' | 'jenkins' | 'unknown';
+    /** Git branch name */
+    branch?: string;
+    /** Git commit SHA */
+    commitSha?: string;
+    /** Pull/Merge request number */
+    prNumber?: number;
+    /** Repository name (owner/repo) */
+    repository?: string;
+    /** Whether this is a PR/MR event */
+    isPullRequest: boolean;
+}
+
+/**
+ * Cloud Evaluation Client
+ *
+ * Sends artifacts to the cloud API for async server-side evaluation.
+ * Artifacts are stored in R2 and processed by Fly.io workers.
+ *
+ * Architecture:
+ * 1. CLI collects artifact locally (code never leaves)
+ * 2. Artifact sent to /api/v1/evaluate, stored in R2
+ * 3. Server queues QStash job for Fly.io worker
+ * 4. CLI polls /api/v1/scans/{id} until complete
+ * 5. Findings returned to CLI for display
+ */
+
+interface CloudEvaluateOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Cloud API base URL */
+    baseUrl: string;
+    /** Specific invariants to run (default: all) */
+    invariants?: string[];
+    /** Invariants to skip */
+    skip?: string[];
+    /** Minimum severity to return */
+    severity?: 'P0' | 'P1' | 'P2';
+    /** Project slug for scan association */
+    projectSlug?: string;
+    /** Timeout in ms (default: 300000 = 5 min) */
+    timeout?: number;
+    /** Poll interval in ms (default: 2000 = 2s) */
+    pollInterval?: number;
+    /** Progress callback */
+    onProgress?: EvaluationProgressCallback;
+    /** CI context (auto-detected if not provided) */
+    ciContext?: CIContext | null;
+}
+interface CloudEvaluateResult {
+    findings: Finding[];
+    stats: {
+        invariantsRun: number;
+        patternsRun: number;
+        findingsCount: number;
+        executionMs: number;
+    };
+    usage: {
+        scansUsed: number;
+        scansRemaining: number;
+    };
+}
+/** Scan status from API */
+type ScanStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+/** Progress callback for evaluation */
+type EvaluationProgressCallback = (info: {
+    status: ScanStatus;
+    message?: string;
+}) => void;
+/**
+ * Check if cloud evaluation is available
+ */
+declare function isCloudEvalAvailable(apiKey?: string): boolean;
+/**
+ * Evaluate artifact via cloud API (async with polling)
+ *
+ * @param artifact The artifact to evaluate
+ * @param options Evaluation options
+ * @throws Error if evaluation fails or times out
+ */
+declare function evaluateCloud(artifact: CollectorArtifact, options: CloudEvaluateOptions): Promise<CloudEvaluateResult>;
+/**
+ * Check cloud API health
+ */
+declare function checkCloudHealth(baseUrl: string): Promise<boolean>;
+/**
+ * Get available invariants from cloud API
+ */
+declare function getCloudInvariants(baseUrl: string, apiKey: string): Promise<Array<{
+    id: string;
+    name: string;
+    description: string;
+    severity: string;
+}>>;
+
+/**
+ * Stable Finding ID Generation
+ *
+ * Generates deterministic, stable IDs for findings that survive:
+ * - Re-runs
+ * - Ordering changes
+ * - Remediation/message tweaks
+ * - Minor code refactors
+ *
+ * IDs are NOT stable across:
+ * - Moving code to different files
+ * - Renaming functions (these are legitimately different anchors)
+ *
+ * Format: `${invariantId}:${hash}` (e.g., WEBHOOK.IDEMPOTENT:9c31f0a2b4d1)
+ */
+
+/**
+ * Extract the identity payload for a finding.
+ * This is what gets hashed to produce the findingId.
+ */
+declare function extractIdentityPayload(finding: Finding): Record<string, string>;
+/**
+ * Generate a stable findingId for a finding.
+ *
+ * @example
+ * const id = generateFindingId(finding);
+ * // "WEBHOOK.IDEMPOTENT:9c31f0a2b4d1"
+ */
+declare function generateFindingId(finding: Finding): string;
+/**
+ * Add findingId to a finding (mutates the finding).
+ * Returns the same finding for chaining.
+ */
+declare function attachFindingId<T extends Finding>(finding: T): T & {
+    findingId: string;
+};
+/**
+ * Add findingIds to all findings in a list.
+ */
+declare function attachFindingIds<T extends Finding>(findings: T[]): (T & {
+    findingId: string;
+})[];
+
+/**
+ * Baseline and Waiver Schema Versions
+ *
+ * These versions are CLI-level (separate from collector artifact schema).
+ * Bump these when the storage format changes.
+ */
+declare const BASELINE_SCHEMA_VERSION = "1.0.0";
+declare const WAIVER_SCHEMA_VERSION = "1.1.0";
+declare const WAIVER_REASON_KEYS: readonly ["false_positive", "acceptable_risk", "will_fix_later", "not_applicable", "other"];
+type WaiverReasonKey = typeof WAIVER_REASON_KEYS[number];
+/**
+ * A baseline entry represents a known finding that should not fail CI.
+ * Baselines are used to adopt scheck incrementally on existing codebases.
+ */
+interface BaselineEntry {
+    /** Stable finding ID (invariantId:hash) */
+    findingId: string;
+    /** The invariant this finding belongs to */
+    invariantId: string;
+    /** File where the finding was detected */
+    file: string;
+    /** Symbol (function/class name) if available */
+    symbol?: string;
+    /** When this was first added to baseline */
+    createdAt: string;
+    /** When this was last seen in a run */
+    lastSeenAt: string;
+    /** Optional notes explaining why this is baselined */
+    notes?: string;
+}
+/**
+ * The baseline file format.
+ */
+interface BaselineFile {
+    /** Schema version for baseline file format */
+    schemaVersion: string;
+    /** CLI version that generated this file */
+    toolVersion: string;
+    /** Collector schema version used when generating findings */
+    collectorSchemaVersion?: string;
+    /** Tool identifier (e.g., "@securitychecks/cli@0.1.0") */
+    generatedBy: string;
+    /** When the baseline was last updated (UTC ISO date) */
+    updatedAt: string;
+    /** Baseline entries keyed by findingId for O(1) lookup */
+    entries: Record<string, BaselineEntry>;
+}
+/**
+ * A waiver temporarily suppresses a finding.
+ * Unlike baselines, waivers expire and require explicit justification.
+ */
+interface WaiverEntry {
+    /** Stable finding ID (invariantId:hash) */
+    findingId: string;
+    /** The invariant this waiver applies to */
+    invariantId: string;
+    /** File where the finding was detected */
+    file: string;
+    /** Symbol (function/class name) if available */
+    symbol?: string;
+    /** Structured waiver reason (optional; aligns with web UI) */
+    reasonKey?: WaiverReasonKey;
+    /** Why this is being waived (required) */
+    reason: string;
+    /** Who created the waiver */
+    owner: string;
+    /** When the waiver expires (ISO date) */
+    expiresAt: string;
+    /** When the waiver was created */
+    createdAt: string;
+}
+/**
+ * The waiver file format.
+ */
+interface WaiverFile {
+    /** Schema version for waiver file format */
+    schemaVersion: string;
+    /** CLI version that generated this file */
+    toolVersion: string;
+    /** Tool identifier (e.g., "@securitychecks/cli@0.1.0") */
+    generatedBy: string;
+    /** When the waiver file was last updated (UTC ISO date) */
+    updatedAt: string;
+    /** Waiver entries keyed by findingId */
+    entries: Record<string, WaiverEntry>;
+}
+
+/**
+ * Baseline and Waiver Storage
+ *
+ * Handles loading, saving, and managing baseline/waiver files.
+ * Files are stored in `.scheck/` directory.
+ */
+
+/**
+ * Load the baseline file, creating an empty one if it doesn't exist.
+ */
+declare function loadBaseline(rootPath: string): Promise<BaselineFile>;
+/**
+ * Save the baseline file with deterministic ordering.
+ */
+declare function saveBaseline(rootPath: string, baseline: BaselineFile, collectorSchemaVersion?: string): Promise<void>;
+/**
+ * Add findings to the baseline.
+ * Returns the number of new entries added.
+ */
+declare function addToBaseline(baseline: BaselineFile, findings: Finding[], notes?: string): number;
+/**
+ * Check if a finding is in the baseline.
+ */
+declare function isInBaseline(baseline: BaselineFile, finding: Finding): boolean;
+/**
+ * Remove stale entries that haven't been seen in a certain number of days.
+ * Returns the number of entries removed.
+ */
+declare function pruneBaseline(baseline: BaselineFile, staleDays?: number): number;
+/**
+ * Load the waiver file, creating an empty one if it doesn't exist.
+ */
+declare function loadWaivers(rootPath: string): Promise<WaiverFile>;
+/**
+ * Save the waiver file with deterministic ordering.
+ */
+declare function saveWaivers(rootPath: string, waivers: WaiverFile): Promise<void>;
+/**
+ * Add a waiver for a finding.
+ */
+declare function addWaiver(waivers: WaiverFile, finding: Finding, options: {
+    reason: string;
+    reasonKey?: WaiverEntry['reasonKey'];
+    owner: string;
+    expiresInDays: number;
+}): WaiverEntry;
+/**
+ * Check if a finding has a valid (non-expired) waiver.
+ * Returns the waiver if valid, undefined if expired or not found.
+ */
+declare function getValidWaiver(waivers: WaiverFile, finding: Finding): WaiverEntry | undefined;
+/**
+ * Remove expired waivers from the file.
+ * Returns the number of waivers removed.
+ */
+declare function pruneExpiredWaivers(waivers: WaiverFile): number;
+/**
+ * Get all waivers that are about to expire (within N days).
+ */
+declare function getExpiringWaivers(waivers: WaiverFile, withinDays?: number): WaiverEntry[];
+
+/**
+ * Baseline and Waiver Matching
+ *
+ * Applies baselines and waivers to findings, categorizing them for CI decisions.
+ */
+
+/**
+ * A finding with its baseline/waiver status resolved.
+ */
+interface CategorizedFinding extends Finding {
+    findingId: string;
+    /** Whether this finding is in the baseline */
+    isBaselined: boolean;
+    /** Active waiver if present */
+    waiver?: WaiverEntry;
+    /** Whether this finding should fail CI */
+    shouldFail: boolean;
+}
+/**
+ * Result of categorizing findings.
+ */
+interface CategorizationResult {
+    /** All findings with status */
+    all: CategorizedFinding[];
+    /** New findings not in baseline (may fail CI) */
+    new: CategorizedFinding[];
+    /** Findings in baseline (won't fail CI) */
+    baselined: CategorizedFinding[];
+    /** Findings with active waivers (won't fail CI) */
+    waived: CategorizedFinding[];
+    /** Summary counts */
+    counts: {
+        total: number;
+        new: number;
+        baselined: number;
+        waived: number;
+        willFail: number;
+    };
+}
+/**
+ * Categorize findings against baseline and waivers.
+ *
+ * @param findings - Raw findings from checkers
+ * @param baseline - Loaded baseline file
+ * @param waivers - Loaded waiver file
+ * @param failSeverities - Which severities should fail CI (default: P0, P1)
+ */
+declare function categorizeFindings(findings: Finding[], baseline: BaselineFile, waivers: WaiverFile, failSeverities?: Severity[]): CategorizationResult;
+/**
+ * Determine CI exit status based on categorized findings.
+ *
+ * @returns 0 for success, 1 for failure
+ */
+declare function getCIExitCode(result: CategorizationResult): number;
+/**
+ * Get a summary message for CI output.
+ */
+declare function getCISummary(result: CategorizationResult): string;
+/**
+ * Detect and handle findingId collisions.
+ * Returns findings with unique IDs (appending :a, :b, etc. if needed).
+ *
+ * This is a defensive measure - collisions should be extremely rare with
+ * 12 hex chars of SHA-256, but we define the behavior explicitly.
+ */
+declare function resolveCollisions(findings: Finding[]): (Finding & {
+    findingId: string;
+})[];
+/**
+ * Check if there are any findingId collisions in a set of findings.
+ * Returns true if collisions exist.
+ */
+declare function hasCollisions(findings: Finding[]): boolean;
+
+/**
+ * Finding Correlation Engine
+ *
+ * Correlates findings across invariants to detect compounding risks.
+ * Multiple findings on the same code path often compound each other,
+ * creating worse outcomes than the sum of their parts.
+ *
+ * Key concepts:
+ * - Correlated findings: Multiple findings sharing a code path
+ * - Compounding risk: Combined severity is higher than individual
+ * - Attack path: Narrative of how findings chain together
+ *
+ * Example:
+ *   Route: POST /api/webhooks/stripe
+ *   ├── WEBHOOK.IDEMPOTENT: ✗ No idempotency check
+ *   ├── TRANSACTION.POST_COMMIT: ✗ Email inside transaction
+ *   └── Combined: If replayed, sends duplicate emails AND inconsistent DB
+ */
+
+interface CorrelatedFinding {
+    /** The primary finding (highest severity) */
+    primary: Finding;
+    /** Related findings on the same code path */
+    related: Finding[];
+    /** Shared context between findings */
+    sharedContext: SharedContext;
+    /** How the findings compound each other */
+    compoundingEffect: CompoundingEffect;
+    /** Adjusted severity based on correlation */
+    adjustedSeverity: Severity;
+    /** Attack path narrative */
+    attackPath?: AttackPath;
+}
+interface SharedContext {
+    /** Common file */
+    file?: string;
+    /** Common function */
+    functionName?: string;
+    /** Common route (if applicable) */
+    route?: string;
+    /** Shared call chain */
+    callChain?: string[];
+    /** Number of findings in this correlation */
+    findingCount: number;
+}
+interface CompoundingEffect {
+    /** Description of how findings compound */
+    description: string;
+    /** Risk multiplier (1.0 = no change, 2.0 = double risk) */
+    riskMultiplier: number;
+    /** Signals explaining the compounding */
+    signals: string[];
+}
+interface AttackPath {
+    /** Title of the attack path */
+    title: string;
+    /** Step-by-step narrative */
+    steps: AttackStep[];
+    /** Overall exploitability */
+    exploitability: 'easy' | 'medium' | 'hard';
+    /** Impact level */
+    impact: 'low' | 'medium' | 'high' | 'critical';
+    /** Time window (if applicable) */
+    timeWindow?: string;
+}
+interface AttackStep {
+    /** Step number */
+    step: number;
+    /** Description of this step */
+    description: string;
+    /** Which finding enables this step */
+    invariantId: string;
+    /** File/line reference */
+    location?: {
+        file: string;
+        line: number;
+    };
+}
+interface CorrelationResult {
+    /** All correlated finding groups */
+    correlations: CorrelatedFinding[];
+    /** Statistics */
+    stats: {
+        totalFindings: number;
+        correlatedFindings: number;
+        correlationGroups: number;
+        severityEscalations: number;
+    };
+}
+/**
+ * Correlate findings to detect compounding risks
+ */
+declare function correlateFindings(results: CheckResult[], artifact: Artifact): CorrelationResult;
+/**
+ * Format a correlated finding for display
+ */
+declare function formatCorrelatedFinding(correlation: CorrelatedFinding): string;
+/**
+ * Format correlation statistics
+ */
+declare function formatCorrelationStats(result: CorrelationResult): string;
+
+/**
+ * Correlation Telemetry
+ *
+ * Reports correlation data to the SecurityChecks SaaS.
+ * This builds the data moat around which invariant combinations
+ * actually compound risk in production codebases.
+ */
+
+interface CorrelationTelemetryConfig {
+    enabled: boolean;
+    endpoint?: string;
+    apiKey?: string;
+    timeout?: number;
+}
+/**
+ * Report correlation results to the SaaS
+ */
+declare function reportCorrelations(result: CorrelationResult, config: CorrelationTelemetryConfig, framework?: string): Promise<{
+    success: boolean;
+    stored?: number;
+    errors?: number;
+}>;
+/**
+ * Report feedback on a correlation (user marking as accurate/inaccurate)
+ */
+declare function reportCorrelationFeedback(requestId: string, wasAccurate: boolean, reason?: string, config?: CorrelationTelemetryConfig): Promise<boolean>;
+
+/**
+ * Anonymous Telemetry
+ *
+ * Reports aggregate scan statistics to the SecurityChecks SaaS.
+ * NO source code, NO file paths, NO PII - just patterns and numbers.
+ *
+ * This data powers:
+ * - Framework-specific calibration
+ * - Pattern effectiveness tracking
+ * - Invariant impact analysis
+ */
+
+interface TelemetryConfig {
+    enabled: boolean;
+    endpoint?: string;
+    apiKey?: string;
+    timeout?: number;
+}
+interface ScanTelemetry {
+    scanId: string;
+    codebase: {
+        filesScanned: number;
+        servicesCount: number;
+        linesOfCode?: number;
+    };
+    frameworks: string[];
+    findings: {
+        byInvariant: Record<string, number>;
+        byPriority: {
+            P0: number;
+            P1: number;
+            P2: number;
+        };
+        total: number;
+    };
+    correlation?: {
+        groups: number;
+        escalations: number;
+        correlatedFindings: number;
+    };
+    calibration?: {
+        calibrated: number;
+        suppressed: number;
+    };
+    patterns?: {
+        applied: number;
+        findings: number;
+    };
+    meta: {
+        duration?: number;
+        clientVersion: string;
+        mode?: 'ci' | 'manual' | 'watch';
+        ciProvider?: string;
+    };
+    baseline?: {
+        size: number;
+        waivers: number;
+        newFindings: number;
+    };
+    feedback?: {
+        waivedCount: number;
+        waiverReasons: Record<string, number>;
+        baselinedCount: number;
+    };
+}
+/**
+ * Build telemetry data from scan results
+ */
+declare function buildTelemetry(result: AuditResult, options: {
+    filesScanned: number;
+    frameworks: string[];
+    correlation?: CorrelationResult;
+    categorization?: CategorizationResult;
+    calibratedCount?: number;
+    suppressedCount?: number;
+    patternsApplied?: number;
+    patternFindings?: number;
+    mode?: 'ci' | 'manual' | 'watch';
+    baselineSize?: number;
+    waiversCount?: number;
+}): ScanTelemetry;
+/**
+ * Report telemetry to the SaaS
+ */
+declare function reportTelemetry(telemetry: ScanTelemetry, config: TelemetryConfig): Promise<boolean>;
+/**
+ * Check if telemetry is opt-out
+ */
+declare function isTelemetryDisabled(): boolean;
+
+/**
+ * Calibration API Client
+ *
+ * "The SaaS advises. The local tool decides."
+ *
+ * This module handles communication with the SecurityChecks Calibration API.
+ * The API provides confidence tuning based on aggregate data from many codebases.
+ *
+ * Key principles:
+ * - No source code is ever sent (only patterns and metadata)
+ * - API suggestions are advisory only
+ * - Local tool retains veto power via minConfidence threshold
+ * - Fails safely to local-only mode on network errors
+ */
+
+interface AggregateCalibrationConfig {
+    enabled: boolean;
+    endpoint?: string;
+    apiKey?: string;
+    timeout?: number;
+    cacheEnabled?: boolean;
+}
+interface FrameworkBaseline {
+    framework: string;
+    avgFindings: number;
+    avgP0: number;
+    avgP1: number;
+    avgP2: number;
+    scansAnalyzed: number;
+    confidence: 'high' | 'medium' | 'low';
+}
+interface InvariantStats {
+    invariantId: string;
+    avgPerScan: number;
+    hitRate: number;
+    p0Rate: number;
+    p1Rate: number;
+    p2Rate: number;
+}
+interface PatternStats {
+    patternId: string;
+    framework: string | null;
+    accuracy: number | null;
+    matchesPerScan: number;
+    confidence: 'high' | 'medium' | 'low';
+}
+interface CorrelationStats {
+    ruleId: string;
+    accuracy: number | null;
+    escalationRate: number | null;
+    isVerified: boolean;
+}
+interface AggregateCalibrationData {
+    version: string;
+    generatedAt: string;
+    frameworks: FrameworkBaseline[];
+    invariants: InvariantStats[];
+    patterns: PatternStats[];
+    correlations: CorrelationStats[];
+    meta: {
+        totalScansAnalyzed: number;
+        lastUpdated: string | null;
+    };
+}
+interface AggregateCalibrationResult {
+    data: AggregateCalibrationData | null;
+    fromCache: boolean;
+    error?: string;
+}
+/**
+ * Fetch aggregate calibration data for the specified frameworks
+ */
+declare function fetchAggregateCalibration(frameworks: string[], config: AggregateCalibrationConfig): Promise<AggregateCalibrationResult>;
+/**
+ * Clear the aggregate calibration cache
+ */
+declare function clearAggregateCache(): void;
+/**
+ * Get the framework baseline for comparison
+ */
+declare function getFrameworkBaseline(calibration: AggregateCalibrationData, framework: string): FrameworkBaseline | undefined;
+/**
+ * Check if a pattern should be skipped due to low accuracy
+ */
+declare function shouldSkipPattern(calibration: AggregateCalibrationData, patternId: string, framework?: string, accuracyThreshold?: number): boolean;
+/**
+ * Get patterns that should be skipped for a framework
+ */
+declare function getSkippedPatterns(calibration: AggregateCalibrationData, framework?: string, accuracyThreshold?: number): string[];
+/**
+ * Get correlation rules with high confidence
+ */
+declare function getVerifiedCorrelations(calibration: AggregateCalibrationData): CorrelationStats[];
+/**
+ * Calculate relative finding severity based on framework baseline
+ */
+declare function calculateRelativeSeverity(findingCount: number, baseline: FrameworkBaseline, type?: 'total' | 'P0' | 'P1' | 'P2'): 'below_average' | 'average' | 'above_average' | 'critical';
+/**
+ * Generate calibration summary for output
+ */
+declare function formatAggregateCalibrationSummary(calibration: AggregateCalibrationData, frameworks: string[], findings: {
+    P0: number;
+    P1: number;
+    P2: number;
+    total: number;
+}): string;
+/**
+ * Check if aggregate calibration is disabled via environment
+ */
+declare function isAggregateCalibrationDisabled(): boolean;
+
+/**
+ * Staff Engineer Templates
+ *
+ * Shared, stable UX helpers used by:
+ * - CLI output (human-readable prompts)
+ * - MCP adapters (Claude Code, etc.)
+ *
+ * Keep these centralized to avoid drift across integration surfaces.
+ */
+type TestFramework = 'jest' | 'vitest' | 'playwright' | (string & {});
+type InvariantLike = {
+    id: string;
+    name: string;
+    requiredProof?: string;
+};
+/**
+ * Returns the "A staff engineer would ask..." question for each invariant.
+ * These are the probing questions that senior engineers ask in code review.
+ */
+declare function getStaffQuestion(invariantId: string): string | null;
+declare function generateTestSkeleton(invariant: InvariantLike | null | undefined, framework: TestFramework, context?: string): string;
+
+export { type AggregateCalibrationConfig, type AggregateCalibrationData, type AggregateCalibrationResult, type AttackPath, type AttackStep, type AuditOptions, BASELINE_SCHEMA_VERSION, type BaselineEntry, type BaselineFile, CLIError, type CategorizationResult, type CategorizedFinding, type CloudEvaluateOptions, type CloudEvaluateResult, type CompoundingEffect, type CorrelatedFinding, type CorrelationResult, type CorrelationStats, type CorrelationTelemetryConfig, type ErrorCode, ErrorCodes, ErrorMessages, ErrorRemediation, type EvaluationProgressCallback, type FrameworkBaseline, type InvariantLike, type InvariantStats, type PatternStats, SUPPORTED_SCHEMA_RANGE, type ScanTelemetry, type SchemaValidationResult, type SharedContext, type TelemetryConfig, type TestFramework, WAIVER_SCHEMA_VERSION, type WaiverEntry, type WaiverFile, addToBaseline, addWaiver, attachFindingId, attachFindingIds, audit, buildTelemetry, calculateRelativeSeverity, categorizeFindings, checkCloudHealth, clearAggregateCache, correlateFindings, evaluateCloud, extractIdentityPayload, fetchAggregateCalibration, formatAggregateCalibrationSummary, formatCorrelatedFinding, formatCorrelationStats, generateFindingId, generateTestSkeleton, getCIExitCode, getCISummary, getCloudInvariants, getCurrentSchemaVersion, getExpiringWaivers, getFrameworkBaseline, getSkippedPatterns, getStaffQuestion, getValidWaiver, getVerifiedCorrelations, hasCollisions, isAggregateCalibrationDisabled, isCLIError, isCloudEvalAvailable, isInBaseline, isTelemetryDisabled, loadBaseline, loadWaivers, pruneBaseline, pruneExpiredWaivers, reportCorrelationFeedback, reportCorrelations, reportTelemetry, resolveCollisions, saveBaseline, saveWaivers, shouldSkipPattern, validateSchemaVersion, wrapError };