ShipCheck

ShipCheck is a Go CLI for auditing whether a repository is trustworthy, reproducible, and ready to use, publish, or run in CI.

It checks concrete repository signals instead of trying to judge code style: stack detection, documented commands, reproducibility hints, README consistency, committed secrets, repository health, dependency metadata, vulnerability data, GitHub repository state, and OpenSSF Scorecard data when network enrichment is enabled.

Current Status

ShipCheck is early but usable. The current build includes:

• Go, TypeScript/JavaScript, Python, Rust, Docker, and GitHub Actions detection
• build, test, lint, typecheck, run, format, Docker, and Makefile command discovery
• README command, badge, placeholder, and local-link checks
• lockfile, runtime version, env example, TypeScript, Docker, README, LICENSE, and local secret checks
• dependency extraction for npm, Go, PyPI, and Cargo lockfiles
• OSV, deps.dev, GitHub API, and OpenSSF Scorecard enrichment
• optional external response cache with --cache-dir
• opt-in safe command execution with --exec
• terminal, JSON, and Markdown reports
• scan, ready, trust, and ci presets
• --version output for release and CI diagnostics

Install

From a local checkout:

go build -o shipcheck ./cmd/shipcheck

Then run:

./shipcheck scan --path . --offline

With Go installed:

go install github.com/sebastian/shipcheck/cmd/shipcheck@latest

Usage

shipcheck scan --path .
shipcheck ready --path . --offline
shipcheck trust --path ../some-repo --format terminal,json
shipcheck ci --path . --fail-on risky --format json

Useful flags:

--path .
--offline
--exec
--timeout 30s
--format terminal,json,markdown
--output shipcheck-report.md
--fail-on risky
--github-token env:GITHUB_TOKEN
--cache-dir ~/.cache/shipcheck
--allow-risky-exec

By default, ShipCheck analyzes local files and may use external enrichers when network access is available. Use --offline to disable all network enrichment.

--exec makes ShipCheck run discovered build, test, lint, and related commands with a timeout. Dangerous commands such as sudo, rm -rf, curl | sh, inline credentials, and writes outside the repository are skipped and reported unless --allow-risky-exec is explicitly set.

Use --cache-dir to persist external API responses between runs. Cached entries expire after 24 hours.

Presets

• scan: general repository audit.
• ready: maintainer-focused readiness check before publishing or handing off a project.
• trust: stricter consumer-focused check before using or depending on a repository.
• ci: pipeline-friendly mode with failure thresholds.

Privacy

ShipCheck is local-first. It does not upload source code, README contents, lockfiles, or arbitrary files.

External enrichers send only the minimal coordinates required by each API. OSV and deps.dev receive dependency ecosystem, package name, and version. GitHub and OpenSSF Scorecard receive the repository owner and name when the remote is hosted on GitHub. Network enrichment can be disabled with --offline.

Development

Run tests:

go test ./...

Build the CLI:

go build -o shipcheck ./cmd/shipcheck

License

MIT