@secretlint/secretlint-rule-example

An example rule for secretlint. It it for testing.


Keywords
secretlint, testing, rule, credential, docker, git, lint, linting, nodejs, secret
License
MIT
Install
npm install @secretlint/secretlint-rule-example@1.1.0

Documentation

Secretlint Actions Status

Secretlint is pluggable linting tool to prevent commit secret/credential file.

Purpose

  • Scan files and if the file has secret and report it
  • Prevent to commit credential files
  • Pluggable architecture

Motivation

Installation

Using Docker

Prerequisites: Require Docker

Use our Docker 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` -it secretlint/secretlint secretlint "**/*"

secretlint/secretlint docker container work without configuration by design.

Built-in rules:

For more details, please see secretlint's Dockerfile.

Using Node.js

Prerequisites: Require Node.js 10+.

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

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

npx secretlint "**/*"

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

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

Usage

secretlint --help show Usage.

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 formatter name. Default: stylish
  --output-file output file path that is written of reported result.
  --no-color disable color of output.
  --secretlintrc Path to .secretlintrc config file. Default: .secretlintrc.*
  --secretlintignore Path to .secretlintignore file. Default: .secretlintignore
  --profile Show performance profile

Examples
  $ secretlint ./README.md
  # glob pattern should be wrapped with double quote
  $ secretlint "**/*"
  $ secretlint "source/**/*.ini"

Configuration

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

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 text pattern that you want to ignore.

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

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

Rule Packages

Secretlint rules has been implemented as separated modules.

Also, Secretlint provide rule preset that package some rule set.

Integration

Pre-commit Hook

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

Husky + lint-staged

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

Install Husky and lint-staged:

npm install husky lint-staged --save-dev

Edit package.json:

{
  // ...
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*": [
      "secretlint"
    ]
  }
}

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

pre-commit

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

Install pre-commit

# macOS. see also https://pre-commit.com/#install
brew 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:

Architecture

Opt-in instead of Opt-out

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.

A documentation per a Rule

We think a rule as a documentation.

Each rule should have reasonable documentation.

  • How?

Why Node.js?

  • Package Manager
    • Require pacakge manager to realize flexible pluggable system
    • Node.js has npm and yarn as package manager
    • Package manger 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

If you interesting in Docker support, please see Docker support · Issue #7

Changelog

See Releases page.

Running tests

Install devDependencies and Run npm test:

yarn test

Contributing

Pull requests and stars are always welcome.

For bugs and feature requests, please create an issue.

See also, CONTRIBUTING.md and CODE_OF_CONDUCT.md

Author

License

MIT © azu