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

> Discover the structured fields in an Evidence record E-nnn within reverse-skill. Learn how this immutable markdown file captures security observations with timestamps, hashes, and commands.

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

---

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

```markdown

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