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() for registration in the MCP framework and implements the tool logic by calling the core query_analysis_info helper, with error handling.
  @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)

  Core helper function that performs the actual API call to retrieve analysis information using the jbxapi client via a blocking thread to fetch analysis_info for the given webid.
  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:1-17 (registration)

  The __all__ list in tools.py exports the get_analysis_info tool function, facilitating its import and registration when the module is imported in server.py.
  __all__ = [ 'submit_analysis_job', 'search_analysis', 'get_analysis_info', 'get_ai_summaries', 'get_dropped_info', 'get_domain_info', 'get_ip_info', 'get_url_info', 'get_signature_info', 'get_unpacked_files', 'get_pcap_file', 'get_list_of_recent_analyses', 'get_process_info', 'get_memory_dumps' ]
• jbxmcp/server.py:19-19 (registration)

  Import of the tools module in the MCP server, which registers all @mcp.tool() decorated functions including get_analysis_info.
  import jbxmcp.tools as tools