scan_file_sandbox

Instructions

Implementation Reference

• src/threatzone_mcp/server.py:254-341 (handler)

  The primary handler for the 'scan_file_sandbox' tool. Decorated with @app.tool for MCP registration. Handles file validation, configuration assembly for ThreatZone sandbox analysis, and performs the API POST request with file upload.

  @app.tool
  async def scan_file_sandbox(
      file_path: str, 
      is_public: bool = False, 
      entrypoint: Optional[str] = None, 
      password: Optional[str] = None,
      environment: str = "w10_x64",
      timeout: int = 180,
      work_path: str = "desktop",
      mouse_simulation: bool = True,
      https_inspection: bool = False,
      internet_connection: bool = False,
      raw_logs: bool = False,
      snapshot: bool = False,
      sleep_evasion: bool = False,
      smart_tracing: bool = False,
      dump_collector: bool = False,
      open_in_browser: bool = False,
      extension_check: bool = True,
      modules: Optional[List[str]] = None,
      auto_config: bool = False
  ) -> Dict[str, Any]:
      """
      Submit a file for advanced sandbox analysis with detailed configuration.
      
      Args:
          file_path: Path to the file to analyze
          is_public: Whether the scan results should be public (default: False)
          entrypoint: File to execute within archive (if applicable)
          password: Password for archive files (if applicable)
          environment: Analysis environment - w7_x64, w10_x64, w11_x64, macos, android, linux (default: w10_x64)
          timeout: Analysis timeout in seconds - 60, 120, 180, 240, 300 (default: 180)
          work_path: Working directory - desktop, root, %AppData%, windows, temp (default: desktop)
          mouse_simulation: Enable mouse simulation (default: True)
          https_inspection: Enable HTTPS inspection (default: False)
          internet_connection: Enable internet connection (default: False)
          raw_logs: Include raw logs (default: False)
          snapshot: Take VM snapshots (default: False)
          sleep_evasion: Enable sleep evasion techniques (default: False)
          smart_tracing: Enable smart tracing (default: False)
          dump_collector: Enable dump collection (default: False)
          open_in_browser: Open files in browser (default: False)
          extension_check: Perform extension check (default: True)
          modules: Analysis modules to use, e.g., ["csi", "cdr"] (default: None)
          auto_config: Use automatic configuration (default: False)
      """
      if not Path(file_path).exists():
          raise ThreatZoneError(f"File not found: {file_path}")
      
      # Build the analyze configuration
      analyze_config = [
          {"metafieldId": "environment", "value": environment},
          {"metafieldId": "private", "value": not is_public},
          {"metafieldId": "timeout", "value": timeout},
          {"metafieldId": "work_path", "value": work_path},
          {"metafieldId": "mouse_simulation", "value": mouse_simulation},
          {"metafieldId": "https_inspection", "value": https_inspection},
          {"metafieldId": "internet_connection", "value": internet_connection},
          {"metafieldId": "raw_logs", "value": raw_logs},
          {"metafieldId": "snapshot", "value": snapshot},
          {"metafieldId": "sleep_evasion", "value": sleep_evasion},
          {"metafieldId": "smart_tracing", "value": smart_tracing},
          {"metafieldId": "dump_collector", "value": dump_collector},
          {"metafieldId": "open_in_browser", "value": open_in_browser}
      ]
      
      # Prepare form data
      data = {
          "analyzeConfig": json.dumps(analyze_config),
          "extensionCheck": str(extension_check).lower()
      }
      
      if entrypoint:
          data["entrypoint"] = entrypoint
      if password:
          data["password"] = password
      if modules:
          data["modules"] = ",".join(modules)
      
      # Build URL with auto parameter
      url = f"/public-api/scan/sandbox?auto={str(auto_config).lower()}"
      
      files = {"file": open(file_path, "rb")}
      try:
          return await get_client().post(url, data=data, files=files)
      finally:
          files["file"].close()

• src/threatzone_mcp/server.py:254-254 (registration)

  FastMCP decorator that registers the scan_file_sandbox function as an MCP tool with the name matching the function name.

  @app.tool

• src/threatzone_mcp/server.py:343-369 (helper)

  A helper tool 'scan_file_sandbox_simple' that provides a simplified interface by calling the main scan_file_sandbox with default parameters and auto_config=True.

  @app.tool
  async def scan_file_sandbox_simple(
      file_path: str, 
      is_public: bool = False, 
      entrypoint: Optional[str] = None, 
      password: Optional[str] = None
  ) -> Dict[str, Any]:
      """
      Submit a file for simple sandbox analysis using default settings.
      
      This is a simplified version of scan_file_sandbox with default configurations.
      Use scan_file_sandbox for advanced configuration options.
      
      Args:
          file_path: Path to the file to analyze
          is_public: Whether the scan results should be public (default: False)
          entrypoint: File to execute within archive (if applicable)
          password: Password for archive files (if applicable)
      """
      return await scan_file_sandbox(
          file_path=file_path,
          is_public=is_public,
          entrypoint=entrypoint,
          password=password,
          auto_config=True  # Use automatic configuration for simplicity
      )

• src/threatzone_mcp/server.py:102-110 (helper)

  Utility function to lazily initialize and return the ThreatZone API client used by scan_file_sandbox.

  def get_client():
      """Get or create the API client."""
      global client
      if client is None:
          if not API_KEY:
              raise ThreatZoneError("THREATZONE_API_KEY environment variable is required")
          client = APIClient(API_KEY)
      return client