JoeSandboxMCP

Instructions

Implementation Reference

• jbxmcp/tools.py:326-407 (handler)

  The core handler function for the 'get_dropped_info' tool. It parses the XML report from Joe Sandbox to extract information about dropped files, including hashes, sizes, processes, and malicious indicators. Decorated with @mcp.tool() for registration.
  @mcp.tool() async def get_dropped_info(webid: str, run: int = 0, only_malicious_elements: bool=True, only_malicious_indicators: bool=True) -> Dict[str, Any]: """ Retrieve metadata for files dropped in a completed analysis, along with their associated detection indicators. This tool returns information about dropped files for a specific sandbox run of an analysis. Each result includes relevant metadata and detection indicators where available. Args: webid (required): The submission ID of the analysis. run (optional, default = 0): The index of the analysis run to inspect. Use 0 for the first run, 1 for the second, etc. only_malicious_elements (default: True): If True, returns only dropped files 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 with: - webid: The analysis ID. - malicious_dropped_files: A list of dropped files marked as malicious, each with: - filename - sha256 - size - type - process (originating process) - dump_name (sandbox-internal reference) - category (e.g., "dropped", "modified") - 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. - count: Total number of malicious dropped files found Notes: - Empty Array returned if no dropped file 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}'"} dropped_files = root.findall('./droppedinfo/hash') results = [] for dropped in dropped_files: attrs = dropped.attrib if attrs.get("malicious", "").lower() == "true" or not only_malicious_elements: indicators = get_indicators(dropped, only_malicious_indicators) file_info = { "filename": attrs.get("file"), "sha256": attrs.get("value"), "type": attrs.get("type"), "size": attrs.get("size"), "process": attrs.get("process"), "dump_name": attrs.get("dump"), "category": attrs.get("category"), "indicators": indicators } for hash_entry in dropped.findall('./value'): key = hash_entry.attrib.get('algo') if key: file_info[key] = hash_entry.text.lower() # Drop any empty/null entries file_info = {k: v for k, v in file_info.items() if v} results.append(file_info) return { "webid": webid, "malicious_dropped_files": results, "count": len(results) } except Exception as e: return { "error": f"Failed to extract malicious dropped file data for submission ID '{webid}' run {run}. " f"Reason: {str(e)}" }
• jbxmcp/tools.py:2-17 (registration)

  The 'get_dropped_info' tool is listed in the module's __all__ export list, indicating it is publicly exposed as part of the tools 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' ]