# How reverse-skill Structures Security Findings Using the Evidence→Finding→Path Methodology

> Learn how reverse-skill structures security findings using the Evidence->Finding->Path methodology. Discover how immutable evidence, validated findings, and reproducible paths document attack flows and solution sequences.

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

---

**reverse-skill enforces a strict, contract-driven workflow where immutable Evidence feeds validated Findings, which are then woven into reproducible Paths that document attack flows, call chains, or solution sequences.**

The **Evidence→Finding→Path** framework is the core methodology defined in `zhaoxuya520/reverse-skill` for transforming raw security observations into auditable, reproducible narratives. This three-layer architecture ensures that every conclusion can be traced back to source data, every path can be rebuilt from its components, and every report meets mandatory validation standards.

## The Three-Layer Architecture

### Evidence: Immutable Observations

**Evidence** represents a single, unchangeable observation—command output, screenshot, file hash, network capture, or manual note. Each piece lives in its own Markdown file following the naming convention `E-{nnn}.md`.

Required fields per the contract in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md):

- `title` – Human-readable description
- `observed_at` – ISO 8601 timestamp
- `source_type` – Category of observation (command, screenshot, hash, etc.)
- `source_ref` – Path to original data
- `content_hash` – Cryptographic hash for integrity
- `repro_command` – Exact command to regenerate
- `raw_excerpt` – Relevant snippet
- `linked_workitem` – Traceability to work item
- `supersedes` – Prior evidence this replaces, if any

The contract enforces that **every Finding must reference at least one Evidence entry** via `evidence_ids`—this field cannot be empty.

Create Evidence manually or use the CLI helper:

```powershell
powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/target1 `
  -Id E-001 -Title "Initial nmap scan" `
  -ReproCommand "nmap -sV -p- 10.10.10.5" `
  -Severity info -Status observed

```

This generates [`work/target1/evidence/E-001.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/work/target1/evidence/E-001.md) with proper front matter.

### Finding: Security Conclusions

**Finding** documents a concise security conclusion—vulnerability, misconfiguration, or reverse-engineering insight. Stored as `F-{nnn}.md` with strict validation rules.

Required fields:

- `title`, `severity`, `category`, `status`
- `evidence_ids` – Links to supporting Evidence (array, minimum one)
- `location` – Where the issue exists
- `impact` – Business/technical consequences
- `confidence` – high/medium/low
- `repro_steps` – Numbered reproduction procedure
- `remediation` – Fix guidance
- `optional_attack` – MITRE ATT&CK technique tags

Critical validation rule: when `status=validated`, `confidence` must not be **low** unless residual risk is explicitly noted. This prevents weakly-supported conclusions from appearing as validated findings.

Example Finding referencing Evidence:

```markdown

### F-001

- title: "Unauthenticated HTTP service exposure"
- severity: high
- category: misconfig
- status: validated
- evidence_ids: [E-001]
- location: 10.10.10.5:80
- impact: Allows attackers to enumerate web resources
- confidence: high
- repro_steps:
  1. Run the nmap command from E-001
  2. Browse to http://10.10.10.5
- remediation: Restrict access to the HTTP service via firewall rules
- optional_attack: T1046

```

### Path: Attack and Analysis Flows

**Path** weaves Evidence and Finding items into coherent narratives—attack chains, call flows, or solution sequences. Defined in `P-{nnn}.md` with three supported `path_type` values: **attack**, **callflow**, or **solve**.

Required fields:

- `title`, `path_type`, `start`, `goal`
- `steps` – Array of actions with optional Evidence/Finding citations
- `residual_risks` – Optional remaining concerns

Step syntax enables bidirectional traceability:

```markdown

### P-001

- title: "Web Exposure Attack Path"
- path_type: attack
- start: External Network
- goal: Gain foothold on target host
- steps:
  1. action: "Port scan" — evidence: E-001 — finding: F-001 | none
  2. action: "Exploit unauthenticated HTTP endpoint" — evidence: none — finding: none | none

```

Mandatory linking rule: if the final step claims privilege acquisition or data exfiltration, the corresponding Finding must be backed by **validated** Evidence.

## Report Generation Integration

The **docs-generator** automatically folds all three artefacts into the final security report. The template at [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) enforces mandatory sections:

| Section | Requirement |
|---------|-------------|
| 0.1 Scope | Engagement boundaries |
| **0.2 Evidence** | All E-* files linked |
| **0.3 Findings** | All F-* entries with status |
| **0.4 Path** | At least one P-* entry |
| 0.5 Timeline | Work item integration |

This guarantees every published deliverable contains a reproducible evidence chain. Generated reports include cross-references like:

```markdown

## 0.2 Evidence

- **E-001** – Initial nmap scan of target (see `work/target1/evidence/E-001.md`)

## 0.3 Findings

- **F-001** – Unauthenticated HTTP service exposure (validated)

## 0.4 Path

- **P-001** – Web Exposure Attack Path (see `work/target1/path/P-001.md`)

```

## Supporting Governance Contracts

The methodology relies on additional contracts for accountability:

- **[`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)** and **[`skills/ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/IDENTITY.md)** – Define who may create or modify Evidence/Finding/Path entries
- **[`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md)** – Links Evidence to work items via `linked_workitem` field for full traceability
- **[`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md)** – Master contract defining all schema and validation rules

These contracts collectively enforce a **transparent, reproducible, and auditable** security investigation pipeline usable across reverse engineering, penetration testing, and CTF documentation.

## Summary

- **Evidence→Finding→Path** is a mandatory, contract-enforced methodology in reverse-skill, not an optional convention
- Evidence files (`E-*.md`) are immutable observations with cryptographic hashes and reproduction commands
- Findings (`F-*.md`) require at least one Evidence reference and enforce confidence rules for validated status
- Paths (`P-*.md`) string together steps with optional Evidence/Finding citations, supporting attack, callflow, and solve narratives
- The docs-generator report template mandates all three artefact types, ensuring reproducible security reporting

## Frequently Asked Questions

### What happens if a Finding references no Evidence?

The contract in [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) explicitly prohibits this. The `evidence_ids` field must contain at least one entry, and validation scripts will reject non-compliant Findings.

### How does reverse-skill prevent Evidence tampering after creation?

Each Evidence file includes a `content_hash` field and an `observed_at` timestamp. While the methodology assumes trusted storage, these fields enable integrity verification. The `supersedes` field allows creating new Evidence that obsoletes prior entries without deletion.

### Can Paths reference other Paths?

The current contract in [`evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) does not define Path-to-Path references. Paths reference Evidence and Finding entries directly via their step syntax, creating a two-level linkage rather than recursive nesting.

### Who is authorized to create Evidence and Findings?

The [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md) and [`skills/ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/IDENTITY.md) contracts define role-based permissions. Typically, Evidence creation is open to all operators, while Finding validation requires elevated privileges, and Path finalization may need lead investigator sign-off.