Evidence Chain Management Specification in the reverse-skill Repository: A Complete Guide to `evidence-finding-path.md`

The evidence-finding-path.md specification defines a markdown-driven workflow connecting raw observations (Evidence) to analyst conclusions (Finding) and reproducible narratives (Path), with mandatory cross-references and validation rules.

The reverse-skill repository provides a rigorous framework for security and reverse-engineering workflows. The evidence-finding-path.md document at skills/ops/evidence-finding-path.md codifies how analysts build evidence chains that are auditable, reproducible, and ready for report generation. This guide covers the specification's core concepts, validation rules, and practical implementation.

Core Components of the Evidence Chain

The specification defines three interconnected components. Each serves a distinct purpose in the analysis workflow.

Evidence: Immutable Observations

Evidence records capture raw artefacts from the investigation. These are immutable facts—command outputs, screenshots, file hashes, logs, or memory dumps.

Mandatory fields include:

• title — human-readable description
• observed_at — timestamp of observation
• source_type — category (screenshot, file, log, command_output, etc.)
• source_ref — pointer to original source
• content_hash — cryptographic hash for integrity
• artifact_path — filesystem location
• repro_command — command to regenerate or view
• raw_excerpt — short sample or preview
• linked_workitem — connection to case tracker
• supersedes — optional reference to prior Evidence this replaces

Finding: Analyst Conclusions

Finding documents represent security or reverse-engineering conclusions derived from Evidence. Every Finding must reference at least one Evidence item.

Mandatory fields include:

• title — finding description
• severity — risk level (info, low, medium, high, critical)
• category — classification (vuln, misconfig, malware, etc.)
• status — discovery state (tentative, confirmed, validated, false_positive)
• evidence_ids — array with ≥1 Evidence references
• location — where the issue exists
• impact — consequence description
• confidence — certainty level
• repro_steps — numbered reproduction procedure
• remediation — fix or mitigation
• optional_attack — MITRE ATT&CK technique ID

Path: Structured Narratives

Path documents describe sequences that connect Evidence to Findings. Paths may represent attack flows, call chains, or solution steps.

Key fields:

• title — path name
• path_type — attack, defense, or analysis
• start — initial state
• goal — end state
• steps — ordered actions, each optionally referencing Evidence and/or Finding
• residual_risks — remaining concerns

Global Validation Rules in evidence-finding-path.md

The specification enforces strict rules for evidence chain integrity. The review_case.py validation tool implements these checks.

Mandatory Requirements

• Every Finding must reference ≥1 Evidence — no ungrounded conclusions permitted
• Paths ending with "privilege/data obtained" findings must use validated Evidence — critical findings require verified backing

Recommended Standards

• Findings promoted to validated should have ≥2 independent Evidence items — for example, one static file hash plus one dynamic command output
• Single Evidence alone may not silently promote a Finding to validated — explicit analyst judgment required

These rules appear in the Validated sufficiency section of skills/ops/evidence-finding-path.md.

Practical Implementation: Creating Evidence Chains

The repository provides CLI helpers and Python validation tools. Below are complete examples from the specification.

Step 1: Create Evidence with PowerShell

The append-evidence.ps1 script generates properly formatted Evidence markdown files under work/<case>/evidence/.

# Record a screenshot with hash verification

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work/Case001 `
    -Id E-001 `
    -Title "Admin console screenshot" `
    -SourceType screenshot `
    -SourceRef "screenshots/admin_console.png" `
    -ArtifactPath "screenshots/admin_console.png" `
    -ReproCommand "display screenshots/admin_console.png" `
    -Severity info `
    -Status observed

This creates work/Case001/evidence/E-001.md with all required fields populated.

Step 2: Author a Finding That References Evidence

Findings are markdown files in work/<case>/findings/. The evidence_ids field creates the chain link.

### F-001

- title: "Local admin privilege escalation via CVE-2023-XXXX"
- severity: critical
- category: vuln
- status: validated
- evidence_ids: [E-001, E-002]
- location: C:\Windows\System32\exploit.exe
- impact: Full system compromise
- confidence: high
- repro_steps:
  1. Run `exploit.exe /run`
  2. Observe elevated token
- remediation: Apply patch KB123456
- optional_attack: T1068

Note the array evidence_ids with two independent items—satisfying the validated standard.

Step 3: Compose the Attack Path

Paths reside in work/<case>/paths/. Each step explicitly links Evidence and Finding.

### P-001

- title: "Privilege escalation path"
- path_type: attack
- start: "User with limited rights"
- goal: "Obtain SYSTEM token"
- steps:
  1. action: "Execute exploit" — evidence: E-001 — finding: F-001
  2. action: "Verify token" — evidence: E-002 — finding: F-001
- residual_risks: "Exploit may be detected by AV"

The step syntax uses inline references (evidence: E-001 — finding: F-001) to maintain explicit traceability.

Step 4: Validate the Complete Chain

The review_case.py script enforces all specification rules.

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

Validation includes:

• Hash integrity verification against stored content_hash values
• Cross-reference checking (all evidence_ids must exist)
• Rule enforcement (Finding coverage, validated sufficiency)
• Path completeness (steps reference valid Evidence/Findings)

Integration with Report Generation and Publishing

The evidence chain feeds multiple downstream systems.

Security Report Templates

The docs-generator uses docs-generator/references/security-report-templates.md to embed evidence chains in final reports. The template renders:

• Tables of all Evidence with hashes and reproduction commands
• Lists of Findings with linked Evidence IDs
• At least one complete Path as a flow diagram or step sequence

Field-Journal Hook

When publishing to the public field-journal, the system automatically extracts:

• Up to three key Evidence IDs
• One core Finding
• A concise Path sentence

This de-identification ensures public artifacts remain useful without exposing sensitive case details.

Key Files in the reverse-skill Evidence Chain System

File	Purpose
skills/ops/evidence-finding-path.md	Master specification defining Evidence, Finding, and Path contracts
docs-generator/references/security-report-templates.md	Report template with Evidence Chain section
skills/scripts/append-evidence.ps1	CLI helper for Evidence creation
skills/case-review/scripts/review_case.py	Validation engine for integrity and rule enforcement

Summary

• The evidence-finding-path.md specification (skills/ops/evidence-finding-path.md) defines a complete markdown workflow for evidence chain management in reverse-skill
• Three core components — Evidence (immutable observations), Finding (analyst conclusions), and Path (structured narratives) — form the chain
• Mandatory rules require every Finding to reference ≥1 Evidence; validated Findings should have ≥2 independent Evidence items
• CLI tools (append-evidence.ps1, review_case.py) automate creation and validation
• Downstream integration feeds security reports and de-identified field journals

Frequently Asked Questions

What is the minimum Evidence required for a Finding?

Every Finding must reference at least one Evidence item in its evidence_ids array. The review_case.py validator rejects Findings with empty or missing evidence references.

Can a Finding with one Evidence be marked validated?

Technically possible but discouraged. The specification states that promoting a Finding to validated status should accompany ≥2 independent Evidence items (e.g., static hash plus dynamic output). Single-Elevation validation requires explicit analyst override.

How does the evidence chain support audit requirements?

Each Evidence carries content_hash and repro_command for integrity verification. The review_case.py --verify-hashes flag cryptographically validates all artefacts. The complete chain — Evidence IDs, Finding references, and Path steps — creates fully traceable analysis lineage.

What happens when Evidence is updated?

Use the supersedes field in new Evidence to reference prior versions. This preserves immutable history while indicating obsolescence. The validator warns on Findings referencing superseded Evidence.

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