starshield-forensics
Enables read-only forensic recovery and health-checking of Brave's Chromium IndexedDB / Local Storage caches, carving uncompacted LevelDB .log WriteBatch frames and reassembling UTF-8 and Blink UTF-16LE JSON records with CRC32C verification.
Supports offline triage of Discord's Electron IndexedDB / Local Storage caches, extracting and epistemically tagging soft-deleted or edited message records (e.g. deletetime, edittime) with byte-offset citations.
Provides deterministic parsing of Electron desktop application IndexedDB / Local Storage .log caches (VS Code, Slack, Teams, Discord, WhatsApp Desktop), including cross-block frame reassembly, Castagnoli CRC32C validation, and zero-PII precheck feasibility gating.
Supports offline triage of the Slack desktop app's Electron IndexedDB / Local Storage .log files, recovering message records and pre-screening compaction status (GO / PARTIAL / NO_GO) without plaintext leakage.
Supports offline recovery of WhatsApp Web / Desktop Electron cache records, carving LevelDB write-ahead logs for JSON and Blink StructuredClone records and flagging deleted or edited entries for evidentiary triage.
starshield-forensics (v0.3.8 — Clean-Room Deterministic DFIR & MCP Toolkit)
English | 简体中文 (
README.zh-CN.md)
Deterministic Chromium & Electron IndexedDB / LevelDB
.logMulti-Schema Record Carver, Structural PNG/JPEG Container Inspector, Financial Checksum Validator & Zero-DependencyMCPServerAuthor: Ziqi Xiao (
@Ziqi) · PyPI:starshield-forensics 0.3.8 (PEP 740)· Homebrew:Ziqi/tap/starshield-forensics· Concept 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 Perfect Checks)· Provenance: SLSA L3 & Sigstore/attestations· Method Validation: UK FSR Statutory Code (FSA – DIG 100) / ISO 17025 Summary · License: MIT (REUSE 3.3) · Runtime: Python >= 3.10 (stdlib only, zero network calls, zero LLM dependencies)
High-Frequency Use Cases (DFIR, FinTech Audit & Developer Diagnostics)
starshield-forensics is an offline, read-only binary inspection and evidence triage toolkit serving three primary audiences with zero third-party dependencies:
FinTech, E-Commerce & Expense-Audit Screenshot Pre-Screening (
starshield inspect-image): Millisecond structural verification of reimbursement receipts, payment screenshots, and disputed attachments—verifying RFC 2083 PNG chunk CRC32 integrity (IHDR/IDAT/IEND/iCCP), multi-segment ISO 10918 JPEGAPP2 ICC_PROFILEcolor headers (acsp), and PhotoshopAPP13 (8BIM)resource blocks alongside offline ISO-7812 Luhn / 89-country ISO-13616 IBAN Mod-97 / ISO-9362 SWIFT validation.Developer & IT Offline Diagnostics for Corrupted Electron / Chrome Caches (
starshield precheck&parse-leveldb-log): Read-only local health check and uncompacted.logwrite-ahead log recovery for corrupted Chromium browser (Chrome,Edge,Brave) and Electron desktop app (VS Code,Slack,Microsoft Teams,Discord,WhatsApp Desktop) IndexedDB / Local Storage caches using strict masked Castagnoli CRC32C (0xA282EAD8) verification.Legal & DFIR Pre-Action Evidentiary Triage (
UK FSR FSA – DIG 100/ISO 17025Aligned): Byte-offset-cited carving of soft-deleted or edited web-messaging and B2B portal records with explicit four-tier epistemic tagging (OBSERVED/DERIVED/INFERRED/UNKNOWN) and ephemeralHMAC-SHA256pseudonymization.
All bundled fixtures in samples/ and starshield/data/—plus the seeded 24-case evaluation suite in benchmark/benchmark_suite.py (StarShield-Bench-24)—are 100% clean-room specification test vectors modeled on a fictional 2025 UK supplier-invoice scenario (GBP 18,400.00, ISO-13616 example IBANs GB82WEST12345698765432 and NO9386011117947, Luhn test string 6200000000000005). Zero real incident data or PII is included.
Related MCP server: VeriSIFT
Epistemic Tiers & Capability Boundary Matrix (v0.3.8)
Every analytical output carries an explicit machine-readable epistemic tier so investigators and solicitors never conflate raw bytes with interpretive leads:
OBSERVED: Directly present in raw input bytes, chunk headers, or JSON fields (bound to physical WAL frame offsets or chunk offsets).DERIVED: Deterministically computed from raw input via standardized algorithms (Castagnoli CRC32C, ISO/IEC 7812 Luhn, ISO-13616 Mod-97, UTC delta arithmetic).INFERRED: Contextual triage lead requiring external corroboration (e.g., server-side bank logs or subpoenaed ISP records); never asserted as standalone proof.UNKNOWN: Explicitly outside the evidentiary boundary of local client artifacts (e.g., records compacted prior to acquisition).
Module | Capability in | Epistemic Boundary & Known Limitations |
Zero-PII Storage Feasibility Gate ( | Scans Chromium & Electron IndexedDB / Local Storage folders or | Pre-screens compaction status prior to triage; does not decompress |
Chromium & Electron LevelDB | Parses 32 KiB physical blocks, verifies masked Castagnoli CRC32C ( | Does not decompress Snappy |
Exported Message & Portal JSON Triage ( | Enumerates soft-deleted ( | Cannot quantify records already compacted or evicted prior to acquisition. |
Financial Checksum Validation ( | Validates payment cards via ISO/IEC 7812 Luhn, IBANs via all 89 SWIFT IBAN Registry country lengths (15–34 chars) + Mod-97, SWIFT/BICs via all 249 ISO 3166-1 alpha-2 country codes + | Does not bundle proprietary Pay.UK Vocalink sort-code modulus weight tables. |
RFC 2083 PNG & ISO 10918 JPEG Container Inspection ( | Enforces PNG | Emits neutral container observations + benign screenshot/OS-resave caveats; never declares standalone "proof of forgery". |
Zero-Dependency | Exposes 4 read-only deterministic tools ( | Enforces |
Keyed Pseudonymization & Cryptographic Agility ( | Default masked mode applies ephemeral per-run | Provides keyed pseudonymization for casual screen/log hygiene—NOT formal legal anonymization under UK GDPR / GDPR. Pass |
10-Second Zero-Install Tryout (uvx) & Installation (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 demoZero-Install AI Agent Integration (starshield mcp for Claude Desktop, Cursor, Antigravity & Windsurf)
Mount StarShield's 4 deterministic read-only binary inspection tools directly into any MCP client (privacy-masked by default via ephemeral HMAC-SHA256 so cloud LLMs never see raw PII, filenames, or raw hashes):
{
"mcpServers": {
"starshield-forensics": {
"command": "uvx",
"args": ["--from", "starshield-forensics", "starshield", "mcp"]
}
}
}Sample Deterministic Output (starshield demo, Default Masked Mode)
{
"epistemic_tier": "OBSERVED",
"schema_detected": "chatsvc",
"leveldb_batch_byte_offset": 397,
"leveldb_sequence_number": 1002,
"is_soft_deleted_in_ui": true,
"sender_mri": "[REDACTED_HMAC:1b71a34908e1]",
"cached_content": "[REDACTED_CONTENT — pass --unredacted to view]",
"extracted_iocs": {
"luhn_validated_cards": ["[REDACTED_HMAC:3ec5f5677098]"],
"mod97_validated_ibans": ["[REDACTED_HMAC:4dad6b1cc0be]", "[REDACTED_HMAC:f21864d3e75c]"]
}
}CLI Subcommands (starshield [--unredacted] [--max-mb 64] [--hmac-digest {sha256,sha384,blake2b}] [--hmac-key-file PATH] <subcommand>)
Subcommand | Input Artifact | Output JSON Summary |
| Built-in synthetic fixtures | Runs end-to-end clean-room WAL, JSON, container, and checksum showcase |
| Chromium folder or | Zero-PII |
| Chromium LevelDB | Physical block CRC32C status, byte-offset-bound carved records, and validated IOCs |
| Exported messaging/portal JSON | Soft-deleted & edited records + per-record IOC schedule |
| PNG or JPEG exhibit | Chunk/marker integrity, ICC profile ( |
| Timezone-aware UTC pairs | Monotonicity verification, clock-skew bounds, and edge-node frequency summary |
| Chat transcript JSON | Descriptive utterance-length & punctuation distribution ( |
| JSON-RPC 2.0 | Read-only MCP server exposing |
Deterministic Core vs. Human-Reviewed Triage
starshield-forensics intentionally contains zero LLM or network code. Byte-offset extraction, CRC32C verification, and banking check-digit math must be 100% deterministic and reproducible, ensuring embedded adversary messages cannot trigger indirect prompt injection during extraction. Any downstream bilingual indexing or legal schedule preparation belongs in a human-reviewed workflow where every statement cites an immutable underlying record hash.
Cryptographic Release Verification & Bit-for-Bit Reproducibility (v0.3.8)
Every official release (starshield.pyz, .whl, .tar.gz, and ISO/IEC 5962:2021 SPDX 2.3 SBOM starshield-forensics-0.3.8.spdx.json) is backed by triple cryptographic verification:
GitHub OIDC + Sigstore (
FulcioX.509 +Rekortransparency log) build provenance & SPDX 2.3 SBOM attestations at/attestations;Isolated SLSA Build Level 3 provenance (
multiple.intoto.jsonlviaslsa-framework/slsa-github-generator);Air-gapped OpenSSH
Ed25519detached maintainer signature (SHA256SUMS.sig) verified againstKEYS.pub.
# 1. Verify Sigstore X.509 + Rekor build & SBOM attestations via GitHub CLI:
gh attestation verify starshield.pyz -R Ziqi/starshield-forensics
# 2. Verify isolated SLSA Build Level 3 provenance (.intoto.jsonl):
slsa-verifier verify-artifact starshield.pyz \
--provenance-path multiple.intoto.jsonl \
--source-uri github.com/Ziqi/starshield-forensics
# 3. Offline air-gapped verification using standard OpenSSH (>=8.2p1) & SHA256SUMS:
ssh-keygen -Y verify -f KEYS.pub -I "2196305+Ziqi@users.noreply.github.com" -n file -s SHA256SUMS.sig < SHA256SUMS
shasum -a 256 -c SHA256SUMS
# 4. Rebuild starshield.pyz & SPDX 2.3 SBOM from source and verify bit-for-bit reproducibility:
python3 scripts/build_reproducible.py --verify
python3 scripts/generate_spdx_sbom.py --verifyGovernance, Method Validation & Security Reporting
Verification / Archival Dimension | Live Status & Permanent Identifier |
Continuous Fuzzing ( |
|
Static Security ( |
|
Supply-Chain Provenance & Licensing ( |
|
Packaging ( |
|
Dual-Tool Forensic Method Validation (UK FSR Statutory Code
FSA – DIG 100[supersedingFSR-C-107] &ISO/IEC 17025Clause 7.2.2 Aligned):VALIDATION_REPORT_FSR_ISO17025.md(482test vectors cross-validated against Googledfindexeddb 20260210&Pillow 13.0.0; open-source validation aid for accredited laboratories, not a claim of laboratory accreditation)OpenSSF Security Insights (v2.0.0), OSPS Baseline Level 3 (EU CRA Aligned) & REUSE 3.3:
SECURITY-INSIGHTS.yml·SECURITY.md §5·REUSE.toml· SWHID (v0.3.7):swh:1:rel:3fa912215b0bb2510f7a2cfdfbd51293e29980c4Security Assurance Case & 12-Month Roadmap:
SECURITY_ASSURANCE_CASE.mdVulnerability Response Policy (48h Ack SLA):
SECURITY.md· GitHub Private Vulnerability ReportingGovernance, Roles & Continuity Policy:
GOVERNANCE.mdContribution, DCO 1.1 & Testing Standards:
CONTRIBUTING.md·CODE_OF_CONDUCT.mdAuthor: Ziqi Xiao (
@Ziqi) — Documentation & Sample Workpaper · GitHub Issues
Available Tools
4 toolsstarshield_demoRun StarShield Clean-Room Synthetic DemoBRead-onlyIdempotent
Execute StarShield's 5 deterministic offline triage engines on embedded 100% synthetic specification vectors (LevelDB 32KiB CRC32C WAL carving, PNG/JPEG ICC & 8BIM container inspection, Luhn/IBAN Mod-97/SWIFT validation, and UTC timestamp corroboration).
Inputs: no named parameters.
starshield_inspect_image_tamperInspect PNG/JPEG Screenshot & Receipt Container ProvenanceARead-onlyIdempotent
Deterministically verify RFC 2083 PNG chunk CRC32 integrity (IHDR/IDAT/IEND/iCCP) and ISO 10918 JPEG APP2 ICC_PROFILE / APP13 Photoshop 8BIM resource blocks for FinTech reimbursement, e-commerce receipt, and disputed screenshot pre-screening.
Inputs: image_path (required).
starshield_precheck_leveldbPrecheck Chromium / Electron Local LevelDB StorageARead-onlyIdempotent
Perform a read-only millisecond diagnostic and GO/PARTIAL/NO_GO feasibility check on a local Chromium browser or Electron desktop app (VS Code, Slack, Microsoft Teams, Discord, WhatsApp Desktop) IndexedDB/LevelDB directory or .log/.ldb file without leaking raw content.
Inputs: target_path (required), schema_mode.
starshield_validate_financial_iocsValidate Payment & Banking Checksums OfflineARead-onlyIdempotent
Scan text offline in <1ms to extract and mathematically verify ISO/IEC 7812 Luhn card numbers, 89-country ISO 13616 IBAN Mod-97 accounts, 250-territory ISO 9362 SWIFT/BIC codes, and intra-message UK Faster Payments Sort Code + 8-digit Account pairs.
Inputs: text (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The three substantive tools target clearly distinct artifact types: LevelDB feasibility, image integrity, and financial IOC validation. The demo tool overlaps conceptually by exercising the same engines, but its explicit synthetic-vector-only scope keeps it mostly distinct; an agent could still mistakenly reach for demo instead of a specific analysis tool.
All tools share a consistent starshield_ snake_case prefix. Three names follow a clear verb_noun pattern, while starshield_demo is a bare noun rather than an action, which is a minor deviation but remains readable and predictable.
Four tools is well-scoped for a narrow forensic triage server. Each tool corresponds to a distinct capability area: demo evaluation, LevelDB precheck, image tamper inspection, and financial IOC validation.
The surface covers precheck, image inspection, financial validation, and a synthetic demo, but lacks a real-data LevelDB carving/extraction tool and a standalone UTC timestamp corroboration operation. These are notable gaps for a full forensic workflow, since some advertised engines appear only inside the synthetic demo.
Maintenance
Related MCP Connectors
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Zero-install remote MCP server for proof-of-existence file attestation.
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA governed MCP server for digital-forensics and incident-response (DFIR) work, exposing curated forensic tools (Volatility 3, Plaso, RegRipper, etc.) through a single FastMCP HTTP endpoint with bearer-token authentication and tamper-evident audit logging.MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server for autonomous, spoliation-proof disk-image triage with self-correcting verification loop.MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server that exposes deterministic NTFS timestomp detection tools for autonomous forensic triage, with architectural guarantees against evidence modification.MIT
- FlicenseAqualityDmaintenanceMCP server for read-only forensic analysis of evidence files using local utilities (file, ExifTool, strings, Volatility).3-