JoeSandboxMCP

Instructions

Implementation Reference

• jbxmcp/tools.py:463-519 (handler)

  The core handler function for the 'get_domain_info' MCP tool. Decorated with @mcp.tool() for registration. Parses the Joe Sandbox XML report to extract domain information, applies filtering based on malicious flags and indicator severity, and structures the output with relevant attributes and indicators.
  @mcp.tool() async def get_domain_info(webid: str, run: int = 0, only_malicious_elements: bool=True, only_malicious_indicators: bool=True) -> Dict[str, Any]: """ Retrieve domains in a completed analysis, along with their associated detection indicators. This tool extracts domains gathered by the sandbox engine and returns relevant context such as resolved IP address, activity status, and detection metadata. Optional filtering parameters allow control over the inclusion of domains and indicators based on their assessed severity. Args: webid (required): The submission ID of the analysis. run (default: 0): Index of the sandbox run to inspect (from the `runs` array in analysis info). only_malicious_elements (default: True): If True, returns only domains explicitly classified as malicious by the sandbox engine. only_malicious_indicators (default: True): If True, limits the returned indicators to those considered clearly malicious by the detection logic. This excludes low-impact behavioral signals and focuses on indicators with a high likelihood of malicious intent or confirmed threat classification. If False, all observed indicators are included regardless of their severity. Returns: A dictionary containing a list of malicious domains. Each entry includes: - name: The domain name. - ip: The resolved IP address, if available. - active: Whether the domain was reachable during analysis. - malicious: 'true' for domains classified as malicious - indicators: List of triggered detection rules, if any. Each entry includes: - desc: Description of the matched detection rule. - data: Matched content or signature. - source: The detection subsystem responsible (e.g. Suricata, Sigma, global traffic etc.). - 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. Notes: - Empty Array returned if no domain was gathered during the analysis """ 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}"} domaininfo = root.findall("./domaininfo/domain") domains = [] for domain_entry in domaininfo: attrs = domain_entry.attrib if attrs.get("malicious") == "true" or not only_malicious_elements: indicators = get_indicators(domain_entry, only_malicious_indicators) domain = { "name": attrs.get("name"), "ip": attrs.get("ip"), "active": attrs.get("active"), "malicious": attrs.get("malicious"), "indicators": indicators } domains.append(domain) return domains except Exception as e: return { "error": f"Failed to get domain info for submission ID '{webid}' run {run}. " f"Reason: {str(e)}" }
• jbxmcp/tools.py:2-17 (registration)

  The __all__ list exports 'get_domain_info' as a public tool, indicating its availability for import and use.
  __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/tools.py:464-494 (schema)

  Function signature and comprehensive docstring define the input schema (webid: str required, run: int=0, only_malicious_elements: bool=True, only_malicious_indicators: bool=True) and output schema (Dict with list of domains including name, ip, active, malicious, indicators).
  async def get_domain_info(webid: str, run: int = 0, only_malicious_elements: bool=True, only_malicious_indicators: bool=True) -> Dict[str, Any]: """ Retrieve domains in a completed analysis, along with their associated detection indicators. This tool extracts domains gathered by the sandbox engine and returns relevant context such as resolved IP address, activity status, and detection metadata. Optional filtering parameters allow control over the inclusion of domains and indicators based on their assessed severity. Args: webid (required): The submission ID of the analysis. run (default: 0): Index of the sandbox run to inspect (from the `runs` array in analysis info). only_malicious_elements (default: True): If True, returns only domains explicitly classified as malicious by the sandbox engine. only_malicious_indicators (default: True): If True, limits the returned indicators to those considered clearly malicious by the detection logic. This excludes low-impact behavioral signals and focuses on indicators with a high likelihood of malicious intent or confirmed threat classification. If False, all observed indicators are included regardless of their severity. Returns: A dictionary containing a list of malicious domains. Each entry includes: - name: The domain name. - ip: The resolved IP address, if available. - active: Whether the domain was reachable during analysis. - malicious: 'true' for domains classified as malicious - indicators: List of triggered detection rules, if any. Each entry includes: - desc: Description of the matched detection rule. - data: Matched content or signature. - source: The detection subsystem responsible (e.g. Suricata, Sigma, global traffic etc.). - 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. Notes: - Empty Array returned if no domain was gathered during the analysis """