shipcheck — pre-publish PII & secret check

shipcheck is a best-effort pre-publish safety net. Run it before npm publish, clawhub publish, or pushing a repo public to catch the stuff you'll regret shipping: absolute /Users/\x3Cyou>/ paths, internal IPs, Tailscale hostnames, API keys, internal project codenames, and soft natural-language personal leaks in markdown.

It is NOT:

• a replacement for manual review
• a full secret scanner (gitleaks / trufflehog cover more)
• a security audit

It is one more pair of eyes before you hit publish.

When to use this skill

Trigger this skill when the user is about to publish or push something public:

• npm publish / npm publish --dry-run
• clawhub publish ./my-skill ...
• git push to a brand-new public repo
• "check leaks", "is it safe to share?", "扫一下个人信息", "发布前体检"

Install

npm i -g @symbolstar/shipcheck
# or one-shot
npx -y @symbolstar/shipcheck

Run

npm package (default mode)

Scans only files that would actually be published — resolves package.json.files, .npmignore, .gitignore statically (does not invoke npm pack).

cd /path/to/npm-package
shipcheck

Skill folder / generic repo

shipcheck --scan-mode=dir ./path/to/skill-or-repo

Common flags

shipcheck --scan-mode=dir|npm     # default: npm
shipcheck --allow \x3Cid>            # acknowledge a finding by id
shipcheck --config ./shipcheck.config.json

What it catches

Recommended workflow

# 1. Run it
shipcheck                       # or: shipcheck --scan-mode=dir .

# 2. Triage findings
#    - real leak → fix the file
#    - false positive → add to shipcheck.config.json allow / forbidden_terms

# 3. Re-run until 0 critical / high
shipcheck

# 4. Publish
npm publish    # or: clawhub publish ./skill --slug ...

Exit codes

Use the exit code in CI or prepublishOnly:

{
  "scripts": {
    "prepublishOnly": "shipcheck && npm run build && npm test"
  }
}

Configuration (optional)

shipcheck.config.json in the project root:

{
  "forbidden_terms": ["AcmeInternalCodename", "ProjectStarfish"],
  "allow": [
    "rule:identity.absolute-home:fixtures/golden/01/setup.md#L12"
  ],
  "scanMode": "npm"
}

Links

• npm: \x3Chttps://www.npmjs.com/package/@symbolstar/shipcheck>
• source: \x3Chttps://github.com/SymbolStar/shipcheck> (public mirror — main dev on local repo)
• author: SymbolStar