submit_analysis_job

Submit files, URLs, websites, or command lines for sandbox analysis to detect malware and security threats with configurable parameters.

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

Input Schema

TableJSON Schema

Name	Required	Description	Default
`wait_for_analysis_end`	Yes
`timeout`	No
`sample_path`	No
`sample_url`	No
`website_url`	No
`command_line`	No
`tags`	No
`analysis_time`	No
`internet_access`	No
`hybrid_code_analysis`	No
`report_cache`	No
`powershell_logging`	No
`ssl_inspection`	No
`vba_instrumentation`	No
`js_instrumentation`	No
`java_jar_tracing`	No
`start_as_normal_user`	No
`email_notification`	No
`secondary_results`	No
`archive_password`	No
`command_line_argument`	No

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)

JoeSandboxMCP