autoremediator 0.5.0 → 0.7.0

package/dist/remediate-from-scan-C-E7gqxF.d.ts

@@ -0,0 +1,211 @@
+/** A resolved CVE entry with affected npm package info */
+interface CveDetails {
+    id: string;
+    summary: string;
+    severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" | "UNKNOWN";
+    cvssScore?: number;
+    epss?: {
+        score: number;
+        percentile: number;
+        date?: string;
+    };
+    kev?: {
+        knownExploited: boolean;
+        dateAdded?: string;
+        dueDate?: string;
+        requiredAction?: string;
+        knownRansomwareCampaignUse?: string;
+    };
+    intelligence?: {
+        cveServicesEnriched?: boolean;
+        gitlabAdvisoryMatched?: boolean;
+        certCcMatched?: boolean;
+        depsDevEnrichedPackages?: number;
+        scorecardProjects?: number;
+        vendorAdvisories?: string[];
+        commercialFeeds?: string[];
+        sourceHealth?: Record<string, {
+            attempted: boolean;
+            changed: boolean;
+            error?: string;
+        }>;
+    };
+    references: string[];
+    affectedPackages: AffectedPackage[];
+}
+/** A single npm package affected by a CVE */
+interface AffectedPackage {
+    name: string;
+    ecosystem: "npm";
+    /** Semver range string for the vulnerable version window, e.g. ">=0.0.0 <4.17.21" */
+    vulnerableRange: string;
+    /** The first version that is NOT vulnerable (the safe upgrade target) */
+    firstPatchedVersion?: string;
+    /** Source that provided this entry */
+    source: "osv" | "github-advisory";
+}
+/** A package found in the consumer's project */
+interface InventoryPackage {
+    name: string;
+    version: string;
+    /** "direct" = listed in package.json; "indirect" = transitive dep */
+    type: "direct" | "indirect";
+}
+/** A package that is both installed and matches a vulnerable range */
+interface VulnerablePackage {
+    installed: InventoryPackage;
+    affected: AffectedPackage;
+    /** The resolved safe upgrade version, if one exists on npm */
+    safeUpgradeVersion?: string;
+}
+/** The outcome of a single patch operation */
+type PatchStrategy = "version-bump" | "override" | "patch-file" | "none";
+type DependencyScope = "direct" | "transitive";
+type UnresolvedReason = "constraint-blocked" | "indirect-dependency" | "install-failed" | "major-bump-required" | "no-safe-version" | "override-apply-failed" | "package-json-not-found" | "patch-apply-failed" | "patch-confidence-too-low" | "patch-generation-failed" | "patch-validation-failed" | "policy-blocked" | "requires-llm-fallback" | "source-fetch-failed" | "validation-failed";
+type PatchStrategyCounts = Partial<Record<PatchStrategy, number>>;
+type DependencyScopeCounts = Partial<Record<DependencyScope, number>>;
+type UnresolvedReasonCounts = Partial<Record<UnresolvedReason, number>>;
+interface PatchResult {
+    packageName: string;
+    strategy: PatchStrategy;
+    fromVersion: string;
+    toVersion?: string;
+    patchFilePath?: string;
+    applied: boolean;
+    dryRun: boolean;
+    message: string;
+    unresolvedReason?: UnresolvedReason;
+    validation?: {
+        passed: boolean;
+        error?: string;
+    };
+}
+interface CorrelationContext {
+    requestId?: string;
+    sessionId?: string;
+    parentRunId?: string;
+}
+interface RemediationConstraints {
+    directDependenciesOnly?: boolean;
+    preferVersionBump?: boolean;
+}
+interface ProvenanceContext {
+    actor?: string;
+    source?: "cli" | "sdk" | "mcp" | "openapi" | "unknown";
+}
+/** Top-level options for the remediate() API and CLI */
+interface RemediateOptions extends CorrelationContext {
+    /** Working directory of the consumer's project (defaults to process.cwd()) */
+    cwd?: string;
+    /** Package manager to use (defaults to auto-detect from lockfile) */
+    packageManager?: "npm" | "pnpm" | "yarn";
+    /** If true, plan and report changes but do not write anything */
+    dryRun?: boolean;
+    /** If true, run package-manager tests after patching */
+    runTests?: boolean;
+    /** Override the LLM provider (falls back to env AUTOREMEDIATOR_LLM_PROVIDER) */
+    llmProvider?: "openai" | "anthropic" | "local";
+    /** Override the model name */
+    model?: string;
+    /** Optional path to a policy file (.autoremediator.json) */
+    policy?: string;
+    /** If false, do not write evidence JSON for this run (default: true). */
+    evidence?: boolean;
+    /** Directory to write .patch files (default: ./patches) */
+    patchesDir?: string;
+    /** If true, run a non-mutating remediation preview (forces dryRun behavior for mutation tools). */
+    preview?: boolean;
+    /** Optional deterministic idempotency key for request replay handling. */
+    idempotencyKey?: string;
+    /** If true, return cached report for matching idempotency key + CVE when available. */
+    resume?: boolean;
+    /** Optional caller provenance fields for evidence and reporting. */
+    actor?: string;
+    source?: "cli" | "sdk" | "mcp" | "openapi" | "unknown";
+    /** Optional orchestration constraints for result enforcement. */
+    constraints?: RemediationConstraints;
+}
+/** Final report returned by the remediation pipeline */
+interface RemediationReport {
+    cveId: string;
+    cveDetails: CveDetails | null;
+    vulnerablePackages: VulnerablePackage[];
+    results: PatchResult[];
+    agentSteps: number;
+    summary: string;
+    evidenceFile?: string;
+    correlation?: CorrelationContext;
+    provenance?: ProvenanceContext;
+    constraints?: RemediationConstraints;
+    resumedFromCache?: boolean;
+}
+
+type ScanInputFormat = "npm-audit" | "yarn-audit" | "sarif" | "auto";
+
+interface ScanOptions extends RemediateOptions {
+    format?: ScanInputFormat;
+    policy?: string;
+}
+interface ScanReport {
+    schemaVersion: "1.0";
+    status: "ok" | "partial" | "failed";
+    generatedAt: string;
+    cveIds: string[];
+    reports: RemediationReport[];
+    successCount: number;
+    failedCount: number;
+    errors: Array<{
+        cveId: string;
+        message: string;
+    }>;
+    evidenceFile?: string;
+    patchCount: number;
+    patchValidationFailures?: Array<{
+        packageName: string;
+        cveId: string;
+        error: string;
+    }>;
+    strategyCounts?: PatchStrategyCounts;
+    dependencyScopeCounts?: DependencyScopeCounts;
+    unresolvedByReason?: UnresolvedReasonCounts;
+    patchesDir?: string;
+    correlation?: CorrelationContext;
+    provenance?: ProvenanceContext;
+    constraints?: RemediationConstraints;
+    idempotencyKey?: string;
+}
+interface CiSummary {
+    schemaVersion: "1.0";
+    status: "ok" | "partial" | "failed";
+    generatedAt: string;
+    cveCount: number;
+    remediationCount: number;
+    successCount: number;
+    failedCount: number;
+    errors: Array<{
+        cveId: string;
+        message: string;
+    }>;
+    evidenceFile?: string;
+    patchCount?: number;
+    patchValidationFailures?: Array<{
+        packageName: string;
+        cveId: string;
+        error: string;
+    }>;
+    strategyCounts?: PatchStrategyCounts;
+    dependencyScopeCounts?: DependencyScopeCounts;
+    unresolvedByReason?: UnresolvedReasonCounts;
+    patchesDir?: string;
+    correlation?: CorrelationContext;
+    provenance?: ProvenanceContext;
+    constraints?: RemediationConstraints;
+    idempotencyKey?: string;
+}
+
+declare function remediate(cveId: string, options?: RemediateOptions): Promise<RemediationReport>;
+declare function planRemediation(cveId: string, options?: RemediateOptions): Promise<RemediationReport>;
+
+declare function remediateFromScan(inputPath: string, options?: ScanOptions): Promise<ScanReport>;
+
+export { type AffectedPackage as A, type CiSummary as C, type DependencyScope as D, type InventoryPackage as I, type PatchResult as P, type RemediateOptions as R, type ScanReport as S, type UnresolvedReason as U, type VulnerablePackage as V, type RemediationReport as a, type CorrelationContext as b, type CveDetails as c, type DependencyScopeCounts as d, type PatchStrategy as e, type PatchStrategyCounts as f, type ProvenanceContext as g, type RemediationConstraints as h, type ScanInputFormat as i, type ScanOptions as j, type UnresolvedReasonCounts as k, remediateFromScan as l, planRemediation as p, remediate as r };

package/llms.txt

@@ -44,7 +44,7 @@ autoremediator ./npm-audit.json --cwd ./my-project --ci
 autoremediator-mcp   # stdio transport — register with any MCP host
 ```
 
-Available MCP tools: `remediate`, `remediateFromScan`
+Available MCP tools: `remediate`, `planRemediation`, `remediateFromScan`
 
 ## Tools (agent / MCP)
 
@@ -55,6 +55,7 @@ Available MCP tools: `remediate`, `remediateFromScan`
 | `check-version-match` | Cross-reference inventory against vulnerable ranges |
 | `find-fixed-version`  | Query npm registry for lowest safe upgrade |
 | `apply-version-bump`  | Update package.json and run package-manager install |
+| `apply-package-override` | Apply package-manager-native override for vulnerable transitive dependencies |
 | `fetch-package-source`| Download package tarball for patch generation |
 | `generate-patch`      | Generate unified diff patch via LLM |
 | `apply-patch-file`    | Write/apply patch file via native or compatibility patch flow |
@@ -63,6 +64,7 @@ Available MCP tools: `remediate`, `remediateFromScan`
 
 ```
 lookup-cve → check-inventory → check-version-match → find-fixed-version → apply-version-bump
+	└─ transitive path: apply-package-override
 	└─ fallback: fetch-package-source → generate-patch → apply-patch-file
 ```
 
@@ -72,11 +74,20 @@ lookup-cve → check-inventory → check-version-match → find-fixed-version
 |--------|------|---------|-------------|
 | `cwd` | string | `process.cwd()` | Project root |
 | `dryRun` | boolean | `false` | Plan only, write nothing |
-| `skipTests` | boolean | `true` | Skip package-manager test command after fix |
+| `runTests` | boolean | `false` | Run package-manager test command after fix |
 | `packageManager` | `npm\|pnpm\|yarn` | auto-detect | Override package manager selection |
-| `llmProvider` | `openai\|anthropic\|local` | `openai` | LLM backend (`local` = deterministic, no API key needed) |
+| `llmProvider` | `openai\|anthropic\|local` | `openai` | LLM backend (`local` = deterministic primary path; fallback patch generation may require model credentials) |
 | `patchesDir` | string | `./patches` | Directory for .patch files |
-| `policyPath` | string | `.autoremediator.json` | Policy file path |
+| `policy` | string | `.autoremediator.json` | Policy file path |
+| `preview` | boolean | `false` | Non-mutating remediation preview (forces dry-run behavior) |
+| `evidence` | boolean | `true` | Write evidence JSON output |
+| `requestId` | string | auto-generated | Request correlation ID |
+| `sessionId` | string | unset | Session correlation ID |
+| `parentRunId` | string | unset | Parent run correlation ID |
+| `idempotencyKey` | string | unset | Replay-safe idempotency key |
+| `resume` | boolean | `false` | Return cached result for matching idempotency key when available |
+| `constraints.directDependenciesOnly` | boolean | `false` | Restrict remediation to direct dependencies |
+| `constraints.preferVersionBump` | boolean | `false` | Reject override and patch remediation |
 
 ## Policy File (`.autoremediator.json`)
 
@@ -114,6 +125,7 @@ lookup-cve → check-inventory → check-version-match → find-fixed-version
 	results: PatchResult[];       // strategy: "version-bump" | "patch-file" | "none"
 	agentSteps: number;
 	summary: string;
+	evidenceFile?: string;
 }
 ```
 
@@ -129,8 +141,11 @@ lookup-cve → check-inventory → check-version-match → find-fixed-version
 	failedCount: number;
 	errors: Array<{ cveId: string; message: string }>;
 	evidenceFile?: string;        // path to .autoremediator/evidence/<runId>.json
-	patchFileCount: number;
+	patchCount: number;
 	patchValidationFailures?: Array<{ packageName: string; cveId: string; error: string }>;
-	patchStorageDir?: string;
+	strategyCounts?: Record<string, number>;
+	dependencyScopeCounts?: Record<string, number>;
+	unresolvedByReason?: Record<string, number>;
+	patchesDir?: string;
 }
 ```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "autoremediator",
   "private": false,
-  "version": "0.5.0",
-  "description": "Automated CVE remediation for Node.js dependencies with CLI, SDK, MCP, and scanner-to-fix workflows.",
+  "version": "0.7.0",
+  "description": "Risk-aware, agentic CVE remediation for Node.js using OSV, CISA KEV, and FIRST EPSS intelligence with policy and evidence controls.",
   "keywords": [
     "security-remediation",
     "dependency-security",