JoeSandboxMCP

Instructions

Implementation Reference

• jbxmcp/tools.py:202-253 (handler)

  The primary handler function for the 'get_analysis_info' tool. It is decorated with @mcp.tool() which registers it as an MCP tool. The function calls the helper query_analysis_info from core.py to fetch the data from Joe Sandbox API and handles any exceptions.
  @mcp.tool() async def get_analysis_info(webid: str) -> Dict[str, Any]: """ Retrieve metadata and status for a previously submitted analysis by its submission ID. Use this tool to check whether an analysis is finished, whether the sample was classified as malicious, and to retrieve contextual metadata such as score, system, and tags. Args: webid (required): The submission ID (also called webid) returned when the sample was uploaded. Returns: If successful, returns a dictionary with fields such as: - status (e.g. "finished", "in progress"): Global analysis state. - detection (e.g. "malicious", "clean"): Overall result summary. - score (integer, e.g. 0-100): The final aggregated threat score. - filename: The original filename or download URL of the submitted sample. - tags: A list of classification or behavioral tags. - scriptname: The Joe Sandbox script used to run the analysis. - has_malwareconfig: True if malware configuration extraction succeeded. - md5, sha1, sha256: Hashes of the submitted sample. - time: The ISO8601 timestamp when the analysis was submitted. - duration: Total time (in seconds) the analysis took. - classification: Internal or customer-specific label (if set). - comments: Analyst comments or notes. - encrypted: Whether the submitted file was password-protected. - threatname: Identified malware families or on behavioral or signature matches. - runs: A list of dictionaries describing individual analysis runs on different systems. Each run contains: - system: The sandbox environment used (e.g., "w7x64l", "w10x64", "lnxubuntu20"). - score: Detection score for that system. - detection: Result for that specific system (e.g., "malicious", "clean"). - yara, sigma, suricata: Boolean flags indicating whether detection engines matched. - error: Any error that occurred during that specific run. Notes: - The `runs` array is useful when the same sample is executed on multiple OS environments. - The top-level `score` and `detection` reflect the most severe result across all runs. If the submission ID is invalid or expired, returns an error object with a reason. """ try: result = await query_analysis_info(webid) return result except Exception as e: return { "error": f"Could not retrieve analysis info for submission ID '{webid}'. " f"Reason: {str(e)}" }
• jbxmcp/core.py:247-263 (helper)

  Supporting utility function in core.py that performs the actual synchronous API call to Joe Sandbox using the client.analysis_info method, wrapped in asyncio.to_thread for async compatibility.
  async def query_analysis_info(webid: str) -> Dict[str, Any]: """ Query information about an analysis. Args: webid: The webid of the analysis to query. Returns: A dictionary containing information about the analysis. """ client = get_client() def blocking_query(): return client.analysis_info(webid=webid) return await asyncio.to_thread(blocking_query)
• jbxmcp/tools.py:202-253 (registration)

  The @mcp.tool() decorator registers the function as an MCP tool, making it available via the FastMCP server in server.py.
  @mcp.tool() async def get_analysis_info(webid: str) -> Dict[str, Any]: """ Retrieve metadata and status for a previously submitted analysis by its submission ID. Use this tool to check whether an analysis is finished, whether the sample was classified as malicious, and to retrieve contextual metadata such as score, system, and tags. Args: webid (required): The submission ID (also called webid) returned when the sample was uploaded. Returns: If successful, returns a dictionary with fields such as: - status (e.g. "finished", "in progress"): Global analysis state. - detection (e.g. "malicious", "clean"): Overall result summary. - score (integer, e.g. 0-100): The final aggregated threat score. - filename: The original filename or download URL of the submitted sample. - tags: A list of classification or behavioral tags. - scriptname: The Joe Sandbox script used to run the analysis. - has_malwareconfig: True if malware configuration extraction succeeded. - md5, sha1, sha256: Hashes of the submitted sample. - time: The ISO8601 timestamp when the analysis was submitted. - duration: Total time (in seconds) the analysis took. - classification: Internal or customer-specific label (if set). - comments: Analyst comments or notes. - encrypted: Whether the submitted file was password-protected. - threatname: Identified malware families or on behavioral or signature matches. - runs: A list of dictionaries describing individual analysis runs on different systems. Each run contains: - system: The sandbox environment used (e.g., "w7x64l", "w10x64", "lnxubuntu20"). - score: Detection score for that system. - detection: Result for that specific system (e.g., "malicious", "clean"). - yara, sigma, suricata: Boolean flags indicating whether detection engines matched. - error: Any error that occurred during that specific run. Notes: - The `runs` array is useful when the same sample is executed on multiple OS environments. - The top-level `score` and `detection` reflect the most severe result across all runs. If the submission ID is invalid or expired, returns an error object with a reason. """ try: result = await query_analysis_info(webid) return result except Exception as e: return { "error": f"Could not retrieve analysis info for submission ID '{webid}'. " f"Reason: {str(e)}" }