get_memory_dumps

Instructions

Download and extract memory dumps from a Joe Sandbox analysis.

This tool retrieves the 'memdumps' archive from the specified analysis run and extracts
all contents into a local directory for further inspection. These files represent raw 
memory snapshots taken during execution.

Files are extracted as-is without renaming or classification.

Output path logic:
- If `save_path` is valid, dumps go to `{save_path}/memdumps/{webid}`
- If not, fallback is `memdumps/{webid}` under the current directory

Args:
    webid (str): Joe Sandbox analysis ID
    run (int, optional): Run index (default: 0)
    save_path (str, optional): Optional base path to save dumps

Returns:
    dict: {
        "output_directory": absolute path to extraction folder,
        "info": "Info string detailing how many memory dumps were downloaded"
        "note": status message (e.g. fallback notice)
    }

Implementation Reference

• jbxmcp/tools.py:801-835 (handler)

  The primary handler function for the 'get_memory_dumps' MCP tool. It is decorated with @mcp.tool() for registration and schema inference, includes input validation via type hints and detailed docstring for IO schema, and delegates the core logic to download_memory_dumps while adding error handling.

  @mcp.tool()
  async def get_memory_dumps(webid: str, run: int = 0, save_path: Optional[str] = None) -> Dict[str, Any]:
      """
      Download and extract memory dumps from a Joe Sandbox analysis.
  
      This tool retrieves the 'memdumps' archive from the specified analysis run and extracts
      all contents into a local directory for further inspection. These files represent raw 
      memory snapshots taken during execution.
  
      Files are extracted as-is without renaming or classification.
  
      Output path logic:
      - If `save_path` is valid, dumps go to `{save_path}/memdumps/{webid}`
      - If not, fallback is `memdumps/{webid}` under the current directory
  
      Args:
          webid (str): Joe Sandbox analysis ID
          run (int, optional): Run index (default: 0)
          save_path (str, optional): Optional base path to save dumps
  
      Returns:
          dict: {
              "output_directory": absolute path to extraction folder,
              "info": "Info string detailing how many memory dumps were downloaded"
              "note": status message (e.g. fallback notice)
          }
      """
      try:
          return await download_memory_dumps(webid, run, save_path)
      except Exception as e:
          return {
              "error": f"Failed to download memory dumps for submission ID '{webid}' run {run}. "
                       f"Reason: {str(e)}"
          }

• jbxmcp/core.py:464-507 (helper)

  Supporting utility function that performs the actual download of the memdumps ZIP from Joe Sandbox API using jbxapi client, handles directory creation with fallback logic, extracts the ZIP contents, lists the extracted files, and returns structured output including paths and counts.

  async def download_memory_dumps(
      webid: str,
      run: Optional[int] = 0,
      save_path: Optional[str] = None
  ) -> Dict[str, Any]:
      jbx_client = get_client()
  
      _, data = jbx_client.analysis_download(webid=webid, run=run, type="memdumps")
  
      default_output_dir = os.path.join("memdumps", f"{webid}-{run}")
      output_dir = default_output_dir
      used_default_path = False
  
      if save_path:
          try:
              output_dir = os.path.join(save_path, "memdumps", f"{webid}-{run}")
              os.makedirs(output_dir, exist_ok=True)
          except (OSError, FileNotFoundError):
              output_dir = default_output_dir
              os.makedirs(output_dir, exist_ok=True)
              used_default_path = True
      else:
          os.makedirs(output_dir, exist_ok=True)
  
      extracted_files: list[str] = []
      with zipfile.ZipFile(io.BytesIO(data)) as zf:
          zf.extractall(path=output_dir)
  
          for name in zf.namelist():
              if name.endswith("/"):
                  continue
              extracted_files.append(os.path.abspath(os.path.join(output_dir, name)))
  
      note = (
          "User-provided save_path was invalid. Default directory was used."
          if used_default_path
          else "Extraction completed successfully."
      )
  
      return {
          "output_directory": os.path.abspath(output_dir),
          "info": f"{len(extracted_files)} memory dumps downloaded",
          "note": note,
      }