JoeSandboxMCP

Instructions

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

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'
  ]