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

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:

• 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 -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 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:

### 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:

### 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 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:

## 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 and skills/ops/IDENTITY.md – Define who may create or modify Evidence/Finding/Path entries
• skills/ops/timeline-workitem.md – Links Evidence to work items via linked_workitem field for full traceability
• 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 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 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 and 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.

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