countersign

README

Countersign

MCP server supply chain security for developers who don't want to blindly trust packages.

Countersign establishes a cryptographic chain of trust for MCP servers. It allows users to verify package signatures and provenance before installation, leveraging the Sigstore ecosystem for cryptographic attestation verification.

The Problem

Developers install MCP servers (via npm or Docker) with zero verification of:

• Provenance — Was this actually built from the claimed source?
• Integrity — Has this package been tampered with?
• Authorship — Who signed this release?

The Solution

$ countersign verify @modelcontextprotocol/server-postgres

✓ Package: @modelcontextprotocol/server-postgres@1.2.3
✓ Signature verified
  └─ Signed by: github.com/modelcontextprotocol/servers/.github/workflows/release.yml
✓ Provenance verified (SLSA Level 3)
✓ Policy: ALLOWED

VERIFIED: @modelcontextprotocol/server-postgres@1.2.3 is trusted

Installation

Go Install

go install github.com/dotsetlabs/countersign/cmd/countersign@latest

From Source

git clone https://github.com/dotsetlabs/countersign.git
cd countersign
make build
./countersign --help

Binary Releases

Download pre-built binaries from the Releases page.

Quick Start

Verify a Package

# Verify an npm package (latest version)
countersign verify @modelcontextprotocol/server-postgres

# Verify a specific version
countersign verify @modelcontextprotocol/server-postgres@1.2.3

# Strict mode: fail if any attestation is missing
countersign verify --strict @anthropic/mcp-server

# JSON output for scripting
countersign verify -o json @example/package | jq .verified

Manage Trusted Publishers

# Add a trusted publisher
countersign trust add --name "Anthropic" "https://github.com/anthropics/*"

# List trusted publishers
countersign trust list

# Remove a trusted publisher
countersign trust remove "https://github.com/anthropics/*"

Commands

Command	Description
verify <package>	Verify signature and provenance of an MCP server
trust add <identity>	Add a trusted publisher
trust list	List trusted publishers
trust remove <id>	Remove a trusted publisher
version	Print version information
completion <shell>	Generate shell completion script

Verify Flags

Flag	Description
--strict	Fail if any required attestation is missing
--require-provenance	Require SLSA provenance attestation
--no-cache	Skip verification cache
-o, --output	Output format: terminal or json
-v, --verbose	Enable verbose output
-q, --quiet	Only output errors and final result

How It Works

Countersign leverages the Sigstore ecosystem to verify:

1. Signatures

Cryptographic proof that a package was signed by a specific identity (GitHub Actions workflow, developer email, etc.).

2. Provenance

SLSA build provenance from the transparency log (Rekor), proving the package was built from the claimed source.

3. Policy

User-defined rules for what publishers to trust, including:

• Trusted publisher identities (e.g., https://github.com/anthropics/*)
• Required attestation types
• SLSA level requirements

Trust Policy

Countersign stores trusted publishers locally in ~/.countersign/store.db.

Default Policy

By default, Countersign will warn for packages without attestations but allow them. For stricter enforcement:

# Require provenance for all packages
countersign verify --require-provenance @example/package

# Fail if any attestation is missing
countersign verify --strict @example/package

Custom Policy

Create ~/.countersign/policy.yaml:

version: "1"
name: "My Policy"
default: warn

trusted_publishers:
  - name: "Anthropic"
    identity: "https://github.com/anthropics/*"
    oidc_issuer: "https://token.actions.githubusercontent.com"

rules:
  - id: require-provenance
    match:
      packages: ["@modelcontextprotocol/*"]
    action: allow
    require:
      signature: true
      provenance: true

Integration with Dotset Labs Tools

Countersign is part of the Dotset Labs security stack:

Stage	Tool	Focus
Pre-install	Hardpoint	Scan dev environment for threats
At install	Countersign	Verify MCP server provenance
At runtime	Tollgate	Control what MCP servers can do

Tollgate Integration

Countersign can be integrated with Tollgate for automatic verification:

# tollgate.yaml
countersign:
  enabled: true
  mode: warn  # "deny", "warn", or "skip"

Supported Registries

Registry	Status
npm (npmjs.org)	✅ Supported
OCI (Docker, ghcr.io, gcr.io, quay.io)	✅ Supported
GitHub Releases	✅ Supported

Performance

Countersign is optimized for fast verification with caching:

Operation	Time	Notes
Package verification	~250ms	Includes npm registry + Rekor lookup
Health check	~170ms	Tests all external services
Cached verification	<10ms	Uses local SQLite cache
Vulnerability scan	~100ms/pkg	npm audit API

Caching:

• Verification results cached in ~/.countersign/store.db
• Cache TTL: 24 hours (configurable)
• Offline mode available with --offline flag

Resource Usage:

• Binary size: ~12MB (includes Sigstore libs)
• Memory: <30MB during verification
• Network: Required for verification (npm, Rekor)

Privacy

• Local-only — All verification happens on your machine
• No telemetry — We don't collect any data
• No cloud — No Dotset Labs servers involved
• Open source — Fully auditable

Development

Prerequisites

• Go 1.24+
• Make

Build

make build       # Build binary
make test        # Run tests
make lint        # Run linters
make clean       # Clean build artifacts

Project Structure

countersign/
├── cmd/countersign/     # CLI entry point
├── internal/
│   ├── cli/             # Cobra commands
│   ├── engine/          # Verification engine
│   ├── registry/        # Registry clients (npm, OCI)
│   ├── attestation/     # Attestation types
│   ├── policy/          # Trust policy
│   ├── store/           # SQLite persistence
│   └── output/          # Output formatting
├── pkg/countersign/     # Public API (for Tollgate)
└── policies/            # Default policy templates

Documentation

• CONTRIBUTING.md - Development guidelines
• SECURITY.md - Security policy and vulnerability reporting
• ERRORS.md - Error codes and troubleshooting guide
• CHANGELOG.md - Version history

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Links

• Documentation
• GitHub Repository
• Issue Tracker
• Dotset Labs