autoremediator 0.8.0 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/autoremediator.svg)](https://www.npmjs.com/package/autoremediator)
 [![npm downloads](https://img.shields.io/npm/dm/autoremediator.svg)](https://www.npmjs.com/package/autoremediator)
-[![license](https://img.shields.io/npm/l/autoremediator.svg)](https://github.com/Rawlings/autoremediator/blob/master/LICENSE)
+[![license](https://img.shields.io/npm/l/autoremediator.svg)](LICENSE)
 [![node](https://img.shields.io/node/v/autoremediator.svg)](https://www.npmjs.com/package/autoremediator)
 [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/Rawlings/autoremediator/pkgs/container/autoremediator)
 [![GitHub Actions](https://img.shields.io/badge/github--actions-marketplace-blue)](https://github.com/marketplace/actions/autoremediator)
@@ -12,111 +12,129 @@
 > It can reduce exposure windows, but it can also introduce operational and supply-chain risk if used without policy controls.
 > Autoremediator is designed for risk-aware automation teams, and should be paired with explicit policy, CI safeguards, and repository protection rules.
 
-Autoremediator is a risk-aware, agentic Node.js CVE remediation package.
+Autoremediator is an agentic CVE remediation platform for Node.js.
 
-It correlates OSV package intelligence with CISA KEV known-exploited signals and FIRST EPSS exploit probability scores to prioritize vulnerabilities more likely to matter in production.
+It turns dependency security from fragmented backlog triage into an autonomous remediation pipeline with threat-intelligence correlation, exploitability-aware prioritization, deterministic execution, and machine-readable evidence.
 
-This package is designed for teams that want remediation integrated into GitHub workflows and CI pipelines with policy and evidence controls.
+It is built for AI-native software delivery, agentic security operations, and policy-governed software supply chain response.
 
-It exposes stable SDK and CLI surfaces for direct CVE remediation and scanner-driven automation.
-
-It also exposes non-mutating planning and correlation context for agent orchestration workflows.
+The outcome is faster containment of dependency exposure, stronger remediation posture, and cleaner telemetry across CI/CD, platform automation, and agent-driven workflows.
 
 See the [documentation](https://rawlings.github.io/autoremediator/docs/getting-started) to get started.
 
-## Why Teams Use It
+## Security remediation, closed loop
 
-- Deterministic remediation pipeline with policy-first behavior
-- Risk-informed prioritization via KEV and EPSS enrichment
-- Scanner-driven remediation for npm audit, yarn audit, and SARIF inputs
-- Clear CI summary outputs for routing and governance
-- Patch lifecycle workflows for listing, inspecting, and validating generated patch artifacts
+Autoremediator operates as a remediation control plane, not a scanner wrapper.
 
-## Primary Use Cases
+It correlates ecosystem advisory data, exploitability telemetry, and operational policy to drive remediation decisions across repositories, portfolios, service surfaces, and agentic execution paths.
 
-- Scheduled GitHub Actions remediation jobs with auto-generated pull requests
-- CI enforcement gates that fail on unresolved remediation outcomes
-- Scanner-to-fix automation from npm audit, yarn audit, and SARIF outputs
-- Platform-level remediation orchestration across many services
-- Agentic integration via CLI, SDK, MCP, and OpenAPI
+When a clean upgrade path exists, it executes a safe dependency bump. When exposure is transitive, it applies package-manager-native overrides and resolutions. When no safe fixed version exists, it escalates into controlled patch generation with confidence thresholds, validation gates, and artifact tracking.
 
-## Core Pipeline Behavior
+Every remediation path is constrained by policy, dry-run controls, validation requirements, and auditable evidence artifacts so autonomous response stays governable, reviewable, and automation-safe.
 
-Autoremediator follows a deterministic remediation order:
+## What sets it apart
 
-1. lookup CVE intelligence
-2. inspect local dependency inventory
-3. match vulnerable installed versions
-4. attempt direct safe version remediation
-5. attempt transitive override/resolution when direct bump is not possible
-6. attempt patch fallback only when safe version paths cannot remediate
+- Exploit-aware prioritization beyond severity-centric triage
+- Deterministic remediation orchestration with explicit safety and failure semantics
+- Multi-strategy execution across direct bumps, transitive overrides, and controlled patch fallback
+- Portfolio-scale coverage across large Node.js repository estates
+- AI ecosystem interoperability through MCP, OpenAPI, SDK, CLI, and agent runtime surfaces
+- Structured evidence, rollups, outcome taxonomy, and agent-consumable telemetry for governance and security analytics
 
-Safety and policy controls are applied through each stage.
+## From signal to remediation
 
-Patch lifecycle operations are available through:
+Canonical remediation flow:
 
-- CLI: `autoremediator patches list`, `autoremediator patches inspect`, `autoremediator patches validate`
-- SDK: `listPatchArtifacts`, `inspectPatchArtifact`, `validatePatchArtifact`
-- MCP and OpenAPI: equivalent patch artifact tools and routes
+1. lookup CVE intelligence
+2. inspect installed dependency inventory
+3. match vulnerable installed versions
+4. attempt safe direct dependency version bump
+5. if transitive, attempt package-manager-native override or resolution
+6. if still unresolved, attempt controlled patch fallback and emit patch artifacts
+
+Outputs remain deterministic across interfaces, including `strategyCounts`, `dependencyScopeCounts`, and `unresolvedByReason`, so CI systems, workflow engines, autonomous agents, and orchestration runtimes can route outcomes without reparsing nested result trees.
 
-## Trust and Advisory Sources
+Patch artifacts are written to `patchesDir` with `.patch.json` manifests and can be listed, inspected, and validated in follow-on automation.
 
-The remediation engine relies on public vulnerability intelligence sources and deterministic policy checks.
+## Intelligence that drives action
 
 Primary sources:
 
-- [OSV](https://osv.dev)
-- [GitHub Advisory Database](https://github.com/advisories)
-- [NVD](https://nvd.nist.gov)
+- [OSV](https://osv.dev): ecosystem-first vulnerability records and affected or fixed ranges
+- [GitHub Advisory Database](https://github.com/advisories): package advisories and ecosystem metadata
+- [NVD](https://nvd.nist.gov): severity context and CVE reference data
 
-Supplemental enrichment and prioritization sources:
+Enrichment and prioritization sources:
 
-- [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
-- [FIRST EPSS](https://www.first.org/epss/)
-- [CVE Services](https://www.cve.org/)
-- [GitLab Advisory Database](https://advisories.gitlab.com)
-- [CERT/CC Vulnerability Notes](https://www.kb.cert.org/vuls/)
-- [deps.dev](https://deps.dev)
-- [OpenSSF Scorecard](https://securityscorecards.dev)
+- [CISA KEV](https://www.cisa.gov/known-exploited-vulnerabilities-catalog): known-exploited vulnerability signal
+- [FIRST EPSS](https://www.first.org/epss/): exploit probability and percentile scoring
+- [CVE Services](https://www.cve.org/): additional CVE references and descriptions
+- [GitLab Advisory Database](https://advisories.gitlab.com): supplemental advisory matching
+- [CERT/CC Vulnerability Notes](https://www.kb.cert.org/vuls/): analyst context for selected CVEs
+- [deps.dev](https://deps.dev): package metadata coverage checks
+- [OpenSSF Scorecard](https://securityscorecards.dev): package trust and repository posture signals
 - Optional vendor and commercial feeds via environment-configured connectors
 
-Trust controls:
+Trust model principles:
 
-- correlate advisory data with local dependency inventory before action
-- prefer safe version remediation when fixed versions are available
-- emit structured evidence so every remediation attempt is traceable
-- preserve unresolved status when confidence or validation gates fail
+- Correlate across multiple advisory, exploitability, and trust sources
+- Preserve evidence so remediation decisions remain auditable
+- Enforce policy and validation gates before outcomes are marked resolved
+- Treat low-confidence or unresolved outcomes as explicit escalation inputs
 
-## Surfaces
+## Built for every surface
 
-- CLI: workflow and CI execution
-- SDK: custom automation programs (`remediate`, `planRemediation`, `remediateFromScan`)
-- MCP: AI host integrations, including Claude Mythos workflows
-- OpenAPI: service-based automation
+- CLI: workflow jobs and CI runs
+- SDK: `remediate`, `planRemediation`, `remediateFromScan`
+- MCP server: agent ecosystem integration, tool invocation, and LLM-orchestrated workflows
+- OpenAPI server: service-based integration and centralized remediation operations
+- VS Code extension: Node CVE Remediator for editor-side scanning and fix actions
 
-Public API naming canon: `runTests`, `policy`, `evidence`, `patchCount`, and `patchesDir`.
+Patch lifecycle operations are exposed consistently:
 
-## Documentation
+- CLI: `autoremediator patches list`, `autoremediator patches inspect`, `autoremediator patches validate`
+- SDK: `listPatchArtifacts`, `inspectPatchArtifact`, `validatePatchArtifact`
+- MCP and OpenAPI: equivalent patch lifecycle operations
 
-- [Docs Home](https://rawlings.github.io/autoremediator/)
-- [Getting Started](https://rawlings.github.io/autoremediator/docs/getting-started): install and first remediation runs
-- [CLI Reference](https://rawlings.github.io/autoremediator/docs/cli): command and option semantics
-- [Scanner Inputs](https://rawlings.github.io/autoremediator/docs/scanner-inputs): scanner adapters and format constraints
-- [Policy and Safety](https://rawlings.github.io/autoremediator/docs/policy-and-safety): policy precedence and operational guardrails
-- [API and SDK](https://rawlings.github.io/autoremediator/docs/api-sdk): public programmatic entry points
-- [Integrations](https://rawlings.github.io/autoremediator/docs/integrations): CI workflows and service integrations
-- [Contributor Guide](https://rawlings.github.io/autoremediator/docs/contributor-guide): architecture and extension guidance
+## Designed for agentic workflows
+
+Recommended orchestration flow:
+
+1. call `planRemediation` to generate a non-mutating plan
+2. apply `remediate` after policy and approval checks
+3. inspect and validate patch artifacts when fallback patching occurs
+
+Public naming canon across surfaces: `runTests`, `policy`, `evidence`, `patchCount`, `patchesDir`.
 
-## Product Direction
+Native change-request support includes GitHub and GitLab workflows, including grouped scan strategies, orchestration-friendly run metadata, and plan-first execution patterns for agentic systems.
 
-- Prioritize automation workflows over one-off manual runs
-- Configure policy and branch protection before broad rollout
-- Use CI summaries and evidence outputs for operational governance
+Packaging shortcut: `pnpm build:vsix` builds the publishable VSIX from the repository root.
 
-## Package
+## Use cases
 
-- [npm package](https://www.npmjs.com/package/autoremediator)
-- [repository](https://github.com/Rawlings/autoremediator)
+- Autonomous security automation in GitHub workflows and CI/CD pipelines
+- Deterministic CI gating for unresolved dependency exposure
+- Scanner-to-remediation conversion for high-volume vulnerability backlogs
+- Embedded remediation for internal AI assistants, copilots, bots, and security platforms
+- Portfolio-wide standardization across large Node.js service estates
+
+## Documentation
+
+- [Docs Home](https://rawlings.github.io/autoremediator/)
+- [Getting Started](https://rawlings.github.io/autoremediator/docs/getting-started): setup, first run, and result interpretation
+- [CLI Reference](https://rawlings.github.io/autoremediator/docs/cli): commands, options, and CI semantics
+- [Scanner Inputs](https://rawlings.github.io/autoremediator/docs/scanner-inputs): supported formats and parsing constraints
+- [Policy and Safety](https://rawlings.github.io/autoremediator/docs/policy-and-safety): policy precedence, safeguards, and fallback controls
+- [API and SDK](https://rawlings.github.io/autoremediator/docs/api-sdk): programmatic integration and CI summary utilities
+- [Integrations](https://rawlings.github.io/autoremediator/docs/integrations): GitHub Actions, MCP, OpenAPI, and multi-stage pipelines
+- [Agent Ecosystems](https://rawlings.github.io/autoremediator/docs/agent-ecosystems): MCP host setup and orchestration examples
+- [Contributor Guide](https://rawlings.github.io/autoremediator/docs/contributor-guide): architecture and contribution standards
+
+## Project References
+
+- [Contributing](CONTRIBUTING.md)
+- [Agent Modes](AGENTS.md)
+- [LLM Context Summary](llms.txt)
 
 ## License