How the Evidence Chain System Ensures Traceability in reverse-skill

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), 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) 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) automates creation with proper field population:

# 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):

# 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), 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), which validates evidence graph integrity before any merge (noted in 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), 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:

### F-001

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

### 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 (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.

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