# Evidence Chain Management Specification in the reverse-skill Repository: A Complete Guide to `evidence-finding-path.md`

> Explore the evidence chain management specification in the reverse-skill repository. Learn how evidence-finding-path.md connects observations to conclusions with mandatory validation.

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

---

**The [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) specification defines a markdown-driven workflow connecting raw observations (Evidence) to analyst conclusions (Finding) and reproducible narratives (Path), with mandatory cross-references and validation rules.**

The **reverse-skill** repository provides a rigorous framework for security and reverse-engineering workflows. The [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) document at [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) codifies how analysts build **evidence chains** that are auditable, reproducible, and ready for report generation. This guide covers the specification's core concepts, validation rules, and practical implementation.

## Core Components of the Evidence Chain

The specification defines three interconnected components. Each serves a distinct purpose in the analysis workflow.

### Evidence: Immutable Observations

**Evidence** records capture raw artefacts from the investigation. These are immutable facts—command outputs, screenshots, file hashes, logs, or memory dumps.

Mandatory fields include:

- `title` — human-readable description
- `observed_at` — timestamp of observation
- `source_type` — category (screenshot, file, log, command_output, etc.)
- `source_ref` — pointer to original source
- `content_hash` — cryptographic hash for integrity
- `artifact_path` — filesystem location
- `repro_command` — command to regenerate or view
- `raw_excerpt` — short sample or preview
- `linked_workitem` — connection to case tracker
- `supersedes` — optional reference to prior Evidence this replaces

### Finding: Analyst Conclusions

**Finding** documents represent security or reverse-engineering conclusions derived from Evidence. Every Finding must reference at least one Evidence item.

Mandatory fields include:

- `title` — finding description
- `severity` — risk level (info, low, medium, high, critical)
- `category` — classification (vuln, misconfig, malware, etc.)
- `status` — discovery state (tentative, confirmed, validated, false_positive)
- `evidence_ids` — **array with ≥1 Evidence references**
- `location` — where the issue exists
- `impact` — consequence description
- `confidence` — certainty level
- `repro_steps` — numbered reproduction procedure
- `remediation` — fix or mitigation
- `optional_attack` — MITRE ATT&CK technique ID

### Path: Structured Narratives

**Path** documents describe sequences that connect Evidence to Findings. Paths may represent attack flows, call chains, or solution steps.

Key fields:

- `title` — path name
- `path_type` — attack, defense, or analysis
- `start` — initial state
- `goal` — end state
- `steps` — ordered actions, each optionally referencing Evidence and/or Finding
- `residual_risks` — remaining concerns

## Global Validation Rules in [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md)

The specification enforces strict rules for evidence chain integrity. The [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) validation tool implements these checks.

### Mandatory Requirements

- **Every Finding must reference ≥1 Evidence** — no ungrounded conclusions permitted
- **Paths ending with "privilege/data obtained" findings must use validated Evidence** — critical findings require verified backing

### Recommended Standards

- **Findings promoted to `validated` should have ≥2 independent Evidence items** — for example, one static file hash plus one dynamic command output
- **Single Evidence alone may not silently promote a Finding to `validated`** — explicit analyst judgment required

These rules appear in the *Validated sufficiency* section of [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md).

## Practical Implementation: Creating Evidence Chains

The repository provides CLI helpers and Python validation tools. Below are complete examples from the specification.

### Step 1: Create Evidence with PowerShell

The `append-evidence.ps1` script generates properly formatted Evidence markdown files under `work/<case>/evidence/`.

```powershell

# Record a screenshot with hash verification

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/Case001 `
    -Id E-001 `
    -Title "Admin console screenshot" `
    -SourceType screenshot `
    -SourceRef "screenshots/admin_console.png" `
    -ArtifactPath "screenshots/admin_console.png" `
    -ReproCommand "display screenshots/admin_console.png" `
    -Severity info `
    -Status observed

```

This creates [`work/Case001/evidence/E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/Case001/evidence/E-001.md) with all required fields populated.

### Step 2: Author a Finding That References Evidence

Findings are markdown files in `work/<case>/findings/`. The `evidence_ids` field creates the chain link.

```markdown

### F-001

- title: "Local admin privilege escalation via CVE-2023-XXXX"
- severity: critical
- category: vuln
- status: validated
- evidence_ids: [E-001, E-002]
- location: C:\Windows\System32\exploit.exe
- impact: Full system compromise
- confidence: high
- repro_steps:
  1. Run `exploit.exe /run`
  2. Observe elevated token
- remediation: Apply patch KB123456
- optional_attack: T1068

```

Note the array `evidence_ids` with two independent items—satisfying the validated standard.

### Step 3: Compose the Attack Path

Paths reside in `work/<case>/paths/`. Each step explicitly links Evidence and Finding.

```markdown

### P-001

- title: "Privilege escalation path"
- path_type: attack
- start: "User with limited rights"
- goal: "Obtain SYSTEM token"
- steps:
  1. action: "Execute exploit" — evidence: E-001 — finding: F-001
  2. action: "Verify token" — evidence: E-002 — finding: F-001
- residual_risks: "Exploit may be detected by AV"

```

The step syntax uses inline references (`evidence: E-001 — finding: F-001`) to maintain explicit traceability.

### Step 4: Validate the Complete Chain

The [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) script enforces all specification rules.

```bash
python3 skills/case-review/scripts/review_case.py work/Case001 \
  --verify-hashes \
  --strict

```

Validation includes:

- Hash integrity verification against stored `content_hash` values
- Cross-reference checking (all `evidence_ids` must exist)
- Rule enforcement (Finding coverage, validated sufficiency)
- Path completeness (steps reference valid Evidence/Findings)

## Integration with Report Generation and Publishing

The evidence chain feeds multiple downstream systems.

### Security Report Templates

The **docs-generator** uses [`docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/references/security-report-templates.md) to embed evidence chains in final reports. The template renders:

- Tables of all Evidence with hashes and reproduction commands
- Lists of Findings with linked Evidence IDs
- At least one complete Path as a flow diagram or step sequence

### Field-Journal Hook

When publishing to the public `field-journal`, the system automatically extracts:

- Up to three key Evidence IDs
- One core Finding
- A concise Path sentence

This **de-identification** ensures public artifacts remain useful without exposing sensitive case details.

## Key Files in the reverse-skill Evidence Chain System

| File | Purpose |
|------|---------|
| [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) | Master specification defining Evidence, Finding, and Path contracts |
| [`docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs-generator/references/security-report-templates.md) | Report template with Evidence Chain section |
| `skills/scripts/append-evidence.ps1` | CLI helper for Evidence creation |
| [`skills/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/case-review/scripts/review_case.py) | Validation engine for integrity and rule enforcement |

## Summary

- **The [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) specification** ([`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)) defines a complete markdown workflow for evidence chain management in reverse-skill
- **Three core components** — Evidence (immutable observations), Finding (analyst conclusions), and Path (structured narratives) — form the chain
- **Mandatory rules** require every Finding to reference ≥1 Evidence; validated Findings should have ≥2 independent Evidence items
- **CLI tools** (`append-evidence.ps1`, [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py)) automate creation and validation
- **Downstream integration** feeds security reports and de-identified field journals

## Frequently Asked Questions

### What is the minimum Evidence required for a Finding?

Every Finding must reference at least one Evidence item in its `evidence_ids` array. The [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) validator rejects Findings with empty or missing evidence references.

### Can a Finding with one Evidence be marked validated?

Technically possible but discouraged. The specification states that promoting a Finding to `validated` status **should** accompany ≥2 independent Evidence items (e.g., static hash plus dynamic output). Single-Elevation validation requires explicit analyst override.

### How does the evidence chain support audit requirements?

Each Evidence carries `content_hash` and `repro_command` for integrity verification. The [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) `--verify-hashes` flag cryptographically validates all artefacts. The complete chain — Evidence IDs, Finding references, and Path steps — creates fully traceable analysis lineage.

### What happens when Evidence is updated?

Use the `supersedes` field in new Evidence to reference prior versions. This preserves immutable history while indicating obsolescence. The validator warns on Findings referencing superseded Evidence.