Vulnerable Dependency Remediation Tool

An LLM-agnostic tool that takes a security team's vulnerability advisory (an Excel export), scopes it to one Spring Boot Maven application's fixable Java library findings, applies the recommended version upgrades to the project's pom.xml, and confirms the project still builds — without a developer hand-hunting through thousands of rows.

The product ships as an MCP (Model Context Protocol) server wrapped over a deterministic Python engine, so it imports into VS Code and IntelliJ AI assistants and works with the developer's model of choice. A plain CLI over the same engine is provided as a zero-LLM fallback.

Full design and roadmap: docs/dependency-remediation-tool-plan_1.md

Why this exists

Dependabot, Renovate, Mend's native PRs, and OWASP Dependency-Check all scan against public CVE feeds. The gap this tool fills: it is driven by the security team's own curated advisory export as the source of truth, scoped to a single app's Java libraries, applied through one LLM-agnostic interface that runs in any team's IDE.

Related MCP server: Java Testing Agent

Scope (v1)

v1 covers Spring Boot Maven apps and stops at a green build. Raising a PR, Mend API integration, and LLM-assisted build recovery are Phase 2 (see the plan).

Transitive / BOM-managed Java findings are in scope: they're remediated via a <dependencyManagement> version pin, verified with mvn dependency:tree (this matters because the advisory scans the resolved artifact, so most findings are managed/transitive, not hand-pinned <version> tags).

Non-goals (v1): no Mend/portal connection, no container/OS package remediation, no Gradle, no automated PRs. Also deferred: <exclusions>-based surgery and auto-applying BOM/parent upgrades (those are suggested for manual review). See the plan for the exact boundary.

How it works

advisory.xlsx ──► filter (owner + Java + not base-image)
              ──► extract (DetailedName, Version, RecommendedVersion)
              ──► dedupe (highest RecommendedVersion wins, Maven-aware)
              ──► classify resolution (direct / property / managed / transitive)
              ──► apply to pom.xml: edit <version>/property, or add a
                  <dependencyManagement> pin for managed/transitive (dry-run by default)
              ──► mvn clean install (green) + mvn dependency:tree (resolved version check)

Architecture

Standard src/ package layout. The deterministic engine (core/) is the product; the CLI and MCP server are thin adapters over it.

src/dep_remediation/
├── core/                       # LLM-agnostic engine (the real product)
│   ├── advisory_parser.py      # read Excel, filter, extract, dedupe -> normalized list   [Phase 1 ✅]
│   ├── version_compare.py      # Maven-aware version comparison                            [Phase 2 ✅]
│   ├── pom_fixer.py            # classify resolution + apply upgrades to pom.xml            [Phase 3 ✅]
│   └── build_runner.py         # mvn clean install + dependency:tree resolution check       [Phase 4 ✅]
├── cli.py                      # plain CLI adapter (parse / fix / verify subcommands)        [✅]
└── mcp_server.py               # FastMCP server (parse_advisory + apply_fixes + verify_build) [Phase 5 ✅]

Entry points (from pyproject.toml): dep-remediation (CLI) and dep-remediation-mcp (MCP stdio server). See CLAUDE.md.

Getting started

Requires Python 3.11+ (and a Maven install — mvn on PATH or a project mvnw wrapper — for the verify step). pyproject.toml is the single source of truth for dependencies — works with either uv (recommended) or plain pip.

# uv
uv sync

# or pip
python -m venv .venv
.venv\Scripts\activate          # Windows  (source .venv/bin/activate on macOS/Linux)
pip install -e ".[dev]"

Parse an advisory (Phase 1)

# Human-readable summary  (console script, or: python -m dep_remediation.cli ...)
dep-remediation parse tests/fixtures/dummy_advisory.xlsx --app app-alpha

# Machine-readable output
dep-remediation parse tests/fixtures/dummy_advisory.xlsx --app app-alpha --json

Example output:

App: app-alpha
  Rows in sheet:           10
  Rows for this app:       9
  Java library rows:       7
  Skipped (other owner):   1
  Skipped (container/OS):  2
  Skipped (base image):    1
  Skipped (missing data):  0

Unique libraries to fix: 4
  LIBRARY                                          CURRENT        -> RECOMMENDED
  com.fasterxml.jackson.core:jackson-databind      2.13.0         -> 2.15.4
  io.netty:netty-codec-dns                         4.2.4.Final    -> 4.2.13.Final
  io.netty:netty-handler                           4.2.4.Final    -> 4.2.15.Final
  org.springframework:spring-core                  5.3.32         -> 6.2.11

Conflicts resolved (highest version wins): 1
  io.netty:netty-handler: chose 4.2.15.Final  from ['4.2.13.Final', '4.2.15.Final']

Fix a pom (Phase 3)

Classifies how each flagged library resolves in the pom and applies the upgrade — editing a direct <version>/property, or adding a <dependencyManagement> pin for BOM-managed/transitive libraries. Dry-run by default (prints the diff); pass --apply to write. Idempotent and never downgrades.

Multi-module reactors are auto-targeted: point fix at the project dir or aggregator pom and the engine routes each finding to the correct pom on its own — direct/property findings are edited in the module that declares them, while managed/transitive findings are pinned once in the aggregator (inherited by every module). No per-module commands.

# Dry-run: show the resolution log + diff (add --json for machine-readable output)
dep-remediation fix path/to/pom.xml --from-advisory tests/fixtures/dummy_advisory.xlsx --app app-alpha

# Apply the changes (single pom)
dep-remediation fix path/to/pom.xml --from-advisory tests/fixtures/dummy_advisory.xlsx --app app-alpha --apply

# Whole multi-module project in one command (point at the project dir or aggregator pom)
dep-remediation fix path/to/project --from-advisory advisory.xlsx --app my-app --apply

Each finding is reported with its resolution class and the strategy applied:

Actions: 4
  [transitive/add-pin]   com.fasterxml.jackson.core:jackson-databind: (managed/transitive) -> 2.15.4  (added <dependencyManagement> pin)
  [transitive/add-pin]   io.netty:netty-codec-dns: (managed/transitive) -> 4.2.13.Final  (added <dependencyManagement> pin)
  [direct/edit-version]  io.netty:netty-handler: 4.2.4.Final -> 4.2.15.Final
  [transitive/add-pin]   org.springframework:spring-core: (managed/transitive) -> 6.2.11  (added <dependencyManagement> pin)

followed by a unified diff — e.g. a parent-managed/transitive pom gets a pinned block:

+    <dependencyManagement>
+        <dependencies>
+            <!-- security pin -->
+            <dependency>
+                <groupId>io.netty</groupId>
+                <artifactId>netty-handler</artifactId>
+                <version>4.2.15.Final</version>
+            </dependency>
+        </dependencies>
+    </dependencyManagement>

Verify the build (Phase 4)

Runs mvn clean install and gates on a green build, then runs mvn dependency:tree to confirm each finding's resolved version is actually the recommended one (a pin can be silently overridden by a BOM). Point it at the aggregator root for a multi-module reactor — resolution is checked across every module.

# build-only gate
dep-remediation verify ./my-app

# build + resolved-version check against the advisory
dep-remediation verify ./my-app --from-advisory tests/fixtures/dummy_advisory.xlsx --app app-alpha

# fix and verify in one shot (only chains after a successful --apply)
dep-remediation fix ./my-app/pom.xml --from-advisory tests/fixtures/dummy_advisory.xlsx --app app-alpha --apply --verify

Overall success requires the build green and every finding resolved; unresolved findings are surfaced for manual review. Honest limit: a green build proves the project compiles, not that a forced transitive pin is runtime-safe.

Recover from a red build

When an applied bump breaks the build, verify returns a reasoning-ready failure: a failure_kind (dependency_resolution / compilation / test), the suspect coordinates it could pin down, and the just-applied bumps (likely culprits). You then re-apply a curated fix set — drop or re-target the offender — and verify again:

# drop a finding from this run (-> manual-review); repeatable
dep-remediation fix ./my-app/pom.xml --from-advisory advisory.xlsx --app my-app --apply \
    --skip org.apache.commons:commons-text

# re-target a finding to a known-good version instead; repeatable
dep-remediation fix ./my-app/pom.xml --from-advisory advisory.xlsx --app my-app --apply \
    --override io.netty:netty-handler=4.2.16.Final

The engine performs the edit; the decision of what to retry is the host LLM's job (it drives this bounded loop via the apply_fixes overrides + verify_build MCP tools — see the remediate-dependencies skill). The engine never reverts, so each attempt re-applies to a clean copy. A green build with any finding still unresolved is reported as needs review, never success. A full captured run is in examples/spring-boot-sample/RECOVERY.md.

Run the tests

pytest -q

Verify version comparison (Phase 2)

python -m dep_remediation.core.version_compare   # runs the built-in self-tests

Run as an MCP server (Phase 5 — parse_advisory + apply_fixes + verify_build)

The server speaks MCP over stdio, so an MCP client (VS Code / IntelliJ AI assistant, Claude Desktop, etc.) launches it. Run directly:

dep-remediation-mcp           # or: uv run dep-remediation-mcp

Full setup guide (VS Code, IntelliJ, Claude Desktop configs + troubleshooting): docs/mcp-setup.md. The protocol surface is covered by tests/test_mcp_server.py (an in-process MCP client round-trip).

Example client config (mcpServers entry):

{
  "mcpServers": {
    "dep-remediation": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/dependency-remediation-mcp-server", "run", "dep-remediation-mcp"]
    }
  }
}

Tools exposed today:

• parse_advisory(xlsx_path, app, base_image_filter=True) — the deduped fix list.

• apply_fixes(pom_path, xlsx_path, app, apply=False) — classify + apply upgrades to a pom; dry-run by default, returns the resolution log, manual-review bucket, and diff.

• verify_build(project_dir, xlsx_path="", app="") — mvn clean install + (optional) resolved-version check; returns the build result with actionable failure context.

(stdio transport reserves stdout for JSON-RPC; the server logs to stderr.)

Try it end to end (example app)

examples/spring-boot-sample/ is a real, intentionally vulnerable multi-module (reactor) Spring Boot app used as the end-to-end test bed — one seeded finding per resolution class (direct / property / managed / transitive), spread across modules so the reactor-aware verify (build + cross-module resolution check at the aggregator root) is exercised on live Maven. Captured runs of the happy path and the build-failure recovery loop are in SHAKEOUT.md and RECOVERY.md.

dep-remediation parse examples/spring-boot-sample/advisory.xlsx --app sample-app
# apply + verify on a COPY so the committed sample stays in its "before" state

The advisory sheet

A single-tab workbook. The engine reads clean columns only — no prose parsing required for the fix:

Description carries the same facts as templated prose and is used only as a fallback for coordinates when DetailedName is blank.

Trust & transparency

Because the tool edits other teams' code it is auditable by design:

• Dry-run by default — show the diff, apply on confirmation.

• Skipped-rows log — how many rows dropped and why.

• Conflict log — which duplicate versions were seen and which won.

• Resolution log — per finding: how it resolves (direct / property / managed / transitive) and the strategy applied (in-place edit vs. <dependencyManagement> pin), plus a manual-review bucket for anything not safely fixable.

• Idempotent, no-downgrade edits — re-running a fix is a no-op; an existing higher version is never lowered.

• Build gating + resolved-version check — success is never claimed on a broken build, and mvn dependency:tree must confirm each finding actually resolved to the recommended version (a pin silently overridden by a BOM is flagged, not hidden).

Roadmap (Phase 2)

Automated PR creation → LLM-assisted build recovery → Mend API source → broader pom coverage → CI/scale. The deterministic core/ engine and the "never claim success on a broken build" rule are invariant. See section 13 of the plan.