console-guard

A security-focused CLI that scans JavaScript/TypeScript codebases for console.* statements that could leak sensitive data, classifies them by risk level, and blocks risky commits via a pre-commit hook.

Why this matters

A misplaced console.log is one of the most common — and most expensive — sources of data leaks. Real incidents from the public record:

• GitHub Actions logs leaking tokens (2020+, recurring): debug console.log statements printing environment variables ended up in publicly readable CI logs, exposing API keys for downstream services.
• Twitter (now X) iOS app, 2018: an internal logger wrote plaintext passwords to disk because of an accidentally enabled debug log path. ~330M users were prompted to rotate credentials.
• NPM packages shipped with debug logs: multiple incidents where authors left console.log(JSON.stringify(req.headers)) in middleware, leaking session tokens to anyone who could capture stdout in a shared environment.
• Browser DevTools exposure: client-side console.log(user) exposes full user objects (PII, internal IDs, role flags) to anyone who opens DevTools — a recurring finding in third-party security audits.

The pattern is always the same: a developer adds a log "just to debug something quickly," forgets to remove it, and it ships. console-guard is the cheap automated check that catches it before it reaches main.

Install

npm install --save-dev console-guard
# or run directly without installing
npx console-guard scan

Requires Node.js 18+.

Usage

Scan the entire project

npx console-guard scan

Scan a specific folder

npx console-guard scan src/

Show only high-risk findings

npx console-guard scan --level=high

Generate an HTML report

npx console-guard report
# writes console-guard-report.html in the current directory

Install the git pre-commit hook

npx console-guard install-hook

After installation, every git commit runs console-guard on staged files. High-risk findings block the commit; medium and low findings only warn.

Interactively remove console statements

npx console-guard fix --level=high

Walks each high-risk finding and asks whether to remove it. y removes the line, n skips, q quits.

Example output

$ npx console-guard scan src/

  RISK     FILE                                      LINE    SNIPPET
  ──────────────────────────────────────────────────────────────────────────────
   HIGH    src/auth/login.ts                         42:5    console.log("login attempt", { password, email })
                    → keywords: password
   HIGH    src/api/payments.ts                       18:3    console.log(`processing cvv=${cvv}`)
                    → keywords: cvv
   HIGH    src/utils/jwt.ts                          71:7    console.log("decoded jwt:", jwt)
                    → keywords: jwt
   MEDIUM  src/api/users.ts                          14:3    console.log(user)
   MEDIUM  src/api/users.ts                          27:3    console.log("user created", user)
   MEDIUM  src/middleware/error.ts                    8:5    console.error(err)
   LOW     src/server.ts                              9:3    console.log("listening on port 3000")
   LOW     src/server.ts                             22:3    console.log("shutting down")

Scanned 47 files
Found 3 HIGH, 3 MEDIUM, 2 LOW risk console statements (8 total)

HTML report

console-guard report writes a self-contained HTML file with color-coded findings:

┌────────────────────────────────────────────────────────────────────┐
│ console-guard report                                                │
│ Scanned 47 files in /repo · generated 2026-05-08T10:14:00.000Z      │
├──────────────┬──────────────┬──────────────┬───────────────────────┤
│ HIGH RISK    │ MEDIUM RISK  │ LOW RISK     │ TOTAL                 │
│      3       │      3       │      2       │      8                │
└──────────────┴──────────────┴──────────────┴───────────────────────┘

Risk classification

| Level | Triggered when… | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | HIGH | Arguments reference identifiers like password, token, secret, apiKey, auth, credentials, jwt, key, private, ssn, cvv, bearer, etc. | | MEDIUM | Arguments include variables, objects, or template interpolations (content unknown at scan time). | | LOW | Arguments are plain string literals only, e.g. console.log("server started"). |

The classifier inspects the textual form of the call's arguments — it doesn't execute or fully parse JavaScript — but it correctly skips matches inside strings, template literals, and comments using a hand-rolled state machine.

CI / CD integration

GitHub Actions

Drop this file at .github/workflows/console-guard.yml:

name: console-guard

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

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run console-guard
        run: npx console-guard scan --level=high

      - name: Upload HTML report
        if: always()
        run: npx console-guard report
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: console-guard-report
          path: console-guard-report.html

console-guard scan --level=high exits with status 1 if any high-risk finding is detected, failing the job.

GitLab CI

console-guard:
  image: node:20
  script:
    - npx console-guard scan --level=high
  artifacts:
    when: always
    paths:
      - console-guard-report.html

Pre-commit (local)

Run once after cloning:

npx console-guard install-hook

The installed hook runs on git commit and refuses commits that introduce high-risk console statements. Use git commit --no-verify to bypass (and explain in the PR why).

Configuration

Currently zero-config. The scanner walks from the working directory, respects .gitignore for the most common patterns, and always skips node_modules, dist, build, out, .next, .git, coverage, and similar build directories.

Supported file extensions: .js, .jsx, .ts, .tsx, .mjs, .cjs.

Programmatic API

import { scan, summarize } from "console-guard";

const result = await scan({ cwd: process.cwd(), level: "high" });
const summary = summarize(result.findings);
console.log(summary); // { high, medium, low, total }

Exit codes

| Code | Meaning | | ---- | ------------------------------------------------------------------------ | | 0 | Clean, or only medium/low findings (in default and report modes). | | 1 | At least one high-risk finding detected. | | 2 | Internal error (bad arguments, I/O failure, etc.). |

Development

npm install
npm run build       # compile TypeScript -> dist/
npm test            # run unit tests
npm run lint        # type-check only

Contributing

Issues and PRs welcome. Please run npm test and npm run build before opening a PR.

License

MIT — see LICENSE.