mpak-scanner

Security scanner for MCP bundles (.mcpb). Reference implementation of the mpak Trust Framework (MTF), an open security standard for MCP server packaging.

Built by NimbleBrain, mpak-scanner powers the mpak Certified verification on the mpak registry, analyzing bundles for supply chain risks, code quality issues, and compliance with the MTF specification.

What it does

mpak-scanner analyzes MCP bundles (.mcpb files) for security issues before installation:

• Supply Chain: SBOM generation, vulnerability scanning, dependency analysis
• Code Quality: Secret detection, malicious pattern detection, static analysis
• Artifact Integrity: Manifest validation, content hashes, signatures
• Provenance: Source repository verification, author identity, build attestation
• Capability Declaration: Tool declarations, permission scopes

Compliance Levels

The scanner evaluates bundles against four compliance levels defined in the MTF specification:

Installation

# Install with uv (recommended)
uv pip install mpak-scanner

# Or with pip
pip install mpak-scanner

External Tools

The scanner integrates with these tools for deeper analysis. Controls gracefully skip if a tool is not installed.

Usage

Command Line

# Scan a bundle
mpak-scanner scan bundle.mcpb

# Output JSON report
mpak-scanner scan bundle.mcpb --json

# Check specific compliance level
mpak-scanner scan bundle.mcpb --level 2

Python API

from mpak_scanner import scan_bundle

report = scan_bundle("bundle.mcpb")
print(f"Compliance Level: {report.compliance_level}")
print(f"Risk Score: {report.risk_score}")

for finding in report.findings:
    print(f"[{finding.severity}] {finding.control}: {finding.message}")

Specification

This scanner implements the mpak Trust Framework (MTF). See the full specification for details on compliance levels, controls, and verification methods.

Development

# Install dev dependencies
uv sync --dev

# Run all tests
uv run pytest

# Lint and format
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type check
uv run ty check src/

# Full verification
uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run ty check src/ && uv run pytest

Test Fixtures

The scanner ships with test fixtures for validation:

See tests/fixtures/README.md for details.

Releasing

Releases are automated via GitHub Actions. Pushing a tag triggers the full pipeline: verify, publish to PyPI (via trusted publishing), and build + push Docker image to GHCR.

Version is defined in one place: pyproject.toml. The runtime version (mpak_scanner.__version__, SCANNER_VERSION) is derived automatically via importlib.metadata.

Steps

1. Bump version in pyproject.toml:

   # Edit pyproject.toml version field, or use hatch:
   hatch version patch   # 0.2.4 → 0.2.5
   hatch version minor   # 0.2.4 → 0.3.0
   

2. Run verification:

   uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run ty check src/ && uv run pytest
   

3. Commit and push:

   git commit -am "scanner: bump to X.Y.Z"
   git push
   

4. Tag and push (this triggers the publish):

   git tag scanner-vX.Y.Z
   git push origin scanner-vX.Y.Z
   

CI will:

• Run lint, format, type check, and unit tests
• Verify the tag matches pyproject.toml
• Build and publish to PyPI
• Build and push Docker image to ghcr.io/nimblebraininc/mpak-scanner:{version} and :latest

See scanner-publish.yml.

Docker Image

The Docker image includes all external security tools (Syft, Grype, TruffleHog, ESLint, Bandit, GuardDog) and installs mpak-scanner from PyPI.

# Pull from GHCR
docker pull ghcr.io/nimblebraininc/mpak-scanner:latest

# Run a scan
docker run --rm -v /path/to/bundle.mcpb:/bundle.mcpb ghcr.io/nimblebraininc/mpak-scanner scan /bundle.mcpb

Related Projects

• mpak registry - Search, download, and publish MCP bundles
• mpak Trust Framework - The security specification this scanner implements
• mpak CLI - CLI for working with MCP bundles

Contributing

See CONTRIBUTING.md for how to add new controls or improve detection rules.

License

Apache License 2.0