Repository files navigation

Secretlint is that Pluggable linting tool to prevent committing credentials.

• Scanner: Found 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

You can view secretlint linting result onhttps://secretlint.github.io/.

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 is0, 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.

Prerequisites: RequireDocker

Use ourDocker container to get an environment with Node.js and secretlint and 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 seesecretlint's Dockerfile.

Prerequisites: RequireNode.js 18+.

Secretlint is written by JavaScript.You can install Secretlint usingnpm:

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 "**/*"

📝 Secretlint supportglob pattern and glob pattern should be wrapped by a double quote.

It is also possible to install Secretlint globally usingnpm install --global. But, We do not recommended it, some rules may be broken in globally.

Prerequisites: None

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

1. Download the latest binary fromReleases 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 seepublish/binary-compiler README.

secretlint --help show Usage.

Secretlint CLI that scan secret/credential data.Usage$ secretlint [file|glob*]Notesupported glob syntax is based on microglobhttps://github.com/micromatch/micromatch#matching-featuresOptions--init             setup config file. Create .secretlintrc.json file from your package.json--format           [String] formatter name. Default: "stylish". Available Formatter: checkstyle, compact, 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.--maskSecrets      enable masking of secret values. replace actual secrets with "***".--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: enExamples$ secretlint ./README.md# glob pattern should be wrapped with double quote$ secretlint "**/*"$ secretlint "source/**/*.ini"# found secrets and mask the secrets$ secretlint .zsh_history --format=mask-result --output=.zsh_history# lint STDIN content instead of file$ echo "SECRET CONTENT" | secretlint --stdinFileName=secret.txtExit StatusSecretlint 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.

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

• Document:Configuring Secretlint

After runningsecretlint --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"    }  ]}

Theid property is the name of secretlint rule package.

Secretlint does not have built-in rule.You want to add some rule and You shouldinstall the package andadd 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: Ifdisabled istrue, 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

For example,@secretlint/secretlint-rule-example hasallows inoptions.Thisallows option define a list ofRegExp-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 inrules.

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"]}}]}]}

For example, you have got following error report by runsecretlint:

$ 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 isEXAMPLE_MESSAGE in@secretlint/secretlint-rule-example.

If you want to ignore this error, please useallowMessageIds.

{"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 inrules.

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"]}]}]}

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

// secretlint-disableTHIS IS SECRET, BUT IT WILL BE IGNORED// secretlint-enable

For more details, please seeConfiguring Secretlint.

Secretlint support--maskSecrets option that mask secrets in lint error message.It is useful that you want to hide secrets in CI logs.

$ secretlint --maskSecrets"**/*"

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

For example, you can mask the secrets of.zsh_history file and overwrite it.

$ secretlint .zsh_history --format=mask-result --output=.zsh_history

Secretlint rules has been implemented as separated modules.

• @secretlint/secretlint-rule-npm
• @secretlint/secretlint-rule-aws
• @secretlint/secretlint-rule-gcp
• @secretlint/secretlint-rule-github
• @secretlint/secretlint-rule-privatekey
• @secretlint/secretlint-rule-basicauth
• @secretlint/secretlint-rule-slack
• @secretlint/secretlint-rule-sendgrid
• @secretlint/secretlint-rule-shopify
• @secretlint/secretlint-rule-openai
• @secretlint/secretlint-rule-linear
• @secretlint/secretlint-rule-secp256k1-privatekey
• @secretlint/secretlint-rule-no-k8s-kind-secret
• @secretlint/secretlint-rule-pattern
• @secretlint/secretlint-rule-no-homedir
• @secretlint/secretlint-rule-no-dotenv

Also, Secretlint provide rule preset that includes recommened rule set.

• @secretlint/secretlint-rule-preset-recommend
  • Recommended rule set

You can create own secretlint rule.

You want to get a secretlint rule for suitable your project and you can create it!A secretlint rule is a just npm package.

If you want to know creating secretlint rule, please seedocs/secretlint-rule.md.

You can use Secretlint with some pre-commit tool.This can prevent to commit secret data by linting with Secretlint.

Applying secretlint to the project and improve security on team developing.

Use Case: If you want to introduce secretlint to Node.js project, this combination is useful.

InstallHusky andlint-staged:

npx husky-init && npm install lint-staged --save-dev

Add hooks to.husky/pre-commit:

npx husky add .husky/pre-commit "npx --no-install lint-staged"

Editpackage.json:

{// add "lint-staged" field"lint-staged":{"*":["secretlint"]}}

This means that check each staged file by Secretlint before commit.

Use Case: You have a project that is developing with Docker. Easy to integrate to secretlint.

Installpre-commit

# macOS. see also https://pre-commit.com/#installbrew install pre-commit

Create.pre-commit-config.yaml:

-   repo: local    hooks:    -   id: secretlint        name: secretlint        language: docker_image        entry: secretlint/secretlint:latest secretlint

Example setup repository:

• https://github.com/azu/secretlint-pre-commit-example

Alternately you can save this script as.git/hooks/pre-commit and give it execute permission(chmod +x .git/hooks/pre-commit):

#!/bin/shFILES=$(git diff --cached --name-only --diff-filter=ACMR| sed's| |\\ |g')[-z"$FILES" ]&&exit 0# Secretlint all selected filesecho"$FILES"| xargs ./node_modules/.bin/secretlint# If you using docker# echo "$FILES" | xargs docker run -v `pwd`:`pwd` -w `pwd` --rm secretlint/secretlint secretlintRET=$?if [$RET-eq 0 ];thenexit 0elseexit 1fi

Use Case: If you want to check any project by secretlint, you can use global git hooks.

Git 2.9+ supportscore.hooksPath.It allow to integrate secretlint globally.

We have created example git hooks project using secretlint + Docker.

• secretlint/git-hooks
  • Requirement: Docker

You can set up by following steps:

# clone this repositorygit clone https://github.com/secretlint/git-hooks git-hookscd git-hooks# integrate secretlint to git hook globallygit config --global core.hooksPath$(pwd)/hooks

After setup ofcore.hooksPath, secretlint check any file before you commit it.

For more details, seesecretlint/git-hooks project.

Node.js version also can be used for global git hook.If you interesting in it, please see@azu/git-hooks.

If you already set secretlintUsing Node.js, you can run secretlint with your configuration onGitHub Actions.

Put.github/workflows/secretlint.yml in your repository.

name:Secretlinton:[push, pull_request]permissions:contents:readjobs:test:name:"Secretlint"runs-on:ubuntu-lateststeps:      -name:checkoutuses:actions/checkout@v3      -name:setup Node.jsuses:actions/setup-node@v3with:node-version:20      -name:Installrun:npm ci      -name:Lint with Secretlintrun:npx secretlint "**/*"

This configuration also integrate Pull Request review comment viaactions/setup-node.

• Example Repository:https://github.com/secretlint/secretlint-github-actions-example
• Example Pull Request:https://github.com/secretlint/secretlint-github-actions-example/pull/1/files

If you want to only check diff files, please see following example:

name:test-diffon:push:pull_request:jobs:test-diff:permissions:contents:readname:"Run secretlint to diff files"runs-on:ubuntu-lateststeps:      -name:checkoutuses:actions/checkout@v4with:# fetch history to get all changed files on push or pull_request eventfetch-depth:0      -name:Get changed filesid:changed-filesuses:tj-actions/changed-files@v44      -name:setup Node ${{ matrix.node-version }}uses:actions/setup-node@v4with:node-version:20      -name:Show changed filesrun:echo "${{ steps.changed-files.outputs.all_changed_files }}"      -name:Installif:steps.changed-files.outputs.any_changed == 'true'run:npm ci      -name:Run secretlintif:steps.changed-files.outputs.any_changed == 'true'run:npx secretlint ${{ steps.changed-files.outputs.all_changed_files }}

Mega-Linter is a linters aggregator natively compliant with any CI tool, embedding80+ linting apps, includingsecretlint by default.

You caninstall it on any repository project using the following command (Node.js must be installed previously)

npx mega-linter-runner --install

Secretlint WebExtension works on your browser.

• Firefox:https://addons.mozilla.org/ja/firefox/addon/secretlint/
• Chrome:https://chrome.google.com/webstore/detail/secretlint/hidpojbnemkajlnibhmeilpgoddkjjkf

This web extension aim to founds credentials that are included in your request/response.

Secretlint WebExtension integrate to DevTools in Chrome/Firefox.This extension help web developer to notice exposed credential.

Please use@secretlint/secretlint-formatter-sarif.

npm install @secretlint/secretlint-formatter-sarif --devsecretlint --format @secretlint/secretlint-formatter-sarif "**/*"

Secretlint project followSemantic Versioning(secretlint-rule-preset-canary is exception).

• Patch release (intended to not break your lint build)
  • A bug fix to the CLI or core (including formatters).
  • Improvements to documentation.
  • Non-user-facing changes such as refactoring.
  • Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).
• Minor release (might break your lint build)
  • A new option.
  • An existing rule is deprecated.
  • A new CLI capability is created.
  • New public API are added (new classes, new methods, new arguments to existing methods, etc.).
    • It might break TypeScript definitions
  • A new formatter is created.
• Major release (break your lint build)
  • A new option to an existing rule that results in secretlint reporting more errors by default.
  • An existing formatter is removed.
  • Add new default rule to rule preset.
  • Part of the public API is removed or changed in an incompatible way.

• git-secrets is useful, but it is hard to setup per project.
  • It main use-case is globally installation
  • Secretlint want to install for a project and customize setting per project.
• repo-security-scanner,Gitleaks andtruffleHog is good scan tools
  • Secretlint need to flexible customize that include ignoring definitions, custom rules.
• detect-secrets is similar tools, but it adopts opt-out approach
  • Secretlint adopts opt-in approach
  • We also need to custom rules by user
    • SeeBring-your own-plugins (BYOP), via --custom-plugins option by KevinHock · Pull Request #255 · Yelp/detect-secrets
• GitHub supportsecret scanning, but it only works after commitpush
  • Secretlint works on your local machine, Secretlint can prevent to commit

• Reduce false-positive of linting
• Integration to developing workflow
• Empower Users to Contribute

Secretlint adopt opt-in approach.

In our experience, linting tools that report various errors by default is difficult to use.Opt-in approach help to introduce Secretlint increasing.

It will help to reduce false-positive by configuration.

We think a rule as a documentation.So, Each rule should have reasonable documentation.

We need to describe why this file is error.A rule that has not documentation, It is just a opinionated.

Describe the reason of error and then it will lead to reduce false-positive error.

Also, Secretlint CLI support hyperlink in Terminal.It means that you can jump to rule documentation from lint error message directly.

Example on iTerm 2: Cmd + Click error's messageId and openAWSSecretAccessKey on your browser.

If you want to know support terminal, please seeHyperlinks in Terminal Emulators.

Also, Welcome to Contribution about secretlint documentation!

• Package Manager
  • Require package manager to realize flexible pluggable system
  • Node.js has npm and yarn as package manager
  • Package manager help to install custom plugin/rule by user
• Exist Reference Implementation
  • Node.js already has pluggable linting tools like ESLint, textlint, stylelint etc
  • So Node.js user familiar with pluggable linting tools
  • Previously, I created textlint as same approach, so I familiar with Node.js
• Users
  • JavaScript is Popular language
  • It means that empower Users to Contribute
  • Users can create own rule by own hand

Of course, secretlint also supportDocker.

SeeReleases page.

Pull requests and stars are always welcome.

For bugs and feature requests,please create an issue.

See also,CONTRIBUTING.md andCODE_OF_CONDUCT.md

You can usenpm run gen:rule command to create new rule.

npm run gen:rule

For more details, please seeCONTRIBUTING.md

Benchmark workflow is run on every commit.

• Benchmark:https://secretlint.github.io/secretlint/dev/bench/

• github/azu
• twitter/azu_re

MIT © azu