# rawlings/autoremediator architecture

> Architecture diagram of the GitHub repository rawlings/autoremediator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rawlings/autoremediator
- Repository: https://github.com/rawlings/autoremediator

## Overview

Autoremediator is a pnpm monorepo centered on a single TypeScript remediation engine, with multiple delivery surfaces layered on top of it. The core architectural idea is: ingest vulnerability findings or direct CVE requests, enrich them with external intelligence, inspect the local dependency graph, attempt safe remediation, and emit deterministic evidence and summary outputs for downstream automation.

At a high level, the repository splits into three major product areas:

1. Core remediation platform
2. User-facing and machine-facing surfaces
3. Documentation and release/publishing infrastructure

Core platform
- `packages/core` is the main subsystem and contains almost all runtime logic.
- It is organized around a shared API layer, a remediation pipeline, scanner ingestion, external intelligence fetchers, and platform abstractions.
- This package is the source of truth for behavior exposed by the CLI, SDK, MCP server, OpenAPI server, and VS Code extension.

The core architecture can be thought of as a pipeline with supporting services:

A. Input and orchestration layer
- `src/api` defines the primary programmatic contract.
- Key entry points include `remediate`, `remediate-from-scan`, and reporting/SARIF helpers.
- `options-schema.ts`, `contracts.ts`, and `context.ts` suggest a typed API boundary that normalizes configuration, runtime context, and request/response shapes.
- `scan-execution.ts` and `scan-outcome.ts` indicate the API can run as a direct remediation flow or as a scanner-driven flow, with explicit outcome modeling.
- This layer is where policy, scan results, and execution options are converted into a structured remediation request.

B. Scanner ingestion boundary
- `src/scanner` is responsible for translating external scanner outputs into the engine’s internal model.
- Supported adapters include:
  - `npm-audit`
  - `yarn-audit`
  - `sarif`
- `parse-input.ts` and `unique-cve-ids.ts` suggest normalization of incoming scan data, de-duplication of vulnerability identifiers, and conversion into a canonical vulnerability set.
- This is an important architectural boundary: the engine does not depend directly on each scanner’s native format. Adapters isolate scanner-specific parsing from the remediation logic.

C. Intelligence and advisory enrichment
- `src/intelligence` contains the sources used to enrich and prioritize vulnerabilities.
- Public advisory sources include OSV, GitHub Advisory Database, NVD, GitLab Advisory Database, and CVE Services.
- Prioritization / enrichment signals include CISA KEV, FIRST EPSS, deps.dev, CERT/CC, OpenSSF Scorecard, and optional external feeds.
- The intelligence layer aggregates multiple external services to produce a more confident view of vulnerability relevance and fixability.
- This layer materially affects the remediation decision because the system prioritizes not just “is vulnerable,” but “how risky and actionable is this issue.”

D. Platform and policy layer
- `src/platform` contains cross-cutting operational concerns:
  - configuration
  - package-manager detection / behavior
  - repository lock and inventory logic
  - evidence generation
  - idempotency
  - policy enforcement
  - shared types
- `policy.ts` is especially important because the README emphasizes policy-driven automation and safety gates.
- `repo-lock.ts` and `package-manager.ts` imply the engine understands repository state and package manager semantics, which are essential for safe dependency modification.
- `evidence.ts` suggests the engine records structured proof of what it inspected and changed, enabling auditability and deterministic CI summaries.

E. Remediation engine
- `src/remediation` is the heart of the product.
- The design is layered into:
  - an orchestration/prompting layer for agentic or guided remediation
  - a local execution layer
  - strategy selection and fallback handling
  - concrete tools for patching, version bumps, package overrides, inventory checks, and CVE lookup
- `pipeline.ts` is the central flow controller.
- `local/` contains the local execution strategy, including primary and fallback paths.
- `runtime-tools.ts` and `orchestration-prompt.ts` suggest the engine can run in a tool-driven or agent-assisted mode, while still remaining deterministic at the output boundary.
- The tool files show the remediation sequence in concrete terms:
  - verify inventory and version matches
  - look up fixed versions
  - fetch package source if needed
  - generate or apply patches
  - apply direct version bumps
  - apply package-manager-native overrides/resolutions when the vulnerable dependency is transitive
- The pipeline reflects the workflow described in the README: direct upgrade first, then override/resolution, then patch fallback if necessary.
- This is a key architectural boundary: mutation of the repository is isolated to the remediation subsystem, not mixed into scanner parsing or intelligence lookup.

F. Output and reporting
- `src/api/reporting.ts` and `sarif.ts` indicate the system can emit structured reports for CI and scanners.
- The README mentions deterministic summaries including `strategyCounts`, `dependencyScopeCounts`, and `unresolvedByReason`.
- These outputs are important because they are designed for downstream routing, dashboards, and automation without reparsing nested result trees.
- The output layer is therefore a deliberate contract boundary between the engine and external automation systems.

Interfaces and delivery surfaces
The repository exposes the same core engine through several fronts:

1. CLI
- `packages/core/src/cli` contains the command-line interface.
- `program.ts`, `runners.ts`, and `output.ts` indicate command setup, execution dispatch, and formatting logic.
- The CLI is likely the primary operational surface for CI jobs and local runs.
- It wraps the core API rather than duplicating remediation logic.

2. MCP server
- `packages/core/src/mcp/server.ts` exposes the engine through the Model Context Protocol.
- This is intended for agentic tooling and AI-assisted workflows.
- The presence of a dedicated MCP server means the core functionality is packaged as a tool-safe service interface, not only as a CLI.

3. OpenAPI server
- `packages/core/src/openapi/server.ts` exposes the engine as an HTTP API.
- This makes the remediation platform usable as a service integration point for internal platforms or bots.
- The architecture separates protocol concerns from the engine so that HTTP handling does not leak into remediation logic.

4. VS Code extension
- `packages/vscode-extension` provides editor-side integration.
- `extension.ts` and `runner.ts` suggest the extension delegates execution to the core engine or a packaged runner.
- This is a separate UI boundary that consumes the same remediation capabilities but is optimized for developer workflows.

Documentation and product presentation
- `packages/docs` is a Vite-based documentation site.
- It contains documentation pages for CLI, API SDK, scanner inputs, policy and safety, integrations, and contributor guidance.
- This package is not part of runtime remediation; it is the product documentation boundary.
- Its structure mirrors the architecture of the main system, which is helpful when drawing a diagram because the docs reflect the intended subsystem decomposition.

Build, packaging, and release infrastructure
- The root contains repository-level packaging and release automation.
- `Dockerfile` indicates a containerized distribution path.
- GitHub Actions workflows publish:
  - Docker images
  - npm packages
  - VS Code extension artifacts
  - docs deployment
  - tagging automation
- `action.yml` indicates the repository also ships as a GitHub Action.
- This means the same core engine is packaged for several deployment modes: CLI/npm, Docker, GitHub Action, VS Code extension, and service interfaces.
- Architecturally, these are distribution channels on top of the same core logic, not separate implementations.

External dependencies and data sources
The core runtime depends heavily on external intelligence services, but these are used as read-only enrichment sources rather than authoritative control planes:
- OSV for vulnerability records
- GitHub Advisories for ecosystem metadata
- NVD for CVE context
- CISA KEV for known-exploited status
- FIRST EPSS for exploit probability
- CVE Services, GitLab advisories, CERT/CC, deps.dev, OpenSSF Scorecard, and optional vendor feeds for supplemental context

These services affect prioritization and confidence, but not the local repository mutation logic itself. That separation is important: intelligence is federated, remediation is local and policy-governed.

Main data flow
A typical flow through the architecture is:

1. A user or automation surface invokes the engine through CLI, SDK/API, MCP, OpenAPI, or the VS Code extension.
2. Input may be a direct CVE request or a scan result from npm audit, yarn audit, or SARIF.
3. The engine normalizes the input and deduplicates vulnerability identifiers.
4. Intelligence services are queried to enrich and prioritize the issue set.
5. The platform layer inspects the repository state, dependency inventory, lock/repo metadata, and policy constraints.
6. The remediation pipeline attempts:
   - direct dependency version bumps
   - package-manager-native overrides/resolutions for transitive issues
   - patch fallback when safe and allowed
7. Validation and safety gates determine whether outcomes can be marked resolved.
8. Structured evidence, summaries, and SARIF/report outputs are produced for CI, dashboards, or orchestration systems.

Architectural boundaries that matter for a diagram
If you are drawing this repository, the most important boundaries are:

- Core engine vs. delivery surfaces
  - Everything in CLI, MCP, OpenAPI, VS Code, and GitHub Action packaging is a shell around the core package.

- Scanner adapters vs. canonical vulnerability model
  - npm audit, yarn audit, and SARIF are ingestion-specific formats, not the engine’s internal representation.

- Intelligence enrichment vs. remediation execution
  - External APIs supply advisory and risk context; the local pipeline makes the actual remediation decision and filesystem changes.

- Policy/evidence vs. mutation
  - Policy and evidence are first-class control and audit layers that gate or describe the mutation process.

- Direct fix vs. transitive fix vs. patch fallback
  - The engine follows a prioritized remediation strategy, and those paths should be shown as distinct branches in any architecture diagram.

- Distribution artifacts vs. runtime behavior
  - npm package, Docker image, GitHub Action, VS Code extension, docs site, and published servers are separate packaging targets for the same core logic.

In short, Autoremediator is a multi-surface remediation platform with a single TypeScript core. The core is composed of scanner ingestion, vulnerability intelligence aggregation, policy-aware remediation orchestration, and structured reporting. All other packages and workflows primarily expose, package, or document that engine for different operational contexts.

Main entry points: [`packages/core/src/api`](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/api) (API layer), [`packages/core/src/remediation/pipeline.ts`](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/remediation/pipeline.ts) (Pipeline), [`packages/docs`](https://github.com/rawlings/autoremediator/tree/HEAD/packages/docs) (Docs site), [`packages/core/src/scanner`](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/scanner) (Scanner ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Core engine"
  api["API layer<br/>contract"]
  scanner["Scanner ingest<br/>adapter"]
  scanner_adapters["Adapters"]
  intelligence["Intelligence<br/>enrichment"]
  intel_sources["Sources<br/>external feeds"]
  platform["Platform<br/>policy/runtime"]
  policy["Policy<br/>guardrails<br/>[policy.ts]"]
  evidence["Evidence<br/>audit trail<br/>[evidence.ts]"]
  remediation["Remediation<br/>engine"]
  pipeline["Pipeline<br/>orchestrator<br/>[pipeline.ts]"]
  local["Local run<br/>execution path"]
  tools["Tools<br/>actions"]
  reporting["Reporting<br/>outputs<br/>[reporting.ts]"]
end

subgraph "Delivery surfaces"
  cli["CLI<br/>surface"]
  mcp["MCP server<br/>surface<br/>[server.ts]"]
  openapi["HTTP API<br/>surface<br/>[server.ts]"]
  vscode["VS Code<br/>editor extension<br/>[extension.ts]"]
end

subgraph "Docs and release"
  docs_site["Docs site<br/>documentation"]
  action["GitHub Action<br/>distribution<br/>[action.yml]"]
  docker["Container image<br/>distribution"]
end

cli -->|"uses"| api
mcp -->|"uses"| api
openapi -->|"uses"| api
vscode -->|"uses"| api
api -->|"accepts scans"| scanner
scanner -->|"parses"| scanner_adapters
scanner -->|"returns canonical input"| api
api -->|"enriches"| intelligence
intelligence -->|"queries"| intel_sources
api -->|"applies"| platform
platform -->|"enforces"| policy
platform -->|"records"| evidence
api -->|"orchestrates"| remediation
remediation -->|"drives"| pipeline
pipeline -->|"executes"| local
local -->|"uses"| tools
pipeline -->|"checks"| policy
pipeline -->|"emits"| evidence
pipeline -->|"summarizes"| reporting
api -->|"formats"| reporting
docs_site -.->|"documents"| cli
docs_site -.->|"documents"| api
docs_site -.->|"documents"| scanner
docs_site -.->|"documents"| policy
action -->|"packages"| cli
docker -->|"packages"| cli

click api "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/api"
click scanner "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/scanner"
click scanner_adapters "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/scanner/adapters"
click intelligence "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/intelligence"
click intel_sources "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/intelligence/sources"
click platform "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/platform"
click policy "https://github.com/rawlings/autoremediator/blob/master/packages/core/src/platform/policy.ts"
click evidence "https://github.com/rawlings/autoremediator/blob/master/packages/core/src/platform/evidence.ts"
click remediation "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/remediation"
click pipeline "https://github.com/rawlings/autoremediator/blob/master/packages/core/src/remediation/pipeline.ts"
click local "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/remediation/local"
click tools "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/remediation/tools"
click reporting "https://github.com/rawlings/autoremediator/blob/master/packages/core/src/api/reporting.ts"
click cli "https://github.com/rawlings/autoremediator/tree/master/packages/core/src/cli"
click mcp "https://github.com/rawlings/autoremediator/blob/master/packages/core/src/mcp/server.ts"
click openapi "https://github.com/rawlings/autoremediator/blob/master/packages/core/src/openapi/server.ts"
click vscode "https://github.com/rawlings/autoremediator/blob/master/packages/vscode-extension/src/extension.ts"
click docs_site "https://github.com/rawlings/autoremediator/tree/master/packages/docs"
click action "https://github.com/rawlings/autoremediator/blob/master/action.yml"
click docker "https://github.com/rawlings/autoremediator/tree/master/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class api,scanner,scanner_adapters,intelligence,intel_sources,platform,policy,evidence,remediation,pipeline,local,tools,reporting toneBlue
class cli,mcp,openapi,vscode toneAmber
class docs_site,action,docker toneMint
```

## Components

### Core engine

Single TypeScript remediation engine and its internal pipeline layers.

- [API layer](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/api): contract · Typed programmatic boundary for remediation requests, execution context, and reports. · `packages/core/src/api`
- [Scanner ingest](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/scanner): adapter · Normalizes scanner outputs into the engine's canonical vulnerability model. · `packages/core/src/scanner`
- [Adapters](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/scanner/adapters): scanner adapters · Parsers for npm audit, yarn audit, and SARIF inputs. · `packages/core/src/scanner/adapters`
- [Intelligence](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/intelligence): enrichment · Aggregates advisory and risk signals to prioritize and contextualize findings. · `packages/core/src/intelligence`
- [Sources](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/intelligence/sources): external feeds · OSV, GitHub Advisory, NVD, KEV, EPSS, deps.dev, CERT/CC, and related feeds. · `packages/core/src/intelligence/sources`
- [Platform](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/platform): policy/runtime · Cross-cutting repo state, package-manager, evidence, idempotency, and policy concerns. · `packages/core/src/platform`
- [Policy](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/platform/policy.ts): guardrails · Safety and governance checks that constrain remediation behavior. · `packages/core/src/platform/policy.ts`
- [Evidence](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/platform/evidence.ts): audit trail · Structured proof of inspection, mutation, and remediation outcomes. · `packages/core/src/platform/evidence.ts`
- [Remediation](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/remediation): engine · Central orchestration for choosing and executing safe fix strategies. · `packages/core/src/remediation`
- [Pipeline](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/remediation/pipeline.ts): orchestrator · Primary flow controller for direct fixes, overrides, and patch fallback. · `packages/core/src/remediation/pipeline.ts`
- [Local run](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/remediation/local): execution path · Local remediation strategy and fallback execution path. · `packages/core/src/remediation/local`
- [Tools](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/remediation/tools): actions · Concrete operations for version checks, fixed-version lookup, patching, and overrides. · `packages/core/src/remediation/tools`
- [Reporting](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/api/reporting.ts): outputs · Deterministic summaries and SARIF/report helpers for downstream automation. · `packages/core/src/api/reporting.ts`

### Delivery surfaces

CLI, protocol servers, and editor integration that expose the core engine.

- [CLI](https://github.com/rawlings/autoremediator/tree/HEAD/packages/core/src/cli): surface · Command-line interface built on top of the core API. · `packages/core/src/cli`
- [MCP server](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/mcp/server.ts): surface · Model Context Protocol interface for agentic tooling. · `packages/core/src/mcp/server.ts`
- [HTTP API](https://github.com/rawlings/autoremediator/blob/HEAD/packages/core/src/openapi/server.ts): surface · OpenAPI-backed server exposing remediation as a service. · `packages/core/src/openapi/server.ts`
- [VS Code](https://github.com/rawlings/autoremediator/blob/HEAD/packages/vscode-extension/src/extension.ts): editor extension · Editor integration that delegates remediation work to the core engine. · `packages/vscode-extension/src/extension.ts`

### Docs and release

Documentation site and packaging/distribution artifacts.

- [Docs site](https://github.com/rawlings/autoremediator/tree/HEAD/packages/docs): documentation · Vite documentation site for CLI, API, scanner inputs, policy, and integrations. · `packages/docs`
- [GitHub Action](https://github.com/rawlings/autoremediator/blob/HEAD/action.yml): distribution · Workflow/action packaging for automation environments. · `action.yml`
- [Container image](https://github.com/rawlings/autoremediator/tree/HEAD/Dockerfile): distribution · Containerized distribution path for the same core remediation engine. · `Dockerfile`

## Connections

- CLI → API layer: uses · CLI delegates to the shared programmatic API.
- MCP server → API layer: uses · MCP requests are routed through the core API boundary.
- HTTP API → API layer: uses · HTTP server wraps the same remediation API.
- VS Code → API layer: uses · Editor extension invokes the shared engine through packaged runners or API calls.
- API layer → Scanner ingest: accepts scans · API normalizes direct remediation requests and scan-driven remediation flows.
- Scanner ingest → Adapters: parses · Scanner ingestion is implemented through format-specific adapters.
- Scanner ingest → API layer: returns canonical input · Normalized findings flow back into the orchestration boundary.
- API layer → Intelligence: enriches · API-led execution consults external intelligence sources for prioritization.
- Intelligence → Sources: queries · Advisory and risk context is gathered from multiple external feeds.
- API layer → Platform: applies · Runtime config, repository state, and policy are resolved through platform abstractions.
- Platform → Policy: enforces · Policy is the gate for safe automation and mutations.
- Platform → Evidence: records · Evidence generation captures inspection and change history.
- API layer → Remediation: orchestrates · API hands the normalized request to the remediation engine.
- Remediation → Pipeline: drives · Pipeline coordinates the remediation workflow.
- Pipeline → Local run: executes · Local strategy performs the repository-bound remediation work.
- Local run → Tools: uses · Local execution relies on concrete remediation tools.
- Pipeline → Policy: checks · Policy gates are consulted before and during mutation steps.
- Pipeline → Evidence: emits · Remediation decisions and results are written as evidence.
- Pipeline → Reporting: summarizes · Final outcomes are converted into deterministic summaries and SARIF/report outputs.
- API layer → Reporting: formats · API exposes reporting helpers for downstream automation.
- Docs site → CLI: documents · Docs describe command-line usage and behavior.
- Docs site → API layer: documents · Docs cover the public API and SDK contract.
- Docs site → Scanner ingest: documents · Docs explain supported scanner inputs and normalization.
- Docs site → Policy: documents · Docs describe safety and governance rules.
- GitHub Action → CLI: packages · GitHub Action wraps the core runnable surface for automation.
- Container image → CLI: packages · Container image distributes the runnable engine and entrypoints.
