JoeSandboxMCP

Instructions

Implementation Reference

• jbxmcp/tools.py:580-644 (handler)

  The core handler function for the 'get_url_info' tool, decorated with @mcp.tool(). It parses the Joe Sandbox XML report to extract URL indicators of compromise (IOCs), filters by maliciousness, handles long URL truncation, attaches detection indicators using get_indicators helper, and returns a list of URL details.
  @mcp.tool() async def get_url_info(webid: str, run: int = 0, only_malicious_elements: bool=True, only_malicious_indicators: bool=True) -> Dict[str, Any]: """ Retrieve urls in a completed analysis, along with their associated detection indicators. This tool extracts urls gathered by the sandbox engine and returns relevant context such as ip address, source, and detection metadata. Optional filtering parameters allow control over the inclusion of urls and indicators based on their assessed severity. Args: webid (required): The submission ID of the analysis. run (default: 0): Index of the sandbox run to inspect (from the `runs` array in analysis info). only_malicious_elements (default: True): If True, returns only urls explicitly classified as malicious by the sandbox engine. only_malicious_indicators (default: True): If True, limits the returned indicators to those considered clearly malicious by the detection logic. This excludes low-impact behavioral signals and focuses on indicators with a high likelihood of malicious intent or confirmed threat classification. If False, all observed indicators are included regardless of their severity. Returns: A dictionary containing a list of malicious URLs. Each entry includes: - url: The observed URL (may be truncated if extremely long). - ip: The resolved IP address associated with the URL (if available). - fromMemory: Whether the URL was extracted from memory. - source: Subsystem or extraction context (e.g., browser, process). - malicious: 'true' for urls classified as malicious - indicators: List of triggered detection rules, if any. Each entry includes: - desc: Description of the matched detection rule. - data: Matched content or signature. - source: The detection subsystem responsible (e.g. Suricata, Sigma, global traffic etc.). - impact: Either "high" or "low", indicating the severity or confidence of the detection. High-impact indicators are strongly associated with malicious behavior or confirmed threats. Low-impact indicators reflect general behavior or environmental traits that may not be malicious on their own. Notes: - Very long URLs are truncated for readability but include their original length as a hint. - Empty Array returned if no url was gathered during the analysis """ try: root = await get_or_fetch_report(webid, run) if root is None: return {"error": f"Could not retrieve or parse report for submission ID '{webid}' run {run}"} urlinfo = root.findall("./urlinfo/url") urls = [] for url_entry in urlinfo: attrs = url_entry.attrib if attrs.get("malicious") == "true" or not only_malicious_elements: indicators = get_indicators(url_entry, only_malicious_indicators) url = attrs.get("name") orig_len = len(url) if len(url) > 150: url = url[:150] + f" <truncated url, orig length={orig_len}>" url = { "url": url, "ip": attrs.get("ip"), "fromMemory": attrs.get("fromMemory"), "source": attrs.get("source"), "malicious": attrs.get("malicious"), "indicators": indicators } urls.append(url) return urls except Exception as e: return { "error": f"Failed to get URL IOCs for submission ID '{webid}' run {run}. " f"Reason: {str(e)}" }
• jbxmcp/tools.py:2-17 (registration)

  The 'get_url_info' tool is exported via the __all__ list, making it available for import from the module.
  __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' ]