MoonYara

MoonYara 是一个以 MoonBit 为主要实现语言的 YARA 风格威胁特征匹配与恶意代码扫描引擎。它面向规则驱动的文件内容筛查、WebShell 特征检测和离线 Wasm/JavaScript 扫描场景。

项目边界是“规则解析 + 特征匹配 + 条件求值 + 示例 CLI”，不是完整 YARA 兼容实现，也不是杀毒软件、进程注入工具或安全结论生成器。扫描结果只能作为规则命中的技术信号，不能替代人工分析。

功能

Aho-Corasick 多模式文本匹配。
Thompson NFA 正则匹配，避免传统回溯式正则的指数级回溯风险。
YARA 风格字符串、Hex 通配符和 Regex 声明。
and、or、not、字符串集合和文件大小等条件求值。
PE、ELF、Mach-O、ZIP、哈希和基础统计模块的安全边界解析。
核心 src 包无系统 IO/FFI 依赖，可构建为 wasm、wasm-gc、js 和 native 目标。

快速开始

从源码构建

git clone https://github.com/Hjyyutr/MoonYara.git
cd MoonYara
moon version --all
moon update
moon fmt --check
moon check --target all
moon build --target wasm,wasm-gc,js
moon test --target all

当前 CI 使用 moon check --deny-warn 和 moon test --deny-warn；moon fmt 与 moon info 采用兼容当前工具链的 --check/生成接口 diff 检查。

Mooncakes 安装

在另一个 MoonBit 模块中添加规范模块名：

moon add Hjyyutr/moonyara
moon update

也可以在 moon.mod 中声明：

import {
  "Hjyyutr/moonyara@0.1.5",
}

上面的固定版本 0.1.5 是本次验收修订候选版本；发布前请先确认 Mooncakes manifest 已出现 0.1.5，再在消费者项目中固定该版本。当前已公开的上一版本为 0.1.4。

包导入路径为：

import {
  "Hjyyutr/moonyara/src",
}

安装验证应在干净目录执行，示例见 scripts/verify_acceptance.ps1 的消费者检查说明。

库 API

let rules_text =
  #|rule PHPWebShell {
  #|  strings:
  #|    $eval = "eval"
  #|    $get = "$_GET"
  #|  condition:
  #|    $eval and $get
  #|}

let compiled = try! @src.compile_rules(rules_text)
let matches = @src.scan_bytes(compiled, b"<?php eval($_GET['cmd']); ?>")
inspect(matches.length(), content="1")

公开核心入口：

compile_rules(String) -> CompiledRules raise YaraError
scan_bytes(CompiledRules, Bytes) -> Array[YaraMatch]
parse_rules(String) -> Array[YaraRule] raise YaraError
parse_pe、parse_elf、parse_macho、parse_zip
calculate_md5、calculate_crc32、calculate_entropy 等基础模块函数

支持的规则子集和错误行为以 src/ 测试为准。空规则、未闭合规则体、非法 Hex/Regex、截断文件和越界 section 会返回错误或安全的无匹配结果，不应被解释为“文件安全”。

CLI

使用仓库自带规则扫描文件：

moon run --target js cmd/main -- -r test_rules/webshell.yara -f test_files/webshell.php

预期结果包含：

Verdict: [ALERT] Malicious signatures found!
Rule matched: WebShellDetect

缺少 -r 或 -f、规则文件不存在、目标文件不存在和规则解析失败时，CLI 会输出用法或错误信息。CLI 是演示工具，不负责递归目录扫描、进程内存扫描或自动隔离文件。

Examples 与 Browser/Wasm

运行 MoonBit 示例：

moon run examples/scan_example

验证 JavaScript 和 WebAssembly 构建：

moon build --target js examples/scan_example
moon build --target wasm-gc examples/scan_example

浏览器 smoke 页面使用 MoonBit 生成的 JavaScript 示例产物：

moon build --target js examples/scan_example
node scripts/serve_browser.mjs

然后打开 http://127.0.0.1:8765/examples/browser/，并在浏览器开发者工具 Console 中查看扫描输出。页面和生成产物路径见 examples/browser/index.html；不要直接双击 HTML，因为浏览器的本地文件策略可能阻止脚本加载。

架构

YARA rule text
      |
    parser
      v
  YaraRule AST ---- compiler ---- CompiledRule
                                      |
              +-----------------------+----------------------+
              |                       |                      |
        Aho-Corasick             Hex matcher             Thompson NFA
              +-----------------------+----------------------+
                                      v
                              MatchContext
                                      v
                              Condition VM
                                      v
                               YaraMatch[]

核心包只处理规则和字节数据；CLI 通过 moonbitlang/x/fs 负责文件 IO，避免把平台依赖带入库 API。

测试与性能

完整本地检查：

moon fmt --check
moon check --deny-warn --target all
moon build --target wasm,wasm-gc,js
moon info --target all
moon test --deny-warn --target wasm,wasm-gc,js
moon build --target native
moon test --deny-warn --target native

运行验收脚本（Windows PowerShell）：

powershell -NoProfile -File scripts/verify_acceptance.ps1

运行可重复的启动/缓存 smoke benchmark：

powershell -NoProfile -File scripts/benchmark.ps1

benchmark 输出会包含实际工具链版本、目标和本机耗时；耗时受 CPU、操作系统、MoonBit 版本和缓存影响，不能跨机器直接比较。

开发与贡献

开发流程：

moon update
moon fmt --check
moon check --target all
moon test --target all
moon info --target all
git diff --exit-code

请阅读 CONTRIBUTING.md。新增功能应同时提供正常路径、非法输入、边界和回归测试；公开 API 变更需要更新 README、CHANGELOG 和生成接口。

发布流程由维护者手工触发：先通过 CI、本地验收脚本、干净消费者安装和版本检查，再创建 tag、Release 并发布 Mooncakes。普通 Pull Request 不需要 Mooncakes 密钥。

许可证、Reference 与 Acknowledgement

项目使用 Apache License 2.0。规则语法兼容性参考 YARA；正则匹配原理参考 Ken Thompson 的 NFA 工作；多模式匹配参考 Aho 与 Corasick 算法。项目没有复制这些项目的实现代码，具体参考范围记录在本 README 和变更记录中。

感谢 MoonBit 团队以及 MoonBit 国产开源生态大赛组委会和评审专家提供的工具链与反馈。

状态

当前版本：0.1.5。GitHub：https://github.com/Hjyyutr/MoonYara；GitLink：https://gitlink.org.cn/Hjyyutr/MoonYara。