secretlintでシークレット漏洩を防ぐ

APIキーやアクセストークンをうっかりGitにコミットしてしまった——開発者なら一度はヒヤリとした経験があるのではないでしょうか。GitHubにpushした瞬間にAWSのアクセスキーが漏洩し、不正利用されるといった事故は実際に起きています。

この記事では、こうしたシークレット漏洩を未然に防ぐツール「secretlint」について、概要から導入・活用方法までを解説します。

secretlintとは

secretlintは、ソースコードやプロジェクトファイルに含まれるクレデンシャル（秘密情報）を検出するリンティングツールです。作者はJavaScript/TypeScriptエコシステムで著名なOSS開発者のazu氏で、Node.js/TypeScriptで実装されています。

ESLintがコード品質をチェックするように、secretlintはシークレットの混入をチェックします。

設計思想

secretlintの特徴的な設計思想は、opt-inアプローチです。

多くのシークレット検出ツールはデフォルトで広範なパターンを検出しようとするため、誤検知（false positive）が多くなりがちです。secretlintは逆のアプローチを取り、ユーザーが明示的に選択したルールのみを適用します。これにより誤検知を大幅に減らし、開発者にとってストレスの少ない検出体験を実現しています。

また、プラガブルアーキテクチャを採用しており、コア自体にはビルトインルールがありません。ルールはすべて個別のnpmパッケージとして提供され、プロジェクトの要件に応じて必要なルールだけを導入できます。

検出できるシークレット

推奨ルールプリセット（@secretlint/secretlint-rule-preset-recommend）を導入すると、以下のシークレットを検出できます。

さらに、@secretlint/secretlint-rule-patternを使えば、正規表現で独自のパターンを定義することも可能です。

導入方法

インストール

プロジェクトにsecretlintをインストールします。

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

初期設定ファイルを生成します。

npx secretlint --init

これにより.secretlintrc.jsonが作成されます。

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

実行

プロジェクト内の全ファイルをスキャンします。

npx secretlint "**/*"

シークレットが検出されると、ファイル名・行番号・ルール名とともにエラーが報告されます。検出されたシークレットの値は、デフォルトで***にマスキングされます。

除外設定

バイナリファイルやビルド成果物など、スキャン不要なファイルは.secretlintignoreで除外できます。

node_modules/
dist/
*.png
*.jpg
package-lock.json

npm scriptへの組み込み

package.jsonにスクリプトを追加しておくと便利です。

{
  "scripts": {
    "secretlint": "secretlint '**/*'"
  }
}

npm run secretlintで手軽に実行できるようになります。

動作を検証する

実際にsecretlintがシークレットを検出できるか、サンドボックスで試してみましょう。

テスト用ファイルの作成

ダミーのシークレットを含むファイルを作成します。

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

検出の実行

npx secretlint test-secrets.txt

以下のような出力が得られます。

test-secrets.txt
  1:21  error  [AWSAccessKeyID] found AWS Access Key ID: ***  @secretlint/secretlint-rule-preset-recommend > @secretlint/secretlint-rule-aws
  2:26  error  [AWSSecretAccessKey] found AWS Secret Access Key: ***  @secretlint/secretlint-rule-preset-recommend > @secretlint/secretlint-rule-aws

✖ 2 problems (2 errors, 0 warnings)

AWSのアクセスキーとシークレットキーの両方が検出されました。***と表示されている箇所が、マスキングされた実際のシークレット値です。

他のシークレットパターン

AWSに限らず、GitHub TokenやSlack Tokenなど様々なシークレットを検出できます。推奨プリセットに含まれるルールの一覧は、secretlintのリポジトリで確認できます。

gitフックの設定

secretlintの真価は、コミット前に自動で実行することで発揮されます。gitのpre-commitフックと組み合わせることで、シークレットを含むコミットをブロックできます。

Husky + lint-staged

Node.jsプロジェクトでは、Huskyとlint-stagedの組み合わせが一般的です。

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

package.jsonにlint-stagedの設定を追加します。

{
  "lint-staged": {
    "*": ["secretlint"]
  }
}

Huskyのpre-commitフックでlint-stagedを実行するよう設定します。

npx lint-staged

これで、git commit実行時にステージングされたファイルに対してsecretlintが自動で走り、シークレットが検出された場合はコミットがブロックされます。

Dockerを使ったpre-commitフック

Node.js環境に依存しないプロジェクトでは、pre-commitフレームワークとDockerイメージを組み合わせる方法もあります。

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

CI/CDでの活用

ローカルのgitフックだけでなく、CI/CDパイプラインでもsecretlintを実行することで、より堅牢なセキュリティチェックを実現できます。

GitHub Actions

name: Secretlint
on: [push, pull_request]
permissions:
  contents: read
jobs:
  secretlint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx secretlint "**/*"

--format githubオプションを使うと、Pull Requestの変更ファイルにアノテーションとしてエラーを表示できます。

      - run: npx secretlint --format github "**/*"

他のツールとの比較

シークレット検出ツールはsecretlint以外にもいくつか存在します。代表的なツールとの違いを整理します。

使い分けの指針

• secretlint: Node.jsプロジェクトとの親和性が高く、ESLintのようなリンター体験を求める場合に最適。pre-commitフックでの利用に向いている
• gitleaks: 軽量・高速で、Git履歴全体を含む包括的なスキャンが必要な場合に最適。CI/CDでの高速スキャンに向いている
• TruffleHog: 検出されたシークレットが実際に有効かどうかをAPIで検証したい場合に最適

これらのツールは排他的ではなく、組み合わせて使うこともできます。例えば、ローカルのpre-commitフックにはsecretlintを、CI/CDのGit履歴スキャンにはgitleaksを使うといった構成は、異なる検出アプローチで多層防御を実現できます。

secretlint-disableディレクティブ

テストデータやドキュメント内のサンプル値など、意図的にシークレットに似たパターンを含める場合があります。secretlintではESLintと同様のディレクティブコメントで、特定の行やブロックの検出を抑制できます。

// secretlint-disable-next-line
const EXAMPLE_KEY = "AKIAIOSFODNN7EXAMPLE";

const token = "xoxb-example-token"; // secretlint-disable-line

// secretlint-disable
// この範囲内ではチェックが無効化される
const config = {
  key: "AKIAIOSFODNN7EXAMPLE",
  secret: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
};
// secretlint-enable

設定ファイルのallowsオプションで、特定のパターンをグローバルに許可することもできます。

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend",
      "options": {
        "allows": ["AKIAIOSFODNN7EXAMPLE"]
      }
    }
  ]
}

まとめ

secretlintは、シークレット漏洩を防ぐための実用的なツールです。

• opt-inアプローチにより誤検知が少なく、開発体験を損なわない
• プラガブルアーキテクチャでプロジェクトに必要なルールだけを導入できる
• gitフックとの連携でコミット前にシークレットをブロックできる
• CI/CDに組み込むことで多層防御を実現できる

シークレットの漏洩は一度起きると影響が大きく、事後対応にも手間がかかります。secretlintをプロジェクトに導入して、漏洩を未然に防ぐ仕組みを整えましょう。

ヒヨリ

APIキーをうっかりコミットしちゃう事故、あたしも聞いたことあるよ…怖いよね。secretlintはpre-commitフックに入れておけば自動でチェックしてくれるから、安心感がすごいんだ！導入もnpm installするだけだし、まずは試してみよう！