Role-Based Access Control (RBAC)

Fine-grained security permissions with defense-in-depth protection for all SysManage operations.

Security Model Overview

SysManage implements a comprehensive role-based access control (RBAC) system that provides fine-grained permissions for every operation in the platform. The system is built on a defense-in-depth security model, ensuring that security checks are enforced at multiple layers.

Defense-in-Depth Architecture

Every protected operation in SysManage uses a two-layer security validation approach:

🖥️ Frontend Layer

UI elements (buttons, menus, actions) are hidden or disabled based on user permissions. This prevents users from attempting unauthorized actions and provides a better user experience.

🔒 Backend Layer

API endpoints validate user permissions before executing any operation. Even if the frontend is bypassed, the backend enforces security with HTTP 403 errors for unauthorized access.

Why Two Layers?

The frontend layer cannot be trusted for security enforcement since it runs in the user's browser and can be manipulated. The backend layer provides the actual security guarantee. Together, they offer both security (backend) and usability (frontend).

Security Role Groups

Security roles are organized into logical groups based on the functional areas they control:

🖥️ Host Management

Controls for managing hosts, their lifecycle, and operational states.

Approve Host Registration - Approve or reject new host registration requests
Delete Host - Remove hosts from the system
View Host Details - Access detailed information about hosts
Reboot Host - Initiate host reboots
Shutdown Host - Shut down hosts
Edit Tags - Modify host tags for organization
Stop Host Service - Stop services running on hosts
Start Host Service - Start services on hosts
Restart Host Service - Restart services running on hosts

📦 Package Management

Controls for software package operations and OS upgrades.

Add Package - Install new software packages on hosts
Apply Software Update - Apply available package updates
Apply Host OS Upgrade - Perform major OS version upgrades

🔐 Secrets Management

Controls for OpenBAO vault and secrets operations.

Deploy SSH Key - Deploy SSH keys to hosts
Deploy Certificate - Deploy SSL/TLS certificates to hosts
Add Secret - Create new secrets in the vault
Delete Secret - Remove secrets from the vault
Edit Secret - Modify existing secrets
Stop Vault - Stop the OpenBAO vault service
Start Vault - Start the OpenBAO vault service

👥 User Management

Controls for managing SysManage users and their accounts.

Add User - Create new user accounts
Edit User - Modify user account details
Lock User - Lock user accounts to prevent access
Unlock User - Unlock previously locked user accounts
Delete User - Remove user accounts from the system
Reset User Password - Reset passwords for user accounts

📜 Script Management

Controls for managing and executing scripts on hosts.

Add Script - Create new scripts in the library
Edit Script - Modify existing scripts
Delete Script - Remove scripts from the library
Run Script - Execute scripts on hosts
Delete Script Execution - Remove script execution history

📊 Report Management

Controls for viewing and generating system reports.

View Report - View reports in the web interface
Generate PDF Report - Export reports as PDF documents

🔗 Integration Management

Controls for managing system integrations and message queues.

Delete Queue Message - Remove messages from the message queue
Enable Grafana Integration - Configure and enable Grafana integration

🔷 Ubuntu Pro Management

Controls for Ubuntu Pro subscription management.

Attach Ubuntu Pro - Attach Ubuntu Pro subscriptions to hosts
Detach Ubuntu Pro - Detach Ubuntu Pro subscriptions from hosts
Change Ubuntu Pro Master Key - Update the Ubuntu Pro master token

Implementation Details

Frontend Permission Checks

The React frontend uses the hasPermission() function to check user permissions. UI elements are conditionally rendered based on these checks:

// Check permission
const [canDeleteHost, setCanDeleteHost] = useState(false);

useEffect(() => {
  const checkPermissions = async () => {
    const permission = await hasPermission(SecurityRoles.DELETE_HOST);
    setCanDeleteHost(permission);
  };
  checkPermissions();
}, []);

// Conditional rendering
{canDeleteHost && (
  <Button onClick={handleDelete}>Delete Host</Button>
)}

Backend Permission Validation

FastAPI endpoints validate user roles before executing operations. Unauthorized access returns HTTP 403:

@router.delete("/host/{host_id}")
async def delete_host(
    host_id: UUID,
    current_user=Depends(get_current_user)
):
    with session_local() as session:
        auth_user = session.query(User).filter(
            User.userid == current_user
        ).first()

        if not auth_user.has_role(SecurityRoles.DELETE_HOST):
            raise HTTPException(
                status_code=403,
                detail="Permission denied: DELETE_HOST role required"
            )

        # Proceed with deletion
        ...

Role Assignment

Administrators can assign roles to users through the Settings → Users interface. Multiple roles can be assigned to each user, providing flexible permission combinations for different organizational needs.

Best Practices

🔒 Principle of Least Privilege

Grant users only the minimum roles necessary to perform their job functions. Avoid giving broad permissions unless absolutely required.

🔍 Regular Role Reviews

Periodically review user role assignments to ensure they remain appropriate. Remove roles when users change responsibilities or leave the organization.

🔐 Separation of Duties

For sensitive operations, consider separating approval and execution roles across different users to prevent unauthorized actions.

📝 Audit Logging

Monitor and review audit logs for role assignments and permission-based actions to detect potential security issues.