JoeSandboxMCP

Instructions

Download all dropped files from a Joe Sandbox analysis.

This tool retrieves the 'dropped' archive from the specified analysis run and extracts
all contents into a local directory for further inspection.

Files are extracted as-is without renaming or classification.

Output path logic:
- If `save_path` is valid, dumps go to `{save_path}/droppedfiles/{webid}`
- If not, fallback is `droppedfiles/{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,
        "files": list of files with full path
        "note": status message (e.g. fallback notice)
    }

Implementation Reference

• jbxmcp/tools.py:836-869 (handler)

  The primary MCP tool handler for 'get_dropped_files'. Decorated with @mcp.tool() for automatic registration. Wraps the core download_dropped_files function, adding error handling and documentation.

  @mcp.tool()
  async def get_dropped_files(webid: str, run: int = 0, save_path: Optional[str] = None) -> Dict[str, Any]:
      """
      Download all dropped files from a Joe Sandbox analysis.
  
      This tool retrieves the 'dropped' archive from the specified analysis run and extracts
      all contents into a local directory for further inspection.
  
      Files are extracted as-is without renaming or classification.
  
      Output path logic:
      - If `save_path` is valid, dumps go to `{save_path}/droppedfiles/{webid}`
      - If not, fallback is `droppedfiles/{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,
              "files": list of files with full path
              "note": status message (e.g. fallback notice)
          }
      """
      try:
          return await download_dropped_files(webid, run, save_path)
      except Exception as e:
          return {
              "error": f"Failed to download dropped files for submission ID '{webid}' run {run}. "
                       f"Reason: {str(e)}"
          }

• jbxmcp/core.py:509-552 (helper)

  The core helper function implementing the download and extraction logic. Downloads the 'bins' ZIP archive from Joe Sandbox API (password-protected with 'infected'), extracts files to a directory (with fallback path handling), and returns file paths.

  async def download_dropped_files(
      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="bins")
  
      default_output_dir = os.path.join("droppedfiles", f"{webid}-{run}")
      output_dir = default_output_dir
      used_default_path = False
  
      if save_path:
          try:
              output_dir = os.path.join(save_path, "droppedfiles", 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, pwd=b"infected")
  
          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),
          "files": extracted_files,
          "note": note,
      }

• jbxmcp/server.py:19-19 (registration)

  Import of tools module in server.py, which executes the @mcp.tool() decorators to register all tools including get_dropped_files with the FastMCP server.

  import jbxmcp.tools as tools