# How the Evidence Chain System Ensures Traceability in reverse-skill

> Discover how the evidence chain system in zhaoxuya520/reverse-skill ensures traceability. Learn about its three-layer hierarchy, linking rules, and automated auditing for robust verification.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-10

---

**The evidence chain system in reverse-skill guarantees end-to-end traceability through a three-layer hierarchy (Evidence → Finding → Path), mandatory linking rules, cryptographic hash verification, and automated graph auditing.**

The `reverse-skill` repository implements a rigorous **evidence chain system** designed specifically for security researchers and reverse engineers who must defend their conclusions in reports, court proceedings, or CTF write-ups. This article examines how the system enforces traceability at every layer of the analysis pipeline, from raw data collection to final report generation.

## The Three-Layer Evidence Hierarchy

At the core of `reverse-skill`'s traceability model is a strictly defined chain with three interconnected layers:

| Layer | Definition | Key Requirement |
|-------|-----------|---------------|
| **Evidence** | Immutable raw observations (commands, screenshots, files, network traces) | SHA-256 hash + reproducible command |
| **Finding** | Security conclusions derived from evidence | Must cite ≥1 evidence IDs |
| **Path** | Ordered action sequence from evidence to objective | Each step references evidence and/or findings |

According to [[`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md), this hierarchy is not merely descriptive—it is **enforceable by code**.

### Evidence Layer: Immutable Raw Observations

The Evidence layer (lines 6-24 of [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md)) mandates four fields for every record:

- `content_hash` – SHA-256 digest of referenced artifacts
- `artifact_path` – location of supporting files
- `repro_command` – exact command to regenerate the observation
- `timestamp` and `observer` – attribution metadata

This design ensures that **any piece of evidence can be independently reproduced and verified** months or years after collection.

### Finding Layer: Conclusions With Mandatory Backing

Findings (lines 43-60) must include:

- `evidence_ids` – **array of at least one Evidence ID**
- `severity` and `confidence` – risk assessment metadata
- `remediation` – actionable guidance

The `MUST` clause on line 26 explicitly prohibits orphan findings. No conclusion enters the system without documented support.

### Path Layer: Logical Execution Flow

Paths (lines 64-84) define `steps` where each step may reference:

- `evidence` – the raw data supporting this step
- `finding` – the conclusion reached at this juncture

This creates a **bidirectional traceability matrix**: traverse forward from evidence through findings to paths, or backward from any path step to its supporting evidence.

## Enforcement Mechanisms

### Contract-Driven Markdown Schema

All records are Markdown files validated against a strict schema. The `append-evidence.ps1` helper (lines 28-33 of [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md)) automates creation with proper field population:

```powershell

# Append a new evidence record (hashes the file automatically)

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/my-case `
    -Id E-001 `
    -Title "Static analysis of binary" `
    -ReproCommand "strings binary.exe | grep flag" `
    -ArtifactPath "evidence/binary_strings.txt" `
    -Severity info `
    -Status observed

```

This prevents ad-hoc or incomplete records from entering the chain.

### Hash-Based Fixity Verification

The `content_hash` field enables **tamper detection**. The `case-review` scripts verify these hashes with `--verify-hashes --strict` (lines 35-39):

```bash

# Verify the whole case graph (hashes + schema)

python3 skills/case-review/scripts/review_case.py work/my-case \
    --verify-hashes --strict

```

Any artifact modification after collection breaks verification and flags the case for review.

### Read-Only Graph Audit

The `case-review` skill ([[`skills/case-review/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/SKILL.md), lines 46-91) performs three critical validations:

1. **Evidence coverage** – Every finding cites ≥1 evidence IDs
2. **Path termination** – All paths end in validated findings
3. **Hash integrity** – Recorded hashes match current artifact states

This audit is **read-only by design**—it never modifies the chain, ensuring forensic defensibility.

### Automated CI Enforcement

The test suite includes [[`skills/case-review/tests/test_review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/tests/test_review_case.py)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/tests/test_review_case.py), which validates evidence graph integrity before any merge (noted in [`CHANGELOG.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CHANGELOG.md) line 64). Broken traceability blocks deployment.

## Integration With Reporting

The **docs-generator** skill ([[`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md), lines 9-22) extracts the structured evidence graph into the final deliverable. The "Evidence Chain" section in generated reports **mirrors the underlying graph exactly**, ensuring consistency between working notes and published analysis.

Example finding and path records in practice:

```markdown

### F-001

- title: Remote Code Execution Vulnerability
- severity: critical
- evidence_ids: [E-001, E-003]
- confidence: high
- remediation: Apply patch XYZ

```

```markdown

### P-001

- title: Exploit Chain
- path_type: attack
- steps:
  1. action: — evidence: E-001 — finding: F-001 | none
  2. action: — evidence: E-003 — finding: F-001 | none

```

## Summary

- **Evidence chain traceability** in `reverse-skill` rests on a mandatory three-layer hierarchy: Evidence → Finding → Path
- **Cryptographic hashing** (`content_hash` with SHA-256) guarantees artifact integrity
- **Schema enforcement** through `append-evidence.ps1` prevents incomplete records
- **Graph auditing** via `case-review` validates coverage, termination, and hash integrity
- **CI automation** blocks commits that break traceability
- **Report integration** ensures published findings match the verified internal graph

## Frequently Asked Questions

### What happens if an evidence file is modified after collection?

The `case-review` script's `--verify-hashes --strict` flag detects the mismatch between the recorded `content_hash` and the current file state. The audit fails, flagging the case for manual review before any report can be generated.

### Can a Finding exist without linked Evidence?

No. The schema in [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) (line 26) includes a `MUST` clause requiring every Finding to reference at least one Evidence ID. The `case-review` audit explicitly checks for orphan findings and rejects them.

### How does the Path layer support different analysis types?

The `path_type` field (line 64) accepts values like `attack`, `call-flow`, or `ctf-solve`, allowing the same evidence chain structure to support penetration testing, reverse engineering, and competitive security exercises without schema changes.

### Is the evidence chain format extensible for custom fields?

The Markdown-based schema permits additional key-value pairs beyond the mandatory fields. However, the `case-review` audit only validates core requirements—custom fields are preserved but not enforced, maintaining backward compatibility while allowing domain-specific extensions.