Bot Roles & Permissions

Prerequisites: Before reading this guide, we recommend familiarizing yourself with the permission model in Core Concepts and the Resources & Credentials page.

Bot Roles are the core mechanism through which the platform governs Bot behavior. With roles, you can precisely control which Resources a Bot can access, which tools it can use, and what parameter ranges it can operate within.

Overview

Monstrum’s permission design is built around one principle: platform-enforced, not AI self-regulated. Permissions don’t “tell the Bot what not to do” — they architecturally guarantee that a Bot cannot perform unauthorized actions.

Permission control operates at two levels:

Tool visibility (Pre-LLM): A Bot can only see tools it has been authorized to use. Unbound Resources and their tools are completely invisible to the Bot
Parameter-level validation (Post-LLM): Even when a Bot calls a visible tool, the parameters must fall within the defined constraints

Core Workflow

A Bot’s permissions come from the Resources you configure. The overall setup flow is:

1. Create Resources (Resource + Credential)
        ↓
2. Create a Bot Role, reference those Resources in the role, and set permissions
        ↓
3. Assign the role to a Bot → The Bot automatically gains the resource access defined in the role

You can also skip roles and bind Resources directly to a Bot (direct binding), but roles are better suited for scenarios where you need to reuse the same permission configuration across multiple Bots.

Bot Roles

A Bot Role is a collection of Permission Entries. Each Permission Entry specifies a Resource and the operations the Bot is allowed to perform on that Resource.

Creating a Role

Click Bot Roles in the left navigation bar
Click Create Bot Role
Fill in the basic information:
- Role name: e.g., “Read-only Ops”, “Repository Admin”
- Description: A brief explanation of the role’s purpose
- Parent role (optional): Inherit permissions from another role

Adding Permission Entries

The core of a role is its Permission Entries. Each entry is associated with a Resource you have already created, defining what operations the Bot is allowed to perform on that Resource.

Click Add Permission Entry and configure:

Field	Description	Required
Select Resource	Choose from Resources you have already created in Resource Management	Yes
Select Credential	Specify which Credential to use. If left empty, all Credentials for that Resource are available	No
Select Operations	Check the operations or tools to allow. If left empty, all operations are allowed	No
Scope Constraints	Set constraint values for each permission dimension (e.g., host allowlist, command allowlist)	No

A single role can contain multiple Permission Entries, each referencing a different Resource. For example, an “Ops” role can include Permission Entries for both an SSH Resource and a Web Resource.

Operation Selection

The list of available operations depends on the Resource type:

Static tool types (SSH, Bot, Web3, Web): Display a fixed list of operations, grouped by function
Dynamic tool types (MCP, Monstrum Agent): Display the tools discovered for that Resource

Operations support glob patterns, for example:

* — Allow all operations
issue.* — Allow all issue-related operations
issue.read — Allow reading issues only

Scope Constraints

Scope Constraints are configured in the form of “only allow [dimension] [value list]”, restricting the parameter ranges when a Bot calls tools:

Only allow host allowlist 10.0.1.*, prod-web-*
Only allow command allowlist ls *, cat /var/log/*
Only allow repository allowlist org/repo-*
Only allow domain allowlist *.github.com

Values use glob pattern matching (fnmatch syntax), where * matches any characters.

Permission Dimensions by Resource Type

Resource Type	Dimension	Description
SSH	`hosts`	Allowed hosts to connect to (glob)
SSH	`commands`	Allowed commands to execute (glob)
Web	`domains`	Allowed domains to scrape (glob)
Web3	`operations`	Allowed operation types (read/write)
Web3	`recipients`	Allowed transfer recipients
Web3	`contracts`	Allowed contracts to call
Web3	`functions`	Allowed contract functions (glob)
Bot	`bots`	Allowed target Bots to call
MCP	`tools`	Allowed tools to call (glob)
Agent	`tools`	Allowed tools to call (glob)
Agent	`paths`	Allowed file paths (glob)
Agent	`commands`	Allowed commands (glob)

Role Inheritance

Roles support parent-child inheritance. A child role inherits all Permission Entries from its parent and can further narrow them (but never expand them).

For example:

Parent role “Ops”: Allows all SSH operations
Child role “Read-only Ops”: Inherits from “Ops”, but restricts the command allowlist to cat *, ls *, tail *

Assigning Roles to Bots

Once you have created a role, assign it to a Bot:

Go to the Bot detail page → Resource Configuration tab
In the Bot Roles section, click Assign Role
Select the role to assign
All Resource bindings defined in the role take effect automatically

After assignment, the Bot Roles section displays the assigned roles along with the number of Resource bindings each contains.

Role Binding vs Direct Binding

The Bot’s Resource configuration page is divided into two sections:

Section	Description
Bot Roles	Resources bound indirectly through roles. Modifying a role updates all associated Bots at once
Direct Resource Binding	Resources bound directly to the Bot without going through a role

Both approaches can coexist. Roles are suited for standardized scenarios (multiple Bots sharing the same permissions), while direct binding is suited for one-off special configurations.

Resource Assignment Overview

In the Resource Assignment Overview tab on the Bot Roles page, you can view the role assignment status across your entire workspace:

Grouped by Bot, showing all Resource bindings for each Bot
Each binding is labeled with its source (which role it comes from)
Supports filtering by role or Resource

Delegate Scope

When Bot A calls Bot B through a Bot Resource, you can set constraints on that delegation to limit Bot B’s effective permissions while executing the delegated task.

Why Delegate Scope Is Needed

Consider this scenario:

Bot A is an orchestrator Bot, bound to Bot B (an ops Bot) and Bot C (a dev Bot)
Bot B has full SSH permissions
Bot A delegates an ops task to Bot B

Without Delegate Scope, Bot B would use its full permissions to execute the task. But Bot A may only want Bot B to execute specific commands during this delegation. Delegate Scope solves exactly this problem.

Configuring Delegate Scope

In Bot A’s Resource configuration where Bot B is bound, set the Delegate Scope:

Tool allowlist: Restrict which tools Bot B can use during the delegated task
Scope Constraints: Further restrict Bot B’s parameter ranges

Intersection Principle

Bot B’s effective permissions during a delegated task = Bot A’s Delegate Scope ∩ Bot B’s own permissions.

This means:

Delegate Scope can only narrow Bot B’s permissions, never expand them
If Bot A’s Delegate Scope allows hosts: ["*"] but Bot B’s own permissions only allow hosts: ["10.0.*"], the effective scope is 10.0.*
Conversely, if Bot B allows all hosts but Bot A’s Delegate Scope only allows 10.0.*, the effective scope is also 10.0.*

Workspace Member Permissions

In addition to Bot-level tool permissions, Monstrum also has workspace member management permissions. These are user-level permissions, entirely separate from the Bot-level permissions described above.

Member Roles

Role	Permissions
Owner	Full control, including deleting the workspace
Admin	Manage Bots, Resources, and members, but cannot delete the workspace
Member	Use Bots, view Resources, but cannot manage configurations
Viewer	Read-only access

Managing Members

Go to the Member Management page in your workspace
Invite new members: Enter an email address and select a role
Change member roles: Update from the member list
Remove members: Remove from the workspace

Common Patterns

Principle of Least Privilege

Configure each Bot with only the minimum permissions needed to complete its work:

SSH Bot: Only allow cat, ls, tail commands, restricted to specific hosts
Web3 Bot: Only allow balance.get (read-only), disallow transfer and contract.send
Orchestrator Bot: Use Delegate Scope to limit the permission scope of child Bots

Role Reuse

Create role templates for common scenarios and assign them to multiple Bots:

“Read-only Ops”: SSH Resource limited to read commands only
“Repository Read-only”: GitHub Resource limited to issue.read, pr.read
“Search Specialist”: Web Resource limited to web.search

Auditing Permission Changes

All permission check results (allowed/denied) are recorded in the audit log. You can view detailed permission validation records in the Audit Log tab of the Data Center.

FAQ

Bot’s Tool Call Was Denied

Check whether the Bot has the corresponding Resource bound (via a role or direct binding)
Check whether the operations in the Permission Entry include the tool in question
Check whether the Scope Constraints cover the parameter values used in the call
Review the denial reason in the Data Center’s Audit Log

Bot Cannot See Tools After Role Assignment

Confirm that the Resources referenced in the role’s Permission Entries still exist and their Credentials are valid
Confirm that the operation selection in the role is not empty

Delegate Scope Too Restrictive, Child Bot Cannot Work

Check the intersection of the Delegate Scope and the child Bot’s own permissions. Make sure the intersection includes the tools and parameter ranges the child Bot needs to complete its task.

Edit this page on GitHub