list_roles
Read-only
Retrieve and display all roles from your Panther security monitoring instance with metadata including permissions and settings for access management.
Instructions
List all roles from your Panther instance.
Returns list of roles with metadata including permissions and settings.
Permissions:{'all_of': ['Read User Info']}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name_contains | No | Case-insensitive substring to search for within the role name | |
| name | No | Exact match for a role's name. If provided, other parameters are ignored | |
| role_ids | No | List of specific role IDs to return | |
| sort_dir | No | Sort direction for the results | asc |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The complete implementation of the 'list_roles' tool, including the @mcp_tool decorator for registration, input schema via Annotated Fields with Pydantic Field descriptions, and the full handler logic that queries the Panther REST API for roles, filters the response, and returns formatted results with pagination info.
@mcp_tool( annotations={ "permissions": all_perms(Permission.USER_READ), "readOnlyHint": True, } ) async def list_roles( name_contains: Annotated[ str | None, Field( description="Case-insensitive substring to search for within the role name", examples=["Admin", "Analyst", "Read"], ), ] = None, name: Annotated[ str | None, Field( description="Exact match for a role's name. If provided, other parameters are ignored", examples=["Admin", "PantherReadOnly", "SecurityAnalyst"], ), ] = None, role_ids: Annotated[ list[str], Field( description="List of specific role IDs to return", examples=[["Admin", "PantherReadOnly"], ["SecurityAnalyst"]], ), ] = [], sort_dir: Annotated[ str | None, Field( description="Sort direction for the results", examples=["asc", "desc"], ), ] = "asc", ) -> dict[str, Any]: """List all roles from your Panther instance. Returns list of roles with metadata including permissions and settings. """ logger.info("Fetching roles from Panther") try: # Prepare query parameters based on API spec params = {} if name_contains: params["name-contains"] = name_contains if name: params["name"] = name if role_ids: # Convert list to comma-delimited string as per API spec params["ids"] = ",".join(role_ids) if sort_dir: params["sort-dir"] = sort_dir async with get_rest_client() as client: result, _ = await client.get("/roles", params=params) # Extract roles and pagination info roles = result.get("results", []) next_cursor = result.get("next") # Keep only specific fields for each role to limit the amount of data returned filtered_roles_metadata = [ { "id": role["id"], "name": role.get("name"), "permissions": role.get("permissions"), "logTypeAccess": role.get("logTypeAccess"), "logTypeAccessKind": role.get("logTypeAccessKind"), "createdAt": role.get("createdAt"), "updatedAt": role.get("updatedAt"), } for role in roles ] logger.info(f"Successfully retrieved {len(filtered_roles_metadata)} roles") return { "success": True, "roles": filtered_roles_metadata, "total_roles": len(filtered_roles_metadata), "has_next_page": bool(next_cursor), "next_cursor": next_cursor, } except Exception as e: logger.error(f"Failed to list roles: {str(e)}") return {"success": False, "message": f"Failed to list roles: {str(e)}"}