AppThreat/chennai

# chennai chennai（chen 与 ai）是一个混合 AI agent，也是一个终端用户界面（TUI），用于探索 AppThreat 的 [atom](https://github.com/AppThreat/atom) 文件。它基于 [chen](https://github.com/AppThreat/chen) 库（Code Hierarchy Exploratory Network，代码层次探索网络）构建，为静态分析、数据流追踪以及 AI 辅助的代码和安全分析提供了一个键盘驱动的交互式环境。 与传统的 SAST 引擎或通用的 LLM 聊天机器人不同，chennai 允许您直接访问底层的图查询，因此您可以在不离开终端的情况下，针对程序的结构和数据流提出任意问题。它完全在您的本地机器上运行，没有服务器后端，也不会有任何数据离开您的环境。 chennai 包含一个内置的 AI agent，它使用 atom 作为基础上下文。该 agent 可以运行 chen DSL 查询、遍历数据流路径、运行图算法、读取源代码文件，并使用 ripgrep 搜索代码，所有这些都可以通过 TUI 内部的单一聊天界面进行编排。该 agent 同时支持 Anthropic 和 OpenAI 兼容的提供商，并且可以在有或没有 LLM 的情况下工作。 ## 使用场景 - 交互式探索由 atom 工具生成的 atom 文件。打开 atom 文件，无需手动编写查询即可浏览方法、调用、命名空间、标签和字面量。 - 从源到汇点的数据流分析。TUI 展示了带有分组路径、子流切换和缓解指标的数据流。 - 图算法执行，包括 PageRank、强连通分量、拓扑排序、支配树以及过程间路径查找。 - AI 辅助的漏洞分析，提供用于安全审查、代码审查、解释和追踪的斜杠命令。agent 通过引擎路由工具调用，并返回结构化的分析结果。 - 基于 REPL 的查询，支持 Tab 补全、命令历史记录，并可通过 eval 命令使用完整的 chen DSL。 ## 环境要求 - 一个需要打开的 atom 文件（来自 atom 工具）。该 atom 文件是通过对代码库运行 atom 所生成的 Code Property Graph（代码属性图）。 - 如果通过 JAR 回退发行版运行引擎，则需要 Java 23 或更高版本。 - TUI 和引擎加起来至少需要 4GB 的可用内存。较大的代码库可能需要更多内存。 ## 安装 chennai 以 npm 包的形式分发，并包含特定于平台的原生二进制文件。 ``` npm install -g @appthreat/chennai ``` 安装完成后，`chennai` 命令将全局可用。 ``` chennai [options] ``` ## 设置 `chennai setup` 命令会通过 npm 安装或更新所需的分析工具（cdxgen、atom、atom-parsetools）： ``` chennai setup ``` 这将运行 `npm install -g --ignore-scripts @cyclonedx/cdxgen @appthreat/atom @appthreat/atom-parsetools`。 ### 工具发现 chennai 会按以下顺序自动检测这些工具： | 工具 | 环境变量 | 搜索路径 | | ------ | ------------ | ------------------------------------------------ | | cdxgen | `CDXGEN_CMD` | PATH → `node_modules/.bin/cdxgen` → npm 全局目录 | | atom | `ATOM_CMD` | `ATOM_CMD` → PATH | | npm | — | PATH | ### Atom 自动生成 当您将 chennai 指向一个没有 `.atom` 文件的项目目录时，它会提示您以交互方式生成一个： ``` $ chennai /path/to/project No .atom file found in /path/to/project Generate one for analysis? This will: └ 1. Run cdxgen to produce a CycloneDX SBOM └ 2. Run atom --with-data-deps to build the atom file Source: /path/to/project [Y/n] ``` 如果未安装相关工具但存在可用的 `npm`，chennai 会在继续执行之前主动提出为您自动安装它们。 ### 软件物料清单 chennai 集成了 [cdxgen](https://github.com/AppThreat/cdxgen)，可自动生成并加载 CycloneDX SBOM，以便进行更深层次的依赖感知分析。当您使用源码或报告目录调用 chennai 时，它首先会查找任何现有的 `.cdx.json` 文件。如果未找到，它会调用 cdxgen 创建一个 BOM，其命名约定为 `sbom--.cdx.json`。 #### 安装 cdxgen（推荐以获得最佳体验） ``` npm install -g @cyclonedx/cdxgen ``` cdxgen 将在 PATH 中被自动检测。您也可以设置 `CDXGEN_CMD` 环境变量以指向自定义位置。安装完成后，当存在源码目录时，chennai 将在启动时自动生成 BOM。 ### BOM 命令 | 命令 | 描述 | | ------------- | --------------------------------------------------------------- | | `bom` | 以可搜索、可排序的表格形式显示所有 BOM 组件 | | `bom ` | 按名称、类型、版本、PURL 或许可证过滤 BOM 组件 | BOM 数据也会被注入到 AI agent 的 prompt 中，用于安全审查和代码审查，从而提升 LLM 对第三方依赖、其许可证以及已知漏洞的理解。 ### 选项 | 选项 | 默认值 | 描述 | | -------------------- | --------------------- | --------------------------------------------------- | | `--engine PATH` | auto | chennai-engine 二进制文件的路径 | | `--theme dark/light` | dark | 颜色主题 | | `--source PATH` | atom 目录 | 用于文件解析的项目源码根目录 | | `--ask TEXT` | -- | Headless 模式：提出问题并打印答案 | | `--provider STR` | anthropic | LLM 提供商（anthropic 或 openai） | | `--model STR` | claude-opus-4-8 | LLM 模型名称 | | `--api-key STR` | 环境变量 | LLM 提供商的 API key | | `--base-url STR` | -- | 用于 OpenAI 兼容 endpoint 的自定义 API base URL | | `--reports-dir PATH` | .chen/chennai-reports | 用于存放 markdown 报告和 BOM 文件的目录 | | `--no-thinking` | false | 在 LLM 请求中忽略 thinking 块 | | `--effort STR` | high | 推理力度（low、medium、high、xhigh、max） | ### 环境变量 - `CHENNAI_ENGINE`：引擎二进制文件的路径。覆盖自动检测。 - `ANTHROPIC_API_KEY`：Anthropic 提供商的 API key。 - `OPENAI_API_KEY`：OpenAI 兼容提供商的 API key。 - `CDXGEN_CMD`：cdxgen 二进制文件的路径。 - `ATOM_CMD`：atom CLI 二进制文件的路径（例如：`/path/to/atom/atom.sh`）。 - `CHENNAI_DEBUG`：设置为任意值以启用解析器诊断。 ### 平台支持 | 平台 | 架构 | 引擎 | TUI | | ------- | ---------------- | ------------- | ------------- | | Linux | x64 (glibc) | 原生 | 原生 | | Linux | arm64 (glibc) | 原生 | 原生 | | Linux | x64 (musl/Alpine)| 原生 (musl) | 原生 (musl) | | macOS | Apple Silicon | 原生 | 原生 | | Windows | x64 | 原生 | 原生 | 其他平台则回退到引擎的 JAR 发行版，而 TUI 在可用的平台上原生运行。 ## 架构 chennai 具有两个通过 stdin/stdout 上的 NDJSON 进行通信的进程。 ### 引擎 (chennai-engine) 该引擎是一个基于 chen 库构建的 Scala 3 应用程序。它读取 atom 文件并对其运行查询。它在受支持的平台上以 GraalVM native-image 二进制文件的形式分发，在其他平台上则以 JAR 发行版的形式分发。 引擎在 stdin 上接收 NDJSON 请求行，并将 NDJSON 响应行写入 stdout。每个请求都有一个 id、一个命令和参数。引擎在启动时打开 atom 文件，并在整个会话期间将其保留在内存中。 ### TUI (chennai) TUI 是一个使用 ratatui 和 crossterm 的 Rust 应用程序。它将引擎作为子进程启动，打开 atom 文件，并呈现一个三面板界面：一个包含行数的摘要面板，一个用于输入的 REPL 面板，以及一个用于结果的输出面板。TUI 会自动检测引擎二进制文件的位置——默认情况下，它会在同一目录中查找 chennai-engine，然后检查标准的开发构建路径。 ## 用户界面 TUI 有三个面板，可通过 Tab 和 Shift+Tab 进行切换。 ### 摘要面板 显示 atom 摘要：语言、版本，以及文件、方法、调用、字面量、命名空间、注解、配置文件和依赖项的行数。在某一行上按 Enter 键会运行该类型的查询，并在输出面板中显示结果。 ### REPL 面板 位于屏幕底部的命令行输入。在此处输入查询以运行它们。REPL 支持： - 命令标签：`files`、`methods`、`calls`、`external methods`、`internal methods`、`namespaces`、`annotations`、`imports`、`literals`、`config files` - DSL 表达式：任何 chen DSL 表达式，例如 `atom.method.name(".*Handler")` - 标签查询：`atom.tag.name("crypto.*")` - 流预设：`dataflows`、`reachables`、`cryptos` - 自定义流 DSL：包含 `reachableByFlows` 或 `.df(` 的表达式 - 带有 `=` 的 DSL 前缀：强制进入原始 eval 模式，例如 `=atom.call.code(".*query.*")` 使用 Ctrl+Space 可以进行 Tab 补全。使用上和下方向键可以访问命令历史记录。 ### 输出面板 显示查询结果。输出面板有以下几种显示模式： **表格视图**：查询结果显示为可滚动、可排序的表格。按 1 到 9 键可对列进行排序。使用 / 键过滤行。按 Enter 键可打开某一行的详细信息窗格。详细信息窗格并排显示节点属性、子表（参数、局部变量）和源代码。 **流视图**：数据流路径以主从分组的形式显示。每个分组代表一条从源到汇点的路径。分组可以折叠。子流通过 `s` 键显示，而已缓解的流（通过 sanitizer 或 validator 的流）可以通过 `m` 键隐藏。 **Agent 视图**：AI agent 的输出呈现为流式转录，包含 thinking 块、工具调用和结果。返回流数据的工具结果可以安装到流视图中，以便进一步探索。 ### 快捷键 | 按键 | 动作 | | ---------------------------- | ---------------------------------- | | q | 退出 | | Tab / Shift+Tab | 向前/向后切换面板 | | Up/Down (或 j/k) | 导航列表，滚动输出 | | PageUp/PageDown (或 b/Space) | 翻页浏览列表 | | Enter | 打开详细信息或执行命令 | | / | 在输出面板中过滤表格 | | 1-9 | 按列对表格进行排序 | | s | 在流视图中切换子流 | | m | 在流视图中切换缓解流 | | d / r | 运行 dataflows 或 reachables 预设 | | Ctrl+S | 将报告保存为 markdown 文件 | ## DSL 查询与遍历 完整的 chen DSL 可通过 eval 命令使用。有关所有遍历步骤和节点类型的参考文档维护在 chen 仓库的 `docs/TRAVERSAL.md` 中。atom 仓库的 `docs/lessons/` 目录下有十九个教程，涵盖了从前端设置到数据流分析和图算法的各个方面。 查询的入口点是 `atom`，代表 Code Property Graph 的根节点。常见的起点包括 `atom.file`、`atom.method`、`atom.call`、`atom.literal`、`atom.tag` 和 `atom.namespace`。这些起点可以与 `.name(".*Handler")`、`.isExternal(false)`、`.callee`、`.caller`、`.cfgNext`、`.dominatedBy` 等步骤进行链式调用。 为了进行基于类型的过滤，DSL 在任何 AST 节点上提供了 `.isCall`、`.isLiteral`、`.isIdentifier`、`.isMethod`、`.isFile` 等断言。 ## 数据流分析 chennai 支持三种流预设，可通过 REPL 或摘要面板访问： - `dataflows`：运行 reachableByFlows，从标记为 framework-input 的源指向标记为 framework-output 的汇点。 - `reachables`：使用默认的 reachables 配置运行 reachableByFlows。 - `cryptos`：运行与加密相关的数据流分析。 自定义流查询使用 `reachableByFlows` 或 `df` 步骤。例如： ``` atom.call.name(".*execute.*").reachableByFlows(atom.call.name(".*getInput.*")) ``` 流视图按源-汇点对结果进行分组，显示路径中的每一个步骤，并指示具有清理或验证标签的方法。引擎支持两种到达定义求解器：默认的 Flux 求解器（低内存分配，在处理大型方法时速度很快）和一个用于比较的经典求解器。 ## 图算法 通过引擎中的 `algo` 命令运行。可用的算法有： - **PageRank**（`centrality`）：根据调用图上的 PageRank 得分和入度中心性对方法进行排名。 - **强连通分量**（`scc`）：在调用图中查找递归簇。 - **拓扑排序**（`toposort`）：按被调用者先于调用者的顺序排列方法，并按 SCC 分组。 - **支配树**（`dominators`）：基于 CFG 边计算每个方法的直接支配节点。 - **过程间路径**（`paths`）：查找给定源方法与目标方法之间受 BFS 限制的调用路径。 ## AI agent 当配置了 API key（通过环境变量或配置文件）后，斜杠命令将被激活。这些命令可以像任何其他命令一样在 REPL 面板中输入。 ### 斜杠命令 | 命令 | 用途 | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `/security-review` | 基于可达性的漏洞分析。查找从源到汇点的污点路径，对发现的问题进行排名，并生成 markdown 报告。使用 `high` 推理力度。 | | `/code-review` | 审查代码变更（diff 或方法）的正确性和安全性。使用 `medium` 推理力度。 | | `/explain` | 对方法、数据流或代码结构进行自然语言解释。使用 `medium` 推理力度。 | | `/trace` | 证明或证伪给定源与汇点之间的污点路径。使用 `high` 推理力度。 | | `/help` | 列出可用的斜杠命令。 | 自由文本输入（不带斜杠）也会被路由到 agent 以回答临时问题。该 agent 可以访问十三种工具：atom_summary、atom_query、atom_dsl_eval、atom_flows、atom_flows_through、atom_detail、atom_algorithms、bom_query、ripgrep、read_file、git_diff、git_log 和 git_show。 agent 使用已配置提供商的流式 API，并实时渲染 thinking 块、文本增量（text deltas）和工具调用。工具结果会被截断为 48 KiB，以符合模型的 token 限制。当 agent 生成流结果时，它们会自动安装到流视图中以供交互式探索。 Agent 报告可以通过 Ctrl+S 保存为 markdown 文件。报告包含完整的转录内容、token 使用情况以及任何生成的数据流路径或分析结果。 ### 离线操作 该 agent 是可选的。当未设置 API key 时，chennai 将作为完全离线的代码分析工具运行，所有查询、数据流和算法功能均可通过 REPL 访问。斜杠命令和自由文本 agent 功能仅在配置了提供商时才会激活。 ## 配置 可以使用位于 `~/.config/chennai/config.toml` 的 TOML 文件、环境变量或 CLI 标志来配置 agent。CLI 标志的优先级高于环境变量，而环境变量的优先级高于配置文件。 配置文件示例： ``` provider = "openai" model = "deepseek-chat" api_key = "sk-..." base_url = "https://api.deepseek.com" effort = "high" ``` ## 开发 ### 前置条件 - Rust 工具链（edition 2024） - Scala 3.8.4 和 sbt - GraalVM Community Edition 25，用于 native-image 构建（开发可选） ### 构建 ``` # Engine (staged JAR distribution) (cd engine && sbt stage) # Engine native image (requires GraalVM) bash ci/native-image.sh # TUI (cd tui && cargo build --release) ``` ### 在本地构建所有 npm 包 ``` bash wrapper/nodejs/scripts/build-local.sh ``` ## 许可证 MIT

标签：AI智能体, DNS重绑定攻击, MITM代理, 云安全监控, 可视化界面, 通知系统, 静态分析