mpak-scanner 0.2.0

Security scanner for MCP bundles. Powers mpak Certified verification.

mpak-scanner

Reference implementation of the mpak Trust Framework (MTF), an open security standard for MCP bundles.

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

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
uv pip install mpak-scanner

# Or with pip
pip install mpak-scanner

External Dependencies

The scanner requires these tools to be installed:

Tool	Purpose	Install
Syft	SBOM generation	brew install syft
Grype	Vulnerability scanning	brew install grype
TruffleHog	Secret detection	brew install trufflehog
GuardDog	Malicious pattern detection	pip install guarddog
Bandit	Python static analysis	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 MTF specification for full details on compliance levels, controls, and verification methods.

Development

Running Tests

# Install dev dependencies
uv pip install -e ".[dev]"

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test class
uv run pytest tests/test_scanner.py::TestCleanL1Bundle -v

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.

Code Quality

# Linting
uv run ruff check src/ tests/

# Format check
uv run ruff format --check src/ tests/

# Type checking
uv run ty check src/

# Fix lint issues
uv run ruff check --fix src/ tests/
uv run ruff format src/ tests/

License

Apache License 2.0

Contributing

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