源于 Claude Code source map 泄露事件 — 一个 57MB 的 .map 文件将 51.2 万行源码暴露在 npm 上。没有任何工具拦截。PubGuard 能做到。

快速开始

git clone https://github.com/MRT-8/pubguard.git
cd pubguard
npm install
npm run build

扫描你的项目：

node dist/cli.js check --dry-run            # 扫描 npm 将要发布的文件
node dist/cli.js check my-pkg.tgz --strict  # 扫描指定 tarball

或通过 npx 使用（发布到 npm 后）：

npx pubguard check --dry-run

加入发布流程（推荐）：

npm install -D pubguard
npm pkg set scripts.prepublishOnly="pubguard check --dry-run --strict"

之后 npm publish 会自动先运行 PubGuard，发现 error 级问题则阻断发布。

检测规则

• sourcemap-leak — .map 文件含 sourcesContent — 完整源码泄露
• sourcemap-reference — JS/CSS 中的 sourceMappingURL 引用
• env-file — .env、.npmrc、credentials.json、SSH 配置等
• private-key — .pem、.key、id_rsa、PEM 编码私钥
• system-prompt — 代码中嵌入的 AI system prompt
• unminified-source — 大型未混淆 JS 文件（疑似未打包的源码）
• debug-config — debug: true、NODE_ENV=development 等调试配置
• internal-url — 内部 URL（*.internal.*、私有 IP 地址）

为什么需要 PubGuard？

现有工具覆盖代码中的密钥和依赖漏洞，但没有工具检查发布包里的实际内容：

| | 代码密钥 | Source map 泄露 | System prompt 暴露 | .env 误发布 | |---|:---:|:---:|:---:|:---:| | TruffleHog / Gitleaks | ✅ | ❌ | ❌ | ❌ | | npm audit | ❌ | ❌ | ❌ | ❌ | | PubGuard | — | ✅ | ✅ | ✅ |

// .pubguardrc.json
{
  "rules": {
    "sourcemap-leak": "error",    // "error" | "warn" | "info" | "off"
    "system-prompt": "error",
    "env-file": "error",
    "private-key": "error",
    "sourcemap-reference": "warn",
    "unminified-source": "warn",
    "debug-config": "warn",
    "internal-url": "warn"
  },
  "ignore": ["dist/vendor/**"],
  "thresholds": {
    "max-package-size": "10MB",
    "max-file-size": "5MB"
  }
}

创建 .pubguard-rules/my-rule.js：

export default {
  id: 'my-custom-rule',
  defaultSeverity: 'warn',
  description: '检测项目特有的敏感内容',
  detect(file) {
    const results = [];
    if (file.path.endsWith('.secret')) {
      results.push({
        ruleId: 'my-custom-rule',
        severity: 'error',
        message: `发现敏感文件: ${file.path}`,
        file: file.path,
        fix: '从发布包中移除此文件',
      });
    }
    return results;
  },
};

GitHub Actions：

- name: 发布安全检查
  uses: pubguard/action@v1
  with:
    strict: true

直接调用：

- run: npx pubguard check --dry-run --strict

完整发布流水线：

- run: npx pubguard check --dry-run --strict  # 产物内容检测
- run: trufflehog filesystem . --fail          # 密钥扫描
- run: npm publish --provenance                # 带 SLSA 签名发布

pubguard check [file.tgz] [options]
pubguard init                        # 创建 .pubguardrc.json 配置文件

选项:
  --dry-run        扫描 npm 将要发布的文件（无需 .tgz）
  --strict         发现 error 级问题时 exit 1
  --format <fmt>   输出格式：text（默认）、json、sarif
  --output <file>  输出到文件
  --config <path>  指定配置文件路径

工作原理

1. 读取包内容（通过 npm pack --dry-run 或 .tgz 文件）
2. 8 条检测规则逐文件扫描
3. 输出发现 + 严重级别 + 修复建议
4. error 级发现 → 非零退出码 → 阻断 npm publish

零依赖。全部本地执行。不外发任何数据。

许可证

Apache-2.0