Evidence→Finding→Path Workflow in reverse-skill: A Complete Technical Guide

The Evidence→Finding→Path workflow creates an immutable audit chain that links raw security artifacts to analytic conclusions and structured attack narratives through Markdown contracts and automated verification scripts.

The zhaoxuya520/reverse-skill repository enforces a rigorous, data-driven security analysis pipeline. This workflow guarantees that every analytic conclusion traces back to concrete, reproducible evidence via standardized Markdown contracts defined in skills/ops/evidence-finding-path.md and companion helper scripts.

Core Concepts and Contracts

The workflow rests on three immutable concepts defined in the master contract at skills/ops/evidence-finding-path.md:

• Evidence – Immutable observations of concrete artifacts stored as E-*.md files (lines 6-24). Captures command output, file hashes, screenshots, or memory dumps with strict field validation.

• Finding – Analytic conclusions derived from one or more Evidence items, stored as F-*.md files (lines 43-61). Requires a non-empty evidence_ids list (lines 51-52) and tracks status and confidence levels.

• Path – Ordered representation connecting Evidence and Findings into attack chains, call-flows, or CTF solve sequences, stored as P-*.md files (lines 64-84). Each step optionally cites specific Evidence and Finding IDs (lines 75-84).

Step 1: Record Immutable Evidence

Evidence files live under work/<case>/evidence/ and follow strict field contracts enforced by helper scripts.

The append-evidence.ps1 CLI creates new evidence records with required fields including title, source, SHA-256 hash, and reproduction command (lines 28-34 of the contract).

# Create a new evidence record with artifact verification

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/MyCase `
  -Id E-001 -Title "Enumerated local users" `
  -ReproCommand "net user" -Severity info -Status observed

If the evidence includes a file artifact, the -ArtifactPath parameter records a SHA-256 hash, guaranteeing fixity and tamper detection.

Step 2: Create Findings that Reference Evidence

Findings are stored as F-*.md files under work/<case>/findings/. The contract mandates that every Finding include a non-empty evidence_ids list linking back to specific Evidence records.

### F-001

- title: "Local privilege escalation via unquoted service path"
- severity: high
- category: vuln
- status: validated
- evidence_ids: [E-001, E-005]
- location: "C:\\Windows\\System32\\svc.exe:0x400"
- confidence: high
- remediation: "Quote the service executable path"

consolidate_evidence.py (and its PowerShell equivalent consolidate-evidence.ps1) automate the creation of Findings by merging multiple Evidence items. This ensures complex vulnerabilities spanning several observations maintain traceability to every supporting artifact.

Step 3: Assemble a Path Connecting Evidence to Findings

Paths live in work/<case>/paths/P-*.md and define the narrative flow from initial observation to final impact. The path_type field adapts the same contract for reverse-engineering call-flows or CTF solve sequences.

Each step in a Path optionally cites both an Evidence ID and a Finding ID, creating a complete traceability chain:

### P-001

- title: "Privilege escalation chain"
- path_type: attack
- start: "Initial low-priv user"
- goal: "Administrator"
- steps:
  1. action: "Enumerate services" — evidence: E-001 — finding: F-001
  2. action: "Exploit unquoted path" — evidence: E-005 — finding: F-002
- residual_risks: "If service binary is signed, exploit may fail"

Step 4: Verify Chain Integrity and Export

review_case.py performs automated contract verification, ensuring all referenced fields exist, cryptographic hashes match, and status transitions follow valid rules.

# Strict verification including hash validation

python3 skills/case-review/scripts/review_case.py work/MyCase \
  --verify-hashes --strict

The script aborts execution on missing evidence, duplicate IDs, or invalid status transitions. Additional assertions run via verify-routing-coherence.ps1.

Once verified, the docs-generator consumes the complete chain from security-report-templates.md to inject Evidence, Finding, and Path sections into the final security report.

Practical Implementation Examples

Appending Evidence with Command Output

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/Case42 `
  -Id E-010 -Title "Local user enumeration" `
  -SourceType command -SourceRef "net user" `
  -ReproCommand "net user" -Severity info -Status observed

Consolidating Evidence into a Finding (Python)

python3 skills/scripts/consolidate_evidence.py \
  --case-root work/Case42 \
  --evidence-ids "E-010,E-011" \
  --finding-id F-005 \
  --title "User enumeration leads to privilege escalation" \
  --severity high --status validated

Creating a Path with Traceable Steps

### P-007

- title: "Credential dump via LSASS"
- path_type: attack
- start: "Low-priv user"
- goal: "Domain admin"
- steps:
  1. action: "Dump LSASS memory" — evidence: E-020 — finding: F-012
  2. action: "Extract NTLM hashes" — evidence: E-021 — finding: F-013
- residual_risks: "Requires admin rights on host"

Final Verification

python3 skills/case-review/scripts/review_case.py work/Case42 \
  --verify-hashes --strict

Summary

• Evidence→Finding→Path creates an immutable audit trail from raw data to final report through Markdown contracts in skills/ops/evidence-finding-path.md.
• Evidence files (E-*.md) capture artifacts with cryptographic hashes and reproduction commands via append-evidence.ps1.
• Findings (F-*.md) must reference specific Evidence IDs, enforced by consolidate_evidence.py and contract lines 51-52.
• Paths (P-*.md) link Evidence and Findings into ordered narratives using the path_type field for flexible interpretation.
• Verification via review_case.py guarantees hash fixity, field completeness, and valid status transitions before report generation.
• Export through docs-generator transforms the verified chain into final security reports using security-report-templates.md.

Frequently Asked Questions

What makes Evidence "immutable" in reverse-skill?

Evidence immutability is enforced through cryptographic hashing and filesystem conventions. When creating evidence via append-evidence.ps1, the -ArtifactPath parameter calculates and stores a SHA-256 hash of the file. The contract at skills/ops/evidence-finding-path.md (lines 28-34) mandates these hash fields, and review_case.py verifies them during validation. Any tampering with evidence files breaks the hash verification, causing the audit chain to fail validation.

How does a Finding link back to specific Evidence?

Every Finding file (F-*.md) must contain a non-empty evidence_ids list as mandated by the contract at lines 51-52 of skills/ops/evidence-finding-path.md. This YAML field accepts an array of Evidence IDs (e.g., [E-001, E-005]). The consolidate_evidence.py script automates this linking by mapping multiple Evidence records to a single Finding ID, ensuring traceability is maintained programmatically rather than manually.

What is the difference between path_type options in a Path file?

The path_type field in Path files (P-*.md) determines how the steps are interpreted while maintaining the same underlying contract structure. According to lines 64-84 of the evidence-finding-path contract, valid types include attack (for security breach narratives), call-flow (for reverse-engineering function traces), or CTF solve sequences. The field adapts the presentation without changing the required Evidence→Finding citation structure in each step.

Why does the workflow require both Python and PowerShell scripts?

The repository provides language-agnostic tooling to accommodate different operational environments. PowerShell scripts (append-evidence.ps1, consolidate-evidence.ps1) integrate natively with Windows security tooling and Active Directory environments. Python scripts (consolidate_evidence.py, review_case.py) offer cross-platform compatibility and advanced cryptographic verification. Both implementations enforce identical contracts defined in skills/ops/evidence-finding-path.md, ensuring consistency regardless of the execution environment.

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