平时排查本地桌面客户端故障、核验跨境付款单据或者把日志喂给 Claude / Cursor 分析时,我一直有两个很具体的痛点:
- 工具链依赖太重,断网环境寸步难行:很多二进制日志解析器或 MCP 服务端动辄依赖二十多个第三方 PyPI 包甚至 C/C++ 编译扩展(比如
python-snappy、pydantic、uvicorn)。一旦在没有外网的内网排查机或只读取证环境里运行,光配环境就要折腾半天,还要担心供应链投毒。 - 直接把原始日志丢给云端大模型,既有隐私泄露风险又容易被脏数据带偏:排查损坏的浏览器缓存或可疑账单记录时,里面往往混着真实银行账号、邮箱甚至恶意构造的文本。
最近我把手里打磨成熟的两个纯离线开源项目整理发布到了 GitHub,核心代码 100% 只用 Python >= 3.10 标准库(dependencies = [])和原生零后端前端,并且都跑通了 Linux 基金会 OpenSSF Best Practices Silver(银牌) 与 SLSA Build Level 3 构建溯源认证。这里简单分享一下两者的设计思路与一行命令上手方式。
一、starshield-forensics(v0.3.8):纯标准库 LevelDB 预写日志抢救、容器初筛与只读 MCP
- GitHub 仓库:
https://github.com/Ziqi/starshield-forensics(MIT 协议 · OpenSSF Silver#16602· Scorecard8.0/10) - 在线文档:
https://ziqi.github.io/starshield/
如果你装了 uv 或 Homebrew,不需要克隆仓库,一行命令就能在本地跑内置合成样本体验:
# 方式 1:uvx 零安装直接跑内置合成演示
uvx --from starshield-forensics starshield demo
# 方式 2:macOS / Linux Homebrew 安装
brew install Ziqi/tap/starshield-forensics
1. 为什么专门针对 Chromium LevelDB .log 做逐块校验?
Chrome、Edge 以及基于 Electron / WebView2 的桌面应用(如 Teams、Slack 等)在本地写缓存和配置时,底层新写入的数据会先追加进 LevelDB 的预写日志(.log 文件,按固定 32,768 字节物理块切分,每帧带 7 字节小端帧头)。在后台 Compaction 压缩进 .ldb 表之前,很多刚撤回的记录或崩溃前的现场还留在 .log 帧里。
我们在用 482 组合成测试向量(StarShield-Bench-24,Zenodo DOI 10.5281/zenodo.24156262)与 Google 开源的 dfindexeddb 做交叉对拍时注意到一个有意思的策略差异:dfindexeddb 在读取 .log 物理帧时只读取了 4 字节校验和字段而未重算比对掩码 Castagnoli CRC32C(当模拟单比特翻转后的字节恰好仍能通过外层结构解析时,会照常当作有效记录输出,相关讨论已提交上游 google/dfindexeddb#92)。
因此在 starshield-forensics 里,我们用纯 Python 标准库手写了完整的掩码 CRC32C 逐帧核验与跨 32 KiB 边界 FIRST / MIDDLE / LAST 碎片重组状态机:遇到意外损坏的帧会精确记录物理字节偏移与期望/实测双校验和并隔离损坏载荷,同时自动扫描下一处合法块边界继续抢救后续记录,避免一处断帧导致整份日志报废。
(注:Chromium 正逐步为新建的 IndexedDB 库引入 SQLite 后端,存量 LevelDB 目录与现行 Local Storage 仍使用 LevelDB,动手前可用内置 starshield precheck 先做零明文快速体检。)
2. 纯标准库写一个兼容双帧协议的 MCP 服务端有多轻?
为了不拉入庞大的异步 Web 框架,starshield/mcp_server.py 直接基于标准输入输出(stdio)实现了 换行分隔 JSON-RPC 2.0 与 Content-Length 头帧 自动识别,直接兼容 Claude Desktop、Cursor、Windsurf 等主流客户端:
{
"mcpServers": {
"starshield": {
"command": "uvx",
"args": ["--from", "starshield-forensics", "starshield", "mcp"]
}
}
}
它只暴露 4 个确定性只读工具(starshield_demo、starshield_precheck_leveldb、starshield_inspect_image_tamper、starshield_validate_financial_iocs),涵盖:
- 截图容器初筛:解析 PNG
iCCP与 JPEGAPP2 / 8BIM资源段,区分系统原生截图与修图软件二次导出痕迹(严格限定为第 0 层容器结构线索,不过度推断); - 跨境金融标识符数学核验:内置 89 国
ISO-13616IBANMod-97、银行卡Luhn与SWIFT/BIC格式校验; - 默认会话级
HMAC-SHA256脱敏:在本地解析阶段先剥离高危字段并打上单向盐值指纹,避免把原始敏感文本直接塞进大模型上下文。
二、澄镜 ClearLens(v1.0.0):零后端、纯浏览器内存运行的应急分诊与外发打码台
- GitHub 仓库:
https://github.com/Ziqi/clearlens(MIT 协议 · OpenSSF Silver#16718· SLSA Level 3) - 在线直接打开(支持断网离线使用):
https://ziqi.github.io/clearlens/
相比命令行工具,很多法务、财务或一线运维更需要一个不用配环境、但绝对不把文件传到任何服务器的可视化小工作台。
ClearLens 全站采用严格的 default-src 'none' 级别离线设计,零后端接口、零统计脚本、零外部字体请求(甚至可以直接下载 Release 里的离线包断网双击 app.html 打开,或 brew install Ziqi/tap/clearlens 启动本地只读预览),内置四个实用工作舱:
- 应急体检舱:快速核对可疑收款变更单据与关键核查清单;
- 外发防泄密打码舱(DLP):向外部协作方或 AI 发送日志前,一键在浏览器内存完成敏感账号、邮箱与标识脱敏;
- 多币种同名换汇去重核算舱:处理多笔跨币种转账流水时,自动剥离本人账户间换汇干扰,算出干净的真实净额表;
- 中英双语标准化技术附表打印舱:一键排版导出带哈希摘要的双语核查记录单。
三、供应链可复核性与后续计划
为了确保安全工具自身经得起审计,两个仓库均启用了:
- ClusterFuzzLite / Atheris 持续模糊测试(
starshield-forensicsOpenSSF Scorecard 实测8.0/10,其中Fuzzing满分10/10); - FSFE REUSE 3.3 全文件 SPDX 许可证头合规;
- GitHub OIDC SLSA Level 3 构建证明与单文件可复现归档包(
.pyz)。
下一步我们计划在 v0.3.9 与 ClearLens v1.1 中补充:
- 保序实体假名代号(如
<IBAN_01>)与本地detokenize反映射,让大模型既拿不到真账号、又能帮调查员理清多账户往来逻辑; - 纯前端
.eml原始邮件头拖入解析,直接在本地标红From / Reply-To不一致、SPF/DKIM/DMARC 异常与形似域名。
两个项目均为 MIT 开源协议,欢迎各位同行试用、挑刺或提 Issue 交流!