Understanding the Role-Map in reverse-skill: How Analyst Roles Are Assigned

The role-map in reverse-skill is a centralized Markdown table located at skills/ops/role-map.md that maps analyst roles to permission tokens, enabling the master routing engine to enforce role-based access control during case initialization and skill execution.

The reverse-skill repository provides a structured framework for reverse-engineering, penetration testing, and threat-hunting workflows. At the heart of its security model sits the role-map, a single source-of-truth file that defines which analysts can execute specific operations. This article examines how skills/ops/role-map.md functions as the authoritative source for RBAC and how analyst permissions are assigned and enforced throughout the framework.

What Is the Role-Map in reverse-skill?

The role-map is a plain Markdown file stored at skills/ops/role-map.md. It contains a table that serves as the definitive registry of all participants in a reverse-skill workflow, mapping each role to a specific set of capabilities.

The table uses three columns: Role, Description, and Core Permissions. Each row defines a distinct analyst tier and lists the permission tokens granted to that tier. The current implementation defines five primary roles:

• Lead Analyst — Oversees a case, authorizes the case-init step, and can invoke any skill. Permissions: read, write, execute.
• Senior Analyst — Handles advanced sub-tasks such as kernel exploitation or protocol reverse-engineering and can approve findings. Permissions: read, write.
• Junior Analyst — Executes low-risk skills like binary diffing or wireless analysis under supervision. Permissions: read.
• Researcher — Contributes reusable artifacts such as reference documentation and templates. Permissions: read, write-templates.
• Automation Bot — Runs scripted pipelines via master-route.ps1 and may only read from or write to temporary workspaces. Permissions: read, write-workspace.

Because the file uses standard Markdown syntax, adding a new role requires only inserting a new row into the table, ensuring the framework remains extensible without code changes.

How Analyst Roles Are Assigned

Analyst role assignment follows a strict four-step workflow that begins when a new case is created and ends with runtime permission enforcement. The process relies on coordination between the case initializer, the master router, and individual skill scripts.

Step 1: Case Creation and Role Declaration

When an operator initializes a new case, the skills/scripts/case-init.ps1 script prompts for an analyst role. This value is written to the analyst: field inside the case-specific work/<case>/scope.md file, establishing the role context for the entire session.

Step 2: Role Lookup Against role-map.md

During initialization, the script reads skills/ops/role-map.md and parses the table to extract the permission list associated with the declared role. The permissions are then exported as an environment variable so downstream components can access them without re-parsing the file.

Step 3: Authorization via MASTER-ROUTING.md

Before any skill is dispatched, the master routing engine defined in skills/ops/MASTER-ROUTING.md inspects the permission set stored in the environment. The router compares the requested skill's requirements against the analyst's granted permissions, blocking any unauthorized execution attempts.

Step 4: Enforcement in Skill Scripts

Every individual skill contains a guard clause that performs a final runtime check. If the current analyst lacks the required permission token—such as execute for destructive operations—the script terminates immediately, preventing accidental or malicious actions.

Code Implementation: Parsing Permissions and Enforcing Guards

The following examples demonstrate how the reverse-skill framework reads the role-map and enforces restrictions in practice.

Fetching Permissions During Case Initialization

The case-init.ps1 script reads the role-map and stores the permission set for the session:

# case-init.ps1 (simplified)

$role = Read-Host "Enter analyst role (Lead|Senior|Junior|Researcher|Bot)"
$roleMap = Get-Content "$PSScriptRoot/../ops/role-map.md" |
            ConvertFrom-Markdown -AsTable
$permissions = $roleMap | Where-Object Name -EQ $role | Select-Object -Expand Permissions

# Export to environment for downstream scripts

$env:REVERSE_SKILL_PERMS = $permissions -join ','

Runtime Guard Clause in Skill Scripts

Each SKILL.md or associated PowerShell script includes a guard that validates permissions before executing sensitive logic:

# SKILL.ps1 (generic guard)

$allowed = $env:REVERSE_SKILL_PERMS -split ','
if (-not $allowed -contains 'execute') {
    Throw "Current analyst role does not have execute permission."
}

# …skill logic continues…

Extending the Role-Map

To add a new role, append a row to the Markdown table in skills/ops/role-map.md:

| **Red Team Lead** | Coordinates multi-stage attack chains, can launch C2 simulations. | `read ⚡ write ⚡ execute` |

The master routing engine automatically recognizes the new role on the next case initialization, applying the defined permissions without requiring updates to the routing logic itself.

Key Files in the RBAC Architecture

The role-based access control system spans several critical files across the repository:

• skills/ops/role-map.md — Central registry mapping analyst roles to permission tokens.
• skills/ops/MASTER-ROUTING.md — Core routing logic that consults the role-map before dispatching any skill.
• skills/scripts/case-init.ps1 — Handles case creation and performs the initial role lookup.
• work/<case>/scope.md — Case-specific file containing the analyst: field that declares the active role.
• skills/**/SKILL.md — Individual skill definitions containing permission guard clauses.
• RULES.md — High-level security policies that enforce the role-based model throughout the repository.

Summary

• The role-map at skills/ops/role-map.md acts as the single source of truth for analyst capabilities in reverse-skill.
• Five predefined roles exist—Lead Analyst, Senior Analyst, Junior Analyst, Researcher, and Automation Bot—each with distinct permission tokens.
• Role assignment occurs during case initialization via case-init.ps1, which reads the role-map and exports permissions to the environment.
• Authorization is enforced by the master routing engine and individual skill guard clauses that check for tokens like execute, write, and write-templates.
• The Markdown-based format allows dynamic role extension by simply adding rows to the table, with immediate effect across the framework.

Frequently Asked Questions

What happens if an analyst role is not found in the role-map?

If case-init.ps1 cannot locate the specified role in skills/ops/role-map.md, the initialization fails with an error, preventing the case from being created. This ensures that only explicitly defined roles with documented permission sets can access the framework.

Can permissions be customized per individual analyst?

No. The reverse-skill framework assigns permissions based on role tiers rather than individual user accounts. All analysts sharing the same role—such as Senior Analyst—receive identical permission tokens. Granular customization requires defining a new role in the role-map.

How does the master routing engine handle permission checks?

The master routing engine reads the REVERSE_SKILL_PERMS environment variable set during initialization. Before invoking any skill referenced in a SKILL.md file, it verifies that the required permission token is present in the list. If the check fails, the router logs the violation and aborts the operation.

Where is the active analyst role stored during a case session?

The active role is declared in the analyst: field of the case-specific work/<case>/scope.md file. This file serves as the persistent record for the case, while the REVERSE_SKILL_PERMS environment variable provides the runtime state used by scripts and the master router during execution.

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