How Findings Are Structured in reverse-skill Using the Evidence-Finding-Path Framework

Findings in reverse-skill must reference at least one Evidence record through the evidence_ids field, creating a mandatory, auditable chain from immutable observations to security conclusions.

The reverse-skill project, created by zhaoxuya520, implements a rigorous three-layer framework that structures every security and reverse-engineering deliverable. At the center of this architecture sits the Finding—a documented conclusion that derives directly from Evidence and optionally feeds into Path records that describe attack flows or exploit chains.

Evidence-Finding-Path Architecture

The framework organizes security work into three distinct layers. Each layer has a specific contract defined in skills/ops/evidence-finding-path.md.

Layer	Description	Storage Pattern
Evidence	Immutable observations including commands, screenshots, logs, and file hashes. Stored as E-* markdown files.	work/<case>/evidence/E-*.md
Finding	The security conclusion derived from Evidence, with mandatory traceability links. Stored as F-{nnn} entries.	work/<case>/findings/F-*.md
Path	Logical flows connecting multiple Findings, such as exploit chains or CTF solve sequences. Stored as P-{nnn} entries.	Case report or dedicated path files

As specified in skills/ops/evidence-finding-path.md (lines 10-24, 45-60, and 64-82), this structure ensures every security claim can be reproduced and audited.

Finding Contract Structure

A compliant Finding follows a strict markdown format with eleven required fields. The contract in skills/ops/evidence-finding-path.md (lines 45-60) defines the following schema:

Field	Purpose	Constraint
title	Human-readable name of the vulnerability or insight	Required
severity	Risk level: critical, high, medium, low, info, n/a_re	Required
category	Classification: vuln, misconfig, design, reverse_algo, bypass, other	Required
status	Lifecycle: candidate, validated, false_positive, accepted_risk	Required
evidence_ids	List of E- identifiers proving the Finding	Must be non-empty (line 62)
location	Observation point: file:line, address, URL, class.method	Required
impact	Narrative description of potential effect	Required
confidence	Assurance level: high, medium, low	low disallowed for validated findings (lines 62-63)
repro_steps	Step-by-step reproduction instructions	Required
remediation	Recommended fix or n/a for pure reverse-engineering	Required
optional_attack	MITRE ATT&CK ID or empty	Required field, optional value

The mandatory non-empty evidence_ids rule (line 62) enforces traceability at the schema level. The validation rule preventing confidence: low for validated findings (lines 62-63) ensures quality gates are met before promotion.

Evidence-to-Finding Linkage Mechanism

Each Finding establishes bidirectional traceability through its evidence_ids list. The corresponding Evidence records provide:

• repro_command: The exact command or action that produced the observation
• artifact_path: Location of supporting files
• content_hash: Cryptographic hash ensuring artifact integrity

The review_case.py script (referenced at lines 37-39 of the case review workflow) performs automated validation:

1. Verifies all evidence_ids exist in the case directory
2. Confirms artifact hashes match recorded values
3. Validates status and confidence compliance with the contract

This cross-checking guarantees that no Finding can exist without verifiable, immutable backing data.

Finding Example: Complete Implementation

Below is a production-ready Finding definition that satisfies all contract requirements. This file would reside at work/<case>/findings/F-001.md:

### F-001

- title: Remote Code Execution via insecure deserialization
- severity: critical
- category: vuln
- status: validated
- evidence_ids: [E-012, E-018]
- location: src/main/java/com/example/Deserializer.java:45
- impact: attacker can execute arbitrary code on the target host
- confidence: high
- repro_steps:
  1. Run the vulnerable service with the crafted payload.
  2. Observe the spawned `/bin/sh` process on the target.
- remediation: Apply input validation and use a safe deserialization library.
- optional_attack: T1203

The referenced Evidence entries E-012 and E-018 would each contain:

• The payload generation command
• Network capture or process listing artifacts
• SHA-256 hashes of the malicious serialized objects

This pairing creates a complete, reproducible evidence chain from observation to conclusion.

Integration with Report Generation

Security reports generated through docs-generator must embed the Findings section with full evidence linkage. According to security-report-templates.md (lines 21-23), every F- entry must display its linked evidence_ids, ensuring the final deliverable preserves the traceability chain.

The template mandates that reviewers and stakeholders can navigate directly from any Finding to its supporting Evidence without external documentation.

Framework Governance Files

The following source files define, enforce, and validate Finding structure in reverse-skill:

File Path	Responsibility
skills/ops/evidence-finding-path.md	Core contract: Evidence, Finding, and Path schema definitions
skills/docs-generator/references/security-report-templates.md	Report format requiring embedded Findings with evidence links
skills/ops/analysis-decision-framework.md	Evidence sufficiency rules for Finding promotion
skills/ops/timeline-workitem.md	Workflow tracking Finding creation and status transitions
skills/ops/case-review/scripts/review_case.py	Automated chain validation before case hand-off

Summary

• Findings require at least one Evidence reference through the mandatory evidence_ids field, enforced by contract at evidence-finding-path.md line 62.
• Schema validation in review_case.py cross-checks evidence existence, artifact hashes, and compliance rules.
• Status-gated confidence levels prevent validated findings from carrying low confidence without explicit residual-risk documentation.
• Report templates mandate evidence linkage visibility in all generated security deliverables.
• Immutable Evidence with content hashing ensures findings remain auditable and reproducible throughout the case lifecycle.

Frequently Asked Questions

What happens if a Finding has no evidence_ids?

The review_case.py validation script will reject the case. The contract at skills/ops/evidence-finding-path.md line 62 explicitly requires evidence_ids to be non-empty, making this a blocking error that prevents report generation.

Can a Finding reference Evidence from another case?

No. The review_case.py cross-checker only validates evidence_ids against the current case's work/<case>/evidence/ directory. Cross-case evidence linkage would break isolation and traceability guarantees.

What is the difference between candidate and validated Finding status?

candidate indicates preliminary analysis requiring further verification. validated means the Finding has passed quality gates including evidence sufficiency review and cannot have confidence: low per lines 62-63 of the evidence-finding-path contract. Promotion between states is tracked via timeline-workitem.md.

How does the framework handle false positives?

Findings with status: false_positive remain in the case record with their original evidence_ids preserved. This maintains audit history and prevents re-analysis of the same evidence, while clearly flagging the conclusion as rejected.

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