How Evidence Records Are Structured and Named in reverse-skill

In reverse-skill, every piece of raw proof is captured as an Evidence record stored as a Markdown file named E-<nnn>.md under work/<case>/evidence/, following a strict schema defined in skills/ops/evidence-finding-path.md that requires a title, source metadata, SHA-256 hash, and reproducible command.

The reverse-skill framework enforces a rigorous evidence-tracking system for security research and CTF workflows. Understanding how evidence records are structured and named ensures reproducible findings and auditable case work. This guide examines the canonical specification and file conventions implemented in the zhaoxuya520/reverse-skill repository.

File Naming Convention and Storage Location

Evidence files reside in a predictable path within case workspaces. According to the source code specification in skills/ops/evidence-finding-path.md, each evidence record follows the naming pattern:

work/<case>/evidence/E-<nnn>.md

Where <case> represents the case directory name and <nnn> is a zero-padded sequential number (e.g., E-001, E-002). This convention ensures chronological ordering and unique identification across the investigation lifecycle.

Required Fields and Markdown Structure

Every Evidence file is a standalone Markdown document that begins with a heading ### E-<nnn> followed by a structured field list. The schema mandates specific metadata fields to maintain forensic integrity.

The Complete Field Schema

Field	Description
title	Human-readable short description of the evidence.
observed_at	Timestamp (optional) when the evidence was collected.
source_type	One of command, screenshot, file, log, memory, network, manual.
source_ref	Reference to the originating command or file path.
content_hash	SHA-256 of the artifact (if a file) or n/a.
artifact_path	Relative path under the case root where the artifact lives.
repro_command	Exact command that can recreate the evidence.
raw_excerpt	Sanitized excerpt of the raw output.
linked_workitem	Optional link to a work-item (WI-<nnn>) that generated the evidence.
supersedes	Optional reference to a previous evidence record that this one replaces.

Mandatory Validation Rules

The reverse-skill specification enforces strict validation rules via the CLI tooling. Every Evidence record must contain:

• A non-empty title field
• A valid repro_command that third parties can execute (or marked as offline-only)

Additionally, every Finding must reference at least one Evidence record to maintain the audit chain.

Automating Evidence Creation with append-evidence.ps1

The repository provides a PowerShell helper script at skills/scripts/append-evidence.ps1 that automates file creation while enforcing naming conventions and required fields.

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/my-case `
  -Id E-002 -Title "Initial memory dump" -SourceType memory `
  -ReproCommand "gcore -o evidence/memdump $(pid)" -ArtifactPath "evidence/memdump.core"

This command generates work/my-case/evidence/E-002.md with properly formatted front matter and validates that mandatory fields are present.

Complete Evidence Record Example

A minimal yet valid evidence file demonstrates the expected structure. Here is an example from the CTF demo at examples/ctf-demo/evidence/E-001.md:

### E-001

- title: Checksec output for binary `pwn1`
- observed_at: 2026-08-16T14:23:00Z
- source_type: command
- source_ref: checksec pwn1
- content_hash: 9f2c3e5b7a1d4f8e9c6b2a4d5e7f1a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f
- artifact_path: evidence/checksec-output.txt
- repro_command: |
    checksec --format=brief pwn1 > evidence/checksec-output.txt
- raw_excerpt: |
    ... (sanitized excerpt of the checksec output) ...
- linked_workitem: WI-001
- supersedes: n/a

Summary

• Evidence records in reverse-skill are Markdown files stored under work/<case>/evidence/ with the naming convention E-<nnn>.md.

• Each file must begin with a heading ### E-<nnn> and contain mandatory fields including title, repro_command, and content_hash.

• The source_type field categorizes evidence as command, screenshot, file, log, memory, network, or manual.

• The skills/scripts/append-evidence.ps1 CLI helper automates creation while enforcing the schema defined in skills/ops/evidence-finding-path.md.

• Validation rules require every Finding to reference at least one Evidence record, ensuring complete audit trails.

Frequently Asked Questions

What is the required filename format for evidence records in reverse-skill?

Evidence files must follow the pattern E-<nnn>.md where <nnn> is a sequential number (e.g., E-001.md, E-002.md). These files reside in the work/<case>/evidence/ directory relative to the case workspace root.

Which fields are mandatory when creating an Evidence record?

Every Evidence record must include a non-empty title and a valid repro_command that third parties can execute. While other fields like observed_at and linked_workitem are optional, the schema requires source_type, source_ref, content_hash, and artifact_path for complete traceability.

How does reverse-skill validate evidence file integrity?

The framework validates that content_hash contains a SHA-256 checksum for file artifacts (or n/a for non-file sources) and verifies that repro_command contains runnable instructions. The append-evidence.ps1 script enforces these constraints during file creation.

Can an evidence record replace or update a previous entry?

Yes, use the supersedes field to reference a previous Evidence record (e.g., supersedes: E-001). This maintains version history while allowing investigators to update or correct evidence without losing the audit trail.

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