/semi-trusted-roles

name: "semi-trusted-roles"
description: "Trigger Pattern SEMI_TRUSTED_ROLE flag (required) - Inject Into Breadth agents, depth-state-trace"

SEMI_TRUSTED_ROLES Skill

> **Trigger Pattern**: SEMI_TRUSTED_ROLE flag (required) > **Inject Into**: Breadth agents, depth-state-trace > **Purpose**: Analyze semi-trusted roles in Aptos Move protocols using capability-based access control, modeling both role-to-user and user-to-role attack vectors

Trigger Patterns

signer|SignerCapability|AdminCap|OperatorCap|KeeperCap|has_role|
assert_admin|assert_operator|friend|acquires|ExtendRef|
DeleteRef|TransferRef|MintRef|BurnRef

Reasoning Template

Step 1: Inventory Role Permissions

Enumerate ALL privileged roles in the protocol:

| Role | Capability / Check | Module | Functions Callable | State Modifiable | External Calls | |------|-------------------|--------|-------------------|-----------------|----------------| | {role} | {SignerCapability / custom Cap struct / signer check / friend} | {module} | {fn list} | {state list} | {calls list} |

**Aptos capability patterns to inventory**:

• **SignerCapability**: Stored in resource, allows generating a signer for the capability's address. Can call any function requiring that signer.
• **Custom capability structs**: `AdminCap`, `OperatorCap` etc. -- often stored in the deployer's account or an Object
• **Signer checks**: `assert!(signer::address_of(account) == @admin, E_NOT_ADMIN)` -- direct address comparison
• **Friend declarations**: `friend module::other` -- allows `other` to call `public(friend)` functions
• **Object Refs**: `ExtendRef`, `DeleteRef`, `TransferRef`, `MintRef`, `BurnRef` -- object-level capabilities
• **Resource account patterns**: Module creates a resource account and stores its `SignerCapability`

For each role at {ROLE_FUNCTIONS}:

• What state does it modify?
• What external calls does it make (via CPI or module calls)?
• What parameters does it accept?

Step 2: Analyze Within-Scope Abuse (Direction A: Malicious Role)

For each permitted action, ask:

**Timing Abuse**:

• Can {ROLE_NAME} execute at harmful times? (front-run users via transaction ordering, during rebalance)
• Can {ROLE_NAME} delay execution to harm users? (withhold keeper actions)

**Parameter Abuse**:

• Can {ROLE_NAME} pass harmful parameters? (max slippage, wrong recipient address, extreme fee values)
• Are parameters validated on-chain, or trusted implicitly from the role?

**Sequence Abuse**:

• Can {ROLE_NAME} execute operations out of order?
• Can {ROLE_NAME} skip required operations in a multi-step process?

**Omission Abuse**:

• Can {ROLE_NAME} harm users by NOT acting? (skip price updates, delay distributions, never trigger harvest)

Step 3: Model Attack Scenarios

Scenario A: Timing Attack
1. {ROLE_NAME} monitors mempool for user transaction {USER_ACTION}
2. {ROLE_NAME} front-runs with {ROLE_ACTION}
3. User's transaction executes with worse conditions
4. Impact: {TIMING_IMPACT}

Scenario B: Parameter Attack
1. {ROLE_NAME} calls {ROLE_FUNCTION} with {MALICIOUS_PARAMS}
2. Parameters are not validated against {EXPECTED_CONSTRAINTS}
3. Impact: {PARAM_IMPACT}

Scenario C: Key Compromise
1. {ROLE_NAME} private key is compromised (or SignerCapability is leaked)
2. Attacker can call: {ROLE_FUNCTIONS}
3. Maximum extractable value: {MAX_DAMAGE}
4. Recovery options: {RECOVERY_PATH}

Step 4: Assess Mitigations

| Mitigation | Present? | Implementation | Effective? | |-----------|----------|----------------|-----------| | Timelock on role actions | YES/NO | {code ref} | {analysis} | | Multisig requirement | YES/NO | {code ref} | {analysis} | | Role revocation function | YES/NO | {code ref} | {analysis} | | Rate limits / cooldowns | YES/NO | {code ref} | {analysis} | | Parameter bounds validation | YES/NO | {code ref} | {analysis} | | Event emission for monitoring | YES/NO | {code ref} | {analysis} |

**Does a removal/revocation function for {ROLE_NAME} EXIST?** If NO -> FINDING: role is irrevocable without module upgrade. Severity: minimum Medium if role can modify user-facing state.

Step 4b: Capability Escalation Analysis

| Capability | Stored Where | Can Be Duplicated? | Can Escalate? | Escalation Path | |-----------|-------------|-------------------|---------------|----------------| | {cap} | {resource/object} | YES/NO (`copy` ability?) | YES/NO | {if YES: how} |

**Aptos-specific escalation vectors**:

• `SignerCapability` has `copy` + `store` abilities -- can it be extracted and stored elsewhere?
• `ExtendRef` allows adding resources to an Object -- can a role add capabilities it shouldn't have?
• `TransferRef` allows ungated transfer of an Object -- can a role transfer an Object holding other capabilities?
• `MintRef` / `BurnRef` -- can a role with mint capability effectively drain the protocol?
• Friend module access -- can a friend module be upgraded to abuse `public(friend)` functions?

Step 4c: Capability Transfer and Duplication

| Capability | Has `copy`? | Has `drop`? | Has `store`? | Transfer Function Exists? | Risk | |-----------|------------|------------|-------------|--------------------------|------| | {cap} | YES/NO | YES/NO | YES/NO | YES/NO | {assessment} |

**Key checks**:

• If capability has `copy` -> it can be duplicated, creating multiple holders
• If capability has `store` -> it can be placed in global storage, potentially accessible by others
• If capability has `drop` -> it can be silently discarded (may not be a risk, but check if protocol assumes it persists)
• If a `transfer_cap()` function exists -> trace who can call it and whether it validates the recipient

Reverse Perspective: User Exploitation of Roles

Step 5: Model User-Side Exploitation (Direction B: Malicious Users)

**Predictability Analysis**:

• Is the role's behavior predictable? (scheduled tasks, triggered by events, MEV-visible)
• Can users observe when the role will act?
• Can users front-run or back-run the role's