search_analysis
Search the JoeSandbox Cloud for malware analyses using structured parameters like file hashes, threat names, detection status, and dates to identify security threats.
Instructions
Search the JoeSandbox Cloud for malware analyses using structured search parameters.
Args:
- md5, sha1, sha256: Exact match
- filename, url, tag, comments, ioc_url, ioc_dropped-file: Substring match
- detection: One of 'clean', 'suspicious', 'malicious', 'unknown'
- threatname: Exact match
- before_date, after-date: ISO 8601 format (YYYY-MM-DD). These are exclusive (the date itself is not included).
- ioc_domain, ioc_public_ip: Exact match
Notes:
- You must provide at least one of the supported parameters.
- If multiple parameters are provided, all conditions must match (AND logic).
- Searches are case-insensitive.
- On the Cloud version, date comparisons use the CET/CEST time zone.
- The 'q' parameter is not supported and should not be used.
Examples:
{"md5": "661f3e4454258ca6ab1a4c31742916c0"}
{"threatname": "agenttesla", "before_date": "2024-12-01"}
{"filename": "agent.exe", "detection": "malicious"}Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| md5 | No | ||
| sha1 | No | ||
| sha256 | No | ||
| filename | No | ||
| url | No | ||
| tag | No | ||
| comments | No | ||
| ioc_url | No | ||
| ioc_dropped_file | No | ||
| detection | No | ||
| threatname | No | ||
| before_date | No | ||
| after_date | No | ||
| ioc_domain | No | ||
| ioc_public_ip | No |
Implementation Reference
- jbxmcp/tools.py:151-200 (handler)Primary handler for the 'search_analysis' MCP tool. Defines input parameters with types and docstring schema. Decorated with @mcp.tool() for automatic registration. Constructs query dict from args and delegates to make_search_request helper.
@mcp.tool() async def search_analysis( md5: Optional[str] = None, sha1: Optional[str] = None, sha256: Optional[str] = None, filename: Optional[str] = None, url: Optional[str] = None, tag: Optional[str] = None, comments: Optional[str] = None, ioc_url: Optional[str] = None, ioc_dropped_file: Optional[str] = None, detection: Optional[Literal["clean", "suspicious", "malicious", "unknown"]] = None, threatname: Optional[str] = None, before_date: Optional[str] = None, after_date: Optional[str] = None, ioc_domain: Optional[str] = None, ioc_public_ip: Optional[str] = None, ) -> str: """ Search the JoeSandbox Cloud for malware analyses using structured search parameters. Args: - md5, sha1, sha256: Exact match - filename, url, tag, comments, ioc_url, ioc_dropped-file: Substring match - detection: One of 'clean', 'suspicious', 'malicious', 'unknown' - threatname: Exact match - before_date, after-date: ISO 8601 format (YYYY-MM-DD). These are exclusive (the date itself is not included). - ioc_domain, ioc_public_ip: Exact match Notes: - You must provide at least one of the supported parameters. - If multiple parameters are provided, all conditions must match (AND logic). - Searches are case-insensitive. - On the Cloud version, date comparisons use the CET/CEST time zone. - The 'q' parameter is not supported and should not be used. Examples: {"md5": "661f3e4454258ca6ab1a4c31742916c0"} {"threatname": "agenttesla", "before_date": "2024-12-01"} {"filename": "agent.exe", "detection": "malicious"} """ query = { k.replace('_', '-'): v for k, v in locals().items() if v is not None and k != "self" } res = await make_search_request(query) if not res: return "No results or an error occurred during the search." return str(res) - jbxmcp/core.py:135-153 (helper)Core helper function implementing the HTTP search request to Joe Sandbox API. Called by the search_analysis handler to execute the search query.
async def make_search_request(query_dict: Dict[str, str]) -> Optional[Dict[str, Any]]: """ Query jbxapi for a search in the existing analyses. Args: query_dict: A dictionary of search parameters. Returns: The search results as a dictionary, or None if the search failed. """ query_dict['apikey'] = os.getenv("JBXAPIKEY") async with httpx.AsyncClient() as client: try: response = await client.post(JBXCLOUD_APIURL + "v2/analysis/search", data=query_dict) return response.json() except Exception as e: print(f"Error during analysis search: {e}") return None - jbxmcp/tools.py:2-17 (registration)__all__ export list in tools.py includes 'search_analysis', facilitating module-level registration/import.
__all__ = [ 'submit_analysis_job', 'search_analysis', 'get_analysis_info', 'get_ai_summaries', 'get_dropped_info', 'get_domain_info', 'get_ip_info', 'get_url_info', 'get_signature_info', 'get_unpacked_files', 'get_pcap_file', 'get_list_of_recent_analyses', 'get_process_info', 'get_memory_dumps' ] - jbxmcp/tools.py:152-168 (schema)Function signature defines the input schema with optional parameters, types, and return type for the tool.
async def search_analysis( md5: Optional[str] = None, sha1: Optional[str] = None, sha256: Optional[str] = None, filename: Optional[str] = None, url: Optional[str] = None, tag: Optional[str] = None, comments: Optional[str] = None, ioc_url: Optional[str] = None, ioc_dropped_file: Optional[str] = None, detection: Optional[Literal["clean", "suspicious", "malicious", "unknown"]] = None, threatname: Optional[str] = None, before_date: Optional[str] = None, after_date: Optional[str] = None, ioc_domain: Optional[str] = None, ioc_public_ip: Optional[str] = None, ) -> str: