submit_analysis_job

Instructions

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

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)