keyguard-core

The secret detection engine behind Key-Guard. Zero runtime dependencies.

Most people want the CLI instead:

npm install -g keyguard-cli

This package exists so the CLI, CI adapters and future editor integrations all agree on what counts as a secret.

Usage

import { scanText } from "keyguard-core";
import { readFileSync } from "node:fs";

const path = "config.js";
const findings = scanText(readFileSync(path, "utf8"), { path });

for (const finding of findings) {
  console.log(`${finding.line}:${finding.column}`, finding.ruleName, finding.preview);
}

Pass { includeWarnings: true } to also get the heuristic entropy matches, which are excluded by default.

Findings carry a redacted preview and a hash fingerprint. The raw matched value is not retained, because printing a secret in full would re-leak it into terminal history and CI logs.

API

| Export | Purpose | | ------------------------- | ----------------------------------------------- | | scanText(text, options) | Scan a string, returns findings | | scanFile(path, options) | Read and scan a file | | redact(value) | Safe preview of a sensitive value | | shannonEntropy(value) | Entropy score | | isPlaceholder(value) | Recognise obvious dummies and public defaults | | hasInlineAllow(line) | Detect a keyguard:allow pragma | | parseIgnoreFile(text) | Parse .keyguardignore | | shouldSkipPath(path) | Hard skips for lockfiles, binaries, and similar | | getServiceInfo(service) | Rotation URL and steps for a service | | RULES | The detection rules |

What it detects

Documented credential formats for AWS, GitHub, GitLab, Slack, Stripe, Google, OpenAI, Anthropic, Atlassian, npm, PyPI, SendGrid, Shopify, Twilio, Mailgun and Discord; private key blocks; JWTs (validated by decoding the header, not just pattern-matched); credentials embedded in connection strings; and generic high-entropy assignments as warnings.

Entropy matches are always warnings, never blocking. Blocking on entropy turns one noisy lockfile into a reason to uninstall the tool.

License

MIT © L-ubu