Protecting Computes with Whitelists and Manifests

Photo by Mike Szczepanski on Unsplash

We’ve added whitelists to Computes to help you protect your network against malicious or unwanted task execution. You will need to run version 14.0.0 or higher to get the new whitelist functionality. If you want to get up and running quickly and explore the whitelists later, check out the Getting Started guide to set up an open whitelist.

What’s changed?

There are two changes that will be immediately noticeable.

1. When starting the computes-daemon you will need to pass the COMPUTES_WHITELIST environment variable or --whitelist parameter.
2. All task definitions must provide a manifest.

A Simple Manifest

Since you will be required to reference your manifest in the whitelists, let’s start by creating a simple manifest for a docker image.

{
  "*": {
    "image": "computes/fibonacci-sum-split:latest"
  }
}

The * represents the platforms that this image will run on. In this case, the * means to use this image for all platforms.

We need to add this manifest to IPFS in order to reference it in our task and whitelist.

cat manifest.json | ipfs dag put
> zdpuArJcUhve8GiwWQM5nhAKfzc3LPztg1EsoYxbpufAzo4Dr

Now that we have the CID of the manifest, we can add it as an authorized manifest in our whitelist.

A Simple Whitelist

A whitelist is a list of manifests that are authorized to run on your Computes node. Let’s use the manifest we created above and allow it to be used in our network.

{
  "runners": {
    "docker-json-runner": {
      "manifests": [
        { "/": "zdpuArJcUhve8GiwWQM5nhAKfzc3LPztg1EsoYxbpufAzo4Dr" }
      ]
    }
  }
}

In our case, we are authorizing the docker-json-runner to use our manifest. Let’s add this whitelist to IPFS and get ready to use it in a task.

cat whitelist.json | ipfs dag put
> zdpuAonyLqnX8V4E7p49VfKg4mCX2qpMzGKxA9ad9WhhQhma3

Use the Whitelist

Let’s run Computes using this whitelist.

computes-daemon --whitelist zdpuAonyLqnX8V4E7p49VfKg4mCX2qpMzGKxA9ad9WhhQhma3 run

A Whitelisted Task

This is the biggest change to Computes from prior versions. Previously you could specify the docker image you wanted to run in the metadata property. This allowed any docker image to run on your machine, and also would not let you change the docker image on different platforms if necessary. Now, you can specify the manifest in your task like so:

{
  "input": {
    "dataset": 2
  },
  "taskDefinition": {
    "runner": {
      "type": "docker-json-runner",
      "manifest": {
        "/": "zdpuArJcUhve8GiwWQM5nhAKfzc3LPztg1EsoYxbpufAzo4Dr"
      }
    },
    "result": {
      "action": "set",
      "destination": {
        "dataset": { "/": "<dataset-hash-here>" },
        "path": "split/results"
      }
    }
  },
  "status": {
    "/": "<status-hash-here>"
  }
}

Thanks to IPFS content addressing, we can be sure that the manifest we reference will always point to the correct docker image tag.

What’s next?

We will be providing more security options in the future to checksum and verify the docker image to ensure it hasn’t been changed in the registry.

Also, we will add support to reference an IPNS entry to allow whitelists to be updated securely and immediately update all nodes on the Computes network.