DockerPulse

AI-powered CLI to scan Docker images for vulnerabilities and generate actionable remediation plans — local with Ollama or cloud with any OpenAI-compatible API.

---

What it does

DockerPulse follows a Scan → Enrich → Heal loop:

1. Scan — runs Trivy against any Docker image and presents a severity-coloured CVE table.
2. Heal — sends findings to an LLM and streams a concrete remediation plan: base-image upgrade, package pins, and a hardened Dockerfile with digest-pinned FROM and non-root USER.
3. Serve — exposes the same tools as an MCP server so Claude Desktop or any MCP client can call them without a terminal.

Local mode (default): everything runs on your machine — no API keys, no data leaves your network.
Cloud mode: set one api_key config option to route LLM calls to Groq, Cerebras, OpenRouter, or any OpenAI-compatible endpoint.

---

Quick Start

Option A — Docker Compose (zero install)

Only Docker required. No Python, no Trivy, no Ollama to install.

git clone https://github.com/erasmo-dominguez-stuff/docker-pulse
cd docker-pulse
cp .env.example .env          # optional: edit OLLAMA_MODEL or DOCKERPULSE_PORT
make stack-up                  # build image, pull model, start all services

make stack-up starts three services: Ollama (local LLM), an init container that pulls the model, and the DockerPulse MCP server at http://localhost:8000/sse.

Use the ./dp wrapper for CLI commands:

./dp doctor
./dp scan python:3.8-slim
./dp heal python:3.8-slim --severity critical,high --output dockerfile

Option B — Native install

# Prerequisites: Python >= 3.11, Trivy, and Ollama (or an API key)
brew install trivy
brew install ollama && ollama pull deepseek-coder:6.7b

git clone https://github.com/erasmo-dominguez-stuff/docker-pulse
cd docker-pulse
pip install -e '.[dev]'
dockerpulse doctor     # verify everything is ready

No GPU? Point DockerPulse at a free cloud API instead — see docs/providers.md.

---

Four commands

# Scan an image for CVEs
dockerpulse scan python:3.8-slim --severity critical,high

# Stream an AI remediation plan (or Dockerfile, or shell commands)
dockerpulse heal python:3.8-slim --output dockerfile --save Dockerfile.hardened

# Verify your setup
dockerpulse doctor

# Start the MCP server (Claude Desktop integration)
dockerpulse serve

---

Documentation

Document	Description
docs/cli.md	Full CLI reference — all commands, options, and examples
docs/configuration.md	Config files, env vars, all options
docs/providers.md	Local Ollama setup and cloud providers (Groq, Cerebras, OpenRouter …)
docs/mcp.md	MCP server setup, Claude Desktop config, SSE vs stdio
docs/architecture.md	Hexagonal architecture, Mermaid diagrams, data flow
docs/comparison.md	Feature matrix vs Docker Scout, Snyk, Grype, Trivy
docs/adr/001-hexagonal-architecture.md	ADR: why hexagonal architecture
docs/adr/002-scanner-abstraction.md	ADR: why Trivy as primary scanner
docs/adr/003-openai-compatible-provider.md	ADR: why a single OpenAI-compatible adapter
docs/proposals/001-rag-cve-enrichment.md	Proposal: RAG pipeline for real-time CVE context
CONTRIBUTING.md	Developer guide — adding scanners, providers, commands, tests

---

GitHub Actions

Block PRs on CRITICAL CVEs with a single step:

- uses: erasmo-dominguez-stuff/docker-pulse/.github/actions/dockerpulse@main
  with:
    image: python:3.8-slim
    severity: critical,high
    fail-on: CRITICAL

Results are posted to the job summary. See .github/actions/dockerpulse/README.md for all inputs and outputs.

---

Roadmap

• scan — CVE table with Trivy
• heal — streaming LLM remediation (plan / Dockerfile / commands)
• doctor — dependency checker
• MCP server — scan_image, heal_image, get_image_history
• Hexagonal architecture — pluggable Scanner and AIProvider ports
• External providers — Groq, Cerebras, OpenRouter via OpenAI-compatible API
• GitHub Actions — reusable workflow with fail-on threshold
• RAG + CVE enrichment — real-time NVD/GHSA context (proposal)
• SBOM generation — CycloneDX / SPDX
• Grype adapter — second scanner source
• Scan history — SQLite persistence per image
• Image diff — compare security posture between versions

---

License

MIT