Metadata-Version: 2.4
Name: mpak-scanner
Version: 0.1.0
Summary: Security scanner for MCP bundles. Powers mpak Certified verification.
Project-URL: Homepage, https://mpak.dev
Project-URL: Documentation, https://mpak.dev/certified
Project-URL: Repository, https://github.com/NimbleBrainInc/mpak-scanner
Project-URL: Changelog, https://github.com/NimbleBrainInc/mpak-scanner/blob/main/CHANGELOG.md
Author-email: NimbleBrain <security@nimblebrain.ai>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: bundle,mcp,mcpb,scanner,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.13
Requires-Dist: click>=8.1.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: ty>=0.0.1a1; extra == 'dev'
Description-Content-Type: text/markdown

# mpak-scanner

Security scanner 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

```bash
# 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](https://github.com/anchore/syft)                     | SBOM generation             | `brew install syft`       |
| [Grype](https://github.com/anchore/grype)                   | Vulnerability scanning      | `brew install grype`      |
| [TruffleHog](https://github.com/trufflesecurity/trufflehog) | Secret detection            | `brew install trufflehog` |
| [GuardDog](https://github.com/DataDog/guarddog)             | Malicious pattern detection | `pip install guarddog`    |
| [Bandit](https://github.com/PyCQA/bandit)                   | Python static analysis      | `pip install bandit`      |

## Usage

### Command Line

```bash
# 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

```python
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

The scanner implements the mpak Trust Framework (MTF). See [spec/MTF-0.1.md](spec/MTF-0.1.md) for the full specification.

## Development

### Running Tests

```bash
# 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    |

See [tests/fixtures/README.md](tests/fixtures/README.md) for details.

### Code Quality

```bash
# 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

- **Code**: Apache License 2.0
- **Specification**: Creative Commons Attribution 4.0 International (CC BY 4.0)

## Contributing

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