JoeSandboxMCP

Instructions

List recent analyses submitted by the user.

This tool returns a summary of the most recent sandbox analyses performed in the current account. Each entry includes the submission ID and a minimal set of metadata useful for follow-up actions such as downloading artifacts or examining behavior.

By default, the tool returns the latest 20 analyses. You can override the `limit` parameter to retrieve more or fewer entries.

For each analysis, the following fields are returned:
    - webid: Unique submission identifier.
    - time: Timestamp of when the analysis was submitted.
    - filename: Original submitted filename or URL.
    - sha256: SHA-256 hash of the submitted object.
    - score: Final detection score assigned by the sandbox.
    - detection: Verdict (e.g., clean, suspicious, malicious).
    - classification: Malware family or type (if available).
    - threatname: Named threat label (e.g., campaign or actor), if detected.
    - systems: List of sandbox systems the sample was run on.
    - num_runs: Total number of sandbox executions (runs) for this submission.

Args:
    limit (optional, default = 20): The number of most recent analyses to return.

Returns:
    A list of dictionaries summarizing each recent analysis.

Implementation Reference

• jbxmcp/tools.py:771-799 (handler)

  The @mcp.tool()-decorated async handler function implementing the tool logic. It wraps the synchronous core helper in asyncio.to_thread for async compatibility.

  @mcp.tool()
  async def get_list_of_recent_analyses(limit: int = 20) -> List[Dict[str, Any]]:
      """
      List recent analyses submitted by the user.
  
      This tool returns a summary of the most recent sandbox analyses performed in the current account. Each entry includes the submission ID and a minimal set of metadata useful for follow-up actions such as downloading artifacts or examining behavior.
  
      By default, the tool returns the latest 20 analyses. You can override the `limit` parameter to retrieve more or fewer entries.
  
      For each analysis, the following fields are returned:
          - webid: Unique submission identifier.
          - time: Timestamp of when the analysis was submitted.
          - filename: Original submitted filename or URL.
          - sha256: SHA-256 hash of the submitted object.
          - score: Final detection score assigned by the sandbox.
          - detection: Verdict (e.g., clean, suspicious, malicious).
          - classification: Malware family or type (if available).
          - threatname: Named threat label (e.g., campaign or actor), if detected.
          - systems: List of sandbox systems the sample was run on.
          - num_runs: Total number of sandbox executions (runs) for this submission.
  
      Args:
          limit (optional, default = 20): The number of most recent analyses to return.
  
      Returns:
          A list of dictionaries summarizing each recent analysis.
      """
      return await asyncio.to_thread(list_recent_analyses, limit)

• jbxmcp/core.py:420-446 (helper)

  The core synchronous helper function that performs the actual API calls to list recent analyses using Joe Sandbox client, collecting metadata up to the specified limit.

  def list_recent_analyses(limit: int = 20) -> List[Dict[str, Any]]:
      jbx_client = get_client()
      results = []
  
      for each in jbx_client.analysis_list_paged():
          info = jbx_client.analysis_info(webid=each["webid"])
  
          systems = list({run.get("system") for run in info.get("runs", []) if run.get("system")})
          num_runs = len(info.get("runs", []))
  
          results.append({
              "webid": info.get("webid"),
              "time": info.get("time"),
              "filename": info.get("filename"),
              "sha256": info.get("sha256"),
              "score": info.get("score"),
              "detection": info.get("detection"),
              "classification": info.get("classification"),
              "threatname": info.get("threatname"),
              "systems": systems,
              "num_runs": num_runs,
          })
  
          if len(results) >= limit:
              break
  
      return results

• jbxmcp/server.py:19-19 (registration)

  Import of the tools module in the server.py, which executes the @mcp.tool() decorators on all tool functions including get_list_of_recent_analyses, registering them with the FastMCP instance.

  import jbxmcp.tools as tools