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/<you>/ 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#

bash

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).

bash

cd /path/to/npm-package
shipcheck

Skill folder / generic repo#

bash

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

Common flags#

bash

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

What it catches#

CategoryExamplesSeveritysecretsAWS keys, GitHub PAT ( ghp_/gho_/ghu_/ghs_/ghr_), OpenAI sk-…, Anthropic sk-ant-…, Google AIza…, Slack xox[bp]-…, JWT, PEM/SSH private keys (~30 rules)critical``identityEmails, China mobile + E.164, /Users/<name>/ & /home/<name>/ absolute paths, SSH fingerprinthigh``infraRFC1918 IPs, Tailscale CGNAT 100.64/10, *.tail<id>.ts.net, *.lan/ *.local, private git remoteshigh``businessUser-defined forbidden_terms from shipcheck.config.json (codenames, internal product names…)medium``softNLChinese first-person personal context in *.md (我家 / 我老板 / 我同事 + 关系词)info``binaries``*.png/.jpg/.mp4/.zip/.pdf > 50 KB inside the publish setwarn

Recommended workflow#

bash

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

CodeMeaning0No findings, or only allow-listed / info / warn``1One or more critical / high / medium findings — do not ship

Use the exit code in CI or prepublishOnly:

json

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

Configuration (optional)#

shipcheck.config.json in the project root:

json

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

Links#

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