JoeSandboxMCP

Instructions

Retrieve high-impact signature detections from a sandbox analysis report.

This tool extracts detection signatures triggered during the specified analysis run. These signatures reflect behavioral or static patterns typically associated with malware, such as code injection, credential theft, or suspicious memory activity as well as general behavioural indicators.
Optional filtering parameters allow control over the inclusion of all signatures or only those with high impact.

Args:
    webid (required): The submission ID of the analysis.
    run (optional, default = 0): Index of the sandbox run to inspect (from the `runs` array in analysis info). Use 0 for the first run.
    only_malicious_indicators (default: True): If True, limits the returned signatures to those considered high impact by the detection logic.

Returns:
    A dictionary containing a list of triggered detection signatures. Each entry includes:
    - desc: Description of the detected malicious behavior or technique.
    - indicators: List of up to three supporting observations. Each indicator includes:
        - desc: Action or operation that triggered the detection (e.g., "Section loaded").
        - context: Process name or source related to the event.
        - evidence: Supporting detail, such as file paths, memory dumps, or rule names.
        - impact: Either "high" or "low", indicating the severity or confidence of the detection.  
            High-impact indicators are strongly associated with malicious behavior or confirmed threats.  
            Low-impact indicators reflect general behavior or environmental traits that may not be malicious on their own.

Implementation Reference

• jbxmcp/tools.py:645-701 (handler)

  The core handler function decorated with @mcp.tool() that implements the get_signature_info tool. It fetches the analysis report XML, parses the signatureinfo section, filters signatures by impact, extracts up to 3 sources per signature, and returns structured data.

  @mcp.tool()
  async def get_signature_info(webid: str, run: int = 0, only_malicious_indicators: bool = True) -> Dict[str, Any]:
      """
      Retrieve high-impact signature detections from a sandbox analysis report.
  
      This tool extracts detection signatures triggered during the specified analysis run. These signatures reflect behavioral or static patterns typically associated with malware, such as code injection, credential theft, or suspicious memory activity as well as general behavioural indicators.
      Optional filtering parameters allow control over the inclusion of all signatures or only those with high impact.
  
      Args:
          webid (required): The submission ID of the analysis.
          run (optional, default = 0): Index of the sandbox run to inspect (from the `runs` array in analysis info). Use 0 for the first run.
          only_malicious_indicators (default: True): If True, limits the returned signatures to those considered high impact by the detection logic.
  
      Returns:
          A dictionary containing a list of triggered detection signatures. Each entry includes:
          - desc: Description of the detected malicious behavior or technique.
          - indicators: List of up to three supporting observations. Each indicator includes:
              - desc: Action or operation that triggered the detection (e.g., "Section loaded").
              - context: Process name or source related to the event.
              - evidence: Supporting detail, such as file paths, memory dumps, or rule names.
              - impact: Either "high" or "low", indicating the severity or confidence of the detection.  
                  High-impact indicators are strongly associated with malicious behavior or confirmed threats.  
                  Low-impact indicators reflect general behavior or environmental traits that may not be malicious on their own.
      """
      try:
          root = await get_or_fetch_report(webid, run)
          if root is None:
              return {"error": f"Could not retrieve or parse report for submission ID '{webid}' run {run}"}
          siginfo = root.findall("./signatureinfo/sig")
          sigs = []
          for entry in siginfo:
              attrs = entry.attrib
              is_malicious_indicator = float(attrs.get("impact", 0.0)) >= 2.0
              if is_malicious_indicator or not only_malicious_indicators:
                  sources = []
                  for source_entry in entry.findall("./sources/source"):
                      source_attrib = source_entry.attrib
                      source = {
                          "desc": source_attrib.get("op"),
                          "context": source_attrib.get("process"),
                          "evidence" : source_entry.text,
                          "impact": "high" if is_malicious_indicator else "low"
                      }
                      sources.append(source)
                      if len(sources) >= 3:
                          break
                  sig = {
                      "desc": attrs.get("desc"),
                      "indicators": sources
                  }
                  sigs.append(sig) 
          return sigs
      except Exception as e:
          return {
              "error": f"Failed to get signature info for submission ID '{webid}' run {run}. "
                       f"Reason: {str(e)}"
          }

• jbxmcp/core.py:100-133 (helper)

  Helper function used by get_signature_info to retrieve or fetch the XML report from cache or Joe Sandbox API.

  async def get_or_fetch_report(webid: str, run: int=0) -> Optional[ET.Element]:
      """
      Get a report from the cache or fetch it from the API.
      
      Args:
          webid: The webid of the report to retrieve.
          run: The analysis run index of the report to retrieve, default: 0
          
      Returns:
          The report as an XML Element, or None if it couldn't be retrieved.
      """
      cache_key = f"{webid}-{run}"
      cached = await report_cache.get(cache_key)
      if cached:
          xml_stream = io.BytesIO(cached)
          xml_tree = ET.parse(xml_stream)
          return xml_tree.getroot()
      
      # If not in cache, fetch from API
      def blocking_download():
          client = get_client()
          _, data = client.analysis_download(webid=webid, type='xml', run=run)
          return data
      
      try:
          data = await asyncio.to_thread(blocking_download)
          await report_cache.set(cache_key, data)
          xml_stream = io.BytesIO(data)
          xml_tree = ET.parse(xml_stream)
          xml_root = xml_tree.getroot()
          return xml_root
      except Exception as e:
          print(f"Error fetching report for webid {webid}, run {run}: {e}")
          return None

• jbxmcp/tools.py:2-17 (registration)

  The __all__ list in tools.py exports get_signature_info, allowing it to be imported and used after import jbxmcp.tools.

  __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'
  ]