How the Evidence-Finding Path Establishes the Evidence Chain in reverse‑skill

The evidence-finding path enforces a strict Evidence → Finding → Path workflow that guarantees every investigative step is traceable, verifiable, and reproducible through SHA‑256 hashing and mandatory contract enforcement.

The evidence-finding path is a core architectural pattern in the zhaoxuya520/reverse-skill repository that transforms raw security artefacts into a tamper-evident audit trail. Defined primarily in skills/ops/evidence-finding-path.md, this workflow ensures that every analysis action—from initial data collection to final reporting—maintains an unbroken chain of custody.

The Evidence Chain Architecture

The framework implements a five-step evidence chain that links raw data to analytical conclusions through cryptographic verification and structured documentation.

Step 1: Evidence Collection with Cryptographic Binding

Raw artefacts (logs, memory dumps, screenshots) are gathered into the case's evidence/ directory. Each piece receives a unique identifier and a SHA‑256 content hash stored in the content_hash field.

This requirement is baked into the contract: no evidence entry is valid without its hash computed at ingestion time.

Step 2: Finding Identification and Hash Linkage

Analysts examine evidence and produce findings—concise markdown statements of what the artefact reveals. Each finding file (e.g., F-001.md) explicitly references its source evidence through the original content_hash.

This bidirectional linkage ensures findings remain tethered to their source material regardless of file moves or renames.

Step 3: Path Construction for Attack Progression

Findings accumulate into a logical path that reconstructs attack progression, compliance gaps, or remediation sequences. The path file aggregates all hashes and findings into a traversable narrative.

The operational command evidence-finding-path + review_case --verify-hashes recomputes stored hashes to detect any evidence tampering before path finalization.

Step 4: Verification and Timeline Append

Before case closure, rules R5 and R20‑R21 in skills/ops/analysis-decision-framework.md mandate:

• Hash re-verification against source files
• Automated append-evidence action to the case work-items timeline

These rules trigger at analysis-decision-framework.md lines 100 and 129, creating a governance checkpoint that prevents incomplete or unverified chains from entering the permanent record.

Step 5: Report Integration for Audit Visibility

Finalized paths feed directly into security reports. The templates in skills/docs-generator/references/security-report-templates.md (line 9) require an Evidence→Finding→Path section, making the chain visible to external auditors.

Contract Enforcement Mechanisms

The evidence chain operates through three layers of enforcement:

Layer	Implementation	Key File
Contract definition	Data schema, naming conventions, hash algorithms	skills/ops/evidence-finding-path.md
Rule enforcement	Mandatory invocation for every ACT operation	RULES.md (line 21)
Operational integration	Automatic evidence recording in skill definitions	Individual SKILL.md files

As stated in README_AI.md (line 42), the evidence chain is a core pre-condition for all AI-assisted operations in the framework.

Practical Implementation: YAML Skill Definition

The following snippet from a domain SKILL.md demonstrates how the path is referenced operationally:

ACT:
  - description: "Run privilege escalation check"
    command: "./check_privesc.sh"
    evidence: "evidence/E-001.md"          # raw command output

    finding:  "F-001.md"                   # analyst interpretation

    path:    "ops/evidence-finding-path.md" # hash verification contract

The path field ensures that evidence-finding-path.md validates the hash linkage before the action completes.

Hash Verification: Bash Helper

This utility script verifies chain integrity after findings are added:

verify_evidence_chain () {
  local evidence_file=$1
  local hash=$(sha256sum "$evidence_file" | cut -d' ' -f1)
  grep -q "$hash" ops/evidence-finding-path.md && echo "✅ Hash verified"
}

# Usage

verify_evidence_chain evidence/E-001.md

The script extracts the SHA‑256 hash and confirms its presence in the central path registry, catching any file corruption or substitution.

Timeline Append: PowerShell Automation

For Windows environments, this script appends new evidence entries with computed hashes:

$evidence = Get-Content -Raw -Path "evidence/E-002.md"
$hash = (Get-FileHash -Path "evidence/E-002.md" -Algorithm SHA256).Hash
Add-Content -Path "ops/evidence-finding-path.md" -Value "`n$hash :: $evidence"

The Get-FileHash cmdlet guarantees algorithmic consistency with Unix-based operations, ensuring cross-platform chain validity.

Source File Reference Map

All evidence chain behavior is codified in these repository locations:

• skills/ops/evidence-finding-path.md — primary contract defining the Evidence→Finding→Path workflow
• RULES.md — mandates evidence chain usage for every ACT step
• README_AI.md — establishes the chain as a core operational pre-condition
• skills/ops/analysis-decision-framework.md — specifies verification (R5) and append (R20-R21) rules
• skills/docs-generator/references/security-report-templates.md — requires Evidence→Finding→Path sections in generated reports
• skills/ops/README.md — module overview and operational guidelines

Summary

• The evidence-finding path creates an immutable audit trail through mandatory SHA‑256 hashing of all artefacts
• Five sequential steps—collection, finding, path construction, verification, and reporting—ensure traceability from raw data to final conclusion
• Rules R5 and R20-R21 in analysis-decision-framework.md enforce verification gates before case closure
• The architecture is cross-platform with reference implementations in Bash and PowerShell
• All ACT operations must declare their evidence, finding, and path fields per RULES.md line 21

Frequently Asked Questions

What makes the evidence chain tamper-evident?

The SHA‑256 content_hash stored at ingestion time is recomputed during verification. Any modification to evidence files—accidental or malicious—produces a hash mismatch that evidence-finding-path.md detects during the --verify-hashes operation.

Can the evidence chain work without automated tools?

Yes. While scripts automate hash computation, the contract only requires that hashes be present and verifiable. Manual workflows using standard sha256sum or Get-FileHash commands satisfy the requirement equally.

How does the framework prevent missing evidence links?

RULES.md explicitly prohibits ACT operations without declared evidence, finding, and path fields. The parser rejects skill definitions lacking these mandatory components, enforcing structural compliance at definition time rather than runtime.

Where is the evidence chain documented for auditors?

Generated reports automatically include the Evidence→Finding→Path section per security-report-templates.md. This section presents the complete hash-linked narrative in auditor-friendly format without requiring repository access.

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