SecretLint — A Linter for Preventing Committing Credentials

According to GitHub’s secret scanning alerts, thousands of secrets are leaked every month. The scary part? Many of these leaks go unnoticed for days or even weeks.

It happens more often than we’d like to admit. I’ve seen AWS keys accidentally pushed to GitHub, API tokens sitting in plain text in config files, and private keys casually hanging out in documentation.

The cost of a leaked credential can be enormous - both in terms of security risks and engineering time spent rotating keys. Taking the time to set up proper safeguards now can save countless hours of incident response later.

That’s where Secretlint comes in. It’s an open-source tool I’ve been using extensively to catch these issues before they become problems.

Getting Started with Secretlint

You have two main options for installing Secretlint:

1. Using Docker (Recommended for CI/CD):

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

2. Using NPM (Better for local development):

I prefer using NPM for local development as it integrates better with other development tools. Let’s walk through that setup.

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

Next, we’ll initialize Secretlint in our project.

1
➜  trevorlasn.com git:(master) ✗ npx secretlint --init

This creates a .secretlintrc.json file in the root of our project.

1
{
2
  "rules": [
3
    {
4
      "id": "@secretlint/secretlint-rule-preset-recommend"
5
    }
6
  ]
7
}

Running Secretlint for trevorlasn.com to see if it catches any secrets.

1
Create /Users/trevorindreklasn/Projects/trevorlasn.com/.secretlintrc.json
2
➜  trevorlasn.com git:(master) ✗ npx secretlint "**/*"
3

4
➜  trevorlasn.com git:(master)

Looks good, I don’t have any secrets in my codebase. To demonstrate how Secretlint works, I’ve created a controlled example below. This shows the type of sensitive information Secretlint is designed to catch:

Running Secretlint on this example triggers our security checks:

1
➜  trevorlasn.com git:(master) ✗ npx secretlint 'src'
2

3
/Users/trevorindreklasn/Projects/trevorlasn.com/src/content/blog/secret-lint/InsecureKeyDisplay.tsx
4
  12:25  error  [PrivateKey] found private key: -----BEGIN RSA PRIVATE KEY-----
5
MIICWwIBAAKBgQCYdGaf5uYMsilGHfnx/zxXtihdGFr3hCWwebHGhgEAVn0xlsTd
6
1QwoKi+rpI1O6hzyVOuoQtboODsONGRlHbNl6yJ936Yhmr8PiNwpA5qIxZAdmFv2
7
tqEllWr0dGPPm3B/2NbjuMpSiJNAcBQa46X++doG5yNMY8NCgTsjBZIBKwIDAQAB
8
AoGAN+Pkg5aIm/rsurHeoeMqYhV7srVtE/S0RIA4tkkGMPOELhvRzGmAbXEZzNkk
9
nNujBQww4JywYK3MqKZ4b8F1tMG3infs1w8V7INAYY/c8HzfrT3f+MVxijoKV2Fl
10
JlUXCclztoZhxAxhCR+WC1Upe1wIrWNwad+JA0Vws/mwrEECQQDxiT/Q0lK+gYaa
11
+riFeZmOaqwhlFlYNSK2hCnLz0vbnvnZE5ITQoV+yiy2+BhpMktNFsYNCfb0pdKN
12
D87x+jr7AkEAoZWITvqErh1RbMCXd26QXZEfZyrvVZMpYf8BmWFaBXIbrVGme0/Q
13
d7amI6B8Vrowyt+qgcUk7rYYaA39jYB7kQJAdaX2sY5gw25v1Dlfe5Q5WYdYBJsv
14
0alAGUrS2PVF69nJtRS1SDBUuedcVFsP+N2IlCoNmfhKk+vZXOBgWrkZ1QJAGJlE
15
FAntUvhhofW72VG6ppPmPPV7VALARQvmOWxpoPSbJAqPFqyy5tamejv/UdCshuX/
16
9huGINUV6BlhJT6PEQJAF/aqQTwZqJdwwJqYEQArSmyOW7UDAlQMmKMofjBbeBvd
17
H4PSJT5bvaEhxRj7QCwonoX4ZpV0beTnzloS55Z65g==
18
-----END RSA PRIVATE KEY-----  @secretlint/secretlint-rule-preset-recommend > @secretlint/secretlint-rule-privatekey
19

20
✖ 1 problem (1 errors, 0 warnings)
21

22
➜  trevorlasn.com git:(master) ✗

The error above shows how Secretlint identifies private keys in your codebase. In a real project, this would prevent the accidental commit of sensitive credentials. This example uses a non-functional key for demonstration purposes only.

What Secretlint Can Detect

Beyond private keys, Secretlint can identify various types of sensitive information:

• AWS access keys and secret keys
• Google Cloud credentials
• API tokens and keys
• Database connection strings
• Basic authentication credentials
• And more through custom rules

Setting Up Pre-commit Hooks

Pre-commit hooks are like security guards for your git repository. They run checks on your code before each commit, making sure no sensitive data slips through. Here’s how to set them up using Husky and lint-staged:

1
# Install dependencies
2
npm install --save-dev husky lint-staged
3

4
# Initialize Husky
5
npx husky-init

This creates a .husky directory in your project with the basic hook setup. Next, we’ll configure it to run Secretlint.

Update your package.json with these settings:

1
{
2
  "scripts": {
3
    "prepare": "husky install"
4
  },
5
  "lint-staged": {
6
    "*": "secretlint"
7
  }
8
}

• The prepare script runs automatically after npm install, setting up Husky for anyone who clones your repository
• lint-staged configuration tells Husky to run Secretlint on all files that are staged for commit

Finally, add the pre-commit hook:

1
npx husky add .husky/pre-commit "npx lint-staged"

Now, when you try to commit a file containing secrets, here’s what happens:

1
➜ git commit -m "Update config"
2
🔍 Running Secretlint...
3
✖ secretlint found 1 problem(s)
4
  ./config.js
5
    1:10  error  Found AWS Access Key: AKIA...
6

7
commit aborted

Want to temporarily skip these checks? (Use with caution!)

1
git commit -m "message" --no-verify

But seriously, if you find yourself wanting to skip these checks, it’s usually a sign that something needs fixing in your code, not in your commit process.

Remember to add these files to your .gitignore

1
node_modules
2
.husky/_

Advanced Configuration

Secretlint’s real power comes from its customization options. Let’s dive into some advanced configurations I use in different scenarios:

Customizing Rules

The basic configuration is just the start. Here’s how I structure more sophisticated rule sets:

1
{
2
  "rules": [
3
    {
4
      "id": "@secretlint/secretlint-rule-preset-recommend",
5
      "rules": [
6
        {
7
          "id": "@secretlint/secretlint-rule-aws",
8
          "options": {
9
            "allows": [
10
              "/^AKIA_EXAMPLE_/",
11
              "/^DUMMY_AWS_/"
12
            ]
13
          }
14
        },
15
        {
16
          "id": "@secretlint/secretlint-rule-github",
17
          "options": {
18
            "allows": [
19
              "/^ghp_EXAMPLE/"
20
            ]
21
          }
22
        }
23
      ]
24
    },
25
    {
26
      "id": "@secretlint/secretlint-rule-pattern",
27
      "options": {
28
        "patterns": [
29
          {
30
            "name": "custom-api-key",
31
            "pattern": "/MY_API_KEY_[A-Z0-9]{32}/",
32
            "message": "Found custom API key"
33
          }
34
        ]
35
      }
36
    }
37
  ]
38
}

Handling False Positives

False positives can be frustrating. Here are three ways I handle them:

1. Using allowMessageIds

1
{
2
  "rules": [
3
    {
4
      "id": "@secretlint/secretlint-rule-aws",
5
      "allowMessageIds": [
6
        "AWSAccountID"  // Ignore AWS account ID detections
7
      ]
8
    }
9
  ]
10
}

2. Using Rule-Specific Allows

1
{
2
  "rules": [
3
    {
4
      "id": "@secretlint/secretlint-rule-privatekey",
5
      "options": {
6
        "allows": [
7
          "/BEGIN PUBLIC KEY/",  // Allow public keys
8
          "/EXAMPLE_PRIVATE_KEY/" // Allow example keys in docs
9
        ]
10
      }
11
    }
12
  ]
13
}

3. Using Inline Comments

1
// secretlint-disable-next-line
2
const exampleKey = "AKIA_EXAMPLE_KEY";
3

4
/* secretlint-disable */
5
const testData = {
6
  key: "test_key",
7
  secret: "test_secret"
8
};
9
/* secretlint-enable */

While Secretlint is great at catching credentials before they make it into your codebase, it’s just one piece of the security puzzle. I’ve found it works best when combined with proper secret management systems, environment variables for configuration, regular security audits, and ongoing team education about security practices.

References

• https://secretlint.github.io/
• https://github.com/secretlint/secretlint
• https://typicode.github.io/husky/