确定性的离线 Chromium LevelDB .log 雕刻工具、PNG/JPEG ICC 来源检查器、财务校验和验证器以及 StarShield-Bench-24
starshield-forensics(v0.3.8 — 洁净室确定性 DFIR 与 MCP 工具包)English | 简体中文 (
README.zh-CN.md)
确定性 Chromium 与 Electron IndexedDB / LevelDB
.log多模式记录雕刻器、结构化 PNG/JPEG 容器检查器、财务校验和验证器与零依赖MCP服务器作者: Ziqi Xiao (
@Ziqi) · PyPI:starshield-forensics 0.3.8 (PEP 740)· Homebrew:Ziqi/tap/starshield-forensics· 概念 DOI:10.5281/zenodo.24145804(v0.3.7:10.5281/zenodo.24156262) · SWHID:swh:1:snp:4ed5efec...· OpenSSF Best Practices:#16602(SILVER — 226%)· Scorecard:8.0 / 10(Fuzzing 10/10 · 11/18 项完美检查)· 来源证明: SLSA L3 与 Sigstore/attestations· 方法验证: 英国 FSR 法定准则(FSA – DIG 100)/ ISO 17025 摘要 · 许可证: MIT(REUSE 3.3) · 运行时: Python >= 3.10(仅标准库,零网络调用,零 LLM 依赖)
starshield-forensics 是一个离线、只读的二进制检查与证据分诊工具包,以零第三方依赖服务三类主要用户:
starshield inspect-image):对报销收据、支付截图和争议附件进行毫秒级结构验证——验证 RFC 2083 PNG 块 CRC32 完整性(IHDR/IDAT/IEND/iCCP)、多段 ISO 10918 JPEG APP2 ICC_PROFILE 颜色头(acsp)以及 Photoshop APP13 (8BIM) 资源块,同时进行离线 ISO-7812 Luhn / 89 国 ISO-13616 IBAN Mod-97 / ISO-9362 SWIFT 验证。starshield precheck 与 parse-leveldb-log):针对损坏的 Chromium 浏览器(Chrome、Edge、Brave)和 Electron 桌面应用(VS Code、Slack、Microsoft Teams、Discord、WhatsApp Desktop) IndexedDB / Local Storage 缓存,使用严格掩码的 Castagnoli CRC32C(0xA282EAD8)验证进行只读本地健康检查与未压缩 .log 预写日志恢复。UK FSR FSA – DIG 100 / ISO 17025):对软删除或编辑过的网络消息和 B2B 门户记录进行带字节偏移引用的数据雕刻,并采用明确的四级认知标签(OBSERVED / DERIVED / INFERRED / UNKNOWN)和临时性 HMAC-SHA256 假名化。samples/ 和 starshield/data/ 中的所有捆绑测试样本——以及 benchmark/benchmark_suite.py 中预置的 24 用例评估套件(StarShield-Bench-24)——均为 100% 洁净室规范测试向量,基于虚构的 2025 年英国供应商发票场景(GBP 18,400.00,ISO-13616 示例 IBAN GB82WEST12345698765432 和 NO9386011117947,Luhn 测试字符串 6200000000000005)建模。不包含任何真实事件数据或 PII。
v0.3.8)每个分析输出都带有明确的机器可读认知层级,使调查人员和律师绝不会将原始字节与解释性线索混为一谈:
OBSERVED:直接存在于原始输入字节、块头或 JSON 字段中(绑定到物理 WAL 帧偏移或块偏移)。DERIVED:通过标准化算法(Castagnoli CRC32C、ISO/IEC 7812 Luhn、ISO-13616 Mod-97、UTC 差值运算)从原始输入确定性计算得出。INFERRED:需要外部佐证(例如服务器端银行日志或传票调取的 ISP 记录)的情境性分诊线索;绝不作为独立证据断言。UNKNOWN:明确超出本地客户端工件证据边界的内容(例如在获取之前已被压缩的记录)。| 模块 | v0.3.8 中的能力 | 认知边界与已知限制 |
|---|---|---|
零 PII 存储可行性门禁(precheck) | 离线扫描 Chromium 与 Electron 的 IndexedDB / Local Storage 文件夹或 .log/.ldb 文件,检查 LevelDB SSTable 尾部魔数(0xdb4775248b80fb57)、.blob 目录以及 Blink 0xFF 头部,输出确定性的 GO / PARTIAL / NO_GO_COMPACTED_OR_UNSUPPORTED 清单,且零明文泄漏。 | 在分诊前预筛压缩状态;不解压 .ldb 块。 |
Chromium 与 Electron LevelDB .log 雕刻器(leveldb_log.py) | 解析 32 KiB 物理块,校验掩码 Castagnoli CRC32C(0xA282EAD8),重组跨块的 FULL/FIRST/MIDDLE/LAST WriteBatch 帧,并跨 Chromium 浏览器与 Electron 桌面应用(Microsoft Teams/Skype 的 chatsvc、Slack、WhatsApp Web/Desktop、Discord、VS Code,以及通过 --schema auto|chatsvc|generic-json 处理的 B2B 发票门户)提取 UTF-8 与 Blink UTF-16LE JSON 记录。 | 不解压 Snappy .ldb SSTable,也不解码非 JSON 的 Blink StructuredClone 原语(路线图:v0.4)。 |
导出的消息与门户 JSON 分诊(triage-json) | 枚举消息与门户导出中的软删除(deletetime / deleted_ts / is_deleted)与已编辑(edittime / edited.ts)JSON 记录,严格按记录提取经验证的 IOC。 | 无法量化在采集前已被压缩或逐出的记录。 |
金融校验和验证(ioc_validators.py) | 通过 ISO/IEC 7812 Luhn 验证支付卡,通过全部 89 个 SWIFT IBAN Registry 国家长度(15–34 字符)+ Mod-97 验证 IBAN,通过全部 249 个 ISO 3166-1 alpha-2 国家代码 + XK(共 250 个代码)+ 停用词过滤验证 SWIFT/BIC,并在 120 字符的消息内窗口内配对英国 Sort Code。 | 不捆绑专有的 Pay.UK Vocalink sort-code 模数权重表。 |
RFC 2083 PNG 与 ISO 10918 JPEG 容器检查(image_containers.py) | 强制校验 PNG IHDR + IDAT + IEND 完整性及逐块 CRC32,有界解压 iCCP 块(acsp),并通过 SOS/EOI(0xFFD9)重组多块 JPEG APP2 ICC_PROFILE + APP13(8BIM)段。 | 输出中立的容器观察结果 + 良性的截图/操作系统重存注意事项;绝不单独宣称“伪造证据”。 |
零依赖 MCP 服务器(mcp_server.py / starshield mcp) | 通过 JSON-RPC 2.0 stdio(换行与 Content-Length 分帧)向 Claude Desktop、Cursor、Google Antigravity 和 Windsurf 暴露 4 个只读确定性工具(starshield_demo、starshield_precheck_leveldb、starshield_inspect_image_tamper、starshield_validate_financial_iocs)。 | 默认强制 HMAC-SHA256 掩码模式,使云端 LLM 永远不会收到原始 PII、文件名或原始 SHA-256 哈希。 |
带密钥的假名化与密码学敏捷性(cli.py) | 默认掩码模式应用每次运行临时的 HMAC-SHA256 令牌(可通过 --hmac-digest {sha256,sha384,blake2b} 和外部 32 字节盐 --hmac-key-file PATH 配置),并抑制原始文件 SHA-256 哈希、精确字节长度、源文件名、PNG tEXt/iTXt 预览、自定义 ICC 名称、精确 UTC 日期,以及失败路径 stderr 中的文件名/字节数/片段。 | 为日常屏幕/日志卫生提供带密钥的假名化——并非英国 GDPR / GDPR 下的正式法律匿名化。仅在授权的离线环境中传入 --unredacted。 |
uvx)与安装(pip PEP 740 / .pyz)# Instant zero-install clean-room showcase (fetches PyPI wheel directly, zero repo clone needed):
uvx --from starshield-forensics starshield demo
# Option A — Official PyPI package (with PEP 740 Sigstore digital attestations, zero dependencies):
pip install starshield-forensics
starshield demo
# Option A2 — macOS / Linux Homebrew Tap (isolated virtualenv formula, zero dependencies):
brew install Ziqi/tap/starshield-forensics && starshield demo
# Option B — Zero-install single-file zipapp (for air-gapped forensic VMs & law-firm IT):
python3 starshield.pyz demo
python3 starshield.pyz precheck /path/to/readonly_chromium_idb_copy
# Option C — Clone & run all 26 unit/MCP tests, fuzzing harness & StarShield-Bench-24 (<1s, zero dependencies):
git clone https://github.com/Ziqi/starshield-forensics.git
cd starshield-forensics
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. python3 -m unittest discover -s tests -v
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. python3 -W error tests/fuzz_parsers.py --stdlib --iterations 2500
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. python3 benchmark/benchmark_suite.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. python3 scripts/verify_cross_tool_forensics.py
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=. python3 -m starshield.cli demo
starshield mcp,适用于 Claude Desktop、Cursor、Antigravity 和 Windsurf)将 StarShield 的 4 个确定性只读二进制检查工具直接挂载到任意 MCP 客户端(默认通过临时 HMAC-SHA256 进行隐私脱敏,因此云端 LLM 永远不会看到原始 PII、文件名或原始哈希):
{
"mcpServers": {
"starshield-forensics": {
"command": "uvx",
"args": ["--from", "starshield-forensics", "starshield", "mcp"]
}
}
}
starshield demo,默认掩码模式)