JoeSandboxMCP

Instructions

Implementation Reference

• jbxmcp/tools.py:744-770 (handler)

  The MCP tool handler function for 'get_pcap_file', decorated with @mcp.tool(). It defines the input schema via type hints and docstring, handles errors, and delegates to the core helper function.
  @mcp.tool() async def get_pcap_file(webid: str, run: int = 0, save_path: Optional[str] = None) -> Dict[str, Any]: """ Retrieve the network traffic capture (PCAP) file from a sandbox analysis. This tool downloads the full packet capture generated during execution of the submitted sample. The PCAP file contains all recorded network traffic for the specified sandbox run, including DNS requests, HTTP traffic, and raw TCP/UDP communications. The PCAP is saved locally with the name `{webid}-{run}.pcap`. If a custom `save_path` is provided, the file is written to that directory. If the path is invalid or inaccessible, the file is saved to a fallback directory named `pcap/`. Args: webid (required): The submission ID of the analysis. run (optional, default = 0): Index of the sandbox run to retrieve. save_path (optional): Custom directory to save the PCAP file. If invalid, a fallback location is used. Returns: A dictionary containing: - output_file: Absolute path to the downloaded PCAP file. - note: Message indicating whether the fallback directory was used. """ try: return await download_pcap_file(webid, run, save_path) except Exception as e: return { "error": f"Failed to download pcap file for submission ID '{webid}' run {run}." f"Reason: {str(e)}" }
• jbxmcp/core.py:382-419 (helper)

  Core helper function that downloads the PCAP file from Joe Sandbox API using jbxapi client. Handles unified or legacy PCAP types, manages save paths with fallback, and writes the file to disk.
  async def download_pcap_file(webid: str, run: Optional[int] = 0, save_path: Optional[str] = None) -> Dict[str, Any]: jbx_client = get_client() try: _, data = jbx_client.analysis_download(webid=webid, run=run, type='pcapunified') except Exception as e: _, data = jbx_client.analysis_download(webid=webid, type='pcap') filename = f"{webid}-{run}.pcap" default_output_dir = os.path.join("pcap") output_dir = default_output_dir used_default_path = False if save_path: try: os.makedirs(save_path, exist_ok=True) output_dir = save_path except (OSError, FileNotFoundError): os.makedirs(default_output_dir, exist_ok=True) used_default_path = True else: os.makedirs(default_output_dir, exist_ok=True) full_path = os.path.abspath(os.path.join(output_dir, filename)) with open(full_path, "wb") as f: f.write(data) note = ( "User-provided save_path was invalid. Default directory was used." if used_default_path else "PCAP download completed successfully." ) return { "output_file": full_path, "note": note }
• jbxmcp/server.py:19-20 (registration)

  Import of the tools module in the server.py, which executes the @mcp.tool() decorators on all tool functions including get_pcap_file, thereby registering them with the MCP server instance 'mcp'.
  import jbxmcp.tools as tools