fullshield 0.4.0 → 1.0.0

package/dist/iac.js

@@ -1,132 +1,2 @@
-import { existsSync, statSync, readFileSync, readdirSync } from 'fs';
-import { relative, join } from 'path';
-import { createHash } from 'crypto';
-
-// src/iac/index.ts
-function makeFindingId(ruleId, file, snippet) {
-  const normalized = (snippet ?? "").replace(/\s+/g, " ").trim();
-  return createHash("sha256").update(`${ruleId}\0${file ?? ""}\0${normalized}`).digest("hex").slice(0, 16);
-}
-
-// src/iac/index.ts
-function finding(ruleId, title, message, file, severity = "high") {
-  return {
-    id: makeFindingId(ruleId, file, message),
-    ruleId,
-    module: "config",
-    title,
-    severity,
-    confidence: "medium",
-    file,
-    message,
-    remediation: "Pin actions by SHA, drop pull_request_target, tighten permissions, close 0.0.0.0/0, encrypt storage, drop privileged."
-  };
-}
-function runBodies(text) {
-  const bodies = [];
-  const lines = text.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    const match = /^(\s*)(?:-\s+)?run:\s*(.*)$/.exec(lines[i] ?? "");
-    if (match === null) continue;
-    const indent = match[1]?.length ?? 0;
-    let body = match[2] ?? "";
-    if (body === "|" || body === ">") {
-      const block = [];
-      for (let j = i + 1; j < lines.length; j += 1) {
-        const line = lines[j] ?? "";
-        if (line.trim() === "") {
-          block.push(line);
-          continue;
-        }
-        const lead = line.match(/^\s*/)?.[0].length ?? 0;
-        if (lead <= indent) break;
-        block.push(line);
-      }
-      body = block.join("\n");
-    }
-    bodies.push(body);
-  }
-  return bodies;
-}
-function walk(dir, out = []) {
-  if (!existsSync(dir)) return out;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (["node_modules", "dist", ".git"].includes(entry.name)) continue;
-      walk(full, out);
-    } else if (entry.isFile()) {
-      out.push(full);
-    }
-  }
-  return out;
-}
-function scanIac(dir, opts = {}) {
-  if (!opts.experimental && process.env.FULLSHIELD_EXPERIMENTAL_IAC !== "1") return [];
-  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
-  const findings = [];
-  for (const file of walk(dir)) {
-    const rel = relative(dir, file).replaceAll("\\", "/");
-    const text = readFileSync(file, "utf8");
-    if (rel.includes(".github/workflows/") && /\.ya?ml$/.test(rel)) {
-      if (/uses:\s+\S+@v\d/.test(text) && !/uses:\s+\S+@[0-9a-f]{40}/.test(text)) {
-        findings.push(finding("IAC-GHA-UNPINNED-001", "GitHub Action not pinned to a commit SHA", "uses: tag instead of SHA", rel));
-      }
-      if (/pull_request_target/.test(text)) {
-        findings.push(finding("IAC-GHA-PRTARGET-001", "pull_request_target workflow", "untrusted PR can run with base secrets", rel, "critical"));
-      }
-      if (/pull_request_target/.test(text) && /actions\/checkout/.test(text) && /github\.event\.pull_request/.test(text)) {
-        findings.push(
-          finding(
-            "IAC-GHA-PRCHECKOUT-001",
-            "pull_request_target checks out pull-request code",
-            "untrusted head can run with the base repository token",
-            rel,
-            "critical"
-          )
-        );
-      }
-      if (runBodies(text).some((body) => /\$\{\{\s*github\.event\./.test(body))) {
-        findings.push(
-          finding(
-            "IAC-GHA-INJECT-001",
-            "Workflow run step interpolates github.event",
-            "untrusted event text is passed to the shell",
-            rel,
-            "critical"
-          )
-        );
-      }
-      if (/permissions:\s*\n\s+contents:\s*write/.test(text) || /permissions:\s+write-all/.test(text)) {
-        findings.push(finding("IAC-GHA-PERMS-001", "Overly broad GitHub Actions permissions", "write-all or contents: write", rel));
-      }
-      if (/echo\s+\$\{\{\s*secrets\.|console\.(?:log|info|debug)\([^)]*secrets\./i.test(text)) {
-        findings.push(finding("IAC-GHA-SECRETLOG-001", "Secret written to workflow logs", "echo or console of secrets.*", rel, "critical"));
-      }
-    }
-    if (/\.tf$/.test(rel)) {
-      if (/acl\s*=\s*"public-read"|block_public_acls\s*=\s*false/.test(text)) {
-        findings.push(finding("IAC-TF-S3PUBLIC-001", "Public S3 bucket", "public-read or public ACLs enabled", rel, "critical"));
-      }
-      if (/0\.0\.0\.0\/0/.test(text) && /22|3306|5432/.test(text)) {
-        findings.push(finding("IAC-TF-SGOPEN-001", "Security group open to the world on a data/admin port", "0.0.0.0/0 on 22/3306/5432", rel, "critical"));
-      }
-      if (/encrypted\s*=\s*false/.test(text)) {
-        findings.push(finding("IAC-TF-UNENCRYPTED-001", "Unencrypted cloud storage", "encrypted = false", rel));
-      }
-    }
-    if (/deployment\.ya?ml$|pod\.ya?ml$/.test(rel) || rel.includes("k8s/")) {
-      if (/privileged:\s*true/.test(text) || /hostNetwork:\s*true/.test(text)) {
-        findings.push(finding("IAC-K8S-PRIV-001", "Privileged or hostNetwork Kubernetes pod", "privileged/hostNetwork true", rel, "critical"));
-      }
-    }
-    if (/compose\.ya?ml$|docker-compose\.ya?ml$/.test(rel)) {
-      if (/privileged:\s*true/.test(text)) {
-        findings.push(finding("IAC-COMPOSE-PRIV-001", "Privileged docker-compose service", "privileged: true", rel, "critical"));
-      }
-    }
-  }
-  return findings;
-}
-
-export { scanIac };
+import {existsSync,statSync,readFileSync,readdirSync}from'fs';import {relative,join}from'path';import {createHash}from'crypto';function d(n,s,e){let r=(e??"").replace(/\s+/g," ").trim();return createHash("sha256").update(`${n}\0${s??""}\0${r}`).digest("hex").slice(0,16)}function o(n,s,e,r,t="high"){return {id:d(n,r,e),ruleId:n,module:"config",title:s,severity:t,confidence:"medium",file:r,message:e,remediation:"Pin actions by SHA, drop pull_request_target, tighten permissions, close 0.0.0.0/0, encrypt storage, drop privileged."}}function v(n){let s=[],e=n.split(/\r?\n/);for(let r=0;r<e.length;r+=1){let t=/^(\s*)(?:-\s+)?run:\s*(.*)$/.exec(e[r]??"");if(t===null)continue;let i=t[1]?.length??0,c=t[2]??"";if(c==="|"||c===">"){let a=[];for(let u=r+1;u<e.length;u+=1){let l=e[u]??"";if(l.trim()===""){a.push(l);continue}if((l.match(/^\s*/)?.[0].length??0)<=i)break;a.push(l);}c=a.join(`
+`);}s.push(c);}return s}function g(n,s=[]){if(!existsSync(n))return s;for(let e of readdirSync(n,{withFileTypes:true})){let r=join(n,e.name);if(e.isDirectory()){if(["node_modules","dist",".git"].includes(e.name))continue;g(r,s);}else e.isFile()&&s.push(r);}return s}function C(n,s={}){if(!s.experimental&&process.env.FULLSHIELD_EXPERIMENTAL_IAC!=="1")return [];if(!existsSync(n)||!statSync(n).isDirectory())return [];let e=[];for(let r of g(n)){let t=relative(n,r).replaceAll("\\","/"),i=readFileSync(r,"utf8");t.includes(".github/workflows/")&&/\.ya?ml$/.test(t)&&(/uses:\s+\S+@v\d/.test(i)&&!/uses:\s+\S+@[0-9a-f]{40}/.test(i)&&e.push(o("IAC-GHA-UNPINNED-001","GitHub Action not pinned to a commit SHA","uses: tag instead of SHA",t)),/pull_request_target/.test(i)&&e.push(o("IAC-GHA-PRTARGET-001","pull_request_target workflow","untrusted PR can run with base secrets",t,"critical")),/pull_request_target/.test(i)&&/actions\/checkout/.test(i)&&/github\.event\.pull_request/.test(i)&&e.push(o("IAC-GHA-PRCHECKOUT-001","pull_request_target checks out pull-request code","untrusted head can run with the base repository token",t,"critical")),v(i).some(c=>/\$\{\{\s*github\.event\./.test(c))&&e.push(o("IAC-GHA-INJECT-001","Workflow run step interpolates github.event","untrusted event text is passed to the shell",t,"critical")),(/permissions:\s*\n\s+contents:\s*write/.test(i)||/permissions:\s+write-all/.test(i))&&e.push(o("IAC-GHA-PERMS-001","Overly broad GitHub Actions permissions","write-all or contents: write",t)),/echo\s+\$\{\{\s*secrets\.|console\.(?:log|info|debug)\([^)]*secrets\./i.test(i)&&e.push(o("IAC-GHA-SECRETLOG-001","Secret written to workflow logs","echo or console of secrets.*",t,"critical"))),/\.tf$/.test(t)&&(/acl\s*=\s*"public-read"|block_public_acls\s*=\s*false/.test(i)&&e.push(o("IAC-TF-S3PUBLIC-001","Public S3 bucket","public-read or public ACLs enabled",t,"critical")),/0\.0\.0\.0\/0/.test(i)&&/22|3306|5432/.test(i)&&e.push(o("IAC-TF-SGOPEN-001","Security group open to the world on a data/admin port","0.0.0.0/0 on 22/3306/5432",t,"critical")),/encrypted\s*=\s*false/.test(i)&&e.push(o("IAC-TF-UNENCRYPTED-001","Unencrypted cloud storage","encrypted = false",t))),(/deployment\.ya?ml$|pod\.ya?ml$/.test(t)||t.includes("k8s/"))&&(/privileged:\s*true/.test(i)||/hostNetwork:\s*true/.test(i))&&e.push(o("IAC-K8S-PRIV-001","Privileged or hostNetwork Kubernetes pod","privileged/hostNetwork true",t,"critical")),/compose\.ya?ml$|docker-compose\.ya?ml$/.test(t)&&/privileged:\s*true/.test(i)&&e.push(o("IAC-COMPOSE-PRIV-001","Privileged docker-compose service","privileged: true",t,"critical"));}return e}export{C as scanIac};

package/dist/incremental.js

@@ -1,13 +1,2 @@
-import { spawnSync } from 'child_process';
-
-// src/incremental/index.ts
-function resolveChangedFiles(cwd, opts = {}) {
-  if (!opts.experimental && process.env.FULLSHIELD_EXPERIMENTAL_PLATFORM !== "1") return [];
-  if (!opts.changed && !opts.since) return [];
-  const run = opts.git ?? ((args) => spawnSync("git", args, { cwd, encoding: "utf8" }).stdout ?? "");
-  const range = opts.since ?? "HEAD";
-  const out = opts.changed ? run(["diff", "--name-only", "--cached"]) : run(["diff", "--name-only", range]);
-  return out.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
-}
-
-export { resolveChangedFiles };
+import {spawnSync}from'child_process';function s(t,n={}){if(!n.experimental&&process.env.FULLSHIELD_EXPERIMENTAL_PLATFORM!=="1")return [];if(!n.changed&&!n.since)return [];let i=n.git??(e=>spawnSync("git",e,{cwd:t,encoding:"utf8"}).stdout??""),r=n.since??"HEAD";return (n.changed?i(["diff","--name-only","--cached"]):i(["diff","--name-only",r])).split(`
+`).map(e=>e.trim()).filter(e=>e.length>0)}export{s as resolveChangedFiles};

package/dist/index.d.ts

@@ -1,10 +1,23 @@
 import * as zod from 'zod';
 
+declare const CAPABILITY_NAMES: readonly ["child_process", "net", "fs_write", "env", "eval", "native", "dynamic_require", "install_script", "obfuscation"];
+type CapabilityName = (typeof CAPABILITY_NAMES)[number];
+
+interface CapabilityPolicy {
+    deny: Partial<Record<CapabilityName, readonly string[]>>;
+    warn: Partial<Record<CapabilityName, readonly string[]>>;
+}
+
 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';
+/** Built-in `Finding.source` tags. Any other ingest tool name is stored as `sarif`. */
+declare const FINDING_SOURCES: readonly ["deterministic", "ai", "user-rule", "npm-audit", "semgrep", "osv-scanner", "sarif"];
+type FindingSource = (typeof FINDING_SOURCES)[number];
+/** Why a finding was moved to `ScanResult.suppressed`. */
+type SuppressedBy = 'types' | `model:${string}`;
 interface FixProposal {
     kind: 'dependency-bump' | 'code-patch' | 'config-add' | 'dependency-override';
     /** Only safe fixes apply without --unsafe. */
@@ -47,8 +60,20 @@ interface Finding {
     dependencyPath?: string[];
     /** Every retained dependency path for this package+advisory (shortest first). */
     dependencyPaths?: string[][];
-    /** Deterministic (default) vs AI-added. AI findings never fail CI. */
-    source?: 'deterministic' | 'ai';
+    /** Built-in tag. An unknown ingest tool name is stored as `sarif`; the original name stays in `sources`. */
+    source?: FindingSource;
+    /** Every tool that agreed on an ingested row. Ingest only. */
+    sources?: string[];
+    /** Original rule id from an external tool. Ingest only. */
+    externalRuleId?: string;
+    /** Every original rule or advisory id on an ingested row. */
+    externalRuleIds?: string[];
+    /** Severity token from the external tool, unchanged. Ingest only. */
+    externalSeverity?: string;
+    /** Sink class copied from a report that already has one. Ingest only. */
+    sinkClass?: string;
+    /** Route exposure copied from a report that already has it. Ingest only. */
+    routeExposure?: 'unauthenticated' | 'authenticated' | 'unknown';
     aiVerdict?: 'true-positive' | 'likely-false-positive' | 'needs-review';
     aiReasoning?: string;
     exploitScenario?: string;
@@ -59,6 +84,27 @@ interface Finding {
     stillAtHead?: boolean;
     /** Read-only identity check (`scan --verify-secrets`). Never includes the secret. */
     verification?: 'live' | 'revoked' | 'unknown';
+    /** 0–100. Present only with FULLSHIELD_EXPERIMENTAL_PRIORITY=1. Severity is never changed. */
+    priority?: number;
+    /** Why `priority` was chosen. Same flag as `priority`. */
+    priorityFactors?: Array<{
+        name: string;
+        points: number;
+        detail: string;
+    }>;
+    /**
+     * Offline structure check. Present only with FULLSHIELD_EXPERIMENTAL_SECRET_CHECK=1.
+     * Never deletes the finding and never changes severity.
+     */
+    secretCheck?: 'checksum-failed' | 'placeholder';
+    /** Set to `test` for test, fixture, example, and sample paths. Flag-only. */
+    context?: 'test';
+    /**
+     * Set on copies listed in `ScanResult.suppressed`.
+     * `types` is the TypeScript receiver check. `model:<package>` is a library model pack.
+     * Absent on findings that are still reported.
+     */
+    suppressedBy?: SuppressedBy;
     /** Why the reachability class was chosen. Present only with FULLSHIELD_EXPERIMENTAL_REACH_EVIDENCE=1. */
     reachabilityEvidence?: {
         imports: Array<{
@@ -101,6 +147,8 @@ interface DepsConfig {
     offline: boolean;
     /** Cache root (contains an `osv/` directory). Relative paths are resolved from cwd. */
     cacheDir?: string;
+    /** Present only when FULLSHIELD_EXPERIMENTAL_CAPABILITIES=1. */
+    capabilityPolicy?: CapabilityPolicy;
 }
 interface AiConfig {
     /** Off by default. Also enabled by `--ai`. */
@@ -125,6 +173,10 @@ interface SastConfig {
     sources?: SastSourceConfig[];
     sanitizers?: SastSanitizerConfig[];
 }
+/** Phase 80. The TypeScript program is not built above `maxFiles`. */
+interface TypesConfig {
+    maxFiles: number;
+}
 interface ResolvedConfig {
     modules: ModuleName[];
     failOn: Severity;
@@ -138,6 +190,9 @@ interface ResolvedConfig {
     deps: DepsConfig;
     ai: AiConfig;
     sast: SastConfig;
+    types: TypesConfig;
+    /** Phase 90. Path to a user Semgrep-style YAML file. Read only when the experimental flag is on. */
+    semgrepRules?: string;
 }
 declare const DEFAULT_CONFIG: ResolvedConfig;
 declare class ConfigError extends Error {
@@ -148,6 +203,30 @@ declare class ConfigError extends Error {
  */
 declare function loadConfig(cwd: string, configPath?: string): Promise<ResolvedConfig>;
 
+interface AttackPathEntry {
+    method: string;
+    path: string;
+    auth: 'present' | 'absent';
+}
+interface AttackPathStep {
+    file: string;
+    line?: number;
+    note: string;
+}
+interface AttackPath {
+    kind: 'sink' | 'dependency' | 'secret';
+    entry?: AttackPathEntry;
+    steps: AttackPathStep[];
+    sink: {
+        id: string;
+        ruleId: string;
+        severity: Severity;
+        file?: string;
+        line?: number;
+    };
+    findingIds: string[];
+}
+
 /** Stable GitHub URL for a shipped rule doc (also valid as a GitLab-comment link). */
 declare function ruleDocsUrl(ruleId: string): string;
 /**
@@ -248,6 +327,15 @@ interface ScanOptions {
     experimentalPolicy?: boolean;
     /** Override git/CI branch when applying `failOn` per branch. */
     policyBranch?: string;
+    /** Phase 85: join existing findings into attack paths. Requires FULLSHIELD_EXPERIMENTAL_PATHS=1. */
+    paths?: boolean;
+    /**
+     * Phase 79. Seconds for `--max-time`. Applied only when
+     * `FULLSHIELD_EXPERIMENTAL_BUDGET=1`.
+     */
+    maxTimeSeconds?: number;
+    /** Phase 90. Overrides `semgrepRules` in config. The file is parsed only when the flag is on. */
+    semgrepRules?: string;
 }
 interface ScanMetadata {
     version: string;
@@ -255,9 +343,9 @@ interface ScanMetadata {
     durationMs: number;
     cwd: string;
     filesScanned: number;
-    modulesRequested: ModuleName[];
+    modulesRequested: readonly ModuleName[];
     /** Requested modules that are actually implemented and ran. */
-    modulesRun: ModuleName[];
+    modulesRun: readonly ModuleName[];
     /** Set when `scan --history` stops at the commit cap. Exact text: `scanned N of M commits`. */
     history?: string;
     /** Phase 48. Direct dependencies no project file imports. Absent when the list is empty. */
@@ -265,6 +353,26 @@ interface ScanMetadata {
         packages: string[];
         advisories: number;
     };
+    /** Phase 81. One line per model pack skipped because the installed version is out of range. */
+    info?: string[];
+    /** Phase 78. Present only when FULLSHIELD_EXPERIMENTAL_PERF2=1. Not findings. */
+    skipped?: {
+        total: number;
+        oversize: number;
+        minified: number;
+        declaration: number;
+        sourceMap: number;
+        generated: number;
+    };
+    /**
+     * Phase 79. Set only when `FULLSHIELD_EXPERIMENTAL_BUDGET` stops the scan early.
+     * An incomplete scan is not a clean result.
+     */
+    incomplete?: true;
+    /** Modules that did not finish. Deps, secrets, and config still run to completion. */
+    incompleteModules?: ModuleName[];
+    /** Source files that did not get a SAST taint pass. */
+    filesNotTaintChecked?: number;
     /** Phase 49. Direct version bumps taken from OSV `fixed` versions. Absent when there is nothing to say. */
     upgradePlan?: {
         bumps: Array<{
@@ -294,6 +402,15 @@ interface ScanResult {
     policy?: PolicyScanResult;
     /** Set when a baseline suppression is missing fields or has expired. */
     suppressionErrors?: string[];
+    /**
+     * Phase 80 and Phase 81. Findings removed from `findings`.
+     * Present when the type checker ran or a model pack suppressed a finding.
+     */
+    suppressed?: Finding[];
+    /** Phase 80. Missing `typescript` (FS-E013) or the types.maxFiles fallback. Printed by the CLI. */
+    typesNotice?: string;
+    /** Phase 85. Present only when scan paths were requested and FULLSHIELD_EXPERIMENTAL_PATHS=1. */
+    paths?: AttackPath[];
 }
 /**
  * Scanner modules register here as their phases are built.
@@ -335,6 +452,8 @@ declare function walkFiles(options: WalkOptions): Promise<string[]>;
  */
 declare function packageVersion(): string;
 
+type FixVerification = 'removes-finding' | 'does-not-remove' | 'introduces-finding';
+
 interface FixOptions {
     cwd?: string;
     modules?: ModuleName[];
@@ -342,12 +461,19 @@ interface FixOptions {
     force?: boolean;
     unsafe?: boolean;
     noBranch?: boolean;
+    /** Re-scan each patch in memory. Also on when FULLSHIELD_EXPERIMENTAL_FIX_VERIFY=1. */
+    experimentalFixVerify?: boolean;
+    /** Write a patch whose rescan still reports the original finding. */
+    forceUnverified?: boolean;
+    /** Accepted by the CLI. It does not write a patch that introduces a finding. */
+    yes?: boolean;
 }
 interface FixPatch {
     file: string;
     ruleId: string;
     safe: boolean;
     diff: string;
+    verified?: FixVerification;
 }
 interface FixResult {
     applied: boolean;
@@ -357,6 +483,8 @@ interface FixResult {
     findings: Finding[];
     /** Set when an override was written to package.json. The lockfile is left unchanged. */
     notice?: string;
+    /** Set when a patch does not remove its finding or would introduce one. */
+    warnings?: string[];
 }
 declare function runFix(options?: FixOptions): Promise<FixResult>;
 
@@ -579,6 +707,41 @@ declare function buildVex(findings: readonly Finding[], format: VexFormat, meta?
 /** Phase 31 worm / VEX / overrides / provenance. Off unless the env flag or CLI option is set. */
 declare function experimentalVex(): boolean;
 
+/** Phase 84. Off unless FULLSHIELD_EXPERIMENTAL_PRIORITY=1 or --experimental-priority. */
+declare const PRIORITY_FLAG = "FULLSHIELD_EXPERIMENTAL_PRIORITY";
+declare function priorityEnabled(): boolean;
+type RouteExposure = 'unauthenticated' | 'authenticated' | 'unknown';
+interface PriorityFactor {
+    name: 'always' | 'severity' | 'confidence' | 'reachability' | 'route' | 'devOnly' | 'sink' | 'sources';
+    points: number;
+    detail: string;
+}
+interface PriorityInput {
+    ruleId: string;
+    module?: ModuleName;
+    severity: Severity;
+    confidence: Confidence;
+    reachability?: Finding['reachability'];
+    routeExposure?: RouteExposure;
+    devOnly?: boolean;
+    /** Explicit class wins over the rule-id map. Omit it to derive. */
+    sinkClass?: string;
+    /** Phase 83. Omitted or 1 means a single source. */
+    agreeingSources?: number;
+}
+interface PriorityScore {
+    priority: number;
+    factors: PriorityFactor[];
+}
+/** Documented table in docs/priority.md. Same input always returns the same score. */
+declare function scorePriority(input: PriorityInput): PriorityScore;
+/** Score a finding. Does not change severity. Phase 56 data is not read. */
+declare function scoreFinding(finding: Finding): PriorityScore;
+/** Attach priority fields only when the flag is on. Order and severity stay as given. */
+declare function applyPriority(findings: readonly Finding[]): Finding[];
+/** Console order when the flag is on: priority, then severity, then file. */
+declare function compareByPriority(a: Finding, b: Finding): number;
+
 /** Static worm indicators: token read + publish / registry PUT / GitHub create / workflow write. */
 declare function analyzeWormIndicators(dir: string): Finding[];
 /** Static: install scripts or code writing .github/, .git/hooks/, or CI config. */
@@ -595,4 +758,27 @@ declare function provenanceCoverage(packages: readonly {
     version: string;
 }[], known: ReadonlyMap<string, boolean>): ProvenanceScore;
 
-export { type AiConfig, type AppliedPolicy, type BaselineFile, CONFIG_FILE_NAME, type Confidence, ConfigError, DEFAULT_CONFIG, DIFF_FLAG, type DepsConfig, type Finding, type FindingSummary, type FixOptions, type FixPatch, type FixProposal, type FixResult, type FullShieldPolicy, type GuardTool, type GuardToolCall, IMPLEMENTED_MODULES, MODULE_NAMES, type McpScanOptions, type ModuleContext, type ModuleName, type NotifyConfig, POLICY_FILE_NAME, POLICY_FLAG, POLICY_PEER_ERROR, PolicyError, type PolicyException, type PolicyScanResult, type ResolvedConfig, SEVERITIES, type SbomComponent, type SbomInput, type ScanDiff, type ScanMetadata, type ScanModule, type ScanOptions, type ScanResult, type Severity, type WalkOptions, analyzeWorkflowTampering, analyzeWormIndicators, applyBaseline, applyInlineSuppressions, applyPolicy, buildCycloneDxVex, buildOpenVex, buildSbom, buildVex, builtinModules, createAiClient, diffScans, experimentalVex, failsCi, guardTools, isInternalAi, isLiveAi, isModuleName, isPolicyEnabled, isSeverity, loadConfig, loadPolicy, makeFindingId, mcpCfgEnabled, mcpHomeConfigPaths, meetsThreshold, packageVersion, parseIgnore, parsePolicy, parseScanDocument, provenanceCoverage, readBaseline, renderConsoleReport, renderCycloneDx, renderDiffText, renderGithubAnnotations, renderGitlabCodeQuality, renderHtmlReport, renderJsonReport, renderJunitReport, renderMarkdownReport, renderPrSummary, renderSarifReport, ruleDocsUrl, runAiFix, runFix, runScan, scan, scanMcpConfig, scanTextForSecrets, severityRank, sortFindings, summarize, validateCycloneDx15, validateCycloneDxVex, validateOpenVex, validateSarif21, walkFiles, writeBaseline };
+/** Local ingest failed for one file. Other files are still read. */
+declare class IngestError extends Error {
+    readonly code = "FS-E012";
+    readonly file: string;
+    readonly schemaError: string;
+    constructor(file: string, schemaError: string);
+}
+
+declare const INGEST_FLAG = "FULLSHIELD_EXPERIMENTAL_INGEST";
+/** Off unless the env flag or `--experimental-ingest` is set. */
+declare function ingestEnabled(explicit?: boolean): boolean;
+
+interface IngestGroup {
+    source: string;
+    findings: Finding[];
+}
+interface IngestLoad {
+    findings: Finding[];
+    groups: IngestGroup[];
+    errors: IngestError[];
+}
+declare function ingestLocalFiles(files: readonly string[]): Promise<IngestLoad>;
+
+export { type AiConfig, type AppliedPolicy, type BaselineFile, CONFIG_FILE_NAME, type Confidence, ConfigError, DEFAULT_CONFIG, DIFF_FLAG, type DepsConfig, type Finding, type FindingSummary, type FixOptions, type FixPatch, type FixProposal, type FixResult, type FullShieldPolicy, type GuardTool, type GuardToolCall, IMPLEMENTED_MODULES, INGEST_FLAG, IngestError, type IngestLoad, MODULE_NAMES, type McpScanOptions, type ModuleContext, type ModuleName, type NotifyConfig, POLICY_FILE_NAME, POLICY_FLAG, POLICY_PEER_ERROR, PRIORITY_FLAG, PolicyError, type PolicyException, type PolicyScanResult, type PriorityFactor, type PriorityInput, type PriorityScore, type ResolvedConfig, type RouteExposure, SEVERITIES, type SbomComponent, type SbomInput, type ScanDiff, type ScanMetadata, type ScanModule, type ScanOptions, type ScanResult, type Severity, type WalkOptions, analyzeWorkflowTampering, analyzeWormIndicators, applyBaseline, applyInlineSuppressions, applyPolicy, applyPriority, buildCycloneDxVex, buildOpenVex, buildSbom, buildVex, builtinModules, compareByPriority, createAiClient, diffScans, experimentalVex, failsCi, guardTools, ingestEnabled, ingestLocalFiles, isInternalAi, isLiveAi, isModuleName, isPolicyEnabled, isSeverity, loadConfig, loadPolicy, makeFindingId, mcpCfgEnabled, mcpHomeConfigPaths, meetsThreshold, packageVersion, parseIgnore, parsePolicy, parseScanDocument, priorityEnabled, provenanceCoverage, readBaseline, renderConsoleReport, renderCycloneDx, renderDiffText, renderGithubAnnotations, renderGitlabCodeQuality, renderHtmlReport, renderJsonReport, renderJunitReport, renderMarkdownReport, renderPrSummary, renderSarifReport, ruleDocsUrl, runAiFix, runFix, runScan, scan, scanMcpConfig, scanTextForSecrets, scoreFinding, scorePriority, severityRank, sortFindings, summarize, validateCycloneDx15, validateCycloneDxVex, validateOpenVex, validateSarif21, walkFiles, writeBaseline };