How the Case-Review Skill Verifies Evidence Chain Integrity in Reverse-Skill

The case-review skill verifies evidence chain integrity by cryptographically validating SHA-256 hashes against actual artifacts and cross-referencing evidence IDs through a traceability graph to ensure every piece of evidence is both cryptographically intact and logically linked within the investigative workflow.

The case-review skill in the zhaoxuya520/reverse-skill repository provides automated verification of digital evidence integrity. When investigating security incidents, maintaining an unbroken chain of custody requires both cryptographic proof that files remain unmodified and logical proof that evidence connects to investigative findings. This skill implements a multi-stage verification pipeline that parses evidence records, normalizes hash values, validates artifacts against the filesystem, and builds a comprehensive traceability graph.

Parsing Evidence Records and Extracting Hashes

The verification process begins in skills/case-review/scripts/review_case.py within the parse_evidence() function (lines 86‑133). This routine recursively scans every markdown file stored under work/<case>/evidence/ and extracts critical metadata fields including content_hash and artifact_path.

Before validation occurs, the skill normalizes hash values through normalize_hash() (lines 43‑50). This function performs four essential transformations:

• Strips whitespace from the input value
• Converts the string to lowercase
• Removes any leading sha256: prefix
• Confirms the resulting string matches the 64‑character hexadecimal format required for SHA‑256 digests

This normalization ensures consistent comparison regardless of how the hash was originally formatted in the evidence record, preventing false mismatches due to capitalization or prefix variations.

Cryptographic Verification Against Artifacts

When the user invokes the skill with --verify-hashes, parse_evidence() delegates artifact validation to verify_artifact() (lines 67‑84). This function performs three critical security checks before computing digests.

Path Security and Directory Traversal Prevention

The routine first resolves the artifact_path relative to the case root if necessary, then validates the resolved location using is_within() (lines 52‑57). This security boundary ensures the artifact remains inside the case directory, preventing directory traversal attacks that could access sensitive files outside the investigation scope.

SHA-256 Computation and Hash Comparison

After confirming the file exists, verify_artifact() calls sha256_file() (lines 59‑64) to compute the artifact's actual SHA‑256 digest. The skill compares this computed hash against the normalized content_hash extracted from the evidence record.

If the digests differ, the skill emits an artifact.hash_mismatch error. For missing files or paths that escape the case directory, the skill generates appropriate warnings to alert investigators of potential custody breaches or missing evidence.

Building the Traceability Graph

Beyond cryptographic integrity, the skill verifies logical integrity through build_traceability() (lines 36‑47). This function constructs a directed graph that cross‑references every evidence ID with work items, timeline events, and report sections.

Any evidence record that lacks references in the investigative workflow triggers an evidence.unlinked warning. This ensures that evidence cannot simply be added to the case without being tied to specific findings, maintaining a complete audit trail from raw data to conclusions and preventing "orphan" artifacts from compromising the investigation's validity.

Executing the Verification Pipeline

The primary entry point review_case() orchestrates the complete verification workflow. Users can run a standard review for quick logical checks, or enable strict cryptographic validation for forensic integrity assurance.

Run a standard review to check traceability without verifying file hashes:

python3 skills/case-review/scripts/review_case.py work/mycase --format markdown

Run a strict review that verifies every artifact against its recorded SHA‑256 hash:

python3 skills/case-review/scripts/review_case.py work/mycase \
    --strict --verify-hashes --format markdown

When the skill detects integrity violations, it outputs structured warnings in markdown table format. A hash mismatch appears as:

| warning | artifact.hash_mismatch | evidence/E-001.md | artifact SHA-256 does not match content_hash |

The skill returns FAIL for critical integrity violations in strict mode, or WARN/PASS depending on the --strict flag configuration and the severity of detected issues.

Summary

• The case-review skill processes evidence records from work/<case>/evidence/ using parse_evidence() (lines 86‑133) to extract content_hash and artifact_path values
• Hash normalization via normalize_hash() (lines 43‑50) standardizes SHA‑256 values to 64‑character hexadecimal format before comparison
• Cryptographic verification through verify_artifact() (lines 67‑84) validates file integrity using sha256_file() (lines 59‑64) while is_within() (lines 52‑57) enforces directory boundaries
• Traceability validation via build_traceability() (lines 36‑47) ensures every evidence ID links to work items, timeline events, or reports, flagging unlinked evidence with evidence.unlinked warnings
• The skill supports both standard and strict verification modes via CLI flags --verify-hashes and --strict

Frequently Asked Questions

What happens when the case-review skill detects a hash mismatch?

When verify_artifact() computes a SHA‑256 digest that differs from the normalized content_hash, the skill records an artifact.hash_mismatch error in the output. In strict mode (--strict), this causes the final verification status to return FAIL, while standard mode reports it as a warning to alert investigators without halting the workflow.

How does the skill prevent access to files outside the case directory?

The verify_artifact() function calls is_within() (lines 52‑57) to validate that resolved artifact paths remain within the case root directory. This check blocks directory traversal attempts that use relative path components like ../ to escape the investigation workspace, ensuring forensic isolation and preventing unauthorized file access during verification.

What is the difference between standard and strict verification modes?

Standard mode reviews evidence metadata and traceability without computing file hashes, suitable for quick logical consistency checks. Strict mode (--strict) combined with --verify-hashes enables cryptographic validation where hash mismatches and critical traceability gaps cause the verification to return FAIL rather than generating warnings, enforcing rigid chain-of-custody requirements.

How does the traceability graph identify unlinked evidence?

The build_traceability() function (lines 36‑47) constructs a mapping of evidence IDs to their references across work items, timeline events, and report sections. Any evidence ID present in the evidence directory but absent from this cross-reference graph triggers an evidence.unlinked warning, ensuring every artifact contributes to the investigative narrative rather than existing as an unreferenced standalone file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}