list_roles
Retrieve a detailed list of roles from Panther instances, including metadata like permissions and settings. Filter by role name, IDs, or sort results to streamline role management and access control.
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 | No | Exact match for a role's name. If provided, other parameters are ignored | |
| name_contains | No | Case-insensitive substring to search for within the role name | |
| role_ids | No | List of specific role IDs to return | |
| sort_dir | No | Sort direction for the results | asc |
Implementation Reference
- Full definition of the list_roles tool, including @mcp_tool decorator for registration, Pydantic input schema via Annotated[Field(...)], and handler logic that queries Panther /roles API with optional filters (name_contains, name, role_ids, sort_dir), processes pagination, filters metadata, handles errors.@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)}"}
- src/mcp_panther/panther_mcp_core/tools/__init__.py:25-38 (registration)Imports the 'roles' tool module (line 33: roles,) ensuring the @mcp_tool decorator on list_roles is executed and the function is added to the tool registry.from . import ( alerts, data_lake, data_models, detections, global_helpers, metrics, permissions, roles, scheduled_queries, schemas, sources, users, )
- src/mcp_panther/server.py:75-75 (registration)Calls register_all_tools(mcp) which registers all tools in the registry (including list_roles) with the FastMCP server instance by calling mcp_instance.tool() for each.register_all_tools(mcp)