# https://github.com/Vorim-AI-Labs/vorim-agent-audit 项目说明书

生成时间：2026-06-18 18:55:59 UTC

## 目录

- [Project Overview & Quick Start](#page-1)
- [System Architecture & Code Layout](#page-2)
- [Detection Rules & Pattern Catalog](#page-3)
- [CLI Usage, Output Formats & CI Integration](#page-4)

<a id='page-1'></a>

## Project Overview & Quick Start

### 相关页面

相关主题：[System Architecture & Code Layout](#page-2), [CLI Usage, Output Formats & CI Integration](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)
- [package.json](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json)
- [src/index.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts)
- [src/types.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts)
- [src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)
- [src/patterns.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)
- [src/report.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts)
- [src/rules/hardcoded-keys.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)
- [src/rules/shared-credentials.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts)
- [vitest.config.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/vitest.config.ts)
</details>

# Project Overview & Quick Start

## 项目定位与目标

`@vorim/agent-audit` 是一款**免费的 AI Agent 代码卫生检查工具**，专注于在源码层面发现 AI Agent 项目中最常见的三类身份反模式：[package.json](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json) 中将其描述为「Scans for hardcoded LLM keys, shared credentials, and long-lived agent permissions in TypeScript, JavaScript, and Python projects」。

该工具的核心价值在于解决一个生产痛点：当 Agent 出现安全事件时，运维团队无法回答「哪个 Agent 触发了动作」「它被授权做什么」「如何撤销权限」这三个问题。[README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md) 通过三个反例（共享 OpenAI Key、`scope: "*"`、`.env` 中硬编码密钥）说明了这些反模式如何让事故无法溯源。

工具运行完全本地化——**无注册、无 API Key、无数据上传**，30 秒内完成扫描并输出报告。

## 快速开始

最简使用方式无需安装，直接通过 npx 触发：

```bash
npx @vorim/agent-audit
```

命令将扫描当前目录，并在终端输出彩色报告。包内同时提供两个二进制入口 [package.json:18-21]()：`vorim-audit` 与 `agent-audit`，二者均指向 `dist/index.js`。

### CI 集成

工具原生支持 CI 场景。[README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md) 给出两种典型集成方式：

**GitHub Actions：**
```yaml
- name: Audit agent code
  run: npx @vorim/agent-audit --fail-on high
```

**Pre-commit Hook（Husky）：**
```json
{
  "scripts": {
    "audit:agents": "vorim-audit --fail-on critical --silent"
  }
}
```

`--fail-on` 参数可设为 `critical | high | medium | none` 中的任意一级，控制进程退出码，便于流水线按严重程度阻断。

### 本地开发

源码构建基于 TypeScript，运行时要求 **Node.js >= 18** [package.json:34-36]()。常用脚本：

| 脚本命令 | 作用 |
|---------|------|
| `npm run build` | 编译 TypeScript 到 `dist/` |
| `npm run dev` | 监听模式编译 |
| `npm test` | 运行 Vitest 单元测试 |
| `npm run lint` | 仅做类型检查（`tsc --noEmit`） |
| `npm run prepublishOnly` | 发布前自动 build + test |

测试入口配置见 [vitest.config.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/vitest.config.ts)，仅扫描 `test/**/*.test.ts`，环境为 Node。

## 核心能力：检测的三大反模式

工具的检测能力由 [src/types.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts) 中的 `Category` 类型精确刻画，分为三类：

| 类别 | 严重等级 | 对应规则文件 | 检测目标 |
|------|---------|-------------|---------|
| `hardcoded-key` | critical / high | [src/rules/hardcoded-keys.ts]() | 源码中硬编码的 LLM/云服务密钥 |
| `shared-credential` | high | [src/rules/shared-credentials.ts]() | 同一文件内多个 Agent 共享同一凭据变量 |
| `long-lived` | medium | （基于 `BROAD_PERMISSION_PATTERNS`） | Agent 配置中通配 scope / 永久有效权限 |

### 硬编码密钥检测

[src/patterns.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts) 维护了一份 `KEY_PATTERNS` 列表，覆盖 OpenAI、Anthropic、Google AI、AWS Bedrock、Azure OpenAI、Stripe、GitHub、Hugging Face、Cohere、Mistral、Perplexity、LangSmith、Pinecone、Slack 等十余家服务。每个 pattern 包含 `provider`、`regex`、`description` 与 `remediation` 四个字段，既用于匹配，也用于报告中的修复建议。

[src/rules/hardcoded-keys.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts) 进一步定义 `CRITICAL_PROVIDERS` 集合（OpenAI、Anthropic、AWS Bedrock、Azure OpenAI、Google AI、Stripe），这些提供商的密钥泄漏后果最严重，因此固定标记为 `critical`。同时内置 `PLACEHOLDER_INDICATORS`（如 `your_api_key`、`example`、`redacted`、`<your-...>`）用于抑制示例代码带来的误报。

### 共享凭据检测

[src/rules/shared-credentials.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts) 通过两步判定「共享凭据」：先用 `CREDENTIAL_PASS_PATTERN` 收集所有 `apiKey/api-key/openai_api_key` 等字段的变量传递点，再用 `AGENT_INSTANTIATION_PATTERN` 识别 `Agent/ChatOpenAI/LLM/Chain/Tool/Crew/Task` 等实例化调用。当**同一变量名在同文件内被引用 ≥ 2 次**时，判定为共享凭据，标记为 high。

## 架构与执行流程

工具的运行流程可拆解为四步：[src/index.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts) 负责解析 commander 参数与调度，[src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts) 负责文件遍历与读入，`src/rules/*` 负责规则匹配，[src/report.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts) 负责格式化输出。

```mermaid
flowchart LR
  A[CLI 入口<br/>src/index.ts] --> B[runScan]
  B --> C[walk 遍历目录<br/>src/scanner.ts]
  C --> D{规则匹配}
  D --> E[hardcoded-keys]
  D --> F[shared-credentials]
  D --> G[BROAD_PERMISSION_PATTERNS]
  E --> H[Finding 集合]
  F --> H
  G --> H
  H --> I[formatCli / formatJson<br/>src/report.ts]
  I --> J[退出码]
```

### 文件遍历策略

[src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts) 维护三组集合：默认忽略目录（`node_modules`、`.git`、`dist`、`.venv`、`__pycache__` 等）、忽略文件基名（各种 lock 文件）、以及扫描白名单扩展名（`.ts/.tsx/.js/.jsx/.py/.go/.rb/.env/.yaml/.json` 等）。默认文件大小上限为 **1MB** [src/scanner.ts]()，并通过「首 1KB 中 NUL 字节比例 > 1%」的启发式判断是否为二进制文件。

## 常见失败模式与限制

1. **示例代码误报**：`PLACEHOLDER_INDICATORS` 仅抑制部分占位符（如 `your_api_key`），自定义占位符仍会触发；可通过 `--ignore` 路径参数缓解。
2. **正则在模板字符串中的误匹配**：[README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md) 明确指出这是 v0.1 的已知限制，`.env` 与 markdown 文件采用与源码相同的正则规则，roadmap 中规划通过 **AST 扫描**（v0.2）解决。
3. **依赖非 ESM 项目**：[package.json]() 中 `"type": "module"`，目标环境必须支持 ESM。
4. **重名变量跨文件**：`shared-credentials` 规则仅在**单文件**作用域内判定，不做跨文件追踪。

## 后续阅读

- [Hardcoded Keys Rule](Hardcoded-Keys-Rule.md) — 深入 `KEY_PATTERNS` 与 `CRITICAL_PROVIDERS` 判定逻辑
- [Scanner & Walk Logic](Scanner-Walk-Logic.md) — 文件遍历、忽略规则与二进制检测
- [CLI Reference](CLI-Reference.md) — 完整 commander 参数与退出码语义
- [Report Formatter](Report-Formatter.md) — CLI/JSON 两种输出格式与排序规则

---

**资料来源汇总**：
- [README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)
- [package.json](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json)
- [src/index.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts)
- [src/types.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts)
- [src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)
- [src/patterns.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)
- [src/report.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts)
- [src/rules/hardcoded-keys.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)
- [src/rules/shared-credentials.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts)
- [vitest.config.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/vitest.config.ts)

---

<a id='page-2'></a>

## System Architecture & Code Layout

### 相关页面

相关主题：[Project Overview & Quick Start](#page-1), [Detection Rules & Pattern Catalog](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts)
- [src/types.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts)
- [src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)
- [src/patterns.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)
- [src/report.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts)
- [src/rules/hardcoded-keys.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)
- [src/rules/shared-credentials.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts)
- [package.json](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json)
- [vitest.config.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/vitest.config.ts)
</details>

# 系统架构与代码组织

## 项目定位与边界

`@vorim/agent-audit` 是一个面向 AI 代理项目的轻量级代码卫生检查工具,定位为「免费、零上传、本地运行」的扫描器。它通过正则规则识别三类常见的代理身份反模式:硬编码 LLM 密钥、多代理共享凭证、长期有效的权限配置 [package.json:1-15](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json#L1-L15)。整个项目刻意保持小型化——一个 TypeScript 文件对应一条规则,测试与样例紧邻源码,目标是让贡献者只需 30 秒即可读懂入口并新增规则 [README.md:60-90](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md#L60-L90)。

工程上,工具兼具 CLI 与库两种使用方式:`bin` 字段声明了 `vorim-audit` 与 `agent-audit` 两个可执行入口,`main`/`types` 字段则允许消费者以 `import { runScan } from "@vorim/agent-audit"` 的形式嵌入到自己的脚本中 [package.json:5-12](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json#L5-L12)。

## 目录与模块职责

代码组织采用「按职责分层」的扁平结构,核心源码全部位于 `src/` 之下:

| 路径 | 角色 |
|------|------|
| `src/index.ts` | CLI 入口与库 API 转发,使用 commander 解析参数 |
| `src/audit.ts` | 编排层,串联文件遍历与所有规则 |
| `src/scanner.ts` | 文件系统遍历器,负责过滤与读取可扫描文件 |
| `src/patterns.ts` | 凭证与权限模式的正则定义(`KEY_PATTERNS`、`BROAD_PERMISSION_PATTERNS`) |
| `src/types.ts` | 跨模块共享的类型契约 |
| `src/report.ts` | 报告格式化(彩色 CLI 输出 + JSON) |
| `src/rules/*.ts` | 单条规则的实现,每个文件对应一个发现类别 |

测试使用 vitest,测试根目录配置为 `test/**/*.test.ts`,运行环境为 Node [vitest.config.ts:1-7](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/vitest.config.ts#L1-L7)。运行时仅依赖 `commander` 与 `picocolors` 两个轻量包,Node 引擎要求 `>=18` [package.json:35-40](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json#L35-L40)。

## 数据流:从命令行到报告

整个流程可以概括为「参数解析 → 文件遍历 → 规则匹配 → 结果聚合 → 报告输出」五个阶段。下面给出端到端的数据流图,展示一次 `vorim-audit .` 调用在各模块之间的数据交接:

```mermaid
flowchart LR
    A[CLI: src/index.ts] -->|runScan path opts| B[audit.ts 编排]
    B -->|walk rootDir| C[scanner.ts 遍历]
    C -->|ScannableFile 流| B
    B -->|file| D[hardcoded-keys.ts]
    B -->|file| E[shared-credentials.ts]
    B -->|file + patterns| F[long-lived rule]
    D -->|Finding| B
    E -->|Finding| B
    F -->|Finding| B
    B -->|ScanResult| G[report.ts]
    G -->|formatCli / formatJson| H[终端或 --output 文件]
```

CLI 在 `src/index.ts` 中通过 `commander` 注册 `[path]` 位置参数以及 `--json`、`-o/--output`、`--silent`、`--fail-on <level>` 等选项,并把控制权转交给 `runScan` [src/index.ts:1-40](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts#L1-L40)。编排层随后驱动 `scanner.ts` 中的 `walk` 生成器逐文件产出 `ScannableFile`,对每个文件调用规则集合。`scanner.ts` 内置默认忽略目录(`node_modules`、`.git`、`dist`、`__pycache__` 等)、文件锁忽略清单以及扩展名白名单,并使用「前 1KB 中 NUL 字节占比超过 1%」的廉价启发式判定二进制文件 [src/scanner.ts:1-50](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts#L1-L50)。规则返回的 `Finding[]` 被汇总成 `ScanResult`,最终由 `report.ts` 按 `SEVERITY_ORDER`(critical → high → medium)排序后渲染为彩色终端输出或 JSON [src/report.ts:1-30](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts#L1-L30)。

## 类型契约与设计取舍

所有跨模块传递的结构都在 `src/types.ts` 中集中声明,使规则实现与报告层之间通过类型而非运行时检查解耦 [src/types.ts:1-25](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts#L1-L25):

```typescript
export type Severity = 'critical' | 'high' | 'medium';
export type Category = 'hardcoded-key' | 'shared-credential' | 'long-lived';

export interface Finding {
  severity: Severity;
  category: Category;
  ruleId: string;
  file: string;
  line: number;
  column?: number;
  snippet: string;
  message: string;
  remediation: string;
  matchedText?: string;
}
```

三档严重度对应 `report.ts` 中的红色 / 黄色 / 蓝色加粗输出,并配有 `✖`、`⚠`、`ⓘ` 图标;三类类别与三条规则一一对应 [src/report.ts:1-25](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts#L1-L25)。`patterns.ts` 中的 `KEY_PATTERNS` 同时携带 `description` 与 `remediation` 字段,规则函数把它们原样塞进 `Finding`,保证 CLI 报告与 JSON 输出携带相同的修复建议 [src/patterns.ts:1-30](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts#L1-L30)。

设计上几个有意识的取舍值得注意:

- **正则而非 AST**:`hardcoded-keys.ts` 刻意「精确率优先于召回率」,不做 AST 解析,以换取零依赖、毫秒级扫描;`patterns.ts` 的注释也强调不与通用秘密扫描器竞争,只覆盖 AI 代理实际携带的密钥 [src/patterns.ts:1-15](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts#L1-L15)。
- **占位符抑制**:`hardcoded-keys.ts` 内置 `PLACEHOLDER_INDICATORS`(如 `your_api_key`、`example`、`fake`),在写报告前过滤样例代码,避免示例仓库被自身规则打爆 [src/rules/hardcoded-keys.ts:1-40](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts#L1-L40)。
- **脱敏输出**:`scanner.ts` 暴露的 `redact()` 函数保留首尾各 4 字符,中间用 `…` 与占位星号替换,使终端输出既可识别又不泄漏完整密钥 [src/scanner.ts:40-50](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts#L40-L50)。

## 小结

总体而言,`vorim-agent-audit` 通过「CLI 入口 + 编排层 + 规则集合 + 格式化层」的四段式架构,把 AI 代理代码卫生检查收敛到数千行 TypeScript 之中。架构边界清晰、依赖极少,并通过集中式类型契约保证规则与报告之间的解耦 [src/types.ts:1-25](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts#L1-L25)。后续 v0.2 计划引入的 AST 扫描、pre-commit hook 安装器与 `.vorim-audit.yml` 自定义规则文件,都将建立在当前这一扁平、可扩展的代码布局之上 [README.md:90-110](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md#L90-L110)。

---

## 参见

- 硬编码密钥规则详解
- 共享凭证检测算法
- CI 集成与退出码策略

---

<a id='page-3'></a>

## Detection Rules & Pattern Catalog

### 相关页面

相关主题：[System Architecture & Code Layout](#page-2), [CLI Usage, Output Formats & CI Integration](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/patterns.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)
- [src/rules/hardcoded-keys.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)
- [src/rules/shared-credentials.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts)
- [src/rules/long-lived.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/long-lived.ts)
- [src/types.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts)
- [src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)
- [package.json](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json)
- [README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)
</details>

# Detection Rules & Pattern Catalog

## 概述与设计目标

`vorim-agent-audit` 的检测规则与模式目录构成整个审计引擎的核心。本工具专注于识别 AI Agent 代码中三类高频身份反模式：硬编码的 LLM 供应商密钥、跨 Agent 共享的凭据、以及永不过期的宽泛权限。规则引擎采取"宁缺毋滥"的设计原则，通过精确的供应商前缀 + 长度匹配来控制误报率，避免与通用密钥扫描工具（如 TruffleHog）做同质化竞争 [资料来源：[src/patterns.ts:1-8]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)。

整个工具无外部网络依赖，纯本地扫描，符合"零数据离开本机"的隐私原则 [资料来源：[README.md:10-15]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)。

## 规则处理流水线

```mermaid
flowchart LR
    A[源码文件] --> B[scanner.ts<br/>文件遍历]
    B --> C[规则分发]
    C --> D1[hardcoded-keys.ts<br/>硬编码密钥]
    C --> D2[shared-credentials.ts<br/>共享凭据]
    C --> D3[long-lived.ts<br/>长期权限]
    D1 --> E[Finding 集合]
    D2 --> E
    D3 --> E
    E --> F[report.ts<br/>CLI 报告]
    E --> G[JSON 输出]
```

`src/scanner.ts` 中的 `walk()` 函数负责按目录遍历源文件，生成 `ScannableFile` 对象（包含绝对路径、相对路径、内容）[资料来源：[src/scanner.ts:60-90]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)。三个规则文件独立消费该对象，输出符合 `Finding` 接口的结构化结果，最终由 `src/report.ts` 汇总成彩色 CLI 报告或 JSON 输出。

## 三大检测规则详解

### 规则一：硬编码密钥检测（critical / high）

该规则遍历 `KEY_PATTERNS` 数组中的所有正则模式，覆盖 OpenAI、Anthropic、AWS Bedrock、Azure OpenAI、Google AI、Stripe、GitHub PAT、Slack、Pinecone、LangSmith、Hugging Face、Cohere、Mistral、Perplexity 等十余个供应商 [资料来源：[src/patterns.ts:10-180]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)。

为降低误报率，规则内置 `PLACEHOLDER_INDICATORS` 机制：当匹配值或所在行包含 `your_api_key`、`example`、`placeholder`、`redacted`、`dummy` 等关键词，或呈现高度重复字符（如 `AAAAAAA`），或唯一字符数 ≤ 5 时，自动判定为占位符并跳过 [资料来源：[src/rules/hardcoded-keys.ts:30-55]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)。

严重性分级由 `CRITICAL_PROVIDERS` 集合决定：OpenAI、Anthropic、AWS Bedrock、Azure OpenAI、Google AI、Stripe 被标记为 `critical`；其余供应商为 `high` [资料来源：[src/rules/hardcoded-keys.ts:10-17]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)。匹配到的真实密钥会经过 `redact()` 函数脱敏——保留首尾各 4 字符，中间用 `…` 替代，避免在终端泄露 [资料来源：[src/scanner.ts:130-135]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)。

### 规则二：共享凭据检测（high）

该规则识别"同一变量被传入多个 Agent/LLM 客户端实例"的反模式——这是 LangChain / CrewAI 教程中最常见的反模式，会导致日志无法区分具体是哪个 Agent 触发了工具调用 [资料来源：[src/rules/shared-credentials.ts:5-15]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts)。

实现方式分两步：先用 `CREDENTIAL_PASS_PATTERN` 正则匹配形如 `apiKey: someVar`、`openai_api_key=someVar` 的凭据传递点，再用 `AGENT_INSTANTIATION_PATTERN` 识别 Agent/ChatOpenAI/Anthropic/Crew/Tool 等实例化调用。若同一变量名在同文件中出现 ≥ 2 次，即标记为共享凭据 [资料来源：[src/rules/shared-credentials.ts:18-40]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/shared-credentials.ts)。

### 规则三：长期权限检测（medium）

该规则通过 `BROAD_PERMISSION_PATTERNS` 数组匹配 `scope: "*"`（通配符 scope）和 `role: admin/superuser/root`（管理员角色）两类配置 [资料来源：[src/patterns.ts:185-188]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)。虽然此类问题不像泄露密钥那样可立即被利用，但它是导致 Agent 事件"爆炸半径"扩大的结构性根源 [资料来源：[src/rules/long-lived.ts:1-25]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/long-lived.ts)。

## 模式目录与严重性总览

| 规则 ID 前缀 | 检测目标 | 典型严重性 | Category |
|--------------|----------|------------|----------|
| `hardcoded-key:openai` / `:anthropic` / `:aws-bedrock` 等 | 供应商 API 密钥 | critical | hardcoded-key |
| `hardcoded-key:github` / `:slack` / `:huggingface` 等 | 框架/平台令牌 | high | hardcoded-key |
| `hardcoded-key:cohere` / `:mistral`（基于变量名启发） | LLM 供应商密钥 | high | hardcoded-key |
| `shared-credential:*` | 跨 Agent 共享变量 | high | shared-credential |
| `long-lived:wildcard-scope` / `:admin-root-role-assignment` | 通配符/管理员配置 | medium | long-lived |

每条 `Finding` 都包含 `severity`、`category`、`ruleId`、`file`、`line`、`column`、`snippet`、`message`、`remediation`、`matchedText`（脱敏后）十个字段 [资料来源：[src/types.ts:1-30]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts)。其中 `remediation` 直接来源于 `KEY_PATTERNS` 中每个供应商条目的修复建议，例如 OpenAI 建议"将密钥迁入密钥管理器（如 AWS Secrets Manager、Doppler），改用短时单 Agent 身份" [资料来源：[src/patterns.ts:14-22]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/patterns.ts)。

## 已知限制与扩展路径

当前规则采用纯正则匹配，对于形如 `process.env.API_KEY` 拼接的密钥赋值或经过 Base64 编码的密钥会漏检 [资料来源：[README.md:90-95]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)。`v0.2` 路线图中计划引入基于 AST 的 TypeScript 与 Python 扫描，并支持 `.vorim-audit.yml` 自定义规则文件与可配置 allowlist [资料来源：[README.md:100-110]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)。

新增模式只需在 `src/patterns.ts` 中追加一个 `KeyPattern` 条目，并在 `test/fixtures/` 中添加对应测试夹具即可 [资料来源：[README.md:120-130]()](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)。

## 另请参见

- 架构与 CLI 入口
- 报告输出格式
- CI 集成与 Pre-commit Hook 使用

---

<a id='page-4'></a>

## CLI Usage, Output Formats & CI Integration

### 相关页面

相关主题：[Project Overview & Quick Start](#page-1), [Detection Rules & Pattern Catalog](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/index.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts)
- [src/report.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts)
- [src/types.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/types.ts)
- [src/audit.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/audit.ts)
- [README.md](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/README.md)
- [package.json](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json)
- [src/scanner.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/scanner.ts)
- [src/rules/hardcoded-keys.ts](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/rules/hardcoded-keys.ts)
</details>

# CLI 使用、输出格式与 CI 集成

`@vorim/agent-audit` 同时提供命令行工具与可作为库导入的编程接口。CLI 入口位于 [`src/index.ts`](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/index.ts)，基于 [`commander`](https://www.npmjs.com/package/commander) 构建；输出格式化逻辑位于 [`src/report.ts`](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/src/report.ts)，支持彩色 CLI 报告与机器可读的 JSON 两种形态。本页聚焦于 CLI 的调用方式、输出格式选择以及在持续集成（CI）流程中的集成策略。

## 1. 命令行界面与可选项

CLI 入口由 `src/index.ts` 中的 `main()` 函数承担，使用 `commander` 声明参数与选项。包 [`package.json`](https://github.com/Vorim-AI-Labs/vorim-agent-audit/blob/main/package.json) 同时注册了两个可执行文件别名——`vorim-audit` 与 `agent-audit`，以兼容不同习惯的开发者。 资料来源：[src/index.ts:20-41]()

### 1.1 位置参数与版本

- `[path]`：待扫描的根目录，默认值为当前目录 (`.`)。
- `--version`：由 `commander` 自动注入，固定为 `0.1.0`，与 `package.json` 中的版本号一致。

### 1.2 主要选项

| 选项 | 作用 | 默认值 |
|------|------|--------|
| `--json` | 输出机器可读 JSON，替代默认的彩色 CLI 报告 | 关闭 |
| `-o, --output <file>` | 将 JSON 输出写入指定文件（隐含启用 `--json`） | 无 |
| `--silent` | 抑制除错误外的一切输出，便于在 CI 中配合 `--output` 使用 | 关闭 |
| `--fail-on <level>` | 当指定严重级别或更差的发现存在时退出非零码 | `critical` |

`--fail-on` 的合法值为 `critical`、`high`、`medium`、`none` 之一。退出码计算由同文件中的 `computeExitCode()` 完成：若 `--fail-on` 设置为 `medium`，则任何 `critical`、`high` 或 `medium` 级别的发现都会导致非零退出；若设置为 `none`，则无论扫描结果如何都返回 `0`。 资料来源：[src/index.ts:60-78]()

## 2. 输出格式

### 2.1 彩色 CLI 报告（默认）

`formatCli()` 接收 `ScanResult` 并生成人类可读的彩色报告。报告首先按严重级别升序排列（critical → high → medium），同级内再按文件路径与行号排序，确保跨文件扫描结果稳定可复现。 资料来源：[src/report.ts:24-32]()

每个 Finding 的严重级别有独立的颜色与图标，由 [`picocolors`](https://www.npmjs.com/package/picocolors)（别名 `pc`）提供颜色支持：

- `critical` → 红色加粗 + `✖`
- `high` → 黄色加粗 + `⚠`
- `medium` → 蓝色加粗 + `ⓘ`

资料来源：[src/report.ts:9-22]()

### 2.2 机器可读 JSON 输出

通过 `--json` 或 `--output` 启用时，`formatJson(result)` 将完整的 `ScanResult` 序列化输出。`ScanResult` 包含 `rootDir`、`filesScanned`、`findings`、`durationMs`、`scannedAt` 五个字段，便于在 CI 中归档或上传到审计平台。 资料来源：[src/types.ts:17-25]()

`--output` 会把 JSON 写入指定文件，并在非 `--silent` 模式下打印一行摘要 `Wrote N findings to <path>`；若仅指定 `--json` 而不指定输出文件，则直接将 JSON 打印到 stdout。 资料来源：[src/index.ts:46-55]()

### 2.3 选择建议

- 交互式本地扫描：使用默认的 CLI 报告，颜色与图标便于快速定位。
- CI 流水线：使用 `--json --output audit-report.json --silent`，将结果落盘便于后续归档与差异比对。

## 3. CI 集成

退出码由 `computeExitCode()` 计算并由 `process.exit()` 直接返回，使其天然适合作为 CI 闸门（quality gate）。默认情况下，仅当存在 `critical` 级别发现时返回非零；可通过 `--fail-on` 调整阈值。 资料来源：[src/index.ts:60-78]()

### 3.1 GitHub Actions

最简集成方式是在 workflow 中通过 `npx` 调用，无需预安装。README 给出的推荐配置如下：

```yaml
- name: Audit agent code
  run: npx @vorim/agent-audit --fail-on high
```

这会在 `high` 及以上严重级别的发现存在时使 Job 失败。 资料来源：[README.md:35-40]()

### 3.2 Pre-commit 钩子

对于本地提交拦截，README 推荐在 `package.json` 的 `scripts` 中加入：

```json
{
  "scripts": {
    "audit:agents": "vorim-audit --fail-on critical --silent"
  }
}
```

随后配合 [Husky](https://typicode.github.io/husky/) 等工具在 `pre-commit` 钩子中调用。`--silent` 抑制常规输出，仅让 `critical` 级别问题阻塞提交。 资料来源：[README.md:42-50]()

## 4. 库形态的程序化调用

除了 CLI，`@vorim/agent-audit` 也以库的形式导出。`src/index.ts` 重导出了 `runScan`、`Finding`、`ScanResult`、`ScanOptions`，使下游代码可以直接 `import { runScan } from "@vorim/agent-audit"`。 资料来源：[src/index.ts:8-9]()

`runScan(options)` 接收 `ScanOptions`（含 `rootDir`、`ignore`、`maxFileSizeBytes`、`followSymlinks`），返回 `Promise<ScanResult>`，依次调用三套规则（`findHardcodedKeys`、`findSharedCredentials`、`findLongLived`）。 资料来源：[src/audit.ts:8-25]()

## 5. 常见使用注意事项

- 默认排除目录覆盖了 `node_modules`、`.git`、`dist`、`build`、`.venv` 等常见构建产物与依赖目录，但仍会扫描 1MB 以内的文件；超出 `DEFAULT_MAX_FILE_BYTES`（1,000,000 字节）的文件将被跳过。 资料来源：[src/scanner.ts:55-58]()
- 误报抑制：`hardcoded-keys` 规则会忽略形如 `your-api-key`、`example`、`placeholder`、`redacted`、`dummy` 等占位符。 资料来源：[src/rules/hardcoded-keys.ts:18-30]()
- README 明确指出 v0.1 的正则扫描不进行 AST 分析，因此对变量赋值与字面量混用的 `.env` 文件仍存在误报风险，计划在 v0.2 中通过 AST 扫描改善。 资料来源：[README.md:55-66]()

## See Also

- [核心类型与 ScanResult 数据结构](types-and-scan-result.md)
- [Patterns 与 Provider 覆盖范围](patterns.md)
- [Hardcoded Keys 规则详解](hardcoded-keys.md)
- [项目主页与 README](https://github.com/Vorim-AI-Labs/vorim-agent-audit)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：Vorim-AI-Labs/vorim-agent-audit

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `vorim-agent-audit` 与安装入口 `@vorim/agent-audit` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npx @vorim/agent-audit`
- 证据：identity.distribution | https://github.com/Vorim-AI-Labs/vorim-agent-audit | repo=vorim-agent-audit; install=@vorim/agent-audit

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Vorim-AI-Labs/vorim-agent-audit | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Vorim-AI-Labs/vorim-agent-audit | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Vorim-AI-Labs/vorim-agent-audit | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Vorim-AI-Labs/vorim-agent-audit | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Vorim-AI-Labs/vorim-agent-audit | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Vorim-AI-Labs/vorim-agent-audit | release_recency=unknown

<!-- canonical_name: Vorim-AI-Labs/vorim-agent-audit; human_manual_source: deepwiki_human_wiki -->