Claude Code 提交泄露密钥的概率是人类的 2 倍。（2025 年，2800 万个硬编码密钥被推送到 GitHub）GitGuardian 追踪了去年 GitHub 上的每一次公开提交，发现 Claude Code 辅助提交的凭据泄露率为 3.2%，而人类基线为 1.5%。Karpathy 将“氛围编程”描述为“完全顺应氛围，拥抱指数增长，甚至忘记代码本身的存在”。当你不再阅读 diff 时，你也就看不到其中发生了什么。你为了提供上下文而粘贴到提示词中的密钥，会被写进配置文件，而代理没有理由将其与其他字符串区别对待。大多数人最终自己动手接入验证：一个调用扫描器的 pre-commit 钩子，或者一个把发现结果传回代理上下文的脚本。这两者都是你现在需要维护的“胶水”，而且它们都运行在编写代码的会话之外。SonarQube（@SonarSource）提供了一款 CLI，彻底消除了这些胶水代码，只需一条命令即可接入 Claude Code：sonar integrate claude -p 这一步会同时注册钩子并配置 SonarQube MCP 服务器，从而为代理的工作提供三层防护：→ 在你提交的每个提示词以及代理读取或写入的每个文件上运行密钥检测。→ 使用完整 CI 扫描所采用的相同规则，对你代理刚刚编写的代码进行静态分析。→ MCP 服务器将这些发现放入 Claude 的上下文，让它读取自己的问题并修复。密钥检测和 MCP 服务器都可以在 SonarQube 免费层使用，而更深层的代码分析和验证层（属于 Sonar Vortex 的一部分）则需要付费计划并具备相应权限。在下面的视频中，一个真实格式的 GitHub 令牌在模型运行之前、于提示词提交时即被拦截。每个 DIY 设置都有效，直到代理的工作流程发生变化，胶水便悄然失效。随工具自带并内置的验证不存在这种失效模式。在此处找到 SonarQube CLI GitHub 仓库：https://fandf.co/3TiIbRc（别忘了点星标）

SonarSource/sonarqube-cli

来源：https://github.com/SonarSource/sonarqube-cli

SonarQube CLI

构建（https://github.com/SonarSource/sonarqube-cli/actions/workflows/build.yml） 质量门状态（https://sonarcloud.io/summary/new_code?id=SonarSource_sonarqube-cli）

在代码进入生产环境之前，在终端中捕获代码质量和安全问题。 SonarQube CLI 将企业级静态分析集成到你的开发工作流中：

• 🔒 密钥检测 — 扫描代码中的硬编码凭据，防止密钥被发送给 LLM 提供商
• ⚡ 快速反馈循环 — 在本地更改上获得服务端问题检测，无需等待 CI/CD
• 🤖 AI 辅助修复 — 为安全漏洞生成修复建议（SonarQube Cloud）
• 🔗 代理集成 — 为 Claude Code、GitHub Copilot CLI、Codex、Cursor 和 Antigravity 提供无缝钩子
• 📊 可脚本化 — 通过 JSON 输出以编程方式查询和管理 SonarQube 问题

可独立使用，或与以下工具集成： Git 钩子、Claude Code、GitHub Copilot CLI、Codex、Cursor、Antigravity、CI/CD 流水线、自定义自动化

🤖 面向 AI 代理： 如果你是正在阅读本文的 AI 代理，请访问 docs/llms.txt（https://github.com/SonarSource/sonarqube-cli/blob/master/docs/llms.txt）以获取为 LLM 消耗而优化的机器可读命令文档。 我们正在积极收集关于此产品的反馈。请通过此表单（https://forms.gle/xE61HS2E5NzxFCSR9）分享你的想法！

文档

• 📘 官方文档： docs.sonarsource.com/sonarqube-cli（https://docs.sonarsource.com/sonarqube-cli）
• 🌐 项目网站： sonarsource.com/sonarqube/cli（https://sonarsource.com/sonarqube/cli）
• 📖 命令参考： sonarsource.com/sonarqube/cli/commands.html（https://sonarsource.com/sonarqube/cli/commands.html）

目录

• 文档
• 使用此 CLI 的三种方式
• 前提条件
• 快速开始
• 第 1 步：安装
• 第 2 步：身份验证
• 第 3 步：尝试基本命令
• 第 4 步：分析本地更改
• 集成
• Claude Code 集成
• Git 钩子
• GitHub Copilot CLI 集成
• 示例输出
• 故障排除
• 状态管理
• 卸载
• 数据收集
• 贡献
• 许可证

使用此 CLI 的三种方式

SonarQube CLI 专为三种不同用例而设计：

1. 🤖 代理式使用 — 内置对 AI 编码代理（Claude Code、GitHub Copilot CLI、Codex、Cursor 和 Antigravity）的支持，并提供防护措施，防止密钥被发送给 LLM 提供商

sonar integrate claude -g
# 现在 Claude Code 会在处理你的代码之前自动扫描密钥

2. 🖥️ 交互式 CLI — 直接在终端中运行命令，手动扫描代码、检查问题和管理 SonarQube 项目

sonar list issues --project my-app
sonar analyze --file file.ext

3. ⚙️ 脚本与自动化 — 集成到脚本中，用于报告、仪表板或自动质量门

# 生成所有项目的问题报告：
sonar list projects | jq -r '.projects[].key' | while read project; do
  echo "Project: $project"
  sonar list issues --project "$project" | jq -r '.issues[].severity' | sort | uniq -c
done

前提条件

安装前，你需要：

• SonarQube 访问权限（选择其一）：
  • SonarQube Cloud（https://sonarcloud.io）— 开源项目免费，私有仓库付费
  • SonarQube Server — 自托管实例（v9.9+）
• 操作系统：Linux（x86-64、ARM64）、macOS（ARM64）或 Windows（x86-64）

可选：

• Git 2.x+ 用于 git 钩子集成
• Claude Code、GitHub Copilot CLI、Codex、Cursor 或 Antigravity 用于 AI 助手集成

首次使用 SonarQube？ 创建一个免费的 SonarQube Cloud 账户（https://sonarcloud.io/sessions/new）— 开源项目无需信用卡。

快速开始

第 1 步：安装

选择适合你环境的安装渠道：

Homebrew（macOS/Linux）：

brew install sonarqube-cli

Mise（macOS、Linux 或 Windows）：

mise use -g sonarqube-cli@latest

安装脚本（Linux/macOS）：

curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash

安装脚本（Windows，PowerShell）：

irm https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.ps1 | iex

验证安装：

sonar --version
# 示例输出: 1.0.0

注意： 使用安装脚本后请重启终端，以便重新加载更新后的 PATH。Homebrew 会自动管理 PATH，Mise 则假定其 shell 激活已配置。

第 2 步：身份验证

连接到 SonarQube Cloud EU（默认）：

sonar auth login
# 打开浏览器登录 SonarQube 并生成用户令牌
# 完成后返回终端

对于 SonarQube Cloud US：

sonar auth login --server https://sonarqube.us

对于自托管的 SonarQube Server：

sonar auth login --server https://sonarqube.mycompany.com

验证身份验证：

sonar auth status
# Verifying token......
# [✓ Connected]
# Server  https://sonarcloud.io
# Org     my-org
# Source  OS Keychain

对于自动化、CI/CD 和 AI 代理，请通过环境变量传递令牌。CLI 在命令执行时读取这些变量，因此不会将任何内容写入磁盘或系统钥匙串。首先生成一个令牌：SonarQube → 我的账户 → 安全 → 生成令牌。然后在调用 sonar 之前定义以下环境变量（在 CI 中使用运行器的密钥存储，或使用你偏好的本地机制——direnv、不受跟踪的 .env 文件、密码管理器的 CLI 等）：

• SonarQube Cloud：SONARQUBE_CLI_TOKEN + SONARQUBE_CLI_ORG
• 自托管 SonarQube Server：SONARQUBE_CLI_TOKEN + SONARQUBE_CLI_SERVER

导出这些变量后，任何命令都可以直接工作，无需进一步配置：

sonar list projects

请同时设置两个变量——如果只存在 SONARQUBE_CLI_TOKEN，CLI 会在 stderr 上打印警告并回退到钥匙串凭据，这通常是自动化不希望的。切勿提交令牌或将其作为 CLI 参数传递。

第 3 步：尝试基本命令

列出你的项目：

sonar list projects
# {"projects":[{"key":"my-org_my-app","name":"my-app"},
#              {"key":"my-org_demo","name":"demo-project"}],
#  "paging":{"pageIndex":1,"pageSize":500,"total":2,"hasNextPage":false}}

默认输出为 JSON。可通过管道传递给 jq 进行临时过滤，例如 sonar list projects | jq -r '.projects[].key'。

扫描文件中的密钥：

cat > test.js <<'EOF'
const STRIPE_KEY = "sk_live_";
EOF
sonar analyze secrets test.js
# Sonar Secrets CLI - BETA (2.43.0.11106)
# Trying to authenticate to SonarQube Server or Cloud, in order to enable complete functionality
# Authentication successful
# Running analysis...
# Found 1 secret
# Stripe API Key
# File: test.js
# Location: [1:21-1:53]
# Secret: sk_*****************************
# ❌ Secrets found (227ms)
# 💡 Remove the reported secret, then rerun the scan.

当发现密钥时，命令以退出码 51 结束。

检查项目中的问题：

sonar list issues --project my-org_my-app --format table --page-size 3
# SEVERITY | RULE | MESSAGE | FILE
# ---------------------------------------------------------------------------------------------------------------
# CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity | src/preview.tsx:17
# CRITICAL | typescript:S2004 | Refactor this code to not nest functions more than 4...   | src/Preview.tsx:235
# CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity | src/Description.tsx:43

支持的格式：json（默认）、table、toon、csv。

💡 提示： --project 标志通常可选——如果你的工作目录包含 sonar-project.properties 文件或 .sonarlint/ 下的 SonarLint 连接模式绑定，CLI 会从该处获取项目键。

第 4 步：分析本地更改（仅限 SonarQube Cloud）

cd your-project-directory
sonar analyze --file file.ext
# 分析未提交更改中的新问题
# 仅显示你在更改中引入的问题

常用选项：

sonar analyze --file src/myfile.ts    # 分析特定文件
sonar analyze --base main             # 分析与 main 分支相比的更改
sonar analyze --branch feature-xyz    # 设置分支上下文

集成

Claude Code 集成

全局设置（钩子适用于所有 Claude Code 会话）：

sonar auth login
sonar integrate claude -g

项目特定设置（钩子仅适用于此项目）：

cd your-project
sonar auth login
sonar integrate claude --project my-org_my-project

这将安装：

• 用于密钥扫描的 Pre-tool-use 钩子 — 防止硬编码凭据被发送给 LLM 提供商
• SonarQube Agentic Analysis 集成 — 在工作流中进行服务端代码质量分析
• 模型上下文协议（MCP）服务器 — 直接从 Claude Code 访问 SonarQube 数据

Git 钩子

Pre-commit 钩子（在每次提交前扫描暂存文件）：

sonar integrate git --hook pre-commit

Pre-push 钩子（在每次推送前扫描已提交文件）：

sonar integrate git --hook pre-push

全局 git 钩子（适用于所有仓库）：

sonar integrate git --hook pre-commit --global

对于 CI/CD 或自动化（非交互模式）：

sonar integrate git --hook pre-commit --non-interactive
# 跳过所有提示，出错时快速失败

GitHub Copilot CLI 集成

全局设置：

sonar auth login
sonar integrate copilot -g

项目特定设置：

cd your-project
sonar auth login
sonar integrate copilot --project my-org_my-project

这将安装：

• 用于密钥扫描的 Pre-tool-use 钩子 — 防止硬编码凭据被发送给 LLM 提供商
• SonarQube Agentic Analysis 集成 — 在工作流中进行服务端代码质量分析
• 模型上下文协议（MCP）服务器 — 直接从 Copilot 访问 SonarQube 数据

示例输出

扫描密钥

$ sonar analyze secrets src/config.ts
sonar-secrets 2.43.0.11106 is already installed (latest)
Sonar Secrets CLI - BETA (2.43.0.11106)
Trying to authenticate to SonarQube Server or Cloud, in order to enable complete functionality
Authentication successful
Running analysis...
Found 1 secret
Stripe API Key
File: src/config.ts
Location: [5:20-5:52]
Secret: sk_*****************************
❌ Secrets found (227ms)
💡 Remove the reported secret, then rerun the scan.

退出码：未发现密钥时为 0，至少发现一个时为 51。

列出问题

sonar list issues 默认输出 JSON；添加 --format table 可查看如下人类可读视图。

$ sonar list issues --project my-org_my-app --severities CRITICAL,BLOCKER --page-size 3 --format table
SEVERITY | RULE | MESSAGE | FILE
-------------------------------------------------------------------------------------------------------------------------
CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity from 26 to the 15 allowed. | code/addons/a11y/src/preview.tsx:17
CRITICAL | typescript:S2004 | Refactor this code to not nest functions more than 4 levels deep. | code/addons/docs/src/blocks/components/Preview.tsx:235
CRITICAL | typescript:S3776 | Refactor this function to reduce its Cognitive Complexity from 23 to the 15 allowed. | code/addons/vitest/src/components/Description.tsx:43

分析本地更改

$ sonar analyze
SonarQube Agentic Analysis: no files in the change set to analyze.

当针对已配置 SonarQube Cloud Agentic Analysis 的项目存在暂存更改时，分析器会以可通过 --format 选择的相同 text/json 格式报告更改集引入的新问题。

面向 LLM 优化的输出格式

对于 AI 编码助手，请使用 --format toon——一种 token 高效、类似 YAML 的 JSON 负载编码：

$ sonar list issues --project my-org_my-app --severities BLOCKER --page-size 1 --format toon
total: 88
p: 1
ps: 1
paging:
  pageIndex: 1
  pageSize: 1
  total: 88
issues[1]:
- key: AZ0avojpNWh-T1cKsujg
  rule: "typescript:S3516"
  severity: BLOCKER
  component: "my-org_my-app:src/ConfigFile.ts"
  project: my-org_my-app
  line: 377
  message: "Refactor this function to not always return the same value."
  type: CODE_SMELL

此格式专为 LLM 解析而设计，可用于 Claude Code、GitHub Copilot CLI、Codex、Cursor、Antigravity 或自定义 AI 工作流。

故障排除

“项目键未找到”

症状： Error: Project 'my-project' not found

原因： 使用了项目显示名称而非项目键。

解决方案： 使用 sonar list projects 的 JSON 输出中的确切项目键：

# 找到正确的键：
sonar list projects -q my-project
# {"projects":[{"key":"my-org_my-project","name":"my-project"}],
#  "paging":{"pageIndex":1,"pageSize":500,"total":1,"hasNextPage":false}}

# 或者仅获取键：
sonar list projects -q my-project | jq -r '.projects[].key'

# 在后续命令中使用键值（而不是名称）：
sonar list issues --project my-org_my-project

“未找到问题”但 SonarQube Web UI 中存在问题

原因： 项目尚未被扫描，或者你正在检查错误的分支。

解决方案：

1. 确认你的项目在 SonarQube 中至少完成了一次扫描
2. 确