# Evidence-Finding-Path Workflow in reverse-skill: Connecting Findings to Reports

> Explore the evidence-finding-path workflow, an immutable audit chain linking security observations to analyst findings and attack narratives. Ensure your reports trace back to reproducible data.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-15

---

**The evidence-finding-path workflow is an immutable audit chain that connects raw observations (Evidence) to analyst conclusions (Findings) and attack narratives (Paths), ensuring every security report traces back to reproducible data.**

The **reverse-skill** repository implements a rigorous evidence-finding-path workflow to structure security assessments and reverse-engineering engagements. This contract-based system mandates that every conclusion references immutable source data, creating an audit trail that the `docs-generator` skill converts into compliant security reports.

## Understanding the Three Core Components

The workflow enforces a strict hierarchy: **Evidence** feeds **Findings**, which are organized into **Paths**. Each component uses a standardized Markdown format with specific filename conventions.

### Evidence (E‑xxx): Immutable Observations

Evidence entries capture raw, unalterable observations as Markdown files named `E‑<nnn>.md`. Each record contains fields for `title`, `source_type`, `source_ref`, `content_hash`, `artifact_path`, and `repro_command`, ensuring any observation can be independently verified.

According to the specification in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) (lines 28-34), analysts create Evidence using the helper script at `skills/scripts/append-evidence.ps1`. This script generates the Markdown file with a unique ID and computes content hashes automatically, preventing tampering after creation.

### Finding (F‑xxx): Analyst Conclusions

Findings represent the security or reverse-engineering conclusions drawn from Evidence. Stored as `F‑<nnn>` entries, each Finding lists `severity`, `category`, `status`, and crucially an `evidence_ids` array that points to supporting Evidence entries (lines 45-53 in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)).

Validation rules in the same file (lines 62-63) enforce two critical constraints:
- Every Finding must reference at least one Evidence ID
- A Finding marked as `validated` cannot carry low confidence unless accompanied by a residual‑risk note

### Path (P‑xxx): Attack and Solution Narratives

Paths provide the narrative structure connecting Evidence and Findings into coherent stories. Whether documenting an attack chain, call flow, or remediation steps, each Path entry (`P‑<nnn>`) contains a `steps` array where individual actions explicitly reference both Evidence (`E‑xxx`) and Finding (`F‑yyy`) IDs (lines 74-82).

This linkage demonstrates *how* the analyst moved from observation to conclusion, satisfying requirements for auditability in security assessments.

## Validation Rules and Quality Gates

The workflow implements hard validation rules to maintain data integrity:

1. **Mandatory Evidence Binding** – No Finding can exist without at least one `evidence_ids` entry. This prevents unsubstantiated claims in final reports.

2. **Confidence Consistency** – The system blocks Findings marked `status: validated` when `confidence: low` unless the analyst explicitly documents residual risk. This prevents overconfidence in tentative conclusions.

3. **Immutable Evidence** – Once created via `append-evidence.ps1`, Evidence files cannot be modified without breaking the `content_hash` validation, ensuring forensic integrity.

## Report Generation: From Chain to Document

The `docs-generator` skill consumes the evidence-finding-path chain to produce security reports. As specified 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) (lines 7-26), the security report template mandates inclusion of:

- **§0 Evidence Chain** – A table of all Evidence entries
- **Findings Section** – List of Findings with hyperlinked Evidence IDs
- **Path Description** – At least one Path showing the attack or solution flow

When executing `skills/docs-generator/scripts/generate-report.ps1`, the generator pulls Markdown tables for Evidence, renders the Findings list with linked Evidence IDs, and inserts the Path steps. This automation guarantees traceability from the final PDF or HTML report back to the raw observations and reproduction commands.

## Practical Implementation Example

Create Evidence using the PowerShell helper:

```powershell

# Create immutable Evidence E-001

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/MyCase `
    -Id E-001 -Title "Found vulnerable configuration" `
    -ReproCommand "nmap -p 22,80 target.com" -Severity info -Status observed

```

Define a Finding that references the Evidence:

```markdown

### F-001

- title: "Unauthenticated SSH access"
- severity: high
- category: misconfig
- status: validated
- evidence_ids: [E-001]
- location: "target.com:22"
- confidence: high
- remediation: "Disable password authentication"

```

Link them in a Path narrative:

```markdown

### P-001

- title: "Privilege escalation path"
- path_type: attack
- start: "Initial foothold"
- goal: "Root access"
- steps:
  1. action: "Enumerate services" — evidence: E-001 — finding: F-001
  2. action: "Exploit CVE-2023-XYZ" — evidence: E-002 — finding: F-002

```

Generate the final report:

```powershell
powershell -File skills/docs-generator/scripts/generate-report.ps1 -CaseRoot work/MyCase

```

## Summary

- The **evidence-finding-path workflow** in **reverse-skill** creates an immutable chain from raw data to final reports, ensuring auditability and reproducibility.
- **Evidence** (`E‑<nnn>.md`) captures immutable observations via `skills/scripts/append-evidence.ps1`, storing reproduction commands and content hashes.
- **Findings** (`F‑<nnn>`) must reference at least one Evidence ID and cannot claim `validated` status with low confidence without residual-risk documentation.
- **Paths** (`P‑<nnn>`) narrate the connection between Evidence and Findings, showing how conclusions were reached.
- The **docs-generator** skill enforces inclusion of this chain in security reports according to the template 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).

## Frequently Asked Questions

### What is the evidence-finding-path workflow in reverse-skill?

The evidence-finding-path workflow is a structured audit chain that mandates every security conclusion (Finding) connects to immutable source data (Evidence) and narrative context (Path). Implemented in the reverse-skill repository, it ensures that reports generated by the `docs-generator` skill contain fully traceable and reproducible findings.

### How does Evidence differ from Findings in the workflow?

**Evidence** (`E‑xxx`) represents raw, immutable observations captured as Markdown files with hashes and reproduction commands, created via `skills/scripts/append-evidence.ps1`. **Findings** (`F‑xxx`) represent the analyst's interpreted conclusions—such as vulnerabilities or misconfigurations—that explicitly reference Evidence IDs in their `evidence_ids` array to substantiate the claim.

### Why are Evidence entries immutable in this workflow?

Evidence entries are immutable to preserve forensic integrity and ensure reproducibility. Once created, the `content_hash` field prevents modification, guaranteeing that reports always reference the exact data observed during the engagement, not interpretations changed after the fact.

### How is the evidence chain validated during report generation?

The `docs-generator` skill validates the chain by enforcing the template requirements 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). It verifies that the report includes the Evidence table, Findings list with linked Evidence IDs, and at least one Path section before rendering the final document, ensuring no Finding appears without supporting Evidence.