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

> Discover the role-map in reverse-skill, a Markdown table assigning analyst roles and permission tokens for master routing engine access control. Learn how roles are assigned.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-06

---

**The role-map in reverse-skill is a centralized Markdown table located at [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) or associated PowerShell script includes a guard that validates permissions before executing sensitive logic:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md):

```markdown
| **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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)** — Central registry mapping analyst roles to permission tokens.
- **[`skills/ops/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.