# Understanding the Evidence Chain in reverse-skill: Three-Tier Structure Explained

> Discover the Evidence Chain in reverse-skill. Understand its mandatory three-tier structure tracing artefacts to attack paths for robust security reports. Learn more!

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

---

**The Evidence Chain is the mandatory backbone of every security report in the reverse-skill framework, enforcing a three-tier hierarchy that traces raw artefacts through analytic findings to logical attack paths.**

The **Evidence Chain** serves as the non-negotiable structural foundation for all security and reverse-engineering deliverables within the *reverse-skill* repository. Defined in [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md), this framework mandates that every report documents the progression from initial data collection to final conclusions through three distinct hierarchical tiers.

## The Three-Tier Hierarchy of the Evidence Chain

The Evidence Chain captures the complete forensic lifecycle, ensuring traceability from immutable data to actionable intelligence.

### Tier 1: Evidence (Raw Artefacts)

The **Evidence** tier catalogs immutable raw data collected during investigations. According to the schema in [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md), each evidence entry requires these core fields:

- **`E-id`**: Unique identifier for the artefact
- **`source_ref`**: File path or origin location
- **`repro_command`**: Exact command or method to reproduce the data
- **`content_hash`**: Cryptographic hash of the content or `n/a` if unavailable

This tier establishes the factual baseline that cannot be disputed, preserving command outputs, file hashes, and screenshots exactly as collected.

### Tier 2: Findings (Analytic Statements)

The **Findings** tier transforms raw evidence into interpreted security statements. Each finding entry utilizes these specific fields as defined in the template:

- **`F-id`**: Unique finding identifier
- **`severity`**: Risk rating (e.g., `high`, `medium`, `low`) or `n/a_re` for non-security items
- **`evidence_ids`**: Array referencing supporting `E-id` values from the Evidence tier
- **`confidence`**: Numeric score (typically 0.0–1.0) indicating certainty
- **`location`**: Affected file path, memory address, or system component
- **`status`**: Verification state such as `verified`, `tentative`, or `disproven`

The `evidence_ids` field creates mandatory cross-references, ensuring every analytic statement grounds itself in Tier 1 data.

### Tier 3: Path (Logical Flow)

The **Path** tier synthesizes discrete findings into coherent attack narratives or analysis flows. Path entries contain:

- **`P-id`**: Unique path identifier
- **`path_type`**: Classification as `attack`, `callflow`, or `solve`
- **Step sequences**: Ordered references linking `E-id` or `F-id` entries to reconstruct the logical progression

This tier answers the "so what" question, transforming isolated facts into a story that explains how an attacker moved through a system or how an analyst derived a conclusion.

## Schema Implementation and Mandatory Fields

The Evidence Chain schema uses strict notation conventions in [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md). The `‖` symbol indicates "or" options (e.g., `content_hash ‖ n/a`), while field dependencies enforce referential integrity between tiers.

Mandatory cross-references ensure that:
1. Every Finding must cite at least one Evidence ID
2. Every Path step must reference valid Evidence or Finding IDs
3. No tier can exist in isolation within a compliant report

## Practical Report Structure

The following Markdown illustrates the three-tier relationship as implemented in reverse-skill deliverables:

```markdown

### 0.2 Evidence

- **E-001**  
  *source_ref*: `examples/ctf-demo/evidence/E-001.md`  
  *repro_command*: `cat /etc/passwd`  
  *content_hash*: `a1b2c3d4e5f6…`

### 0.3 Findings

- **F-001**  
  *severity*: `high`  
  *evidence_ids*: `E-001`  
  *confidence*: `0.92`  
  *location*: `/etc/passwd`  
  *status*: `verified`

### 0.4 Path

- **P-001** (type=`attack`)  
  1. **E-001** → **F-001** – Initial foothold discovered.  
  2. **F-001** → **F-002** – Lateral movement to `admin` account.  
  3. **F-002** → **E-003** – Credential dump captured.

```

## Enforcement and Validation

The reverse-skill framework enforces Evidence Chain compliance through automated validation. The PowerShell script `skills/scripts/verify-routing-coherence.ps1` checks that every generated report contains the mandatory Evidence Chain section, rejecting any deliverable that lacks the three-tier structure or contains broken cross-references between tiers.

## Key Documentation Files

| File | Purpose |
|------|---------|
| [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) | Defines the complete three-tier schema, field specifications, and required values |
| [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) | Describes contractual Evidence Chain requirements and links to templates |
| `skills/scripts/verify-routing-coherence.ps1` | Automated compliance checker that validates report structure |

## Summary

- The **Evidence Chain** is mandatory for all reverse-skill security reports and serves as the structural backbone
- Three distinct tiers: **Evidence** (raw immutable data), **Findings** (analytic interpretation), and **Path** (logical narrative flow)
- Strict ID schemas (`E-id`, `F-id`, `P-id`) and cross-reference fields ensure traceability between tiers
- The `verify-routing-coherence.ps1` script enforces compliance, preventing reports from shipping without the complete chain
- Vendor-specific overlays may add adjacent sections (Scope, Timeline) but cannot modify or bypass the core three-tier hierarchy

## Frequently Asked Questions

### What is the primary purpose of the Evidence Chain in reverse-skill?

The Evidence Chain ensures **forensic traceability** by mandating that every conclusion in a security report links back to reproducible raw data. This architectural requirement prevents unsupported assertions and creates an audit trail from initial artefacts through analytic interpretation to final narrative, as specified in [`security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/security-report-templates.md).

### How does the three-tier structure maintain data integrity?

The structure enforces **referential integrity** through mandatory cross-tier dependencies. Findings must reference valid Evidence IDs via the `evidence_ids` field, and Paths must reference specific Evidence or Finding IDs in their step definitions. This creates an unbroken chain of custody where every analytic statement traces directly to immutable raw data.

### What validation occurs if the Evidence Chain is missing from a report?

The `verify-routing-coherence.ps1` script automatically rejects any report lacking the Evidence Chain section. This enforcement aligns with the contractual standards defined in [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md), treating the three-tier structure as a non-negotiable deliverable requirement that must exist before a report can be marked complete.

### Can organizations customize the Evidence Chain for specific vendor requirements?

While vendor-specific overlays can extend the report structure with additional sections such as Scope or Timeline, they cannot modify or bypass the core three-tier hierarchy. The Evidence Chain remains the immutable backbone of every reverse-skill deliverable, ensuring consistent forensic standards across all security reporting contexts.