KengoTODA/inspequte
GitHub: KengoTODA/inspequte
一款专为 CI/CD 和 AI Agent 设计的快速 JVM 字节码静态分析工具，输出标准化 SARIF 报告。
Stars: 5 | Forks: 2
# inspequte
[](https://github.com/KengoTODA/inspequte/actions/workflows/ci.yml)
[](https://crates.io/crates/inspequte)
[](https://plugins.gradle.org/plugin/io.github.kengotoda.inspequte)
[](https://www.gnu.org/licenses/agpl-3.0.en.html)
[](https://www.conventionalcommits.org/en/v1.0.0/)
inspequte 是一款快速、优先考虑 CLI 的静态分析工具，专为 JVM class 和 JAR 文件设计。
它专注于 CI/CD 速度、确定性输出以及仅 SARIF 报告，以实现全球标准兼容性。
该名称结合了 "inspect" 和 "cute"。CLI 命令为 `inspequte`。
## 目标
- 为 CI 流水线提供快速启动和分析。
- 无需 IDE 集成。
- 输出确定性的 SARIF v2.1.0，便于 LLM 友好的自动化。
## 本地规则工作流 (Codex skills)
`.codex/skills/` 下提供了五个用于顺序规则工作的本地技能：
- `inspequte-rule-plan`
- `inspequte-rule-spec`
- `inspequte-rule-impl`
- `inspequte-rule-verify`
- `inspequte-rule-no-go-resume`
推荐顺序：
1. 计划：运行 `inspequte-rule-plan`，提供简短的规则想法和目标 `rule-id`。
2. 规范：运行 `inspequte-rule-spec` 以编写 `src/rules//spec.md`。
3. 实现：基于 `spec.md` 运行 `inspequte-rule-impl` 并添加测试。
4. 准备隔离的验证输入：
scripts/prepare-verify-input.sh [base-ref]
cargo build > verify-input/reports/cargo-build.txt 2>&1
cargo test > verify-input/reports/cargo-test.txt 2>&1
cargo audit --format sarif > verify-input/reports/cargo-audit.sarif
5. 验证：仅使用 `verify-input/` 运行 `inspequte-rule-verify`（无 plan/log 上下文）。
当规则实现在 GitHub Actions 上被标记为 No-Go 时，运行
`inspequte-rule-no-go-resume` 以：
1. 从源 PR 继承 `plan/spec/impl`，
2. 弥补 No-Go 原因中缺失的实现/测试缺口，
3. 更新 `prompts/references/no-go-history.md`，记录实现状态和修复说明。
使用拆分的提示词以减少上下文混淆：
- `prompts/ideate-rule.md`
- `prompts/authoring-plan.md`
- `prompts/authoring-spec.md`
- `prompts/authoring-impl.md`
- `prompts/authoring-verify.md`
- `prompts/authoring-no-go-resume.md`
编排参考：
- `prompts/authoring-rule.md`
规则文档生成是确定性的：
```
scripts/generate-rule-docs.sh
```
此命令重新生成 `docs/rules/index.md` 和 `docs/rules/.md`。
## 字节码/JDK 兼容性
- 支持高达 Java 21（主版本号 65）的 JVM class 文件。
- 在未来的版本中，某些高级字节码属性可能仍会被跳过。
- 某些检查（例如针对局部变量的 Prefer EnumSet 规则）依赖于
`LocalVariableTypeTable` 属性，该属性仅在类使用调试符号编译时存在
（例如 `javac -g`）。字段和方法签名在没有调试信息的情况下仍会被分析。
## 安装
通过 Homebrew tap 安装：
```
brew install KengoTODA/tap/inspequte
```
或从 GitHub Releases 下载预编译的二进制文件：
- Linux (x86_64): `inspequte--amd64-unknown-linux-gnu.tar.gz`
- Linux (ARM64): `inspequte--arm64-unknown-linux-gnu.tar.gz`
- macOS (Apple Silicon): `inspequte--arm64-apple-darwin.tar.gz`
- macOS (Intel): `inspequte--amd64-apple-darwin.tar.gz`
- Windows (x86_64): `inspequte--amd64-pc-windows-msvc.zip`
（`TAG` 是 GitHub 发布标签，例如 `inspequte-v0.15.1`。）
Linux/macOS 示例：
```
TAG="$(gh release list --repo KengoTODA/inspequte --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName')"
TARGET="arm64-apple-darwin" # use amd64-apple-darwin on macOS Intel, arm64-unknown-linux-gnu on Linux ARM64, amd64-unknown-linux-gnu on Linux x86_64
curl -fL -o inspequte.tar.gz \
"https://github.com/KengoTODA/inspequte/releases/download/${TAG}/inspequte-${TAG}-${TARGET}.tar.gz"
tar -xzf inspequte.tar.gz
chmod +x inspequte
sudo mv inspequte /usr/local/bin/inspequte
```
Windows (PowerShell) 示例：
```
$Tag = gh release list --repo KengoTODA/inspequte --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName'
$Asset = "inspequte-$Tag-amd64-pc-windows-msvc.zip"
Invoke-WebRequest -Uri "https://github.com/KengoTODA/inspequte/releases/download/$Tag/$Asset" -OutFile "inspequte.zip"
Expand-Archive -Path "inspequte.zip" -DestinationPath "."
# 移动到包含在 PATH 中的目录
Move-Item ".\\inspequte.exe" "$HOME\\bin\\inspequte.exe" -Force
```
### 手动下载二进制文件的 macOS 说明 (Gatekeeper)
macOS 可能会阻止直接运行从互联网下载的二进制文件（Gatekeeper/隔离行为）。
请遵循 Apple 的官方指南以允许执行：
- [Gatekeeper and runtime protection](https://support.apple.com/guide/security/gatekeeper-and-runtime-protection-sec5599b66df/web)
- [Open a Mac app from an unknown developer](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac)
对于终端工具，在确认二进制文件来源自官方发布版后，您可以移除隔离属性：
```
xattr -d com.apple.quarantine /usr/local/bin/inspequte
```
## CLI 用法
```
inspequte --input app.jar --classpath lib/ --output results.sarif
```
设置 SARIF `run.automationDetails.id`（GitHub 代码扫描类别）：
```
inspequte --input app.jar --classpath lib/ --output results.sarif \
--automation-details-id "inspequte/./main"
```
创建当前发现的基线，以便在未来的运行中忽略它们：
```
inspequte baseline --input app.jar --classpath lib/ --output inspequte.baseline.json
```
使用基线运行以仅输出新问题：
```
inspequte --input app.jar --classpath lib/ --output results.sarif --baseline inspequte.baseline.json
```
如果省略 `--baseline` 输出/输入路径，默认使用 `.inspequte/baseline.json`；缺失文件将被忽略。
您可以通过在路径前加上 `@` 前缀来从文件中读取输入或 classpath 列表。
文件格式为每行一个路径；空行和以 `#` 开头的行将被忽略。
```
inspequte --input @inputs.txt --classpath @classpath.txt --output results.sarif
```
仅使用 `--rules` 运行特定规则。
您可以提供逗号分隔的 ID，重复该选项，或从 `@file` 加载 ID。
```
inspequte --input app.jar --output results.sarif \
--rules SYSTEM_EXIT,THREAD_RUN_DIRECT_CALL \
--rules RETURN_IN_FINALLY
inspequte --input app.jar --output results.sarif --rules @rules.txt
```
对于 `@rules.txt`，每行使用一个规则 ID（支持嵌套的 `@file` 引用）；空行和以 `#` 开头的行将被忽略。
通过 `--json` 提供对 Agent 友好的 JSON 输入：
```
inspequte --json '{"command":"scan","input":["app.jar"],"classpath":["lib/"],"rules":["SYSTEM_EXIT"],"output":"results.sarif"}'
inspequte --json @request.json
cat request.json | inspequte --json -
```
`--json` 与 path/rules/baseline 扫描标志（`--input`, `--classpath`, `--rules`, `--baseline`, `--output`, `--allow-duplicate-classes`）互斥。
请求负载的 JSON Schema 发布于：
- https://kengotoda.github.io/inspequte/schemas/cli-option.json
## Gradle 用法
使用 Gradle 插件：
```
plugins {
id("java")
id("io.github.kengotoda.inspequte") version ""
}
inspequte {
// Optional: forward OTLP collector URL to inspequte via --otel
otel.set("http://localhost:4318/")
// Optional: prefix for --automation-details-id (task appends /)
automationDetailsIdPrefix.set("inspequte/custom-path")
}
// Registered automatically:
// - writeInspequteInputsMain / writeInspequteInputsTest
// - inspequteMain / inspequteTest
// Each inspequte task emits:
// build/inspequte//report.sarif
```
该插件将所有生成的 `inspequte*` 任务挂载到 `check`。
`inspequte` 命令必须在 `PATH` 中可用。
默认情况下，每个任务将 `--automation-details-id` 设置为
`inspequte//`。
您也可以在任务运行时通过 CLI 传递收集器 URL：
`./gradlew inspequteMain --inspequte-otel http://localhost:8080`
您可以从 CLI 覆盖任务的自动化详情 ID：
`./gradlew inspequteMain --inspequte-automation-details-id "inspequte/override/main"`
## SARIF 输出 (示例)
```
{
"version": "2.1.0",
"$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
"runs": [
{
"tool": {
"driver": {
"name": "inspequte",
"informationUri": "https://github.com/KengoTODA/inspequte"
}
},
"results": []
}
]
}
```
## CI 集成 (GitHub Actions)
在 CI 中使用 Gradle 插件并从 GitHub Releases 安装 CLI：
```
- name: Install inspequte
uses: KengoTODA/setup-inspequte@8d212fa51a56245829f88e60f081c6549e312c57
- name: Setup Java
uses: actions/setup-java@v5.2.0
with:
distribution: temurin
java-version: "21"
- name: Setup Gradle
uses: gradle/actions/setup-gradle@v5.0.2
- name: Run inspequte tasks
run: ./gradlew check --no-daemon
- name: Upload SARIF to GitHub Code Scanning (optional)
uses: github/codeql-action/upload-sarif@v4.32.6
with:
sarif_file: results.sarif
```
## Coding agent 集成
使用 coding agent（Codex, Claude Code, GitHub Copilot）运行 `inspequte`，检查
生成的 SARIF，并提出修复建议。
请参阅：
- `docs/coding-agent.md` 获取运行 `inspequte` 的提示词示例。
- `docs/github-actions.md` 获取 GitHub Actions 自动化示例。
用于 coding agent 的示例提示词：
```
Run:
inspequte --input app.jar --classpath lib/ --output results.sarif
Then:
1) Summarize findings by rule ID.
2) Prioritize high-impact issues.
3) Propose patch-ready fixes with file paths.
```
## 许可证
AGPL-3.0。参见 `LICENSE`。
标签：AGPL, DevSecOps, Gradle, JAR, JVM, Kotlin, LLM辅助, Redis利用, Rust, SARIF, Scala, 上游代理, 云安全监控, 可视化界面, 后台面板检测, 开源, 性能优先, 插件, 漏洞测试, 确定性输出, 编码代理, 网络流量审计, 网络调试, 自动化, 通知系统, 静态分析