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

> Discover how reverse-skill structures findings using the Evidence-Finding-Path framework. Link immutable observations to security conclusions with an auditable chain.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-31

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`:

```markdown

### 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/evidence-finding-path.md) | Core contract: Evidence, Finding, and Path schema definitions |
| [`skills/docs-generator/references/security-report-templates.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/references/security-report-templates.md) | Report format requiring embedded Findings with evidence links |
| [`skills/ops/analysis-decision-framework.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/analysis-decision-framework.md) | Evidence sufficiency rules for Finding promotion |
| [`skills/ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/timeline-workitem.md) | Workflow tracking Finding creation and status transitions |
| [`skills/ops/case-review/scripts/review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/evidence-finding-path.md) line 62.
- **Schema validation** in [`review_case.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/review_case.py) validation script will reject the case. The contract at [`skills/ops/evidence-finding-path.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.