Guard what you publish.

Source Map Leak Detection | System Prompt Exposure | Sensitive File Guard

English | 中文

---

Born from the Claude Code source map leak — a 57 MB .map file exposed 512K lines of proprietary code on npm. No tool caught it. PubGuard would have.

Quick Start

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

Scan your project:

node dist/cli.js check --dry-run            # scan what npm would publish
node dist/cli.js check my-pkg.tgz --strict  # scan a tarball, fail on errors

Or install globally / via npx (after publishing to npm):

npx pubguard check --dry-run

Add to your publish workflow (recommended):

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

Now npm publish automatically runs PubGuard first. Errors block the publish.

What It Detects

• sourcemap-leak — .map files with sourcesContent — full source code exposure
• sourcemap-reference — sourceMappingURL comments pointing to map files
• env-file — .env, .npmrc, credentials.json, SSH configs
• private-key — .pem, .key, id_rsa, PEM-encoded private keys
• system-prompt — AI system prompts embedded in published code
• unminified-source — Large unminified JS files (likely unbundled source)
• debug-config — debug: true, NODE_ENV=development left in builds
• internal-url — Internal/corporate URLs (*.internal.*, private IPs)

Why PubGuard?

Existing tools find secrets in code or vulnerabilities in dependencies. Nobody checks what's actually inside your published package:

	Secrets in code	Source map leak	System prompt leak	.env in package
TruffleHog / Gitleaks	✅	❌	❌	❌
npm audit	❌	❌	❌	❌
PubGuard	—	✅	✅	✅

Configuration

// .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"
  }
}

Custom Rules

Create .pubguard-rules/my-rule.js:

export default {
  id: 'my-custom-rule',
  defaultSeverity: 'warn',
  description: 'Detect something specific to my project',
  detect(file) {
    const results = [];
    if (file.path.endsWith('.secret')) {
      results.push({
        ruleId: 'my-custom-rule',
        severity: 'error',
        message: `Secret file found: ${file.path}`,
        file: file.path,
        fix: 'Remove this file from the package',
      });
    }
    return results;
  },
};

CI/CD Integration

GitHub Actions:

- name: Check publish safety
  uses: pubguard/action@v1
  with:
    strict: true

Or directly:

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

Combined with secret scanning:

- run: npx pubguard check --dry-run --strict  # artifact content
- run: trufflehog filesystem . --fail          # secrets
- run: npm publish --provenance                # publish with SLSA

SARIF for GitHub Code Scanning:

- run: npx pubguard check --dry-run --format sarif --output pubguard.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: pubguard.sarif

CLI Reference

pubguard check [file.tgz] [options]
pubguard init                        # create .pubguardrc.json

Options:
  --dry-run        Scan files npm would publish (no .tgz needed)
  --strict         Exit 1 on any error
  --format <fmt>   text (default), json, sarif
  --output <file>  Write report to file
  --config <path>  Custom config path

How It Works

1. Reads your package contents (via npm pack --dry-run or .tgz file)
2. Runs each file through 8 detection rules
3. Reports findings with severity + fix suggestions
4. Exits non-zero if errors found → blocks npm publish

Zero dependencies. All local. No data leaves your machine.

License

Apache-2.0