starshield-forensics (v0.3.8 — Clean-Room Deterministic DFIR & MCP Toolkit)

English | 简体中文 (README.zh-CN.md)

Deterministic Chromium & Electron IndexedDB / LevelDB .log Multi-Schema Record Carver, Structural PNG/JPEG Container Inspector, Financial Checksum Validator & Zero-Dependency MCP Server

Author: 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:

1. 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 JPEG APP2 ICC_PROFILE color headers (acsp), and Photoshop APP13 (8BIM) resource blocks alongside offline ISO-7812 Luhn / 89-country ISO-13616 IBAN Mod-97 / ISO-9362 SWIFT validation.
2. Developer & IT Offline Diagnostics for Corrupted Electron / Chrome Caches (starshield precheck & parse-leveldb-log): Read-only local health check and uncompacted .log write-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.
3. Legal & DFIR Pre-Action Evidentiary Triage (UK FSR FSA – DIG 100 / ISO 17025 Aligned): 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 ephemeral HMAC-SHA256 pseudonymization.

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.

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).

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 demo

Zero-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>)

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:

1. GitHub OIDC + Sigstore (Fulcio X.509 + Rekor transparency log) build provenance & SPDX 2.3 SBOM attestations at /attestations;
2. Isolated SLSA Build Level 3 provenance (multiple.intoto.jsonl via slsa-framework/slsa-github-generator);
3. Air-gapped OpenSSH Ed25519 detached maintainer signature (SHA256SUMS.sig) verified against KEYS.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 --verify

Governance, Method Validation & Security Reporting

Verification / Archival Dimension	Live Status & Permanent Identifier
Continuous Fuzzing (ClusterFuzzLite / Atheris)
Static Security (CodeQL SAST) & Deterministic CI
Supply-Chain Provenance & Licensing (REUSE 3.3)
Packaging (Homebrew Tap) & Scholarly / UNESCO Archival

• Dual-Tool Forensic Method Validation (UK FSR Statutory Code FSA – DIG 100 [superseding FSR-C-107] & ISO/IEC 17025 Clause 7.2.2 Aligned): VALIDATION_REPORT_FSR_ISO17025.md (482 test vectors cross-validated against Google dfindexeddb 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:3fa912215b0bb2510f7a2cfdfbd51293e29980c4
• Security Assurance Case & 12-Month Roadmap: SECURITY_ASSURANCE_CASE.md
• Vulnerability Response Policy (48h Ack SLA): SECURITY.md · GitHub Private Vulnerability Reporting
• Governance, Roles & Continuity Policy: GOVERNANCE.md
• Contribution, DCO 1.1 & Testing Standards: CONTRIBUTING.md · CODE_OF_CONDUCT.md
• Author: Ziqi Xiao (@Ziqi) — Documentation & Sample Workpaper · GitHub Issues