list_threat_actors
Search and browse threat actors to discover recent additions, filter by name or UUID, and generate threat intelligence reports with pagination and sorting options.
Instructions
Get threat actors
Use this tool when you need to search, browse, or list multiple threat actors. This is particularly useful for:
Discovering recently added threat actors in the database
Searching for specific threat actors by name
Creating reports on threat actor landscapes
Building comprehensive threat intelligence briefings
Comparing multiple threat actors
Args:
filter (str, optional): A string used to filter threat actors. It can start with specific prefixes:
* name:: Filter by Name.
* uuid:: Filter by UUID.
* If no prefix is provided, it defaults to a name filter.
Defaults to "".
offset (int, optional): The number of items to skip before starting to collect the result set.
Defaults to 0.
limit (int, optional): The maximum number of items to return. Minimum value is 1.
Defaults to 10 (API default is 100).
sort (str, optional): Field to sort by - either 'name', 'created_at', or 'updated_at'.
Defaults to 'created_at'.
order (str, optional): Sort order - either 'asc' or 'desc'.
Defaults to 'desc'.
Returns: Dict[str, Any]: Dictionary containing: - total: Total number of threat actors matching the filter criteria - offset: Current pagination offset - limit: Number of items returned per page - message: Status message (usually null when successful) - data: List of threat actor records, each containing: - uuid: Unique identifier for the threat actor - name: Machine-readable name (typically lowercase with underscores) - display_name: Human-readable name with proper formatting - gen_description: Generated description (if available) - misp_uuid: Reference ID in MISP (Malware Information Sharing Platform) - created_at: Timestamp when this record was first added - updated_at: Timestamp when this record was last modified - enriched_at: Timestamp when this record was last enriched with additional data
Note: This function returns summary information about threat actors. To get detailed information including mentions and intelligence sources for a specific threat actor, use the get_threat_actor() function with the uuid or name.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| offset | No | ||
| limit | No | ||
| sort | No | created_at | |
| order | No | desc |
Implementation Reference
- The handler function for the 'list_threat_actors' MCP tool, registered via @mcp.tool() decorator. Includes input parameters, comprehensive docstring defining schema, and proxies the call to the underlying MalloryAI client API.
@mcp.tool() @handle_api_errors async def list_threat_actors( filter: str = "", offset: int = 0, limit: int = 10, sort: str = "created_at", order: str = "desc", ) -> Dict[str, Any]: """Get threat actors Use this tool when you need to search, browse, or list multiple threat actors. This is particularly useful for: - Discovering recently added threat actors in the database - Searching for specific threat actors by name - Creating reports on threat actor landscapes - Building comprehensive threat intelligence briefings - Comparing multiple threat actors Args: filter (str, optional): A string used to filter threat actors. It can start with specific prefixes: * `name:`: Filter by Name. * `uuid:`: Filter by UUID. * If no prefix is provided, it defaults to a name filter. Defaults to "". offset (int, optional): The number of items to skip before starting to collect the result set. Defaults to 0. limit (int, optional): The maximum number of items to return. Minimum value is 1. Defaults to 10 (API default is 100). sort (str, optional): Field to sort by - either 'name', 'created_at', or 'updated_at'. Defaults to 'created_at'. order (str, optional): Sort order - either 'asc' or 'desc'. Defaults to 'desc'. Returns: Dict[str, Any]: Dictionary containing: - total: Total number of threat actors matching the filter criteria - offset: Current pagination offset - limit: Number of items returned per page - message: Status message (usually null when successful) - data: List of threat actor records, each containing: - uuid: Unique identifier for the threat actor - name: Machine-readable name (typically lowercase with underscores) - display_name: Human-readable name with proper formatting - gen_description: Generated description (if available) - misp_uuid: Reference ID in MISP (Malware Information Sharing Platform) - created_at: Timestamp when this record was first added - updated_at: Timestamp when this record was last modified - enriched_at: Timestamp when this record was last enriched with additional data Note: This function returns summary information about threat actors. To get detailed information including mentions and intelligence sources for a specific threat actor, use the get_threat_actor() function with the uuid or name. """ return await malloryai_client.threat_actors.list_threat_actors( filter=filter, offset=offset, limit=limit, sort=sort, order=order ) - malloryai/mcp/server/server.py:16-35 (registration)Dynamic registration mechanism that imports all tool modules (including threat_actors.py), triggering the @mcp.tool() decorators to register the list_threat_actors tool.
def load_tools(): """Dynamically load all tool modules in the tools package""" # Get the tools directory tools_dir = Path(__file__).resolve().parent.parent / "tools" # Find all Python modules in the tools directory for _, module_name, _ in pkgutil.iter_modules([str(tools_dir)]): # Skip the __init__ module if module_name != "__init__": # Import the module importlib.import_module(f"malloryai.mcp.tools.{module_name}") debug_log(f"Loaded tool: {module_name}") def initialize_server(): """Initialize the server by loading all tools""" try: debug_log("Starting tool loading...") load_tools() debug_log("Tools loaded successfully")