sehgalrishabh/fortifai-cli

## 什么是 FortifAI CLI? FortifAI CLI 是一款针对生产环境 AI 智能体的黑盒对抗性测试工具。它向你的智能体 HTTP endpoint 直接发射一个经过筛选的攻击 payload 库——涵盖 **prompt injection**、**goal hijacking**、**data exfiltration**、**privilege escalation** 等——并报告它发现的每一个信号。 它是为那些交付 AI 智能体并想知道：“_这会被利用吗？_” 的团队构建的，在别人替他们回答这个问题之前。 ## 覆盖范围 FortifAI payload 映射到两个行业安全标准： | Standard | Coverage | | ------------------------ | -------------------------------------------------------- | | **OWASP Agentic Top 10** | AA1 – AA10 (Goal Hijacking → Resource Exhaustion) | | **OWASP LLM Top 10** | LLM01 – LLM10 (Prompt Injection → Unbounded Consumption) | 每个攻击 payload 都带有 `severity`（`CRITICAL` / `HIGH` / `MEDIUM` / `LOW`）和 `attack_vector` 元数据，因此每个发现都能映射回一个真正的风险类别。 ## 前置条件 | Requirement | Version | | ---------------- | ------------------------------------ | | Node.js | ≥ 18 | | npm | ≥ 8 | | FortifAI API key | [获取一个 →](https://getfortifai.com) | 需要一个 API key 来下载加密的 payload 知识库。你可以从你的 FortifAI 仪表板获取一个。 ## 快速开始 ### 1. 安装 ``` npm install -g @fortifai/cli ``` 或者在不安装的情况下运行： ``` npx @fortifai/cli scan ``` ### 2. 认证 ``` fortifai auth ``` 这会将你的 API key 写入你的配置文件。要跳过提示： ``` fortifai auth --api-key fai_your_key_here ``` ### 3. 配置你的智能体 在你的项目根目录下创建一个 `fortifai.config.yaml`（或 `.ts` / `.js`）： ``` # fortifai.config.yaml agents: - name: customer-support-agent endpoint: http://localhost:3000/api/chat method: POST inputField: message headers: Content-Type: application/json Authorization: Bearer your-dev-token scan: concurrency: 5 rateLimitPerSecond: 5 ``` ### 4. 运行扫描 ``` fortifai scan ``` 就是这样。FortifAI 将向你的 endpoint 发射所有 payload，收集结果，并将完整的评估报告上传到你的仪表板。 ## 配置 FortifAI 从工作目录向上搜索它找到的第一个配置文件。支持的格式（按搜索顺序）： ``` fortifai.config.ts fortifai.config.js fortifai.config.yaml fortifai.config.yml ``` ### 完整配置参考 ``` // fortifai.config.ts export default { // Your FortifAI API key (or set via `fortifai auth`) apiKey: "fai_...", agents: [ { // ─── Required ────────────────────────────────────────── name: "my-agent", // Identifier in reports endpoint: "https://my-api.com/v1/chat", // URL to hit inputField: "message", // Body key for the payload // ─── Optional ────────────────────────────────────────── method: "POST", // Default: POST headers: { Authorization: "Bearer sk-...", "Content-Type": "application/json", }, additionalParams: { model: "gpt-4o", stream: false, }, }, ], scan: { concurrency: 5, // Max in-flight requests (default: 5, min: 1) rateLimitPerSecond: 5, // Max new requests/sec (default: 5, 0 = unlimited) }, }; ``` ### Agent 字段 | Field | Type | Required | Description | | ------------------ | -------- | :------: | ----------------------------------------------------------------- | | `name` | `string` | ✅ | 报告中使用的可读智能体标识符 | | `endpoint` | `string` | ✅ | 要测试的智能体 endpoint 的完整 URL | | `inputField` | `string` | ✅ | 接收攻击 payload 的 Body key | | `method` | `string` | — | HTTP method (默认: `POST`) | | `headers` | `object` | — | 每个请求发送的 Headers (auth tokens, Content-Type 等.) | | `additionalParams` | `object` | — | 与 `inputField` 一起合并的额外 body 字段 | ### 扫描调优字段 | Field | Type | Required | Default | Description | | ------------------------- | ------------- | :------: | ------- | ---------------------------------------------------------------- | | `scan.concurrency` | `integer ≥ 1` | — | `5` | 最大并行进行中的请求 | | `scan.rateLimitPerSecond` | `number ≥ 0` | — | `5` | 每秒启动的最大新请求数。`0` 禁用节流 | ## CLI 参考 ### `fortifai scan` 针对你配置的智能体运行对抗性 payload。 ``` Usage: fortifai scan [options] Options: --config Working directory containing fortifai config (default: cwd) --concurrency Max in-flight requests (overrides config) --rate-limit Max request starts per second (overrides config, 0 = unlimited) -h, --help Display help ``` **示例:** ``` # 从当前目录进行 Basic scan fortifai scan # 指向特定项目 fortifai scan --config ./path/to/project # Stress test — 无限并发，无速率限制 fortifai scan --concurrency 20 --rate-limit 0 # Conservative — 2 个并行请求，每秒 2 个 fortifai scan --concurrency 2 --rate-limit 2 ``` ### `fortifai auth` 使用你的 FortifAI API key 对 CLI 进行认证。 ``` Usage: fortifai auth [options] Options: --api-key Provide key directly (skips interactive prompt) --config Working directory containing fortifai config -h, --help Display help ``` 该命令会向上搜索目录树以查找现有的配置文件，并将 `apiKey` 字段写入其中。如果不存在配置，则会创建一个最小的 `fortifai.config.yaml`。 **示例:** ``` # 交互式提示 fortifai auth # 非交互式 (CI / 脚本) fortifai auth --api-key fai_your_key_here ``` ## 工作原理 ``` You FortifAI CLI FortifAI Cloud ──── ──────────── ────────────── │ │ │ │ fortifai scan │ │ │──────────────────────▶│ │ │ │── loadConfig() ──▶ │ │ │ │ │ │── POST /api/payloads ─▶│ │ │ x-fortifai-key │ │ │◀── AES-256-GCM pack ───│ │ │ (Brotli compressed) │ │ │ │ │ │── notifyScanStarted() ▶│ │ │ (creates "running" │ │ │ stub on dashboard) │ │ │ │ │ Your Agent │ │ │ ────────── │ │ │ │── POST /your/endpoint ▶│ │ │ { message: payload } │ │ │◀── { ... response ... }│ │ │ (×150+ with concurrency│ │ │ + rate limiting) │ │ │ │ │ │── POST /api/scans ─────▶│ │ │ NDJSON scan log │ │ │ (attack results + │ │ │ scan.final) │ │ │ │ │ │◀── { dashboardUrl } ───│ │◀── Dashboard URL ─────│ (evaluation runs │ │ │ server-side) │ ``` ### 执行流水线（详情） 1. **Config discovery** — 向上遍历目录树查找 `fortifai.config.*` 2. **Payload fetch** — 使用你的 API key 从 FortifAI Cloud 下载加密的知识库；使用 AES-256-GCM + Brotli 解密 3. **Scan stub** — 通知仪表板扫描已开始（创建一个 `running` 条目） 4. **Attack execution** — 以可配置的并发度（`p-limit`）和 token-bucket 速率限制运行每个 `agent × payload` 组合 5. **Progress tracking** — 每完成 10% 向 NDJSON 日志写入 `summary.checkpoint` 记录 6. **Console summary** — 打印请求结果 (2xx/4xx/5xx/timeouts)、延迟百分位数 (p50/p95/p99) 和信号计数 7. **Upload** — 将完整的 NDJSON 扫描日志 POST 到仪表板；评估在服务端运行，结果显示在你的仪表板中 ### 并发和速率限制 这两个调节器协同工作以防止你的智能体过载： ``` rateLimitPerSecond = 5 ← token bucket: max 5 new requests started per second concurrency = 5 ← p-limit: max 5 requests in flight simultaneously At steady state: ≤ 5 requests active + no burst beyond 5 new starts/second ``` 设置 `--rate-limit 0` 禁用节流（仅应用并发上限）。设置 `--concurrency 1` 将所有请求串行化。 ### 请求处理 | Condition | Recorded as | | ------------------------- | ----------------------------------- | | HTTP response received | Status code (2xx / 3xx / 4xx / 5xx) | | No response in 10 seconds | `timeout` | | DNS / network failure | `error` + error message | 所有请求和响应 body 均按原样捕获在 NDJSON 日志中，以便在仪表板上进行完整的取证重放。 ## NDJSON 扫描日志 每次扫描都会生成一个结构化的 NDJSON 日志并上传到仪表板。每一行都是一个 JSON envelope： ``` { "schema": "fortifai.scanlog/v1", "scanId": "scan_...", "seq": 1, "ts": "...", "kind": "...", "phase": "...", "level": "INFO", "data": { ... } } ``` ### 记录类型 | `kind` | When | Description | | -------------------- | ---------- | ---------------------------------------------- | | `scan.meta` | 开始 | CLI 版本, schema 版本, 开始时间 | | `scan.config` | 开始 | 执行参数, 智能体列表, payload 数量 | | `scan.phase` | 生命周期 | 阶段转换 (init → running → complete) | | `attack.result` | 每次攻击 | Payload 发送, 完整请求 + 响应, 延迟 | | `summary.checkpoint` | 每 10% | 运行总计: 结果, 延迟百分位数 | | `scan.final` | 结束 | 汇总摘要, 每个智能体的统计, 判定 | | `scan.error` | 失败时 | 错误阶段和消息 | ## 仪表板 扫描完成后，FortifAI Cloud 使用其基于 LLM 的评估引擎评估每个攻击响应，并在你的仪表板中填充： - **Overall verdict** — `PASS` / `WARN` / `FAIL` - **Risk score** — 0–10 综合得分 - **Signal breakdown** — 按 `CRITICAL` / `HIGH` / `MEDIUM` / `LOW` 分类的问题发现 - **Per-agent evaluation** — 每个智能体的单独判定、得分和置信度 - **OWASP Agentic Top 10 heatmap** — 哪些攻击类别命中 - **Full signal chain** — 发送的 payload → 智能体响应 → 检测证据 仪表板 URL 会在每次扫描结束时打印： ``` ✔ Dashboard https://getfortifai.com/dashboard/scans/scan_1234567890 ``` ## 安全性 - **Payload transport** — 攻击知识库使用 AES-256-GCM 加密。你的 API key 用于密钥派生；payload 绝不会以未加密形式存储在磁盘上。 - **API authentication** — 所有发往 FortifAI Cloud 的请求都使用 `x-fortifai-key` header。 - **No data persistence** — CLI 不会向磁盘写入任何文件。扫描日志在内存中构建并直接上传。 - **Request isolation** — 每个智能体调用都是一个具有 10 秒超时的无状态 HTTP 调用。 ## 开发 ### 设置 ``` git clone https://github.com/fortifai/cli cd cli npm install ``` ### 命令 ``` npm run typecheck # Type-check without emitting npm test # Run test suite (vitest) npm run build # Compile TypeScript → dist/ npm run dev # Run CLI directly from source (tsx) npm run scan # Alias: tsx src/index.ts scan ``` ### 项目结构 ``` src/ ├── index.ts CLI entry point (Commander setup) ├── commands/ │ ├── scan.ts fortifai scan — orchestrates a full scan run │ └── auth.ts fortifai auth — API key setup ├── config/ │ └── loadConfig.ts Config file discovery and validation ├── attacks/ │ ├── loadPayloads.ts Fetch + decrypt + decompress payload KB │ └── executor.ts Concurrent attack runner (p-limit + rate limiter) ├── agents/ │ └── invokeAgent.ts Single HTTP request to an agent endpoint ├── report/ │ ├── ndjsonWriter.ts In-memory NDJSON log builder │ ├── formatter.ts Console summary + metric aggregation │ ├── uploadReport.ts POST scan log to dashboard │ └── notifyLifecycle.ts Scan start/failure dashboard stubs └── types/ └── index.ts Shared TypeScript types ``` ### 运行测试 ``` npm test # 包含覆盖范围 npx vitest run --coverage ``` 测试位于 `__tests__/` 中，涵盖：配置加载、payload 解密、并发攻击执行、智能体 HTTP 调用和报告格式化。 ## 故障排除 **`Invalid or inactive API key`** → 运行 `fortifai auth` 重新输入你的 key。Key 必须以 `fai_` 开头并在你的仪表板中处于活动状态。 **`Quota exceeded`** → 你套餐的每月攻击配额已用完。升级或等待下一个计费周期。 **所有请求超时** → 你的智能体 endpoint 不可达或响应太慢。检查配置中的 `endpoint` 并确保服务正在运行。默认超时为每个请求 10 秒。 **Config not found** → FortifAI 从你的工作目录向上搜索。确保 `fortifai.config.yaml`（或 `.ts`/`.js`）存在于当前目录或父目录中。使用 `--config ` 显式指定。 **`BLOB_READ_WRITE_TOKEN is not set` (自托管)** → 你的后端缺少 blob 存储配置。请参阅仪表板部署指南。 ## 许可证 MIT © [FortifAI](https://getfortifai.com)

**[FortifAI](https://getfortifai.com)** · **[Dashboard](https://app.getfortifai.com)** · **[npm](https://www.npmjs.com/package/@fortifai/cli)**

标签：AI安全, Chat Copilot, DLL 劫持, GNU通用公共许可证, HTTP端点测试, MITM代理, Node.js, OWASP Top 10, PE 加载器, TypeScript, 协议分析, 固若金汤, 大语言模型, 安全合规, 安全插件, 对抗性测试, 数据窃取, 暗色界面, 权限提升, 目标劫持, 私有化部署, 网络代理, 网络安全, 自动化攻击, 防御规避, 隐私保护, 零日漏洞检测, 黑盒测试