Ghidra BSim 的 Elasticsearch 后端：BSimElasticPlugin（lsh 插件）安装与实战部署指南

本文基于 Ghidra 扩展 BSimElasticPlugin 的 README，完整讲解如何把 BSim（Binary Similarity）数据库的后端从 PostgreSQL 切换到 Elasticsearch：包括 lsh 插件的安装、单节点试用部署、用户管理、bsim 命令行建库与签名提交，以及版本兼容性问题的处理方法。读完本文，你可以独立完成一套"开箱即用"的 Elasticsearch 版 BSim 部署，并理解该插件在 Elasticsearch 内部实际注册了哪些组件。

为什么要用 Elasticsearch 做 BSim 后端

BSim 是 Ghidra 内置的二进制相似度分析框架，它把二进制中的函数提炼为特征向量，再通过向量近邻检索实现"跨二进制找相似函数"。BSim 的数据库后端有多种选择，其中 Elasticsearch 后端要求集群上预先安装一个 BSim 专用的插件——lsh 插件。该插件以标准的 Elasticsearch 插件格式打包为 lsh.zip，随 BSimElasticPlugin 扩展一起分发，扩展的 extension.properties 将其描述为 "Elastic search backend for BSim"。

与 PostgreSQL 后端不同，Elasticsearch 后端不能用 Ghidra 提供的 bsim_ctl 命令管理——命令行参考文档明确指出 bsim_ctl 不能用于 Elasticsearch 服务器或本地 H2 数据库，集群的启动、停止与日常运维都需要按照 Elasticsearch 自身的文档进行。这也是本文的部署流程全部围绕 Elasticsearch 原生命令展开的原因。

安装 lsh 插件到 Elasticsearch 集群

README 的核心要求是：lsh 插件必须安装在集群的每一个节点上，并且每个节点安装后必须重启才能生效。

对于单节点（或逐个节点操作）的场景，使用 Elasticsearch 发行版自带的 elasticsearch-plugin 脚本完成安装。命令在节点的 Elasticsearch 安装目录下执行，参数是一个指向 lsh.zip 的 file:// URL：

bin/elasticsearch-plugin install file:///path/to/ghidra/Ghidra/Extensions/BSimElasticPlugin/data/lsh.zip

只需把 URL 中绝对路径的前半段替换为你自己的 Ghidra 安装路径。

插件打包内容与入口类

要理解这个 zip 里装的是什么，可以查看扩展内的插件描述文件 plugin-descriptor.properties：

description=Feature Vector Plugin
version=1.0
name=lsh
classname=org.elasticsearch.plugin.analysis.lsh.AnalysisLSHPlugin
java.version=1.21
elasticsearch.version=8.19.7

几个关键事实由此确认：

• 插件名为 lsh（启动日志里加载的插件列表里看到的就是这个名字）；
• 入口类是 AnalysisLSHPlugin；
• 该插件绑定 Elasticsearch 8.19.7、要求 Java 1.21——Elasticsearch 的插件安装脚本会严格校验版本匹配，这是后文"版本不匹配"问题的根源。

从源码结构看，AnalysisLSHPlugin 同时实现了 Elasticsearch 的 AnalysisPlugin 和 ScriptPlugin 两个接口，也就是说它在节点上注册了两类东西：

1. 自定义分词器 lsh_tokenizer：构造器中通过 tokFactoryMap 注册了名为 lsh_tokenizer 的 provider，实际由 LSHTokenizerFactory 创建分词器。工厂从索引设置中读取两个参数：

   • k_setting（LSH 参数 k）
   • l_setting（LSH 参数 L）

   这两个常量定义在客户端侧的 ElasticUtilities 中，与 lsh_weights、idf_config 一起构成 LSH（局部敏感哈希）向量编码的配置体系。

2. 自定义脚本引擎 bsim_scripts：BSimScriptEngine 只支持评分（ScoreScript.CONTEXT）上下文，用于在检索阶段执行向量比较脚本（VectorCompareScriptFactory），让相似度打分直接在 Elasticsearch 内部完成。

另外，AnalysisLSHPlugin.onIndexModule 会在索引模块加载时扫描形如 index.analysis.tokenizer.lsh_<name>. 的索引设置键，从中取出 idf_config 与 lsh_weights 构建服务端的向量工厂——源码注释特意说明"服务端工厂从不用于生成签名"，签名生成始终由 Ghidra 客户端完成，服务端只负责检索时的向量计算。

部署与验证：以单节点为例做试用环境

集群层面的配置、启停与管理请遵循 Elasticsearch 官方文档。如果只是想快速试跑 BSim，可以直接在命令行启动单节点：

bin/elasticsearch

启动后日志会输出到控制台，节点启动完成的标志之一是加载的插件列表中出现 [lsh]——这就是安装成功的验证点。

用户与密码管理

Elasticsearch 通常以开启密码认证的模式启动：首次启动时会自动创建一个 elastic 用户，其随机生成的密码会打印在控制台（仅此一次，请务必记下）。

要为 BSim 创建额外的用户，可以用如下 curl 命令创建（在命令行中这是一个带 -d JSON 负载的单条命令）：

curl -k -u elastic:XXXXXX -X POST "https://localhost:9200/_security/user/ghidrauser?pretty" -H 'Content-Type: application/json' -d'
{
  "password" : "changeme",
  "roles" : [ "superuser" ],
  "full_name" : "Ghidra User",
  "email" : "[e-mail]"
}
'

参数说明：

• -k：忽略自签证书校验（试用环境的常见做法）；
• -u elastic:XXXXXX：把 XXXXXX 换成首次启动时打印的 elastic 用户密码，用于鉴权；
• roles：示例使用内置角色 superuser（管理员权限）；如果只需要只读访问，可以改用内置角色 viewer 创建用户。

用 bsim 命令行连接 Elasticsearch

节点跑起来之后（无论试用还是正式集群），就可以直接使用 Ghidra 的 bsim 命令了。一个重要的协议约定：

Ghidra/BSim 客户端和 bsim 命令在 URL 中看到 https 协议时，会自动假定这是一个 Elasticsearch 服务器；elastic 协议也可以显式指定，二者等价。对 Elasticsearch 不支持使用 http 协议。

URL 的一般形式（见 BSim 命令行参考）为：

elastic://[<username>@]<hostname>[:<port>]/<dbname>

创建 BSim 实例

bsim createdatabase elastic://1.2.3.4:9200/repo medium_32

它等价于：

bsim createdatabase https://1.2.3.4:9200/repo medium_32

其中 1.2.3.4:9200 是 Elasticsearch 地址，repo 是仓库（数据库）名，medium_32 是配置模板（config template），请根据实际的主机名、端口、仓库名调整。

从 Ghidra Server 仓库生成并提交签名

bsim generatesigs ghidra://1.2.3.4/repo --bsim elastic://1.2.3.4:9200/repo

这条命令从 ghidra:// 指向的 Ghidra Server 仓库中提取函数、生成相似度签名，并提交到上面创建的 Elasticsearch 数据库。generatesigs 的完整语法（支持 --config|-c <config_template>、--commit、--overwrite 等选项）可以在 CommandLineReference.html 中查到。

在 Ghidra GUI 中使用

在 Ghidra 的 BSim 客户端里，把同样的 URL（如 elastic://1.2.3.4:9200/repo）填入数据库连接面板，即可向你的 Elasticsearch 部署发起相似度查询。BSim 的详细使用方法见 Ghidra 自带的 BSim 文档（含 DatabaseConfiguration 章节，其中"Elasticsearch Configuration"部分描述了该后端的整体定位）。

版本兼容性与 plugin-descriptor.properties 调整

这是 README 中最容易被忽略、但实际部署中最常踩坑的一节，完整结论如下：

• 当前 BSim 插件是在 Elasticsearch 8.19.7 上测试的；
• 从 8.16 开始，Elasticsearch 脚本接口发生了变化，使得该 BSim 插件与更早的版本不兼容；
• lsh 插件的 jar 在更新的 Elasticsearch 版本上通常可以不作修改地工作。

Elasticsearch 插件会在描述文件中显式声明所适配的 Elasticsearch 版本，版本不匹配时插件脚本会拒绝安装。如果你的 Elasticsearch 版本与 8.19.7 略有差异，可以手动调整：

1. 解开 lsh.zip；

2. 找到压缩包内的配置文件 elasticsearch/plugin-descriptor.properties；

3. 修改其中的版本行：

   elasticsearch.version=8.19.7
   

   把 8.19.7 改为你实际安装的版本号；

4. 重新打包 zip，再执行 bin/elasticsearch-plugin install ...。

需要注意，这是"在自担风险（proceed at your own risk）"前提下的做法：邻近版本可能工作，但仓库不承诺任何兼容性。

小结

BSimElasticPlugin 的价值在于把 BSim 的向量检索能力"下沉"到 Elasticsearch 集群内部：从源码看，插件注册了 lsh_tokenizer 分词器（携带 k_setting/l_setting 等 LSH 参数）和 bsim_scripts 评分脚本引擎，使相似度打分发生在数据库侧。对运维者而言，落地步骤可以浓缩为四步：

1. 在每个集群节点上执行 bin/elasticsearch-plugin install file:///.../BSimElasticPlugin/data/lsh.zip 并重启；
2. 确认启动日志的插件列表中出现 [lsh]；
3. 创建/准备数据库用户（如示例中的 ghidrauser）；
4. 用 elastic:// 或 https:// URL 通过 bsim createdatabase / bsim generatesigs 完成建库与签名提交，并在 Ghidra 的 BSim 连接面板填入同一 URL 开始查询。

关键参考路径：扩展说明 Ghidra/Extensions/BSimElasticPlugin/README.md、插件描述 Ghidra/Extensions/BSimElasticPlugin/contribZipExclude/plugin-descriptor.properties、插件入口 Ghidra/Extensions/BSimElasticPlugin/src/org/elasticsearch/plugin/analysis/lsh/AnalysisLSHPlugin.java，以及客户端 BSim 文档 CommandLineReference.html 与 DatabaseConfiguration.html。