Gatewarden Shield Image Builder MCP

AI-Assisted Hardened Container Image Generation

Generate production-grade Dockerfiles following the 15 GWShield hardening pillars. Works with Claude, Gemini, OpenCode, and any MCP-compatible AI agent.

What this tool does

This is a Model Context Protocol (MCP) server that encodes the full GWShield hardening methodology into an AI-accessible tool. It enables any AI coding agent to generate Dockerfiles, smoke tests, version pins, and supporting files that conform to the same standards used by the production GWShield image pipeline.

The server does not build images. It generates files.

The 15 Hardening Pillars

Every generated Dockerfile enforces these pillars:

Installation

No global install required. The server runs on demand via npx.

Run once to confirm the server starts:

npx -y gwshield-image-builder-mcp

Then add it to your agent config:

Claude Desktop / Claude Code

File: ~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "gwshield-image-builder": {
      "command": "npx",
      "args": ["-y", "gwshield-image-builder-mcp"]
    }
  }
}

Restart Claude Desktop after saving.

OpenCode

File: ~/.config/opencode/config.json or opencode.json (project)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gwshield-image-builder": {
      "type": "local",
      "command": ["npx", "-y", "gwshield-image-builder-mcp"],
      "enabled": true
    }
  }
}

OpenCode uses "mcp" (not "mcpServers") with type: "local" and a command array.

Cursor

File: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "gwshield-image-builder": {
      "command": "npx",
      "args": ["-y", "gwshield-image-builder-mcp"]
    }
  }
}

Continue (VS Code / JetBrains)

File: .continue/mcpServers/gwshield.yaml (workspace)

name: GWShield Image Builder
version: 0.0.1
schema: v1
mcpServers:
  - name: gwshield-image-builder
    command: npx
    args:
      - "-y"
      - "gwshield-image-builder-mcp"

Gemini CLI

File: ~/.gemini/settings.json

{
  "mcpServers": {
    "gwshield-image-builder": {
      "command": "npx",
      "args": ["-y", "gwshield-image-builder-mcp"]
    }
  }
}

From source

git clone git@github.com:gwshield/images-mcp.git
cd images-mcp
npm install
npm run build

Then point your MCP client to:

{
  "mcpServers": {
    "gwshield-image-builder": {
      "command": "node",
      "args": ["path/to/images-mcp/dist/index.js"]
    }
  }
}

All agents use the npx stdio transport — no daemon, no port, no persistent process.

MCP Tools

MCP Prompts

MCP Resources

Example prompts

Ask your agent any of these after connecting the server:

"Harden my Go HTTP service" Uses harden_image → suggest_runtime_base → generate_dockerfile (distroless runtime, CGO_ENABLED=0, UID 65532, pinned builder digest) → validate_dockerfile confirms all 15 pillars.

"Review my existing Dockerfile" Uses review_dockerfile → validate_dockerfile. Returns a structured report: which pillars pass, which fail, and concrete fixes for each gap.

"Generate a smoke test for my nginx image" Calls generate_smoke_test with the image family and binary path. Returns a script that checks binary execution, non-root user, no shell, and clean exit code.

"Build, scan, and fix until clean" Uses build_test_iterate. The agent guides you through docker build → trivy image → fix → repeat until Trivy reports zero HIGH or CRITICAL findings (max 5 iterations).

Image Family Classification

The server classifies services into build families to select the correct Dockerfile pattern:

Supply Chain Security

Verifying a published version

Consumers can verify the provenance attestation for any published version using cosign:

# Verify SLSA provenance attestation for a specific version
cosign verify-attestation \
  --type slsaprovenance1 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp "^https://github.com/gwshield/images-mcp/.github/workflows/publish.yml@refs/tags/v" \
  $(npm pack gwshield-image-builder-mcp --dry-run --json | jq -r '.[0].filename')

Alternatively, provenance is visible directly on the npm registry page under the "Provenance" tab for each published version.

Reporting security issues

See SECURITY.md for the vulnerability disclosure policy. Use GitHub private security advisories to report vulnerabilities confidentially.

Build philosophy

This tool encodes the same hardening philosophy used across all Gatewarden Shield images:

• From source, from scratch -- no vendor base images
• Security first, not convenience first -- no init scripts, no shell
• Scan evidence required -- no claims without proof
• Transparent false positives -- scanner noise documented, not hidden

Inspiration and Acknowledgments

The design of this MCP server was influenced by Viktor Farcic's work on AI-assisted Dockerfile generation. His generate-dockerfile prompt in the dot-ai and dot-ai-stack repositories demonstrated that encoding Dockerfile best practices as structured AI prompts produces consistently better output than ad-hoc generation.

Key ideas we adopted or adapted from his approach:

• Project-analysis-first workflow -- analyze the codebase before generating, rather than relying solely on user-provided parameters
• Explicit .dockerignore generation -- treat .dockerignore as a first-class build artifact, not an afterthought
• Verify everything before adding it -- never assume a package, path, or binary exists; always verify from the actual project context
• Build-test-iterate loop -- build the image, run it, check logs, run linters and scanners, iterate until clean (available via the build_test_iterate prompt)

Where Viktor's approach is language-agnostic and general-purpose, this server is opinionated and security-hardened: it enforces the 15 GWShield pillars, targets scratch and distroless runtimes exclusively, and generates the full file set (Dockerfile, versions.env, smoke.sh, allowlist, risk statement) required by the GWShield image pipeline.

Thank you, Viktor, for making your prompts and methodology open source.

License

Apache-2.0 -- Gatewarden / RelicFrog Foundation