Understanding the Evidence → Finding → Path Chain in reverse-skill

The Evidence → Finding → Path chain is the mandatory three-stage data model in the reverse-skill repository that structures every security and reverse-engineering workflow into immutable observations, validated conclusions, and actionable sequences.

This architectural pattern enforces reproducibility and auditability across forensic investigations, penetration tests, and CTF challenges. According to the zhaoxuya520/reverse-skill source code, the chain lives in skills/ops/evidence-finding-path.md and requires analysts to progress through three distinct layers before generating final reports.

The Three-Stage Data Model

The reverse-skill framework divides every investigation into three immutable asset types stored as markdown files in work/<case>/.

Evidence: Immutable Observations

Evidence represents raw, tamper-evident records of what was observed. Stored as E-{nnn}.md files under work/<case>/evidence/, each evidence asset must include mandatory fields that guarantee immutability and reproducibility.

Key fields include:

• content_hash – Cryptographic hash ensuring integrity
• observed_at – ISO 8601 timestamp
• source_ref – Pointer to original log or artifact
• repro_command – Exact command to regenerate the observation

As specified in skills/ops/evidence-finding-path.md, evidence files are append-only. The supersedes field allows chaining corrections without invalidating previous hashes.

Finding: Analyst Conclusions

Finding assets (F-{nnn}.md) represent analyst-level interpretations derived from one or more evidence files. Each finding must reference at least one evidence ID via the evidence_ids array.

Critical validation rules enforced by the framework:

• status=validated requires confidence ≠ low unless residual_risks is explicitly documented
• Must specify severity (low/medium/high/critical) and category (vuln/malware/config)
• location and impact fields provide spatial and business context

The finding layer acts as the interpretation boundary between raw data and human analysis.

Path: Actionable Sequences

Path assets (P-{nnn}.md) connect findings into ordered sequences that achieve higher-level goals. The path_type field adapts to domain requirements (attack, callflow, or solve).

Each step in the steps array must reference:

• evidence – The supporting observation
• finding – The derived conclusion
• action – The narrative or operational instruction

Paths enable attack chain reconstruction, call-flow documentation, and CTF solve walkthroughs while maintaining full traceability back to original evidence.

Architectural Flow

The reverse-skill implementation enforces a five-phase workflow:

1. Evidence Creation – Analysts or automated scripts write E-{nnn}.md files using CLI helpers like skills/scripts/append-evidence.ps1. This guarantees immutability through hashes and timestamps.

2. Finding Composition – Validation logic in skills/case-review/scripts/review_case.py ensures every finding references sufficient evidence before status can transition to validated.

3. Path Assembly – P-{nnn}.md files string together steps, with the docs-generator module consuming these assets to produce final reports.

4. Verification & Reporting – The generator mandates inclusion of Scope summaries, Evidence tables, Findings lists, and at least one Path, as defined in skills/docs-generator/references/security-report-templates.md.

5. Auditability – The read-only case-review script verifies hash integrity and cross-references work items, enforcing that no finding exists without supporting evidence.

Implementation Details and File Structure

The reverse-skill repository organizes validation logic and templates across four key locations:

File	Purpose
skills/ops/evidence-finding-path.md	Authoritative schema specification for all three stages
skills/docs-generator/references/security-report-templates.md	Report templates enforcing chain inclusion
skills/case-review/scripts/review_case.py	Python validation engine for hash verification and sufficiency checks
skills/scripts/append-evidence.ps1	PowerShell CLI for creating Evidence markdown files

The naming convention (E-, F-, P- prefixes with zero-padded numeric identifiers) ensures lexical sorting and unambiguous referencing across the evidence chain.

Practical Code Examples

The following markdown snippets demonstrate the exact schema required for each stage. These can be generated automatically using the CLI helpers or written manually.

Evidence File Example (E-001.md)

### E-001

- title: Suspicious PowerShell command execution
- observed_at: 2026-08-24T14:32:00Z
- source_type: command
- source_ref: work/sample/commands.log
- content_hash: 3a7bd3e5f9c2c0e8b9d9a6c4a1b1e2f3d4c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9
- artifact_path: work/sample/powershell-output.txt
- repro_command: |
    powershell -NoProfile -ExecutionPolicy Bypass -File script.ps1
- raw_excerpt: |
    Get-Process | Where-Object {$_.CPU -gt 1000}
- linked_workitem: WI-001
- supersedes: none

Finding File Example (F-001.md)

### F-001

- title: High‑CPU PowerShell process indicates possible crypto‑miner
- severity: high
- category: vuln
- status: validated
- evidence_ids: [E-001]
- location: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
- impact: Unauthorized CPU consumption and potential data exfiltration
- confidence: high
- repro_steps:
  1. Run the command recorded in E-001
  2. Observe CPU usage spike
- remediation: Investigate scheduled tasks and disable the suspicious script
- optional_attack: T1496

Path File Example (P-001.md)

### P-001

- title: Crypto‑miner deployment chain
- path_type: attack
- start: Initial user login
- goal: Persistent cryptomining on the host
- steps:
  1. action: Execute PowerShell → evidence: E-001 → finding: F-001
  2. action: Deploy miner binary → evidence: E-005 → finding: F-003
  3. action: Establish persistence → evidence: E-009 → finding: F-007
- residual_risks: None

Create these assets programmatically using:

powershell -File skills/scripts/append-evidence.ps1 `
  -CaseRoot work/<case> `
  -Id E-001 `
  -Title "Suspicious PowerShell command execution" `
  -ReproCommand "powershell -NoProfile..." `
  -Severity high `
  -Status observed

Validation and Auditability

The skills/case-review/scripts/review_case.py script implements read-only audit logic that enforces the Evidence → Finding → Path contract. It performs three critical checks:

• Hash Integrity – Verifies content_hash values against current file contents
• Reference Validation – Ensures every evidence_ids entry points to an existing E- file
• Sufficiency Rules – Confirms high-severity findings do not rely solely on low-confidence evidence without documented residual risks

This validation layer prevents "silent" validation states where findings appear authoritative without proper evidentiary backing.

Summary

• The Evidence → Finding → Path chain structures all reverse-skill investigations into three immutable, linked asset types.
• Evidence (E-*.md) provides tamper-evident raw observations with mandatory hashes and reproduction commands.
• Findings (F-*.md) require at least one evidence reference and enforce confidence thresholds via review_case.py.
• Paths (P-*.md) sequence findings into attack chains, call flows, or CTF solutions while maintaining full traceability.
• The docs-generator module mandates inclusion of all three stages in final security reports.
• CLI helpers in skills/scripts/ and validation logic in skills/case-review/ automate creation and verification of the chain.

Frequently Asked Questions

What happens if a Finding references Evidence that has been superseded?

The supersedes field in Evidence files creates a forward chain without invalidating historical hashes. When review_case.py audits a case, it checks the supersedes lineage to ensure analysts review the correct evidence version. Findings should reference the most current non-superseded evidence ID unless documenting historical context.

How does reverse-skill enforce the Evidence → Finding → Path relationship?

Validation occurs at two levels. First, the markdown schema in skills/ops/evidence-finding-path.md defines mandatory fields. Second, skills/case-review/scripts/review_case.py performs runtime verification, checking that every evidence_ids array contains valid references and that high-severity findings possess sufficient evidentiary support before status can be set to validated.

Can Path files reference multiple Findings from the same Evidence?

Yes. The steps array in Path files supports many-to-many relationships. A single piece of evidence can support multiple findings (e.g., one log entry revealing both vulnerability and misconfiguration), and a single path can weave together findings derived from overlapping evidence sets. Each step explicitly links one evidence ID to one finding ID.

What is the difference between path_type attack and callflow?

The path_type field adapts the chain to domain-specific narratives. attack chains map adversary TTPs (Tactics, Techniques, and Procedures) for penetration testing reports. callflow documents reverse-engineered function call sequences. solve paths structure CTF write-ups. The docs-generator module applies different templates based on this type while maintaining the underlying Evidence → Finding → Path structure.

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