Understanding reverse-skill's Ops Contracts: Scope-Contract, Evidence-Finding-Path, and Role-Map

reverse-skill uses three plain Markdown contracts—scope-contract, evidence-finding-path, and role-map—to enforce authorization, structured documentation, and clear role responsibilities across every security engagement.

This guide explains how to implement reverse-skill's ops contracts based on the source files in zhaoxuya520/reverse-skill. These contracts replace ad-hoc tracking with lightweight, version-controlled Markdown that requires no database or external ticketing system.

---

What Are reverse-skill's Ops Contracts?

The skills/ops/ directory contains three complementary contracts that govern every phase of a reverse-engineering, pentest, or security engagement:

Contract	File Location	Purpose
Scope-contract	skills/ops/scope-contract.md	Authorization gate before any active operation
Evidence-finding-path	skills/ops/evidence-finding-path.md	Three-layer evidence chain (raw → analyzed → narrative)
Role-map	skills/ops/role-map.md	Role-to-skill mapping and hand-off protocols

All contracts use human-readable Markdown with machine-parseable keys, enabling both manual editing and PowerShell automation.

---

Scope-Contract: The Authorization Gate

The scope-contract in skills/ops/scope-contract.md mandates that no active "ACT" step can occur without a valid scope.md file. This hard gate prevents unauthorized operations by enforcing explicit documentation of assets, constraints, and sign-offs.

Required Sections in scope.md

Every case scope must include:

• meta – case ID, operator, primary skill, lead role, specialist roles
• auth – authorization status (granted required), basis, evidence reference
• in_scope – assets, surfaces, allowed activities
• out_of_scope – explicitly excluded targets and actions
• network_profile – connectivity mode: offline, lab_only, authorized_target_only, or unrestricted_lab
• constraints – timebox, stealth level, data handling rules
• deliverables – required artifacts (report, field journal, diagrams, timeline)
• signoff – checklist that must pass before proceeding

Creating a Scope-Contract with PowerShell

Use the case-init.ps1 helper to bootstrap a new case:

powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\case-init.ps1 `
  -Hint "Enumerate vulnerable IoT devices" -CaseName "iot-audit"

This creates work/iot-audit/scope.md pre-filled with the template structure.

Validating Scope Before Action

The contract enforces that auth.status must equal granted and network_profile.mode must match the operational environment. A minimal valid scope looks like:

## auth

- status: granted
- basis: bug_bounty_scope
- evidence_of_auth: ticket/12345

## network_profile

- mode: authorized_target_only
- notes: Only enumerated targets may be contacted

## signoff

- ready_for_act: true
- checklist:
  - [x] auth.status = granted
  - [x] in_scope.assets non-empty
  - [x] network_profile.mode chosen
  - [x] out_of_scope reviewed

---

Evidence-Finding-Path: Structured Documentation Chain

The evidence-finding-path contract in skills/ops/evidence-finding-path.md defines a three-layer hierarchy connecting raw observations to validated findings and complete attack or solve narratives.

The Three Layers

Layer	ID Pattern	Mandatory Fields	Purpose
Evidence	E-001	title, observed_at, source_type, source_ref, content_hash, repro_command, raw_excerpt, linked_workitem, supersedes	Immutable raw observation
Finding	F-001	title, severity, category, status, evidence_ids, location, impact, confidence, repro_steps, remediation	Analyst conclusion with evidence backing
Path	P-001	title, path_type, start, goal, steps, residual_risks	End-to-end narrative linking steps to evidence and findings

Recording Evidence with CLI Helpers

The append-evidence.ps1 script creates properly formatted evidence files:

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/iot-audit `
  -Id E-001 -Title "Nmap open ports" -ReproCommand "nmap -sV 192.168.1.10" `
  -Severity info -Status observed

This generates work/iot-audit/evidence/E-001.md with all required fields pre-populated.

Creating Findings and Paths Manually

Findings reference evidence IDs and add analysis:

### F-001

- title: Exposed Telnet service with default credentials
- severity: critical
- category: vuln
- status: validated
- evidence_ids: [E-001, E-002]
- location: 192.168.1.10:23
- confidence: high
- repro_steps:
  1. telnet 192.168.1.10
  2. Login with admin/admin
- remediation: Disable Telnet; enforce SSH with key auth

Paths connect findings into operational narratives:

### P-001

- title: IoT device compromise via Telnet
- path_type: attack
- start: Network access to target segment
- goal: Root shell on IoT gateway
- steps:
  1. action: Discover Telnet service — evidence: E-001 — finding: F-001
  2. action: Enumerate connected devices — evidence: E-003 — finding: F-002
  3. action: Exploit UART debug interface — evidence: E-010 — finding: F-005
- residual_risks: Physical access required for step 3

Enforcement Rules in evidence-finding-path

• Every Finding must reference at least one Evidence (evidence_ids non-empty)
• Validated Findings cannot have confidence: low without noted residual risk
• Paths must reference Evidence for each step; final Finding must be validated before success claim

---

Role-Map: Responsibility and Hand-Off Management

The role-map contract in skills/ops/role-map.md defines who operates on which skills and how responsibilities transition during an engagement. It operates independently of any orchestration engine—all data stays in Markdown.

Core Role Codes

Code	Full Name	Primary Skills
lead	Engagement Lead	Scope writing, role assignment, timeline management
cie	Intelligence & Enumeration Specialist	Recon, OSINT, asset discovery
cpe	Exploitation & Post-Exploitation Specialist	Vulnerability validation, privilege escalation
cre	Reverse Engineering Specialist	Binary analysis, firmware extraction
doc	Documentation & Reporting Specialist	Report generation, diagram creation

Lead Protocol Requirements

The lead role must:

1. Write or approve the scope.md file
2. Assign specialist roles in meta.specialist_roles
3. Manage all hand-off transitions
4. Maintain timeline.md with role-prefixed entries

Hand-Off Matrix and Triggers

Role transitions require specific triggers and deliverables:

From	To	Trigger	Required Deliverable
lead	cie	Scope approved, authorization granted	Completed scope.md with ready_for_act: true
cie	cpe	Live service or vulnerability discovered	Asset list with evidence references
cpe	cre	Binary or firmware obtained for analysis	Sample file with extraction notes
any	doc	Evidence/Finding draft complete	Structured markdown ready for report

Single-Agent Usage

When one analyst performs multiple roles, prefix all timeline entries with role tags:

# timeline.md

[lead] 2024-01-15 09:00 – Scope created, auth granted for target.example.com
[cie] 2024-01-15 10:30 – Open ports discovered on 203.0.113.5
[cie] → [cpe] 2024-01-15 10:35 – Handoff: SSH service identified, begin exploitation
[cpe] 2024-01-15 11:00 – Validated weak key authentication (E-005 → F-003)
[cpe] → [doc] 2024-01-15 12:00 – Path P-001 complete, draft findings ready

---

Complete Workflow Example

This example demonstrates all three reverse-skill ops contracts in sequence:

1. Initialize Case (Scope-Contract)

powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\case-init.ps1 `
  -Hint "Audit Windows AD environment" -CaseName "ad-audit"

Edit work/ad-audit/scope.md:

## meta

- case_id: 20240115-01
- operator: analyst1
- primary_skill: windows-ad
- lead_role: lead
- specialist_roles: [cie, cpe]

## auth

- status: granted
- basis: internal_audit
- evidence_of_auth: email/audit-approval-2024q1

## in_scope

- assets: [10.10.10.5]
- surfaces: [ldap, kerberos, smb]
- activities: [recon, exploit_validate, post_exploit]

## network_profile

- mode: authorized_target_only

## constraints

- timebox: 40 hours
- stealth: low_interaction

## signoff

- ready_for_act: true
- checklist:
  - [x] auth.status = granted
  - [x] in_scope.assets non-empty
  - [x] network_profile.mode chosen

2. Record Evidence (Evidence-Finding-Path)

powershell -File skills/scripts/append-evidence.ps1 -CaseRoot work/ad-audit `
  -Id E-001 -Title "Anonymous LDAP bind successful" `
  -ReproCommand "ldapsearch -x -h 10.10.10.5 -s base namingcontexts" `
  -Severity info -Status observed

3. Create Finding

<!-- work/ad-audit/finding/F-001.md -->

### F-001

- title: LDAP server allows anonymous bind
- severity: medium
- category: config_weakness
- status: validated
- evidence_ids: [E-001]
- location: 10.10.10.5:389
- confidence: high
- repro_steps:
  1. Execute ldapsearch with -x flag
  2. Observe successful connection without credentials
- remediation: Disable anonymous bind in slapd.conf

4. Build Attack Path

<!-- work/ad-audit/path/P-001.md -->

### P-001

- title: Domain enumeration via anonymous LDAP
- path_type: attack
- start: Network connectivity to domain controller
- goal: Complete domain user list
- steps:
  1. action: Confirm anonymous bind — evidence: E-001 — finding: F-001
  2. action: Extract user list with filter (objectClass=user) — evidence: E-010 — finding: F-005
  3. action: Identify password policy — evidence: E-011 — finding: F-006
- residual_risks: Account lockout possible if interaction limits exceeded

5. Document Role Transitions (Role-Map)

<!-- work/ad-audit/timeline.md -->
[lead] 2024-01-15 09:00 – Scope approved, specialist roles assigned.
[cie] 2024-01-15 10:00 – LDAP port discovered on 10.10.10.5:389.
[cie] → [cpe] 2024-01-15 10:15 – Handoff: authentication service identified.
[cpe] 2024-01-15 11:00 – Anonymous bind validated, E-001 created.
[cpe] 2024-01-15 11:30 – Domain enumeration complete, F-005/F-006 created.
[cpe] → [doc] 2024-01-15 12:00 – Path P-001 finalized for reporting.

---

Summary

• Scope-contract (skills/ops/scope-contract.md) is the mandatory authorization gate—no active operations without auth.status: granted and completed sign-off checklist
• Evidence-finding-path (skills/ops/evidence-finding-path.md) enforces a three-layer documentation hierarchy: immutable Evidence → validated Finding → narrative Path
• Role-map (skills/ops/role-map.md) defines role-to-skill assignments, lead protocols, and hand-off triggers with required deliverables
• All contracts use plain Markdown with parseable keys, enabling both manual editing and PowerShell automation via case-init.ps1 and append-evidence.ps1
• The framework is tool-agnostic—no external APIs, databases, or ticketing systems required

---

Frequently Asked Questions

What happens if I try to run an active operation without a scope-contract?

According to the scope-contract.md source, no ACT step is permitted without a valid scope.md file showing auth.status: granted. The contract explicitly states "No scope → only documentation/routing allowed." Attempting reconnaissance, exploitation, or reverse engineering without authorization triggers a protocol violation.

How does evidence-finding-path ensure findings are reproducible?

The contract mandates that every Evidence include repro_command, source_ref, and content_hash fields. Every Finding must reference at least one Evidence via evidence_ids and include repro_steps. This creates an auditable chain from raw observation to analyst conclusion, with the Path layer providing narrative context for complex operations.

Can I use reverse-skill's ops contracts without the PowerShell helpers?

Yes. The contracts are pure Markdown with no dependency on case-init.ps1 or append-evidence.ps1. You can manually create work/<case>/scope.md, evidence/E-*.md, finding/F-*.md, and other files following the templates in skills/ops/. The PowerShell scripts are convenience wrappers that enforce field presence and consistent formatting.

How do role-map hand-offs work when multiple analysts collaborate?

The lead role manages transitions via the hand-off matrix documented in role-map.md. Each transition requires a trigger condition (e.g., "live service discovered") and a deliverable (e.g., asset list with evidence references). The transfer is recorded in timeline.md with role prefixes ([cie] → [cpe]), creating an audit trail of responsibility changes.

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