Shadow Tunneling

Overview

Shadow tunnels simplify exercising proxy flows, such as TIE Proxy or PCC Agent. They enable you to replace cloud apps with lightweight gRPC proxies that forward all interactions to a shadow remote running outside the VRE. Because you control the shadow remote, you can direct the behavior of the cloud apps and controllers to exercise any scenario relevant to verifying PCC’s privacy and security properties.

Shadow tunnels are not usable in production environments; PCC’s customer security policy includes multiple safeguards that prevent their use outside the VRE.

The CloudBoard repository includes the source, gRPC, and proto definitions to implement your own shadow remote. The cloudboard-vre-cli tool, which ships with the release’s PCC tools, provides an example implementation that you run on your host.

Enable shadow tunnel functionality

Bypassing the safeguards that prevent shadow tunnels in production requires the following configuration changes in the VRE:

Disable Restricted Execution Mode

Because neither ShadowTunnelCloudApp nor ShadowTunnelCloudController is listed as allowed by Restricted Execution Mode (REM), you need to disable REM to use them.

You can use rem-dev mode to disable REM by specifying the following in your darwin-init config:

{"userspace-reboot": "rem-dev"}

Relax security policy

A proxy node validates the attestation of each node it forwards a request to, and a proxy running under a customer security policy rejects the tunnel node’s attestation. You need to remove the config-security-policy key from the darwin-init configuration of any proxy VRE node that uses the tunnel node, so the proxy accepts that attestation.

Apply cloud-app-specific configuration

You can configure each cloud app separately within the secure-config section of the darwin-init configuration. This example details the behavior for TIECloudApp, which provides inference.

First, enable shadowing:

"com.apple.cloudboard.cloudApp.TIECloudApp.shadow.enabled": true

Then, define the host and port on which your remote service listens. The shadow remote runs on your Mac, so this is your host’s address on the VM network, which is 192.168.64.1 for the default NAT configuration:

"com.apple.cloudboard.cloudApp.TIECloudApp.shadow.remoteHost": "192.168.64.1",
"com.apple.cloudboard.cloudApp.TIECloudApp.shadow.remotePort": 8080

The shadow controller registers the workload name you give it, which the client’s workload type must match:

"com.apple.cloudboard.cloudApp.TIECloudApp.shadow.workloadName": "tie-cloudboard-apple-com"

Additionally, configure the preferences section to disable TIECloudApp’s built-in controller, because the shadow tunnel replaces it:

{ "application_id": "com.apple.cloudos.cloudOSInfo", "key": "tieEnabled", "value": false }

Other configuration items exist; they are documented within the ShadowCloudAppConfig type.

Bypass workload-type validation

cb_jobhelper validates each cloud app’s process name against an internal allow list of expected workload types and rejects the request with an unknownWorkloadType error if the name isn’t present. Neither ShadowTunnelCloudApp nor ShadowTunnelCloudController is on this list, so set the following secure-config override to skip the check:

"com.apple.cloudboard.skipMultiAppValidations": true

Run the shadow tunnel server

Run the tunnel server on your Mac, listening on the host and port you configured above, and start the compute VRE. cloudboard-vre-cli is one of the release’s PCC tools, so you launch it through pccvre instance invoke, passing one or more response scripts:

% pccvre instance invoke -N <instance-name> tool cloudboard-vre-cli shadowRemote \
    <response-script>.json --host 0.0.0.0 --port 8080 --log-level warn

The warn log level reports each connection, the bytes received, and script progress. Instead of scripted responses, --mode sink logs everything the cloud app sends and returns nothing, and --mode example prints an example script without starting the server.