So you want to do Apple PCC research?

Welcome, the more people who start doing this research the better off everyone will be!

What do you need?

You need an Apple Silicon Mac. I would suggest that you not do this on your primary machine. This process somewhat reduces your security posture on whatever computer you do it on. Quoting Apple:

Before using the VRE, you will need to configure your Mac to run security research virtual machines. This allows additional access to hardware features, which in turn might expose additional attack surface.

I would also recommend at minimum 16GBs of RAM. Apple says 24GBs, but you can get away with less. I suspect doing it on 8GBs would be a total non-starter. Having under 24GBs of RAM means that you may find that sometimes things will fail such as interacting with the research model etc.

A word on space: these virtual environments you will be using are a bit space hungry–but not too bad. It's worth having at least 100+GBs available before you start.

Now what?

Make sure that you are running at least MacOS 15.1. (It should go without saying, but you need to have administrator rights for this.) Open the Terminal on the Mac you picked and run:

echo "/System/Library/SecurityResearch/usr/bin" | sudo tee /etc/paths.d/20-vre        

This sets up your path so you access the pccvre tool. Now boot the Mac to recovery. Open the Terminal in recovery and run:

csrutil allow-research-guests enable        

Double check your work with:

csrutil allow-research-guests status        

You should see that allow-research-guests is now enabled. Now reboot.

Time to Setup a Research VM

Once logged in start by running the following in the terminal:

pccvre release list        

This will give you a list of all of the PCC releases available. Take note of the index of whatever release you want to use. Probably the latest one, but dealers choice. Next run:

pccvre release download $release-index        

Where the release-index is whatever value you picked from before. If you have a slow internet connection this can take some time. Once the process has finished you are now ready to build your first virtual environment. I will give you the example of building a research variant. Consult the documentation for how do other things. In the terminal run:

pccvre instance create --variant research --boot-args serial=3 -N $instance-name --release $release-index        

Where instance-name is whatever you want to call it. The release-index is whatever index you downloaded before. The boot-args specified gives you more verbose serial logs from the kernel.

This will again take some time when it is finished you can run:

pccvre instance list        

This will show you a list of the instances you have created with their status and IP if they are booted. Looks something like:

name                 status         ecid                                ipaddr
vre                      running      758585c29e0fbe30    192.168.64.8
vre-test             shutdown   dd6ac0e7a7825f33     -        

Example from Apple's documentation.

Now we need to enable SSH access. If you already have an SSH key you can use that. If not, then you will need to create one. If you don't know how to do this there are plenty of guides online such as: https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-openssh-on-macos-or-linux.

To enable SSH on your instance run the following command:

pccvre instance configure ssh -N $instance-name -p $path_to_ssh_public_key        

As before the instance-name is whatever you specified before. The path to the SSH key is likely something like:

~/.ssh/id_rsa.pub        

Assuming the command completed successfully you should have SSH enabled. There are lots more customizations you can make, but to align the configuration with the other options we have set we are going to change restricted execution mode.

To do this we need to dump the darwin-init configuration. Run the following command:

pccvre instance configure darwin-init dump -N $instance-name >> $path-to-file        

I would suggest you save this initial configuration file. Same rules apply with name and the $path to file can be whatever. The file output needs to be a .json such as init.json. Open this file in your text editor of choice. Modify this line from:

"userspace-reboot" : "rem"        

to:

"userspace-reboot" : "rem-dev"        

(See here for why you should do this: https://security.apple.com/documentation/private-cloud-compute/vreinteraction#Disable-Restricted-Execution-Mode)

Save the file with a new name. Now we need to apply the config with:

pccvre instance configure darwin-init set -N $instance-name -I $path-to-new-file        

It should say:

Replaced darwin-init configuration for VRE instance.         

If successful, otherwise you will need to fix your syntax. Now you are ready to boot.

Starting your Instance

Run the following command:

pccvre instance start -N $instance-name        

You should see the instance start in the terminal window. You can then connect to it with SSH using:

ssh -i $path-to-rsa-key root@ip-address        

You can obtain the IP address from the pccvre instance list command from above. It may take a little while for the instance to complete booting ever after the terminal output stops.

That's it! Congratulations you have taken your first steps into this brave new world of Private Cloud Compute research. There is a lot to learn, and this post is just to get you up and running.

Learn More

https://security.apple.com/documentation/private-cloud-compute/virtualresearchenvironment