How holaOS Handles Privacy: macOS Permissions and SSRF Protection

holaOS protects user privacy through a dual-layer approach: macOS system-level permission handling via the open_macos_settings tool and network-level SSRF protection through ssrfSafeFetch validation that blocks private IP ranges.

The holaboss-ai/holaOS repository implements a comprehensive privacy model designed for secure AI agent operations. Understanding how holaOS handles privacy reveals two distinct security layers: operating system permission management for macOS and server-side request forgery (SSRF) prevention for all external network communications.

macOS System-Level Permission Management

The open_macos_settings Tool Implementation

In runtime/api-server/src/runtime-agent-tools.ts (lines 6035-6082), the openMacosSettings function provides the runtime interface for macOS privacy controls. When an agent encounters a permission failure for Screen Recording, Accessibility, or Full Disk Access, it invokes this tool to open the specific System Settings → Privacy & Security pane.

The implementation first attempts to register Holaboss with macOS through the desktop bridge, triggering the native permission prompt. When successful, the system displays the standard macOS dialog requesting user consent for the specific capability.

Desktop Bridge Integration and Fallback Logic

The tool implements a two-tier execution strategy to ensure reliability:

1. Primary path: Uses the desktop bridge (Electron main process) to call POST /api/v1/macos-permission
2. Fallback path: Invokes the host open command with x-apple.systempreferences:com.apple.preference.security?{anchor} URLs

If the desktop bridge is unavailable, the tool automatically falls back to the host command method, ensuring agents can always guide users to the correct privacy settings regardless of the runtime environment.

Network Request Privacy and SSRF Protection

URL Validation with assertPublicHttpUrl

The runtime/api-server/src/ssrf-guard.ts file (lines 5-15, 29-65, 88-102, 115-165) contains the core protection logic. The assertPublicHttpUrl function resolves DNS hosts and validates that no address falls into restricted ranges:

• Private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
• Loopback: 127.0.0.1, ::1
• Link-local: 169.254.0.0/16 (including cloud metadata endpoints like 169.254.169.254)
• Unique-local: IPv6 unique-local addresses

The isBlockedIpLiteral helper performs these checks before any network connection is established.

Automatic Enforcement in External Fetches

Every external HTTP(S) request routes through ssrfSafeFetch, which automatically applies the validation. The downloadUrl tool in runtime/api-server/src/workspace-download-url.ts demonstrates this integration in production use.

Unless explicitly whitelisted via the SANDBOX_SSRF_ALLOW_HOSTS environment variable, any URL resolving to a non-public address is rejected with a 400 error: url resolves to a non-public address.

Practical Implementation Examples

Requesting macOS Screen Recording Permission

// Agent requests macOS Screen Recording access
await agent.callTool("open_macos_settings", { pane: "screen_recording" });

When the desktop bridge is present, the response confirms:

{
  "opened": true,
  "via": "desktop",
  "message": "Requested the macOS 'screen recording' permission …"
}

If the bridge is unavailable, the response indicates "via": "host" while still successfully opening the settings pane.

Downloading Resources with Built-in SSRF Protection

// Safe download automatically validated against private ranges
await agent.callTool("download_url", {
  url: "https://example.com/image.png",
  workspaceId: "ws_123"
});

Behind the scenes, downloadUrl calls ssrfSafeFetch, which validates the URL format, resolves DNS, checks against blocked IP literals, and performs the fetch with manual redirect handling.

Configuring SSRF Allowlists for Internal Services

# Allow specific internal host:port combinations

export SANDBOX_SSRF_ALLOW_HOSTS="my.internal.service:8080,build-server.local:3000"

Running holaOS with this environment variable permits agents to access specific internal services while maintaining protection against unauthorized network probing.

Summary

• macOS permission handling is implemented in runtime/api-server/src/runtime-agent-tools.ts through the openMacosSettings tool, which bridges to the Electron main process or falls back to host commands.
• SSRF protection is enforced globally via ssrfSafeFetch in ssrf-guard.ts, blocking all private, loopback, and metadata IP ranges before connection establishment.
• Network privacy applies automatically to every external fetch including the downloadUrl tool, unless hosts are explicitly whitelisted via SANDBOX_SSRF_ALLOW_HOSTS.
• Capability declaration in runtime/harnesses/src/runtime-capability-tools.ts (lines 830-834) documents the privacy tools available to agents.

Frequently Asked Questions

How does holaOS request macOS permissions when an agent operation fails?

When an agent attempts a privileged operation like screencapture and encounters a permission error, it invokes the open_macos_settings tool with the specific pane name (e.g., screen_recording, accessibility). The tool attempts to register Holaboss with macOS through the desktop bridge to trigger the native permission prompt, or falls back to opening the system preferences URL directly.

What specific SSRF protection does holaOS implement?

According to the ssrf-guard.ts source code, holaOS validates every external URL using assertPublicHttpUrl, which resolves DNS and blocks addresses in private ranges (10.x, 172.16.x, 192.168.x), loopback (127.0.0.1), link-local (169.254.x), and unique-local IPv6 ranges. This prevents agents from accessing internal services or cloud metadata endpoints like 169.254.169.254.

Can I allow holaOS agents to access internal network addresses?

Yes, set the SANDBOX_SSRF_ALLOW_HOSTS environment variable with comma-separated host:port combinations before starting the runtime. This whitelist bypasses the SSRF guard for specific internal addresses while maintaining protection for all other non-public ranges.

Where is the privacy capability defined in the holaOS codebase?

The privacy capability schema is declared in runtime/harnesses/src/runtime-capability-tools.ts (lines 830-834), where the open_macos_settings tool is categorized under the macOS permissions group. This schema informs agents that they should invoke this tool whenever an operation fails due to missing OS-level permissions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}