secretlint

library12.2.0jsnpmunverified

Secretlint is a powerful CLI tool designed for scanning codebases to detect and prevent the leakage of sensitive data like API keys, credentials, and private information. The current stable version is 12.2.0, with minor and patch releases occurring frequently, and major versions introducing breaking changes like Node.js engine requirements. It offers a highly extensible architecture through pluggable rules and presets (e.g., `@secretlint/secretlint-rule-preset-recommend`), supporting various file formats and offering multiple output formatters including `stylish`, `mask-result`, and `github` annotations. Key differentiators include its focus on precise secret detection, a flexible configuration system using `.secretlintrc` files, and the ability to mask secrets in output, making it suitable for CI/CD pipelines and pre-commit hooks.

auth-security devops testing

npm install secretlint

github ↗package ↗

INSTALL

IMPORT

SIG · SECRETLINT

secretlint

auth-securityjavascriptv12.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'secretlint';

✗ const run = require('secretlint').run;

The primary function for programmatic execution of the Secretlint CLI logic. Typically used in scripts or custom runners.

SecretlintCoreResult

✓ import { SecretlintCoreResult } from 'secretlint';

TypeScript type for the structured result object returned by linting operations, useful for programmatic analysis. Re-exported from `@secretlint/core`.

loadConfig

✓ import { loadConfig } from 'secretlint';

Function to programmatically load Secretlint configuration files (e.g., `.secretlintrc.json`). Re-exported from `@secretlint/config-loader`.

SecretlintCLIOptions

✓ import { SecretlintCLIOptions } from 'secretlint';

TypeScript type defining the structure of options that can be passed to the `run` function, mirroring CLI arguments. Re-exported from `@secretlint/shared-type`.

Demonstrates initializing a basic `.secretlintrc.json` and then running `secretlint` both via the command line (using `npx`) and programmatically using the `run` function, showing secret detection and output masking.

import { run } from 'secretlint'; import * as fs from 'node:fs/promises'; import * as path from 'node:path'; const tempDir = path.join(process.cwd(), '.secretlint-temp'); const tempFile = path.join(tempDir, 'example.js'); const configFile = path.join(tempDir, '.secretlintrc.json'); async function quickstart() { await fs.mkdir(tempDir, { recursive: true }); await fs.writeFile(tempFile, 'const secretKey = "sk_live_YOUR_SECRET_KEY_123";'); await fs.writeFile(configFile, JSON.stringify({ "rules": [ { "id": "@secretlint/secretlint-rule-preset-recommend", "rule": "@secretlint/secretlint-rule-preset-recommend" } ] }, null, 2)); try { console.log('Running secretlint CLI via npx:'); // Using child_process for CLI demo, or `run` for programmatic const { execa } = await import('execa'); // Using dynamic import for execa const cliResult = await execa('npx', [ 'secretlint', tempFile, '--secretlintrc', configFile, '--format=stylish' ], { reject: false, cwd: tempDir }); console.log(cliResult.stdout); if (cliResult.exitCode === 1) { console.log('CLI detected secrets and exited with code 1.'); } else { console.log('CLI finished, no secrets detected or --output was used.'); } console.log('\nRunning secretlint programmatically with `run` function:'); const programmaticResult = await run([tempFile], { cwd: tempDir, secretlintrc: configFile, format: 'mask-result' }); console.log(programmaticResult.output); if (programmaticResult.ok === false) { console.log('Programmatic run detected secrets.'); } else { console.log('Programmatic run finished, no secrets detected.'); } } catch (error) { console.error('An error occurred:', error); } finally { await fs.rm(tempDir, { recursive: true, force: true }); } } quickstart();

secretlint --version

Debug

Known issues

breakingSecretlint v12.0.1 and later require Node.js version 22 or higher. Earlier Node.js versions are not supported and will cause runtime errors.

fix

Upgrade your Node.js environment to version 22 or newer.

affects: >=12.0.1

breakingStarting with Secretlint v12.0.0, new rules were added to the default `@secretlint/secretlint-rule-preset-recommend`. This means existing projects updating to v12 might suddenly report new secrets or issues that were not previously detected.

fix

Review your `secretlint` configuration and findings after upgrading. Add new `allow` rules or custom `.secretlintrc.json` configurations to suppress false positives or ignore newly detected secrets.

affects: >=12.0.0

gotchaWhen using glob patterns in shell commands (e.g., `bash`, `zsh`), you must wrap the patterns in double quotes (e.g., `secretlint "**/*"`). Failure to do so will cause your shell to expand the glob, potentially leading to errors like 'no matches found' or incorrect file processing.

fix

Always quote glob patterns: `secretlint "source/**/*.js"` instead of `secretlint source/**/*.js`.

affects: >=1.0.0

gotchaThe `--output` option fundamentally alters `secretlint`'s exit status. If `--output` is specified, `secretlint` will exit with status `0` (success) even if secrets are found. This can hide issues in CI/CD pipelines.

fix

In CI/CD, if `--output` is used, explicitly check the output file for detected secrets or use a custom formatter that returns a non-zero exit code upon finding secrets if you need the pipeline to fail.

affects: >=1.0.0

gotchaSecret detection inherently comes with a risk of false positives. Generic patterns can flag legitimate, non-secret data. Relying solely on default presets without review can lead to unnecessary alerts.

fix

Thoroughly review initial scan results. Use the `allow` configuration in `.secretlintrc.json` to explicitly ignore known false positives. Customize rule sets to be more precise for your codebase.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Node.js v18.17.1 is not supported. secretlint requires Node.js v22.0.0 or later.

Running secretlint with an unsupported Node.js version.

fix

Upgrade your Node.js environment to version 22 or higher using `nvm install 22 && nvm use 22` or similar version management tools.

zsh: no matches found: "**/*"

The shell attempted to expand the glob pattern before passing it to secretlint, and found no matches, or interpreted it incorrectly.

fix

Ensure glob patterns are enclosed in double quotes when used in the terminal: `secretlint "**/*"`.

Failed to load config file: .secretlintrc.json. Error: Failed to parse JSON file

The `.secretlintrc.json` file is either missing, has incorrect JSON syntax, or is not accessible.

fix

Run `npx secretlint --init` to create a default configuration, or carefully check your `.secretlintrc.json` file for syntax errors.

ReferenceError: SecretlintCoreResult is not defined

Attempting to use a type or function from the `secretlint` package programmatically without a proper ES module import statement.

fix

Ensure you are using `import { SecretlintCoreResult } from 'secretlint';` for TypeScript or CommonJS equivalent when using programmatically.

Upgrade

Version history

12.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/secretlint/secretlint ↗

packagehttps://www.npmjs.com/package/secretlint ↗