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

> Learn how the case-review skill verifies evidence chain integrity using SHA-256 hashes and traceability graphs. Ensure your evidence is cryptographically sound and logically linked.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-09-01

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash
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:

```bash
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:

```markdown
| 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.