[Sprint 5] Implement Roles API Module

[talltechy]

Overview

Implement comprehensive Roles API module following v2.0 BaseAPI pattern for role and permission management.

Scope

• List available roles
• Get role details and permissions
• Role privilege enumeration
• Custom role support (if API supports)
• Helper methods for common workflows
• Integration with InsightVMClient
• Comprehensive docstrings with type hints
• Error handling
• Unit tests (when test framework ready)

API Endpoints

• GET /api/3/roles - List all roles
• GET /api/3/roles/{id} - Get role details
• GET /api/3/privileges - List all privileges (if available)

Implementation Checklist

• Create src/rapid7/api/roles.py
• Implement RoleAPI class extending BaseAPI
• Add roles sub-client to InsightVMClient
• Create documentation in docs/ROLES_API.md
• Update Memory Bank (activeContext.md, progress.md)
• Create feature branch: feature/issue-{number}-roles-api

Key Features

• Built-in Roles: Global admin, security manager, site owner, user
• Privilege Sets: Detailed permission listings per role
• Custom Roles: Support for organization-specific roles (if available)
• Permission Checking: Validate user capabilities
• Helper Methods: get_admin_role(), get_by_name(), has_privilege()

Role Types (Common)

• Global Administrator: Full system access
• Security Manager: Vulnerability and security management
• Site Owner: Manage specific sites
• Asset Owner: Manage specific asset groups
• User: Read-only or limited access

Estimated Size

~200-250 lines of code

Definition of Done

• RoleAPI module implemented with all endpoints
• Integrated with InsightVMClient as client.roles
• Documented with usage examples
• Memory Bank updated
• PR created and ready for review

References

• Context7 API Documentation: /riza/rapid7-insightvm-api-docs
• BaseAPI Pattern: src/rapid7/api/base.py
• Related Module: src/rapid7/api/users.py