mpak-scanner 0.2.5

Security scanner for MCP bundles. Powers mpak Certified verification.

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:

Level	Name	Target	Controls
L1	Basic	Personal projects	6
L2	Standard	Team tools, published packages	12
L3	Verified	Production, enterprise	17
L4	Attested	Critical infrastructure	20

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.

Tool	Purpose	Install
Syft	SBOM generation	brew install syft
Grype	Vulnerability scanning	brew install grype
TruffleHog	Secret detection	brew install trufflehog
GuardDog	Malicious package detection	uv pip install guarddog
Bandit	Python static analysis	uv pip install bandit
ESLint	JavaScript static analysis	npm install -g eslint eslint-plugin-security

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:

Fixture	Tests	Expected
clean-l1-bundle/	Valid L1 bundle	All controls pass
has-secrets-bundle/	CQ-01 detection	Fails with secret findings
invalid-manifest-bundle/	AI-01 validation	Fails on missing fields
missing-tools-bundle/	CD-01 validation	Fails on tool issues
has-vulns-bundle/	SC-02 detection	Fails with CVE findings
node-server-bundle/	Node.js bundle	All controls pass
unsafe-node-bundle/	CQ-05 detection	Fails with unsafe patterns

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

For production deployment to ECR/K8s, see deployments/mpak/.

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