@shivam-sharma/codeguardian

Lightweight CLI to scan repositories for accidentally committed secrets (API keys, tokens, private keys). This short guide starts with how to use CodeGuardian in your project, how to integrate it into CI, and then explains the feature and configuration.

How developers use CodeGuardian.

---

Installation (two quick ways):

• Run directly with npx (no install required):

npx @shivam-sharma/codeguardian

• Install as a dev dependency (recommended for team projects):

npm install --save-dev @shivam-sharma/codeguardian

Basic commands:

• Scan entire repository:

npx codeguardian

• Scan only staged files (fast; good for pre-commit hooks):

npx codeguardian --staged

Default config:

If no config is provided, CodeGuardian uses built-in rules to scan for common secrets (API keys, tokens, etc.).

Custom config:

You can create a .codeguardianrc.json file to define your own regex rules and files to ignore:

{
  "ignoreFiles": ["package-lock.json", "dist/**"],
  "rules": [
    { "name": "AWS Key", "pattern": "AKIA[0-9A-Z]{16}", "flags": "g" }
  ]
}

Rules are JavaScript regular expressions expressed as strings. flags is optional (for example g). The scanner will try to compile each rule. invalid patterns are skipped.

How to integrate with CI (GitHub Actions).

Use the built-in workflow .github/workflows/codeguardian.yml or add a step to your pipeline to run the scanner in CI mode. Example snippet:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  scan:
    name: Run CodeGuardian
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "22"
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Run CodeGuardian scanner (CI mode)
        run: npx codeguardian --ci

When run with --ci the CLI exits with a non-zero code if any findings are detected — this will fail the job and block merges until issues are resolved.

What CodeGuardian offers

---

• Rule-based scanning: configure regex rules (name, pattern, flags) to detect secrets.
• Built-in detection for AWS, Azure, Google Cloud, Heroku, JWTs, Slack tokens, and more.
• Scan performance stats: see time taken, memory usage, and file count at the end of each run.
• ignoreFiles: glob list to skip noisy files (lockfiles, build artifacts).
• Staged-file scanning: run only what will be committed (fast pre-commit checks).
• Husky integration: optional pre-commit hooks to block commits locally.
• CI-ready: --ci mode for failing pipelines on findings.
• Unused JS/TS module detection: Each scan, CodeGuardian will warn about JavaScript and TypeScript files that are not imported or required by any other file (excluding entry points like index.js, main.ts, etc.). These warnings help you clean up unused code, but do not block CI or fail the scan.

CLI options

• -c, --config <path> — path to JSON config file (default: .codeguardianrc.json)
• -s, --staged — only scan staged files
• --ci — CI mode: exit non-zero when findings exist
• -v, --verbose — verbose output

Adding scripts to package.json

you can add a script to your package.json to simplify running the scanner:

  "scripts": {
    "scan": "codeguardian"
  }