CyberStrikeAI/docs/en-US/rbac.md

CyberStrikeAI RBAC Administration Guide

中文

CyberStrikeAI can execute Agents, MCP tools, WebShell operations, C2 actions, and batch jobs. RBAC therefore applies beyond navigation visibility: it is enforced across HTTP APIs, resource queries, Agent contexts, built-in and external MCP tools, background jobs, and chatbot execution.

---

1. Two different kinds of roles

Concept	Management location	Purpose
Platform role (RBAC Role)	Platform permissions	Controls which features and resources a user may access
AI testing role (Agent Role)	Roles / roles/*.yaml	Controls Agent prompts, methodology, and candidate tools

An AI testing role is not an authorization boundary. Selecting a penetration-testing role does not grant platform permissions, and granting RBAC permissions does not change the Agent prompt.

---

2. Authorization model

An operation is allowed only when all relevant checks pass:

enabled account
  + required permission for the route/tool
  + scope attached to that permission
  + resource owner / explicit assignment / parent inheritance
  + additional rules for process-global operations

Request flow:

1. Login issues a Bearer token whose session contains user, roles, permissions, and per-permission scopes.
2. HTTP middleware maps the route to a permission, for example GET /api/projects → project:read.
3. Resource-ID requests also check ownership, explicit assignments, or supported parent inheritance.
4. Agent execution receives an immutable Principal through context.Context.
5. Built-in MCP tools authorize both the tool and resource IDs in tool arguments. External MCP has separate restrictions.
6. Denials are written to RBAC/audit logs.

Frontend button hiding is only a usability feature. The server is the security boundary.

---

3. Built-in platform roles

Role	Scope	Default capability
Administrator admin	all	Every known permission, including RBAC, configuration, terminal, audit deletion, and global definition management
Operator operator	assigned	Normal read/write/execute work; excludes RBAC, core configuration, terminal, audit management, external MCP execution, and several global definition writes
Auditor auditor	all	Read permissions across modules plus audit:read; no writes
Viewer viewer	assigned	Read-only access within authorized resources

System roles cannot be edited or deleted. Their grants are rebuilt from the current permission catalog during upgrade, preventing stale grants from older versions. Create custom roles for different job functions.

An account without a role can still authenticate but has almost no business capability; do not treat “no role” as a complete job profile.

---

4. Permission catalog

Permissions use module:action. Common actions are read, write, delete, and execute. The authoritative catalog for the running build is available in Platform permissions or GET /api/rbac/metadata.

Module	Permissions
Account	auth:self
Dashboard	dashboard:read
Chat	chat:read, chat:write, chat:delete
Agent	agent:execute, agent:local-execute
HITL	hitl:read, hitl:write
Tasks	tasks:read, tasks:write, tasks:delete
Projects	project:read, project:write, project:delete
Vulnerabilities	vulnerability:read, vulnerability:write, vulnerability:delete
WebShell	webshell:read, webshell:write, webshell:delete
C2	c2:read, c2:write, c2:delete
MCP	mcp:read, mcp:execute, mcp:write, mcp:external:execute
Knowledge	knowledge:read, knowledge:write, knowledge:delete
Skills	skills:read, skills:write, skills:delete
Markdown Agents	agents:read, agents:write, agents:delete
AI testing roles	roles:read, roles:write, roles:delete
Workflows	workflow:read, workflow:execute, workflow:write, workflow:delete
Configuration	config:read, config:write
Terminal	terminal:execute
Audit	audit:read, audit:delete
RBAC	rbac:read, rbac:write
Notifications	notification:read, notification:write
Robots	robot:read, robot:write
Files	files:read, files:write, files:delete
Attack chain	attackchain:read, attackchain:write
FOFA	fofa:execute
OpenAPI	openapi:read
Chat groups	group:read, group:write, group:delete
Monitor	monitor:read, monitor:write, monitor:delete

Important distinctions:

• agent:execute runs Agents but does not grant local filesystem, shell, or arbitrary configured command access.
• agent:local-execute is the local execution fallback and should be limited to trusted operators.
• mcp:execute protects the authenticated MCP HTTP entry point.
• mcp:external:execute allows Agent calls to external MCP tools and currently also requires all scope.
• mcp:write manages external MCP configuration; it is separate from external tool execution.
• robot:write manages robot configuration and the test endpoint. Chatbot conversations use the bound user or configured service account's business permissions.

---

5. Resource scopes

Each role has one scope:

Scope	Meaning	Typical use
all	All resources covered by the permission	Administrator, global auditor
assigned	Explicitly assigned resources and supported parent-resource inheritance	Project member, assigned asset operator
own	Primarily resources created by/owned by the user; some resource types also support explicit assignment or parent inheritance	Personal workspace, isolated robot identity

Users may have multiple roles. Permissions are unioned, while scopes are merged for the same permission only:

all > assigned > own

Example:

Global audit role:  project:read  + all
Personal editor:    project:write + own

Effective:
project:read  → all
project:write → own

A global read role does not widen an unrelated write permission. Authorization code must use ScopeFor(permission), not the user's broadest display scope.

Process-global restrictions

Some definitions have no owner. Their mutations require the corresponding permission with all scope even if the user has a write key:

• AI testing roles, Skills, and Markdown Agents.
• External MCP configuration.
• Robot configuration.
• Workflow definitions.
• Knowledge mutations other than search.
• Global HITL allowlist, reviewer, and audit policy.
• C2 Profile mutations.
• Some global monitor statistics.

---

6. Ownership, assignments, and inheritance

Use Platform permissions → Member details → Resource assignments. Directly assignable resource types include:

• project
• conversation
• vulnerability
• webshell
• batch_task
• c2_listener

A batch request accepts at most 100 resources. Duplicate grants are skipped.

Supported inheritance includes:

Child resource	Parent access source
Conversation	Project
Vulnerability	Project or related conversation
Message, process detail, attack chain	Conversation
C2 Session	Listener
C2 Task/file/event	Session, Task, or Listener chain

Assigning a project therefore usually avoids assigning each conversation and vulnerability separately. The concrete route/tool server check remains authoritative.

---

7. Web administration workflow

Create a user

1. Sign in as an administrator and open Platform permissions.
2. Create a user with username, display name, an eight-character-or-longer password, and enabled status.
3. Assign one or more platform roles.
4. For assigned roles, configure resource assignments.
5. Have the user sign in again and verify roles, permission count, and scope in the top-right user menu.

Create a custom role

1. Give the role a job-oriented name and description.
2. Select all, assigned, or own.
3. Select only required permissions.
4. Test list, detail, mutation, deletion, Agent, and tool behavior with a test account.
5. Assign it to production users only after verification.

System roles are immutable; create a custom role instead of modifying them.

When changes take effect

• Updating a user, password, enabled state, or role membership revokes that user's sessions; they must sign in again.
• Updating or deleting a custom role revokes all sessions; all users must sign in again.
• Robots resolve the bound user/service account on every message, so disablement and role changes affect the next message.
• Background batch jobs resolve a Principal from the task owner rather than trusting frontend state.

---

8. Suggested role templates

Read-only project member

Scope: assigned
dashboard:read
chat:read
project:read
vulnerability:read
files:read
attackchain:read

Daily security operator

Scope: assigned
agent:execute
chat:read / chat:write
project:read / project:write
vulnerability:read / vulnerability:write
tasks:read / tasks:write
files:read / files:write
hitl:read / hitl:write

Add agent:local-execute or terminal:execute only when local commands are required. Add individual :delete permissions only when deletion is part of the job.

Robot service account

Scope: own (isolated workspace) or assigned (specific projects)
agent:execute
chat:read / chat:write
optional project, vulnerability, and knowledge permissions

admin can be used as a robot service account, but exact sender allowlisting still applies. Every allowlisted sender receives full permissions and shares admin-owned data. See the Robot guide.

---

9. Agent, MCP, and robot boundaries

Agent

The HTTP user becomes an immutable Principal propagated to single-agent, multi-agent, workflow, and tool contexts. A long-running task may survive an SSE disconnect while retaining that identity.

Built-in MCP

Every built-in tool requires an explicit authorization policy. WebShell tools check both webshell:read/write/delete and the target connection_id; project, vulnerability, task, and C2 tools validate resource arguments as well. An unregistered built-in policy fails closed. Other local/configured tools require agent:local-execute.

External MCP

Agent calls to external MCP require mcp:external:execute with all scope because an external service's resource model is not protected by local ownership and assignments.

Robots

• user_binding: each platform sender binds their own RBAC user.
• service_account: exact allowlisted senders share one RBAC user.
• Platform signature verification authenticates message origin, not business authorization.
• Run whoami to inspect the effective Principal.

---

10. RBAC API

All requests use:

Authorization: Bearer <token>

Management routes require rbac:read or rbac:write; the resource picker requires rbac:write.

Method	Path	Purpose
GET	/api/rbac/me	Current user, roles, permissions, overall scope, per-permission scopes
GET	/api/rbac/metadata	Permission catalog, roles, grants, and scopes
GET/POST	/api/rbac/users	List/create users
PUT/DELETE	/api/rbac/users/:id	Update/delete a user
GET/POST	/api/rbac/roles	List/create roles
PUT/DELETE	/api/rbac/roles/:id	Update/delete a custom role
GET	/api/rbac/resources?type=project&q=...	Search assignable resources
GET/POST	/api/rbac/resource-assignments	List/create assignments
DELETE	/api/rbac/resource-assignments/:id	Revoke an assignment

Create a user:

curl -X POST http://localhost:8080/api/rbac/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "operator01",
    "display_name": "Security Operator 01",
    "password": "change-me-123",
    "enabled": true,
    "roles": ["operator"]
  }'

Create a custom role:

curl -X POST http://localhost:8080/api/rbac/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Auditor",
    "description": "Read assigned projects",
    "scope": "assigned",
    "permissions": ["chat:read", "project:read", "vulnerability:read"]
  }'

Assign projects:

curl -X POST http://localhost:8080/api/rbac/resource-assignments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "USER_ID",
    "resource_type": "project",
    "resource_ids": ["PROJECT_ID_1", "PROJECT_ID_2"]
  }'

---

11. Audit and operations recommendations

• Use individual administrator accounts instead of sharing one password.
• Name custom roles by job function and document purpose/owner.
• Review high-risk permissions separately: terminal:execute, agent:local-execute, c2:write/delete, webshell:write/delete, rbac:write, and config:write.
• Periodically review all roles, service accounts, robot allowlists, and dormant users.
• On offboarding, disable the account first, then revoke robot bindings, assignments, and sessions.
• Monitor RBAC denials, user/role changes, resource assignments, and robot service-account execution in audit logs.
• Pair RBAC with HITL for dangerous tools; permission to invoke does not bypass approval policy.

---

12. Troubleshooting

A button is missing

The frontend hides actions based on /api/rbac/me. Verify the required permission. Direct API calls are still rejected server-side.

Permission exists but the resource is denied

Inspect the scope for that specific permission, not only the overall display scope. Then check owner, explicit assignment, and parent assignment.

Role changed but the user sees old access

Role changes revoke sessions. Sign in again. Robots resolve again on the next message.

A global mutation is denied despite write

Process-global definitions require the corresponding permission with all scope. Create a dedicated global administration role instead of widening unrelated permissions.

Agent chat works but commands fail

agent:execute and agent:local-execute are separate. Grant local execution only when necessary and combine it with HITL, tool allowlists, and audit.

External MCP requires global scope

The user needs mcp:external:execute, and that permission's scope must be all.