Secretlint

Secretlint is a Pluggable linting tool to prevent committing credentials.

Features

• Scanner: Find credentials in a project and report these
• Project Friendly: Easy to set up your project and integrate CI services
• Pre-Commit Hook: Prevent committing credential files
• Pluggable: Allow creating custom rule and flexible configuration
• Documentation: Describe the reason that rule detect it as secret

Quick Demo

You can view secretlint linting result on https://secretlint.github.io/.

Quick Start

You can try to use Secretlint on your project at one command.

If you already have installed Docker:

docker run -v `pwd`:`pwd` -w `pwd` --rm -it secretlint/secretlint secretlint "**/*"

If you already have installed Node.js:

npx @secretlint/quick-start "**/*"

After running, If you got empty result and exit status is 0, your project is secure. Otherwise, you got some error report, your project includes credential as raw data.

You want to get continuous security, Please see following installation guide and setup pre-commit hook and CI.

Installation

Using Docker

Prerequisites: Require Docker

Use our Docker container to get an environment with Node.js and secretlint running as fast as you can download them.

You can check all files under the current directory with secretlint by following command:

docker run -v `pwd`:`pwd` -w `pwd` --rm -it secretlint/secretlint secretlint "**/*"

secretlint/secretlint docker container work without configuration by design.

This Docker Image has built-in packages:

• @secretlint/secretlint-rule-preset-recommend
• @secretlint/secretlint-rule-pattern
• @secretlint/secretlint-formatter-sarif

For more details, please see secretlint's Dockerfile.

Using Node.js

Prerequisites: Require Node.js 20+.

Secretlint is written by JavaScript. You can install Secretlint using npm:

npm install secretlint @secretlint/secretlint-rule-preset-recommend --save-dev

You should then set up a configuration file:

npx secretlint --init

Finally, you can run Secretlint on any file or directory like this:

npx secretlint "**/*"

:memo: Secretlint supports glob pattern and glob pattern should be wrapped by a double quote.

It is also possible to install Secretlint globally using npm install --global. But, We do not recommend it, some rules may be broken globally.

Using Single-Executable Binary

Prerequisites: None

You can use secretlint command without Node.js by using a single-executable binary.

1. Download the latest binary from Releases page
2. Change the file permission to executable: chmod +x ./secretlint
3. Run ./secretlint --init to create a configuration file
4. Run ./secretlint "**/*" to lint your project

For more details, please see publish/binary-compiler README.

Usage

secretlint --help shows Usage.

Secretlint CLI that scan secret/credential data.

Usage
$ secretlint [file|glob*]

Note
supported glob syntax is based on microglob
https://github.com/micromatch/micromatch#matching-features

Options
--init             setup config file. Create .secretlintrc.json file from your package.json
--format           [String] formatter name. Default: "stylish". Available Formatter: checkstyle, compact, github, jslint-xml, junit, pretty-error, stylish, tap, unix, json, mask-result, table
--output           [path:String] output file path that is written of reported result.
--no-color         disable ANSI-color of output.
--no-terminalLink  disable terminalLink of output.
--no-maskSecrets   disable masking of secret values; secrets are masked by default.
--secretlintrc     [path:String] path to .secretlintrc config file. Default: .secretlintrc.*
--secretlintignore [path:String] path to .secretlintignore file. Default: .secretlintignore
--stdinFileName    [String] filename to process STDIN content. Some rules depend on filename to check content.

Options for Developer
--profile          Enable performance profile.
--secretlintrcJSON [String] a JSON string of .secretlintrc. use JSON string instead of rc file.

Experimental Options
--locale            [String] locale tag for translating message. Default: en

Examples
$ secretlint ./README.md
# glob pattern should be wrapped with double quote
$ secretlint "**/*"
$ secretlint "source/**/*.ini"
# output masked result to file
$ secretlint .zsh_history --format=mask-result --output=.zsh_history
# lint STDIN content instead of file
$ echo "SECRET CONTENT" | secretlint --stdinFileName=secret.txt

Exit Status
Secretlint exits with the following values:

    - 0:
      - Linting succeeded, no errors found.
      - Found lint error but --output is specified.
    - 1:
      - Linting failed, errors found.
    - 2:
      - Unexpected error occurred, fatal error.

Configuration

Secretlint has a configuration file .secretlintrc.{json,yml,js}.

• Document: Configuring Secretlint

After running secretlint --init, you'll have a .secretlintrc.json file in your directory.

In it, you'll see some rules configured like this:

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend"
    }
  ]
}

The id property is the name of secretlint rule package.

Secretlint does not have built-in rule. You want to add some rule and You should install the package and add the rule to .secretlintrc file.

Each rule has same configuration pattern:

• options: Option definition for the rule. For more details, see each rule documentation
• disabled: If disabled is true, disable the rule
• allowMessageIds: allowMessageIds is an array of message id that you want to suppress error report
  • message id is defined in each rule and please see the rule documentation

Example: options

For example, @secretlint/secretlint-rule-example has allows in options. This allows option define a list of RegExp-like String that you want to ignore.

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-example",
      "options": {
        "allows": [
          "/dummy_secret/i"
        ]
      }
    }
  ]
}

When you use a preset like @secretlint/secretlint-rule-preset-recommend, you need to put the option in rules.

For example, an option for @secretlint/secretlint-rule-preset-recommend > @secretlint/secretlint-rule-aws

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend",
      "rules": [
        {
          "id": "@secretlint/secretlint-rule-aws",
            "options": {
              "allows": [
	            // it will be ignored
                "xxxx-xxxx-xxxx-xxxx-xxxx"
              ]
            }
        }
      ]
    }
  ]
}

Example: allowMessageIds

For example, you have got following error report by run secretlint:

$ secretlint "**/*"

SECRET.txt
  1:8  error  [EXAMPLE_MESSAGE] found secret: SECRET  @secretlint/secretlint-rule-example

✖ 1 problem (1 error, 0 warnings)

This error's message id is EXAMPLE_MESSAGE in @secretlint/secretlint-rule-example.

If you want to ignore this error, please use allowMessageIds.

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-example",
      "allowMessageIds": ["EXAMPLE_MESSAGE"]
    }
  ]
}

When you use a preset like @secretlint/secretlint-rule-preset-recommend, you need to put the option in rules.

For example, If you want to ignore "AWSAccountID" and "AWSAccessKeyID" of "@secretlint/secretlint-rule-aws", you can write following.

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend",
      "rules": [
        {
          "id": "@secretlint/secretlint-rule-aws",
          "allowMessageIds": ["AWSAccountID", "AWSAccessKeyID"]
        }
      ]
    }
  ]
}

Ignoring by comment

@secretlint/secretlint-rule-filter-comments supports ignoring comment like secretlint-disable.

// secretlint-disable

THIS IS SECRET, BUT IT WILL BE IGNORED

// secretlint-enable

For more details, please see Configuring Secretlint.

Use Cases

Mask secrets in lint error message (Default behavior)

Secretlint masks secrets in lint error messages by default. This is useful to prevent accidental secret exposure in CI logs, terminal output, or when using AI agent tools.

# Secrets are masked by default
$ secretlint "**/*"

To show actual secret values in the output, use --no-maskSecrets:

$ secretlint --no-maskSecrets "**/*"

Fix secrets

Secretlint can not fix the secrets automatically. However, It is useful that --format=mask-result mask the secrets of input file.

For example, you c