How Evidence Is Appended in reverse-skill: Complete PowerShell Workflow

Evidence is appended in reverse-skill by executing the append-evidence.ps1 PowerShell script, which validates case directories, creates structured markdown files in the evidence/ folder, and chronologically updates the timeline.md log to maintain an immutable audit trail.

The reverse-skill repository provides a structured case management framework for digital forensics and penetration testing workflows. Understanding how evidence is appended in reverse-skill requires examining the PowerShell automation scripts that enforce consistent documentation standards. The entire process centers on skills/scripts/append-evidence.ps1, which serves as the single entry point for adding reproducible artifacts to a case.

The Core Evidence Appending Script

The primary mechanism for adding evidence resides in skills/scripts/append-evidence.ps1. This script acts as the gatekeeper for case data integrity, ensuring every piece of evidence receives a unique identifier, proper attribution, and chronological placement within the investigation timeline.

When invoked, the script performs three critical operations: it validates the target case directory structure, generates a new markdown evidence file (e.g., E-001.md) containing supplied metadata, and appends a corresponding entry to the case-wide timeline.md file located in the case root.

Step-by-Step Evidence Appending Workflow

The reverse-skill framework follows a strict four-phase workflow when appending evidence to maintain forensic integrity.

1. Initialize the Case Directory

Before adding evidence, analysts must run skills/scripts/case-init.ps1 to create the working directory structure under work/<case-name>. This establishes the evidence/ folder and initializes the timeline.md file that will track all subsequent evidence additions.

2. Gather and Document Evidence

After collecting artifacts during reconnaissance, the analyst invokes append-evidence.ps1 with specific metadata parameters. Required inputs include the evidence ID (e.g., E-001), descriptive title, reproducible command used to generate the artifact, and the artifact's file path.

3. Script Execution and File Generation

Upon execution, append-evidence.ps1 performs automated validation checks to confirm the case directory exists and is writable. The script then creates a structured markdown file in the evidence/ directory containing the supplied fields. If provided, the script also copies raw excerpt content via the -RawExcerptFile or -RawExcerpt parameters directly into the evidence documentation for quick reference.

Simultaneously, the script inserts a chronological entry into timeline.md, ensuring the new evidence appears in the correct temporal sequence within the final report.

4. Verification via Smoke Testing

The skills/scripts/smoke.ps1 utility validates the appending operation by confirming the new evidence file exists in the expected location and verifying the timeline entry was recorded correctly. This sanity check ensures immutability of case data and detects any filesystem inconsistencies.

PowerShell Implementation Examples

The following examples demonstrate the canonical usage patterns for appending evidence in reverse-skill, as documented in skills/ops/evidence-finding-path.md.

Append a cryptographic hash as new evidence:

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work\my-case `
    -Id E-002 `
    -Title "Malware SHA256" `
    -ReproCommand "sha256sum evidence/malware.bin" `
    -ArtifactPath "evidence\malware.bin"

Append manual analysis findings with inline excerpt:

powershell -File skills/scripts/append-evidence.ps1 `
    -CaseRoot work\my-case `
    -Id E-003 `
    -Title "Interesting string" `
    -RawExcerpt "The function xyz() is called with suspicious parameters..." `
    -ArtifactPath "evidence\strings.txt"

Execute the validation suite after appending:

powershell -File skills/scripts/smoke.ps1 -Name append-evidence.ps1

Critical Files in the Evidence Appending Process

Several files within the zhaoxuya520/reverse-skill repository define and implement the evidence appending workflow:

• skills/scripts/append-evidence.ps1 — Core PowerShell script that creates evidence markdown files and updates the timeline log.
• skills/ops/evidence-finding-path.md — Documentation specifying required parameters and the canonical calling convention for evidence appending.
• skills/scripts/smoke.ps1 — Sanity-check utility that verifies evidence file existence and timeline integrity.
• skills/scripts/case-init.ps1 — Directory initialization script that prepares the case structure for evidence reception.
• skills/pentest-tools/SKILL.md — References the evidence appending workflow within penetration testing contexts.
• skills/MASTER-ROUTING.md — Contains the canonical command line examples for appending evidence during automated routing workflows.

Integration with Master Routing and Pentest Workflows

The evidence appending mechanism integrates directly with reverse-skill's broader automation framework. As documented in skills/MASTER-ROUTING.md, the append-evidence.ps1 script receives orchestrated calls during master routing executions, allowing automated tools to submit findings directly into case files without manual intervention.

Similarly, skills/pentest-tools/SKILL.md references these scripts when documenting how penetration testing tools should output findings, ensuring that dynamic scan results follow the same immutable documentation standards as manual evidence collection.

Summary

• Centralized Script: All evidence appending flows through skills/scripts/append-evidence.ps1, ensuring consistent metadata capture.
• Immutable Timeline: Every append operation updates timeline.md to maintain chronological integrity of the investigation.
• Validation Required: The smoke.ps1 script verifies successful evidence registration and filesystem consistency.
• Parameter-Driven: Analysts supply -CaseRoot, -Id, -Title, -ReproCommand, and -ArtifactPath to create reproducible evidence records.
• Framework Integration: The process integrates with master routing and pentest tool workflows for automated case population.

Frequently Asked Questions

What parameters are required to run append-evidence.ps1?

The script requires five mandatory parameters: -CaseRoot specifies the case directory path, -Id provides a unique evidence identifier (e.g., E-001), -Title describes the evidence, -ReproCommand records the exact command used to generate the artifact, and -ArtifactPath indicates the relative path to the evidence file. Optional parameters include -RawExcerpt for inline text or -RawExcerptFile for referencing external text files.

How does reverse-skill ensure evidence integrity after appending?

The framework enforces integrity through immutable timeline updates and automated validation. After appending, the smoke.ps1 script verifies that the markdown file exists in the evidence/ directory and confirms the chronological entry appears in timeline.md. This dual-verification ensures that once evidence is recorded, it remains traceable within the case audit trail.

Can evidence be appended to existing case files, or only new ones?

The append-evidence.ps1 script creates new evidence files for each unique ID (e.g., E-001.md), but updates the existing timeline.md file to maintain the chronological record. While individual evidence files are created anew, the timeline acts as an append-only log that grows with each new submission, preserving the historical sequence of the investigation.

Where is the evidence appending process documented in the repository?

The primary documentation resides in skills/ops/evidence-finding-path.md, which details the workflow parameters and calling conventions. Additional references appear in skills/MASTER-ROUTING.md for automation contexts and skills/pentest-tools/SKILL.md for penetration testing integration examples.

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