Quipu

一个用于编写、验证、编译和测试 YARA 规则的桌面工作台。

Quipu（发音为“KEE-poo”）将项目浏览器、支持 YARA 的编辑器、YARA-X 编译器和聚焦的扫描结果整合到一个本地应用中。它内嵌了 YARA-X 及其语言服务器，因此你无需单独安装 YARA。

[!IMPORTANT] Quipu 处于 MVP 阶段。构建目标为 Linux 和 Windows x86-64。 Windows 桌面验证覆盖 Windows 11 24H2；参见 验证记录。 实验性 macOS 构建已有 CI 覆盖和用户确认的 构建验证；参见验证记录。

功能

• 将包含 .yar 和 .yara 文件的文件夹作为工作区打开，或从一条 临时规则开始。
• 浏览推断或配置的入口点、嵌套包含、外部包含以及项目问题。
• 使用 Monaco 语法高亮、补全、悬停文档和实时 YARA-X 诊断进行编辑。
• 编译完整工作区，然后扫描输入的文本或选定的文件。
• 检查匹配的规则、模式、偏移量、字节长度，并在十六进制查看器中 高亮显示字节。
• 从诊断信息和匹配结果直接跳转到其源定义。
• 从有界的本地缓存中恢复未更改的已编译规则集。
• 使用应用附带的一组小型、自包含的示例项目进行工作。

规则和扫描目标均在本地处理。Quipu 不会将其内容发送到远程服务。

在 Linux 上安装

Linux x86-64 软件包发布在 GitHub Releases 页面：

软件包	适用场景	安装或运行
AppImage	在受支持的发行版上便携使用	chmod +x Quipu_*.AppImage && ./Quipu_*.AppImage
.deb	Ubuntu 22.04+ 和 Debian 12+	sudo apt install ./Quipu_*.deb
.rpm	较新的 Fedora 发行版	sudo dnf install ./Quipu-*.rpm

.deb 和 .rpm 软件包使用系统 WebKitGTK 运行时。如果你的发行版 无法满足该依赖，请使用 AppImage。

开发包可从成功的 CI 运行中以 quipu-linux-x86_64 制品的形式获取。 CI 和 Release 调用相同的 Linux 工作流，包括软件包验证和 原生菜单冒烟测试。合并的 SHA256SUMS 文件由 Release 提供， 而非由各个 CI 制品提供。

Quipu 软件包目前未签名。每个版本都包含一个 SHA256SUMS 文件；请将其与软件包一起下载，并使用以下命令验证你 下载的文件：

sha256sum --ignore-missing --check SHA256SUMS

校验和可检测意外损坏，但不是经过认证的签名。

在 Windows 上安装

对于 Windows x86-64 软件包（v0.3.0 及更高版本），请从 GitHub Releases 下载安装程序。 开发构建也可作为 quipu-windows-x86_64 和 quipu-windows-offline-x86_64 产物从成功的 CI 运行中获取。

• 使用 NSIS .exe 安装程序进行当前用户安装。
• 也提供 MSI .msi 安装程序。
• 对于气隙系统，请选择 -offline.exe 或 -offline.msi 安装程序 （即 quipu-windows-offline-x86_64 CI 产物）。这些较大的软件包包含 完整的 Microsoft Edge WebView2 运行时安装程序，可在无互联网访问的情况下安装它。
• 标准安装程序在缺少运行时会下载 WebView2，因此 安装可能需要互联网访问。

安装程序未签名，因此 Windows 可能会显示未知发布者或 SmartScreen 警告。在继续之前，请确认你的下载来自此仓库的 发布版本或工作流。

发布软件包包含一个合并的 SHA256SUMS 文件。在 PowerShell 中，计算 你下载的安装程序的哈希值（替换示例文件名）：

Get-FileHash -Algorithm SHA256 .\Quipu_VERSION_x64-setup.exe
Get-Content .\SHA256SUMS

将该哈希与该确切文件名对应的条目进行比较，忽略字母大小写。 单个 CI 产物不包含合并后的发布校验和文件。

如果在重启后忘记编译规则集，请查看随附指南中的 Windows Defender 故障排除。 其中说明了如何确认隔离情况，以及在需要时如何仅排除缓存 目录。

实验性 macOS 构建

CI 工作流会为 Apple Silicon 和 Intel 构建临时签名的 DMG，目标为 macOS 15 或更高版本。构建它们不需要 Apple Developer 会员资格， 但它们未经公证，启动时可能需要绕过 Gatekeeper。 有关 CI 产物、构建说明 以及当前验证状态，请参阅 macOS 开发。

快速开始

1. 启动 Quipu 并选择 File → Open Example… → Basic text match。
2. 在编辑器中浏览 text_indicators.yar。
3. 选择 Rules → Compile Workspace 或按下 Ctrl+Shift+B。
4. 使用 Rules → Scan Target 扫描准备好的目标，或按下 Ctrl+Shift+Enter。
5. 展开一个匹配项并选中它，以检查高亮显示的字节。

完整指南随 Quipu 一起打包在 Help → Documentation 下。其源代码 也可在 documentation/content 中获取。

工作区与 quipu.toml

在没有配置的情况下，Quipu 会递归发现规则文件，并从每个未被其他文件包含的文件中 推断出一个入口点。当你需要显式入口点、包含 目录或排除项时，请在工作区根目录添加 quipu.toml：

schema = 1
entrypoints = ["main.yar"]
include_dirs = ["rules", "../shared-rules"]
exclude = ["fixtures/**", "vendor/legacy/**"]

有关完整的项目模型和清单参考，请参阅 工作区与项目。

从源码构建

所有平台都需要：

• Rust 1.93 或更高版本
• Node.js 22.12 或更高版本
• Zola 0.23.6
• Git

对于 Windows，请按照 Windows 开发 中的说明配置 MSVC 构建工具、Windows SDK、WebView2 运行时以及 PowerShell 构建命令。

对于实验性的 macOS 构建，请按照 macOS 开发 中的说明操作。

Linux 还需要 Tauri 和 WebKitGTK 所需的原生库。

在 Debian 或 Ubuntu 上，使用以下命令安装原生依赖：

sudo apt update
sudo apt install -y \
  build-essential \
  curl \
  file \
  libayatana-appindicator3-dev \
  libgtk-3-dev \
  librsvg2-dev \
  libssl-dev \
  libwebkit2gtk-4.1-dev \
  patchelf \
  rpm \
  wget

然后构建全部三种 Linux 软件包格式：

git clone https://github.com/corelight/quipu.git
cd quipu/app
npm ci
npm run tauri -- build --bundles appimage,deb,rpm

构建产物会写入 app/src-tauri/target/release/bundle/ 目录下。首次构建可能需要较长时间，因为 Cargo 需要从源码编译 YARA-X 及其依赖项。

Windows 构建配置、安装程序行为以及文件系统限制在 Windows 开发 中有详细说明。

开发与测试

安装依赖并启动开发应用程序：

cd app
npm ci
npm run tauri -- dev

使用以下命令运行前端单元测试、生产前端构建和 Rust 测试：

cd app
npm test
npm run build

cd src-tauri
cargo test --locked

原生菜单验收测试套件对 Linux 显示服务器有额外要求。其设置与用法请参见 test/README.md。

架构

Quipu 是一个 Tauri 应用，前端使用原生 TypeScript，后端使用 Rust：

• Vite 将前端和 Monaco 编辑器打包进应用的 webview。
• Tauri IPC 将 UI 与 Rust 中的工作区、文件系统、编译、缓存和扫描服务连接起来。
• YARA-X 编译器和语言服务器在进程内运行。
• Zola 构建一个离线文档站点，并将其嵌入应用中。

app/src/           TypeScript frontend
app/src-tauri/     Rust backend and desktop packaging
documentation/    Source for the bundled offline guide
examples/          Projects bundled with the application
test/ui/           Native-menu acceptance test harness

应用程序版本在 app/package.json 中定义；Tauri 在为软件包命名和报告运行版本时会读取该值。

当前限制

• 发布包面向 Linux 和 Windows x86-64。macOS Apple Silicon 和 Intel 构建仍为实验性 CI 产物；请参阅 macOS 验证记录。
• Quipu 一次扫描一个选定的文件或一个文本缓冲区，而不是目录 或批次。
• 新规则在工作区根目录创建。移动和删除操作在 Quipu 之外 执行。
• 临时规则可以编译和扫描，但不能保存或缓存。

贡献与安全

欢迎贡献。在 提交拉取请求之前，请阅读 CONTRIBUTING.md。

请不要在公开 issue 中报告安全漏洞。请遵循 SECURITY.md 中的私密报告流程。

致谢

Quipu 由 Corelight 构建，并基于 YARA-X、 Monaco Editor 和 Tauri。

许可证

Quipu 在 3-clause BSD 许可证下分发。请参阅 LICENSE。 来自第三方的软件声明位于 THIRD_PARTY_LICENSES。