JoeSandboxMCP

Instructions

Implementation Reference

• jbxmcp/tools.py:38-149 (handler)

  The primary handler for the 'submit_analysis_job' MCP tool. This async function is decorated with @mcp.tool(), defines the tool's input schema via type hints and defaults, includes comprehensive documentation, merges user-provided parameters, handles timeouts, and invokes the core make_submission helper to interact with the Joe Sandbox API.
  @mcp.tool() async def submit_analysis_job( wait_for_analysis_end: bool, timeout: Optional[int] = 1200, sample_path: Optional[str] = None, sample_url: Optional[str] = None, website_url: Optional[str] = None, command_line: Optional[str] = None, tags: Optional[List[str]] = None, analysis_time: int = 120, internet_access: bool = True, hybrid_code_analysis: bool = True, report_cache: bool = False, powershell_logging: bool = False, ssl_inspection: bool = True, vba_instrumentation: bool = True, js_instrumentation: bool = True, java_jar_tracing: bool = True, start_as_normal_user: bool = False, email_notification: bool = False, secondary_results: bool = False, archive_password: Optional[str] = None, command_line_argument: Optional[str] = None, ) -> str: """ Submit a file, URL, website, or command line for sandbox analysis using Joe Sandbox. This tool analyzes one of the following: - A local file (`sample_path`) - A remote file URL (`sample_url`) - A website to visit (`website_url`) - A raw command line to execute (`command_line`) Only one input type must be provided. The rest of the arguments configure how the analysis is performed. For URL and website analysis, make sure `internet_access=True` to allow downloads or navigation. Args: wait_for_analysis_end: If True, the tool will block and wait until the sandbox analysis is complete before returning. If False, the tool returns immediately after submission. timeout (default: 1200): Max number of seconds to wait for analysis completion, this is only relevant if wait_for_analysis_end is True. File to Upload (required — provide exactly one): sample_path: Path to a local file to upload and analyze. sample_url: Direct download URL for a file to analyze. website_url: Website to visit and analyze in a browser. command_line: Command line string to execute in the sandbox. Sandbox configuration parameters (optional): tags (default: null): Optional tags for the submission. analysis_time (default: 120): Time in seconds to run the analysis. internet_access (default: True): Enable internet during analysis. report_cache (default: False): Use cached results if available. powershell_logging (default: False): Enable PowerShell script logging. ssl_inspection (default: True): Enable HTTPS inspection. vba_instrumentation (default: True): Instrument VBA macros. hybrid_code_analysis (default: True): Enable Hybrid Code Analysis (HCA). js_instrumentation (default: True): Instrument JavaScript. java_jar_tracing (default: True): Enable Java tracing. start_as_normal_user (default: False): Run the sample without admin privileges. email_notification (default: False): Send notification when complete. secondary_results (default: False): Generate post-analysis artifacts. archive_password (default: None): This password will be used to decrypt submitted archives (zip, 7z, rar etc.). command_line_argument (default: null): Startup arguments for the sample. Returns: A dictionary containing: - analyses: A list of extracted analysis entries, each with: - webid: Unique identifier for the individual analysis which can be used to retrieve results. - sha256: SHA-256 hash of the analyzed file or object. - filename: Name of the submitted file or artifact. - status: status of the analysis, either finished or running/submitted/accepted """ # Merge params params = { "tags": tags, "analysis-time": analysis_time, "internet-access": internet_access, "hybrid-code-analysis": hybrid_code_analysis, "report-cache": report_cache, "powershell-logging": powershell_logging, "ssl-inspection": ssl_inspection, "vba-instrumentation": vba_instrumentation, "js-instrumentation": js_instrumentation, "java-jar-tracing": java_jar_tracing, "start-as-normal-user": start_as_normal_user, "email-notification": email_notification, "secondary-results": secondary_results, "archive-password": archive_password, "command-line-argument": command_line_argument, } # Strip None values params = {k: v for k, v in params.items() if v is not None} # Call general handler try: result = await asyncio.wait_for(make_submission( wait_for_analysis_end, sample_path=sample_path, sample_url=sample_url, website_url=website_url, command_line=command_line, params=params, ), timeout=1200 ) except asyncio.TimeoutError: return { "final_status": "timeout", "message": f"Timed out after {timeout} seconds." } return result
• jbxmcp/core.py:154-205 (helper)

  Key helper function called by the tool handler to perform the actual submission. Validates exactly one input type is provided, uses the jbxapi client to submit file/url/website/command_line, and polls the submission status until completion if requested.
  async def make_submission( wait_for_analysis_end: bool, sample_path: Optional[str] = None, sample_url: Optional[str] = None, website_url: Optional[str] = None, command_line: Optional[str] = None, params: Optional[Dict[str, Any]] = None ) -> Dict[str, Any]: """ Submit a sample, URL, website, or command line for analysis. Only one of the input methods should be provided. Raises ValueError if none or multiple are given. Args: wait_for_analysis_end: wait until the analysis is finished before returning the result sample_path: Path to a local file. sample_url: URL of a remote sample file. website_url: Website URL to analyze. command_line: Command line string to analyze. params: Dictionary of sandbox parameters. Returns: A dict containing the submission result. Raises: ValueError: If none or multiple input methods are provided. """ params = params or {} client = get_client() # Check that exactly one input method is provided methods_provided = sum(bool(x) for x in [sample_path, sample_url, website_url, command_line]) if methods_provided != 1: raise ValueError("Exactly one of sample_path, sample_url, website_url, or command_line must be provided.") # Submit based on the input method if sample_path: def blocking_upload(): with open(sample_path, 'rb') as f: return client.submit_sample(f, params=params) submission_obj = await asyncio.to_thread(blocking_upload) elif sample_url: submission_obj = client.submit_sample_url(sample_url, params=params) elif website_url: submission_obj = client.submit_url(website_url, params=params) elif command_line: submission_obj = client.submit_command_line(command_line, params=params) return await poll_submission(submission_obj, wait_for_analysis_end)
• jbxmcp/server.py:19-19 (registration)

  Import of the tools module in the main server.py file. This executes the module, invoking the @mcp.tool() decorators which register 'submit_analysis_job' (and other tools) with the FastMCP instance.
  import jbxmcp.tools as tools
• jbxmcp/core.py:207-245 (helper)

  Supporting polling function used by make_submission to wait for analysis completion, querying submission status periodically and extracting webids, hashes, filenames, and status.
  async def poll_submission( submission_obj: Dict[str, Any], wait_for_analysis_end: bool, poll_interval: int = 3 ) -> Dict[str, Any]: """ Polls the submission state from Joe Sandbox API Args: submission_obj containing the submission id wait_for_analysis_end: True if the function should only return if the analysis has concluded """ def blocking_func(submission_id: str): return jbx_client.submission_info(submission_id=submission_id) jbx_client = get_client() await asyncio.sleep(5) # allow submission to initialize submission_id = submission_obj.get("submission_id") or submission_obj.get("submission-id") while True: info = await asyncio.to_thread(blocking_func, submission_id) # If not waiting, or analysis has completed if not wait_for_analysis_end or info.get("status") == "finished": analyses = info.get("analyses", []) result = { "analyses": [ { "webid": a.get("webid"), "sha256": a.get("sha256"), "filename": a.get("filename"), "status": info.get("status"), } for a in analyses ] } return result await asyncio.sleep(poll_interval)