security

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Security: Secret Detection

安全：机密检测

This skill activates when performing secret detection, credential scanning, or implementing security checks for leaked sensitive data in code repositories.

当需要执行机密检测、凭证扫描，或为代码仓库中泄露的敏感数据实施安全检查时，将激活此技能。

When to Use This Skill

何时使用此技能

Activate when:

Scanning repositories for leaked secrets, API keys, or credentials
Setting up pre-commit hooks for secret detection
Auditing codebases for exposed passwords or tokens
Implementing CI/CD security pipelines
Checking git history for accidentally committed secrets
Validating that .gitignore excludes sensitive files

在以下场景激活：

扫描代码仓库中泄露的机密信息、API密钥或凭证
配置提交前钩子（pre-commit hooks）以进行机密检测
审计代码库中暴露的密码或令牌
实施CI/CD安全流水线
检查Git历史记录中是否存在意外提交的机密信息
验证.gitignore是否排除了敏感文件

Pre-Commit Hook (Automatic)

自动提交前钩子

When this skill is loaded, a pre-commit hook automatically scans staged files for secrets before every

git commit

command. This provides defense-in-depth by catching secrets before they enter git history.

加载此技能后，每次执行

git commit

命令前，提交前钩子会自动扫描暂存文件中的机密信息。这通过在机密信息进入Git历史记录前将其拦截，实现了纵深防御。

Hook Behavior

钩子行为

git commit -m "message"
         ↓
PreToolUse hook fires
         ↓
Extract staged files
         ↓
Run gitleaks --no-git
         ↓
    ┌─ Clean ─┴─ Secrets ─┐
    ↓                     ↓
  Allow               Block commit
  commit              (exit code 2)

git commit -m "message"
         ↓
PreToolUse钩子触发
         ↓
提取暂存文件
         ↓
执行gitleaks --no-git
         ↓
    ┌─ 无泄露 ─┴─ 发现机密 ─┐
    ↓                     ↓
  允许提交               阻止提交
                        (退出码2)

What Gets Scanned

扫描范围

Only staged files are scanned (not the entire working tree)
Uses
```
.gitleaks-baseline.json
```
if present to ignore known false positives
Uses
```
.gitleaks.toml
```
if present for custom detection rules

仅扫描暂存文件（而非整个工作区）
若存在
```
.gitleaks-baseline.json
```
文件，将忽略已知误报
若存在
```
.gitleaks.toml
```
文件，将使用自定义检测规则

When Secrets Are Detected

发现机密时的处理

If the hook detects secrets, the commit is blocked with guidance:

[gitleaks] SECRETS DETECTED in staged files!
[gitleaks] Commit blocked. Remove secrets before committing.
[gitleaks]
[gitleaks] Options:
[gitleaks]   1. Remove the secret from the file
[gitleaks]   2. Use environment variables instead
[gitleaks]   3. Add to .gitleaks-baseline.json if false positive

若钩子检测到机密信息，将阻止提交并给出指引：

[gitleaks] 在暂存文件中检测到机密信息！
[gitleaks] 提交已阻止。请移除机密信息后再提交。
[gitleaks]
[gitleaks] 可选操作：
[gitleaks]   1. 从文件中删除机密信息
[gitleaks]   2. 使用环境变量替代
[gitleaks]   3. 若为误报，添加至.gitleaks-baseline.json

Container Runtime Requirements

容器运行时要求

The hook requires a container runtime to run gitleaks. It auto-detects:

Apple Container (macOS 26+)
Docker (Docker Desktop or Engine)
Colima via mise

If no runtime is available, the hook logs a warning and allows the commit.

该钩子需要容器运行时来执行gitleaks，它会自动检测以下运行时：

Apple Container（macOS 26+）
Docker（Docker Desktop或Engine）
Colima（通过mise）

若未检测到可用运行时，钩子将记录警告并允许提交。

When to Use security-review Instead

何时改用security-review技能

Use the

security-review

skill for:

STRIDE threat modeling
Security architecture reviews
Vulnerability assessments
Security documentation and reports
Risk prioritization
Attack surface analysis

Task	Use `security`	Use `security-review`
Scan for secrets in code	✓
Detect leaked API keys	✓
Pre-commit secret scanning	✓
STRIDE threat modeling		✓
Security architecture review		✓
Vulnerability assessment		✓
Security report documentation		✓
Risk prioritization		✓

以下场景请使用

security-review

技能：

STRIDE威胁建模
安全架构评审
漏洞评估
安全文档与报告
风险优先级排序
攻击面分析

任务	使用 `security`	使用 `security-review`
扫描代码中的机密信息	✓
检测泄露的API密钥	✓
提交前机密扫描	✓
STRIDE威胁建模		✓
安全架构评审		✓
漏洞评估		✓
安全报告文档		✓
风险优先级排序		✓

Gitleaks

Gitleaks is an open-source tool for detecting secrets and sensitive information in git repositories. It scans commit history and file contents for patterns matching known secret formats.

Gitleaks是一款开源工具，用于检测Git仓库中的机密信息和敏感数据。它会扫描提交历史和文件内容，匹配已知机密格式的模式。

Common Secrets Detected

常见检测到的机密类型

AWS Access Keys and Secret Keys
Google Cloud API Keys
GitHub Personal Access Tokens
Private Keys (RSA, SSH, PGP)
Database Connection Strings
JWT Tokens
Stripe API Keys
Slack Tokens
Generic Passwords and API Keys

AWS访问密钥和秘密密钥
Google Cloud API密钥
GitHub个人访问令牌
私钥（RSA、SSH、PGP）
数据库连接字符串
JWT令牌
Stripe API密钥
Slack令牌
通用密码和API密钥

Basic Usage

基础用法

bash

undefined

bash

undefined

Scan current directory

扫描当前目录

gitleaks detect --source="." -v

Scan with JSON report

扫描并生成JSON报告

gitleaks detect --source="." -v --report-path=report.json --report-format=json

Scan only staged changes (pre-commit)

仅扫描暂存的变更（提交前场景）

gitleaks protect --staged

Scan git history

扫描Git历史记录

gitleaks detect --source="." --log-opts="--all"

undefined

gitleaks detect --source="." --log-opts="--all"

undefined

Configuration

配置

Create a

.gitleaks.toml

file to customize detection:

toml

[extend]

创建

.gitleaks.toml

文件来自定义检测规则：

toml

[extend]

Extend default rules

扩展默认规则

useDefault = true

[[rules]] id = "custom-api-key" description = "Custom API Key Pattern" regex = '''(?i)custom[-]?api[-]?key['"]?\s*[=:]\s*'"''' keywords = ["custom_api_key", "custom-api-key"]

[allowlist] paths = [ '''.gitleaks.toml$''', '''(.)?test(.)''', '''.git''' ]

regexes = [ '''EXAMPLE_.*''', '''REDACTED''' ]

undefined

useDefault = true

[[rules]] id = "custom-api-key" description = "自定义API密钥模式" regex = '''(?i)custom[-]?api[-]?key['"]?\s*[=:]\s*'"''' keywords = ["custom_api_key", "custom-api-key"]

[allowlist] paths = [ '''.gitleaks.toml$''', '''(.)?test(.)''', '''.git''' ]

regexes = [ '''EXAMPLE_.*''', '''REDACTED''' ]

undefined

Exit Codes

退出码

```
0
```
: No leaks found
```
1
```
: Leaks detected
Other: Configuration or runtime error

```
0
```
: 未发现泄露
```
1
```
: 检测到泄露
其他值：配置或运行时错误

Scripts

脚本

This skill includes scripts for running gitleaks with automatic container runtime detection.

此技能包含用于运行gitleaks的脚本，可自动检测容器运行时。

gitleaks.nu (Nushell)

gitleaks.nu（Nushell脚本）

Cross-platform Nushell script with automatic runtime detection:

bash

undefined

跨平台Nushell脚本，支持自动运行时检测：

bash

undefined

Run with auto-detected runtime

使用自动检测到的运行时执行

nu scripts/gitleaks.nu

Specify runtime

指定运行时

nu scripts/gitleaks.nu --runtime docker nu scripts/gitleaks.nu --runtime container # Apple Container (macOS 26+) nu scripts/gitleaks.nu --runtime colima

nu scripts/gitleaks.nu --runtime docker nu scripts/gitleaks.nu --runtime container # Apple Container（macOS 26+） nu scripts/gitleaks.nu --runtime colima

Generate report

生成报告

nu scripts/gitleaks.nu --report ./report.json

Use custom config

使用自定义配置

nu scripts/gitleaks.nu --config ./.gitleaks.toml

Scan specific path

扫描指定路径

nu scripts/gitleaks.nu --path ./src

undefined

nu scripts/gitleaks.nu --path ./src

undefined

gitleaks.sh (Bash)

gitleaks.sh（Bash脚本）

Bash script with the same capabilities:

bash

undefined

具备相同功能的Bash脚本：

bash

undefined

Run with auto-detected runtime

使用自动检测到的运行时执行

./scripts/gitleaks.sh

Specify runtime

指定运行时

./scripts/gitleaks.sh --runtime docker ./scripts/gitleaks.sh -R container

Generate report

生成报告

./scripts/gitleaks.sh --report ./report.json

Use custom config

使用自定义配置

./scripts/gitleaks.sh --config ./.gitleaks.toml

undefined

./scripts/gitleaks.sh --config ./.gitleaks.toml

undefined

Container Runtimes

容器运行时

The scripts support three container runtimes with automatic detection:

脚本支持三种容器运行时，并可自动检测：

Detection Priority

检测优先级

Apple Container (macOS 26+) - Native macOS containerization
Docker - Docker Desktop or Docker Engine
Colima - Lightweight container runtime via mise

Apple Container（macOS 26+）- macOS原生容器化工具
Docker - Docker Desktop或Docker Engine
Colima - 轻量级容器运行时（通过mise管理）

Apple Container (macOS 26+)

Apple Container（macOS 26+）

Native container support in macOS 26 and later:

bash

undefined

macOS 26及以上版本的原生容器支持：

bash

undefined

Check status

检查状态

container system status

Start runtime

启动运行时

container system start

Run gitleaks

执行gitleaks

container run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v

undefined

container run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v

undefined

Docker

Docker Desktop or Docker Engine:

bash

undefined

Docker Desktop或Docker Engine：

bash

undefined

Check status

检查状态

docker info >/dev/null 2>&1

Start (macOS)

启动（macOS系统）

open -a Docker

Run gitleaks

执行gitleaks

docker run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v

undefined

docker run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v

undefined

Colima via mise

Colima（通过mise）

Lightweight runtime managed through mise:

bash

undefined

由mise管理的轻量级运行时：

bash

undefined

Check status

检查状态

mise exec colima@latest -- colima status

Start runtime

启动运行时

mise exec colima@latest -- colima start

Run gitleaks

执行gitleaks

mise exec colima@latest -- docker run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v


Using `mise exec` provides automatic installation and version management without requiring global installation.

mise exec colima@latest -- docker run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v


使用`mise exec`可自动完成安装和版本管理，无需全局安装。

Pre-Commit Integration

提交前钩子集成

Add gitleaks to pre-commit hooks:

yaml

undefined

将gitleaks添加到提交前钩子：

yaml

undefined

.pre-commit-config.yaml

repos:

repo: https://github.com/gitleaks/gitleaks rev: v8.18.0 hooks:
- id: gitleaks


Install and run:

```bash
pre-commit install
pre-commit run gitleaks --all-files

repos:

repo: https://github.com/gitleaks/gitleaks rev: v8.18.0 hooks:
- id: gitleaks


安装并执行：

```bash
pre-commit install
pre-commit run gitleaks --all-files

CI/CD Integration

CI/CD集成

GitHub Actions

yaml

name: Gitleaks

on: [push, pull_request]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

yaml

name: Gitleaks

on: [push, pull_request]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

yaml

gitleaks:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect --source="." -v
  allow_failure: false

yaml

gitleaks:
  stage: security
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect --source="." -v
  allow_failure: false

Baseline Management

基线管理

Create a baseline to ignore known false positives:

bash

undefined

创建基线以忽略已知误报：

bash

undefined

Generate baseline

生成基线

gitleaks detect --source="." -v --baseline-path=.gitleaks-baseline.json

Scan using baseline

使用基线进行扫描

gitleaks detect --source="." -v --baseline-path=.gitleaks-baseline.json


Add `.gitleaks-baseline.json` to version control to track acknowledged findings.

gitleaks detect --source="." -v --baseline-path=.gitleaks-baseline.json


将`.gitleaks-baseline.json`加入版本控制，以跟踪已确认的检测结果。

Best Practices

最佳实践

Shift-Left Security

左移安全

Enable gitleaks in pre-commit hooks to catch secrets before they enter history
Run scans on every PR in CI/CD pipelines
Scan regularly even if not making changes

在提交前钩子中启用gitleaks，在机密信息进入历史记录前拦截
在CI/CD流水线的每个PR中执行扫描
即使没有变更，也定期执行扫描

When Secrets Are Found

发现机密信息后的处理

Revoke immediately - Rotate the exposed credential
Remove from history - Use
```
git filter-branch
```
or BFG Repo Cleaner
Add to .gitignore - Prevent future commits of sensitive files
Update baseline - If false positive, add to baseline

立即吊销 - 轮换暴露的凭证
从历史记录中移除 - 使用
```
git filter-branch
```
或BFG Repo Cleaner工具
添加到.gitignore - 防止未来提交敏感文件
更新基线 - 若为误报，将其添加到基线中

Prevention

预防措施

Use environment variables for secrets
Use secret management tools (Vault, AWS Secrets Manager)
Add secret patterns to
```
.gitignore
```
Configure IDE plugins to warn about secrets
Use
```
.env.example
```
files without real values

使用环境变量存储机密信息
使用机密管理工具（如Vault、AWS Secrets Manager）
将机密信息模式添加到.gitignore
配置IDE插件以警告机密信息
使用不含真实值的
```
.env.example
```
文件

Mise Tasks Template

Mise任务模板

Copy the mise tasks from

templates/mise.toml

to add gitleaks scanning to any project:

bash

undefined

将

templates/mise.toml

中的Mise任务复制到项目中，即可添加gitleaks扫描功能：

bash

undefined

Available tasks after copying template

复制模板后可用的任务

mise gitleaks # Scan with Apple Container (default) mise gitleaks:docker # Scan with Docker mise gitleaks:colima # Scan with Colima

mise gitleaks:stop # Stop all runtimes mise gitleaks:stop:container mise gitleaks:stop:docker mise gitleaks:stop:colima


The tasks automatically:
- Detect and use `.gitleaks-baseline.json` if present
- Start the container runtime if not running
- Scan the repository root

mise gitleaks # 使用Apple Container扫描（默认） mise gitleaks:docker # 使用Docker扫描 mise gitleaks:colima # 使用Colima扫描

mise gitleaks:stop # 停止所有运行时 mise gitleaks:stop:container mise gitleaks:stop:docker mise gitleaks:stop:colima


这些任务会自动：
- 检测并使用已存在的`.gitleaks-baseline.json`
- 若运行时未启动则自动启动
- 扫描仓库根目录

Key Principles

核心原则

Defense in depth: Run checks at multiple stages (local, CI, scheduled)
Fail fast: Block PRs with detected secrets
Zero tolerance: Treat all secret exposures as security incidents
Continuous monitoring: Schedule regular scans of entire history
Clear ownership: Define who handles secret remediation

纵深防御：在多个阶段（本地、CI、定时任务）执行检查
快速失败：阻止包含机密信息的PR
零容忍：将所有机密信息暴露视为安全事件
持续监控：定期扫描完整的历史记录
明确职责：定义机密信息修复的负责人