fullshield 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+declare const SEVERITIES: readonly ["info", "low", "medium", "high", "critical"];
+type Severity = (typeof SEVERITIES)[number];
+declare const MODULE_NAMES: readonly ["deps", "secrets", "sast", "config"];
+type ModuleName = (typeof MODULE_NAMES)[number];
+type Confidence = 'low' | 'medium' | 'high';
+interface FixProposal {
+    kind: 'dependency-bump' | 'code-patch' | 'config-add';
+    /** Only safe fixes apply without --unsafe. */
+    safe: boolean;
+    /** Unified diff. */
+    diff: string;
+}
+interface Finding {
+    /** Stable hash of ruleId + file + normalized snippet. */
+    id: string;
+    /** e.g. "SAST-SQLI-001" */
+    ruleId: string;
+    module: ModuleName;
+    title: string;
+    severity: Severity;
+    confidence: Confidence;
+    /** e.g. "CWE-89" */
+    cwe?: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    /** Secrets MUST be masked: first 4 chars + **** */
+    snippet?: string;
+    /** What's wrong, in plain English. */
+    message: string;
+    /** How to fix. */
+    remediation: string;
+    fix?: FixProposal;
+    /** OSV id, CVE, docs. */
+    references?: string[];
+    /** Cross-file taint steps (Phase 13). */
+    trace?: Array<{
+        file: string;
+        line?: number;
+        note: string;
+    }>;
+    /** Dependency reachability (Phase 13 / harden-3). */
+    reachability?: 'reachable' | 'imported-not-called' | 'reachable-via-dependency' | 'not-imported' | 'reachability-unknown';
+    /** Lockfile path from an imported direct dependency, e.g. express > body-parser > qs. */
+    dependencyPath?: string[];
+    /** Deterministic (default) vs AI-added. AI findings never fail CI. */
+    source?: 'deterministic' | 'ai';
+    aiVerdict?: 'true-positive' | 'likely-false-positive' | 'needs-review';
+    aiReasoning?: string;
+    exploitScenario?: string;
+    explanation?: string;
+}
+interface FindingSummary {
+    total: number;
+    bySeverity: Record<Severity, number>;
+}
+declare function isSeverity(value: string): value is Severity;
+declare function isModuleName(value: string): value is ModuleName;
+declare function severityRank(severity: Severity): number;
+/** True when `severity` is at or above `threshold`. */
+declare function meetsThreshold(severity: Severity, threshold: Severity): boolean;
+/** CI gate: deterministic findings only. `source: 'ai'` never fails a build. */
+declare function failsCi(finding: Finding, threshold: Severity): boolean;
+/** Stable finding id: sha256 of ruleId + file + whitespace-normalized snippet. */
+declare function makeFindingId(ruleId: string, file: string | undefined, snippet: string | undefined): string;
+/** Sort by severity (desc), then file, line, ruleId for stable output. */
+declare function sortFindings(findings: readonly Finding[]): Finding[];
+declare function summarize(findings: readonly Finding[]): FindingSummary;
+
+declare const CONFIG_FILE_NAME = "fullshield.config.json";
+interface NotifyConfig {
+    slackWebhookEnv: string;
+}
+interface DepsConfig {
+    /** When true, OSV is never contacted; cache only. */
+    offline: boolean;
+    /** Cache root (contains an `osv/` directory). Relative paths are resolved from cwd. */
+    cacheDir?: string;
+}
+interface AiConfig {
+    /** Off by default. Also enabled by `--ai`. */
+    enabled: boolean;
+    /** Hard cap per scan (spec §16.1). */
+    maxCostUsd: number;
+    /** Highest-severity findings sent to the model first. */
+    maxFindings: number;
+}
+interface ResolvedConfig {
+    modules: ModuleName[];
+    failOn: Severity;
+    ignore: string[];
+    baseline: string;
+    notify: NotifyConfig;
+    deps: DepsConfig;
+    ai: AiConfig;
+}
+declare const DEFAULT_CONFIG: ResolvedConfig;
+declare class ConfigError extends Error {
+}
+/**
+ * Load fullshield.config.json from `configPath` (must exist) or from
+ * `<cwd>/fullshield.config.json` (optional), merged over defaults.
+ */
+declare function loadConfig(cwd: string, configPath?: string): Promise<ResolvedConfig>;
+
+interface ModuleContext {
+    cwd: string;
+    /** Posix-style relative paths of every scannable file under cwd. */
+    files: string[];
+    config: ResolvedConfig;
+}
+interface ScanModule {
+    name: ModuleName;
+    run(ctx: ModuleContext): Promise<Finding[]>;
+}
+interface ScanOptions {
+    /** Directory to scan. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Subset of modules to run. Defaults to config.modules. */
+    modules?: ModuleName[];
+    /** Explicit path to fullshield.config.json. */
+    configPath?: string;
+    /** Scan only files staged in git (pre-commit mode). */
+    staged?: boolean;
+    /** Cache-only OSV lookups (no network). */
+    offline?: boolean;
+    /** Write the current (post-suppression) findings to the baseline file. */
+    updateBaseline?: boolean;
+    /** Opt-in AI: `true` enables the client; a string selects a mode. */
+    ai?: boolean | 'triage' | 'explain' | 'logic';
+    /** Phase 22 incremental (requires experimentalIncremental or FULLSHIELD_EXPERIMENTAL_PLATFORM=1). */
+    changed?: boolean;
+    since?: string;
+    experimentalIncremental?: boolean;
+    changedFiles?: string[];
+}
+interface ScanMetadata {
+    version: string;
+    startedAt: string;
+    durationMs: number;
+    cwd: string;
+    filesScanned: number;
+    modulesRequested: ModuleName[];
+    /** Requested modules that are actually implemented and ran. */
+    modulesRun: ModuleName[];
+}
+interface ScanResult {
+    findings: Finding[];
+    summary: FindingSummary;
+    metadata: ScanMetadata;
+    config: ResolvedConfig;
+}
+/**
+ * Scanner modules register here as their phases are built.
+ * Phase 5: deps + secrets + sast + config.
+ */
+declare const builtinModules: readonly ScanModule[];
+declare const IMPLEMENTED_MODULES: readonly ModuleName[];
+/**
+ * Core scan: load config, walk files, run the requested modules that exist,
+ * then dedupe, sort, and summarize findings. `modules` is injectable so the
+ * engine's orchestration is testable independently of built-in modules.
+ */
+declare function runScan(options?: ScanOptions, modules?: readonly ScanModule[]): Promise<ScanResult>;
+/** Public library API: scan with the built-in modules. */
+declare function scan(options?: ScanOptions): Promise<ScanResult>;
+
+interface WalkOptions {
+    cwd: string;
+    /** Extra gitignore-style patterns (from config) on top of .gitignore. */
+    ignore?: string[];
+}
+/**
+ * Recursively list files under `cwd`, respecting the project's .gitignore and
+ * the config `ignore` globs. Returns sorted, posix-style relative paths.
+ * Symlinks are never followed (a scanner must not escape the scan root).
+ */
+declare function walkFiles(options: WalkOptions): Promise<string[]>;
+
+/**
+ * Resolve the fullshield package version by walking up from this module
+ * (works from both src/ during tests and dist/ in the built package).
+ */
+declare function packageVersion(): string;
+
+interface FixOptions {
+    cwd?: string;
+    modules?: ModuleName[];
+    apply?: boolean;
+    force?: boolean;
+    unsafe?: boolean;
+    noBranch?: boolean;
+}
+interface FixPatch {
+    file: string;
+    ruleId: string;
+    safe: boolean;
+    diff: string;
+}
+interface FixResult {
+    applied: boolean;
+    reverted: boolean;
+    branch?: string;
+    patches: FixPatch[];
+    findings: Finding[];
+}
+declare function runFix(options?: FixOptions): Promise<FixResult>;
+
+type AiProviderName = 'anthropic' | 'openai' | 'ollama' | 'fixture';
+type AiMode = 'triage' | 'explain' | 'logic' | 'fix';
+interface AiCompleteRequest {
+    mode: AiMode;
+    prompt: string;
+    model?: string;
+}
+interface AiCompleteResponse {
+    json: unknown;
+    costUsd: number;
+    cached: boolean;
+    redactedPrompt: string;
+}
+interface AiClientOptions {
+    enabled: boolean;
+    config?: AiConfig;
+    /** Injected fetch for tests. Never used when fixtures are on. */
+    fetchImpl?: typeof fetch;
+    provider?: AiProviderName;
+    apiKey?: string;
+    model?: string;
+    /** When true (default), only recorded fixtures are used — no network. */
+    useFixtures?: boolean;
+}
+interface AiClient {
+    enabled: boolean;
+    useFixtures: boolean;
+    networkCalls: number;
+    spentUsd: number;
+    complete(req: AiCompleteRequest): Promise<AiCompleteResponse | null>;
+}
+/** Live provider is opt-in via FULLSHIELD_AI_LIVE=1 (used by `npm run test:live-ai`). */
+declare function isLiveAi(): boolean;
+/**
+ * Triage and logic stay in-tree for fixtures/tests but are not a 0.1.0 CLI
+ * surface. Library callers must set FULLSHIELD_AI_INTERNAL=1.
+ */
+declare function isInternalAi(): boolean;
+/**
+ * AI provider. Off by default. CI and the default path use recorded fixtures
+ * and never open a socket. A live provider is used only when `useFixtures`
+ * is false — tests inject `fetchImpl`; `test:live-ai` talks to local Ollama.
+ */
+declare function createAiClient(options: AiClientOptions): AiClient;
+
+/** Scan one file's text with every secrets rule. Secrets are always masked. */
+declare function scanTextForSecrets(path: string, text: string): Finding[];
+
+interface AiFixResult {
+    accepted: boolean;
+    attempts: number;
+    diff: string;
+    file?: string;
+}
+/**
+ * Draft a patch for findings that have no rule-based fix. Apply in a temp
+ * copy, rescan, optionally run tests. Keep only if the finding disappears
+ * and no new findings appear. Max 2 attempts. Never writes the user's tree.
+ */
+declare function runAiFix(options: {
+    cwd: string;
+    client: AiClient;
+}): Promise<AiFixResult>;
+
+interface BaselineFile {
+    version: 1;
+    findings: Array<{
+        id: string;
+        ruleId: string;
+        file?: string;
+        line?: number;
+    }>;
+}
+declare function readBaseline(path: string): Promise<BaselineFile | undefined>;
+declare function writeBaseline(path: string, findings: readonly Finding[]): Promise<void>;
+declare function applyBaseline(findings: readonly Finding[], baseline: BaselineFile | undefined): Finding[];
+
+declare function parseIgnore(line: string): {
+    ruleId: string;
+    reason: string;
+} | undefined;
+/**
+ * Drop findings whose file:line is immediately preceded by
+ * `fullshield-ignore RULE-ID: reason` (reason required). Same-line comments
+ * also count.
+ */
+declare function applyInlineSuppressions(findings: readonly Finding[], sources: Readonly<Record<string, string>>): Finding[];
+
+/** Human-readable report: findings grouped by severity, highest first. */
+declare function renderConsoleReport(result: ScanResult): string;
+
+/** Standalone HTML report. Finding text is escaped; secrets are already masked. */
+declare function renderHtmlReport(result: ScanResult): string;
+
+/** Machine-readable report: full findings plus summary and scan metadata. */
+declare function renderJsonReport(result: ScanResult): string;
+
+/** Shareable Markdown report grouped by severity (highest first). */
+declare function renderMarkdownReport(result: ScanResult): string;
+
+/** SARIF 2.1.0 report for GitHub Code Scanning and other consumers. */
+declare function renderSarifReport(result: ScanResult): string;
+/**
+ * Structural SARIF 2.1.0 schema check for the documents we emit.
+ * Returns an empty array when valid; otherwise human-readable errors.
+ */
+declare function validateSarif21(doc: unknown): string[];
+
+declare function buildSbom(cwd: string): Promise<Record<string, unknown>>;
+
+interface SbomComponent {
+    name: string;
+    version: string;
+    license?: string;
+    purl?: string;
+}
+interface SbomInput {
+    name: string;
+    version: string;
+    components: SbomComponent[];
+    findings?: Finding[];
+}
+declare function validateCycloneDx15(doc: unknown): string[];
+declare function renderCycloneDx(input: SbomInput): Record<string, unknown>;
+
+export { type AiConfig, type BaselineFile, CONFIG_FILE_NAME, type Confidence, ConfigError, DEFAULT_CONFIG, type DepsConfig, type Finding, type FindingSummary, type FixOptions, type FixPatch, type FixProposal, type FixResult, IMPLEMENTED_MODULES, MODULE_NAMES, type ModuleContext, type ModuleName, type NotifyConfig, type ResolvedConfig, SEVERITIES, type SbomComponent, type SbomInput, type ScanMetadata, type ScanModule, type ScanOptions, type ScanResult, type Severity, type WalkOptions, applyBaseline, applyInlineSuppressions, buildSbom, builtinModules, createAiClient, failsCi, isInternalAi, isLiveAi, isModuleName, isSeverity, loadConfig, makeFindingId, meetsThreshold, packageVersion, parseIgnore, readBaseline, renderConsoleReport, renderCycloneDx, renderHtmlReport, renderJsonReport, renderMarkdownReport, renderSarifReport, runAiFix, runFix, runScan, scan, scanTextForSecrets, severityRank, sortFindings, summarize, validateCycloneDx15, validateSarif21, walkFiles, writeBaseline };