Evidence Record E-{nnn} in reverse-skill: Complete Field Reference and Usage Guide

An Evidence record (E-{nnn}) in reverse-skill is an immutable markdown file that captures a single security observation using 10+ structured fields, including ISO-8601 timestamps, SHA-256 content hashes, source classifications, and reproducible command blocks.

Evidence records form the foundational audit trail in the zhaoxuya520/reverse-skill framework for security research, reverse engineering, and CTF workflows. Each record follows a strict field contract defined in skills/ops/evidence-finding-path.md, ensuring that every observation remains immutable, attributable, and reproducible. The framework requires that every Finding reference at least one Evidence record, with validated Findings requiring multiple independent evidences.

Required and Conditional Fields

According to the contract in skills/ops/evidence-finding-path.md, every Evidence record must include seven core fields that establish identity, timing, and reproducibility:

• title: A concise, human-readable name for the observation (e.g., "pwn1 ELF triage (checksec)")
• observed_at: ISO-8601 timestamp marking when the observation occurred
• source_type: Classification of the evidence origin using one of command, screenshot, file, log, memory, network, or manual
• source_ref: Specific identifier or path referencing the source (command ID, file path, or arbitrary identifier)
• content_hash: SHA-256 hash of the artifact when source_type is file; otherwise set to n/a
• repro_command: Exact command that reproduces the observation, formatted as a fenced code block within the markdown
• raw_excerpt: Redacted snippet or excerpt illustrating the evidence (e.g., binary headers, log lines, or screenshot descriptions)

Two fields operate under conditional requirements:

• artifact_path: Required only when content_hash contains a SHA-256 value, specifying the relative path to the stored artifact under the case root
• linked_workitem: Set to a Work Item identifier (WI-{nnn}) that this evidence supports, or explicitly n/a if the observation is orphaned

Optional Metadata Fields

Three optional fields provide versioning and impact classification without affecting the core validity of the record:

• supersedes: Reference to a prior Evidence record (E-{nnn}) that this observation replaces, or none if initial
• severity: Impact classification using standardized values such as high, medium, low, or info
• status: Lifecycle state indicating validation progress, such as observed or validated

Real-World Examples from the Repository

The zhaoxuya520/reverse-skill repository provides concrete implementations in examples/ctf-demo/evidence/ demonstrating proper field population across different security scenarios:

• E-001.md: Captures checksec command output for ELF binary analysis, showing source_type: command and structured raw_excerpt formatting
• E-002.md: Documents a gets() stack overflow demonstration with reproducible crash commands
• E-003.md: Records a remote exploit execution resulting in flag capture, illustrating network-based evidence capture

These samples demonstrate how repro_command and raw_excerpt fields preserve critical context for security assessments.

Creating Evidence Records

You can generate compliant Evidence records using either manual markdown templates or the automated CLI helper.

Manual Markdown Template

Create a file at work/<case>/evidence/E-010.md following this exact structure:

### E-010

- title: OpenSSL 1.1.1 memory leak
- severity: high
- status: observed
- observed_at: 2026-08-30T14:22:00Z
- source_type: command
- source_ref: static analysis
- repro_command: |
    ./vuln_binary -leak
- raw_excerpt: |
    malloc(): corrupted top size
- content_hash: 3a7f9d2e5c1b8e6f4d9a0b2c6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f
- artifact_path: evidence/leak-output.txt
- linked_workitem: WI-015
- supersedes: none

Automated Creation with append-evidence.ps1

The skills/scripts/append-evidence.ps1 PowerShell script validates required fields, computes SHA-256 hashes for artifacts, and writes properly formatted markdown to the correct directory:

powershell -File skills/scripts/append-evidence.ps1 `
   -CaseRoot work/mycase `
   -Id E-010 `
   -Title "OpenSSL 1.1.1 memory leak" `
   -Severity high `
   -Status observed `
   -ObservedAt "2026-08-30T14:22:00Z" `
   -SourceType command `
   -SourceRef "static analysis" `
   -ReproCommand "./vuln_binary -leak" `
   -RawExcerpt "malloc(): corrupted top size" `
   -ArtifactPath "evidence/leak-output.txt" `
   -LinkedWorkitem WI-015

Validation Rules and Relationships

The Evidence record system enforces specific relationships within the reverse-skill framework. Every Finding must reference at least one Evidence record through the linked_workitem field to maintain traceability. For a Finding to achieve validated status, the framework requires backing from multiple independent evidences. The supersedes field maintains an immutable audit chain when observations are updated or corrected, ensuring that superseded records remain in the historical record while newer records acknowledge their lineage.

Summary

• Evidence records (E-{nnn}.md) store single, immutable security observations in markdown format within work/<case>/evidence/
• Seven mandatory fields establish core identity: title, observed_at, source_type, source_ref, content_hash, repro_command, and raw_excerpt
• Two conditional fields (artifact_path, linked_workitem) are required only when specific conditions are met (hash presence or Work Item linkage)
• Three optional fields (supersedes, severity, status) provide versioning, impact classification, and lifecycle tracking
• The field contract is formally defined in skills/ops/evidence-finding-path.md
• Reference implementations exist in examples/ctf-demo/evidence/ (E-001.md through E-003.md)
• Use skills/scripts/append-evidence.ps1 for automated, validation-compliant record creation

Frequently Asked Questions

What is the difference between source_type and source_ref in an Evidence record?

The source_type field classifies the origin using predefined categories (command, screenshot, file, log, memory, network, manual), while source_ref provides the specific identifier within that category. For example, a source_type of command paired with a source_ref of "static-analysis-ID-123" indicates the observation originated from a specific static analysis command execution. This separation allows the framework to filter by category while maintaining precise provenance tracking.

How does the content_hash field work in reverse-skill Evidence records?

The content_hash field stores a SHA-256 hash of the artifact when the source_type is file, enabling cryptographic verification of evidence integrity throughout the investigation lifecycle. When this field contains a hash value (not n/a), the artifact_path field becomes conditionally required and must specify the relative path to the stored artifact. For non-file sources such as manual observations or network captures, this field is explicitly set to n/a.

Can an Evidence record (E-{nnn}) be modified after creation?

Evidence records are designed to be immutable to preserve forensic integrity. Instead of modifying existing records, the framework uses the supersedes field to create a new record that explicitly references the obsolete one. This maintains an immutable audit trail where E-010 might supersede E-009, preserving the complete history of observations while clearly indicating the current authoritative record.

How do I link Evidence records to Work Items (WI-{nnn})?

Use the mandatory linked_workitem field to specify the identifier of the Work Item (WI-{nnn}) that the evidence supports. If the observation is not yet associated with a specific Work Item, you must explicitly set this field to n/a rather than omitting it. The reverse-skill framework requires that every validated Finding be backed by at least one Evidence record through this linkage mechanism, ensuring complete traceability from observation to conclusion.

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