npm package: @shivam-sharma/codeguardian
Description: CLI to scan repos for sensitive secrets before pushing
Author: Shivam Sharma
Latest version: 2.4.4

<div align="center">

 <span>
    <h1>@shivam-sharma/codeguardian</h1>
</span>

<a href="https://github.com/shivarm/code-guardian/actions/workflows/codeguardian.yml/badge.svg"><img alt="Node.js CI" src="https://github.com/shivarm/code-guardian/actions/workflows/codeguardian.yml/badge.svg"></a>
<a href="https://www.npmjs.com/package/@shivam-sharma/codeguardian"><img alt="npm version" src="https://img.shields.io/npm/v/@shivam-sharma/codeguardian"></a>
<a href="./LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/shivarm/code-guardian"></a>
<a href="https://github.com/shivarm/code-guardian/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/shivarm/code-guardian"></a>

</div>


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.

<div align="center">
<img width="1240" height="752" alt="image" src="https://github.com/user-attachments/assets/b28f515e-8402-471b-ad82-21df4fb63aea" />
</div>

## How developers use CodeGuardian.

---

Installation (two quick ways):

- Run directly with npx (no install required):

```bash
npx @shivam-sharma/codeguardian
```

- Install as a dev dependency (recommended for team projects):

```bash
npm install --save-dev @shivam-sharma/codeguardian
```

## 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:

```json
{
  "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:

```yaml
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: @shivam-sharma/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:

```json
  "scripts": {
    "scan": "codeguardian"
  } 
```