Vlad the validator 🧛

⚠️ Super early days, we live in master. Vlad is still young and subject to change.

Vlad forces client interactions to be limited to the resources prefixed with the same OU= as the user TLS certificate. With OU=tst I could interact with service tst_thing and tstthing but not different_service. The same principle holds for networks, volumes and every other resource type. A public OU is automatically added for all clients.

Because we can't mutate the response to the client, global indexing is allowed, but deletion, inspection, update, etc is restricted to the client OU prefix.

Installation | Development | Docker Hub

Certificate requirements

Following along with https://docs.docker.com/engine/security/https/ we need to make a slight modification to the client certificate signing request.

The line

openssl req -subj '/CN=client' -new -key key.pem -out client.csr

Becomes the following (where groupname is set)

openssl req -subj '/CN=client/OU=groupname' -new -key key.pem -out client.csr

Installation

docker plugin install c45y/vlad --alias vlad

To complete, add vlad to your authorization-plugins configuration in daemon.json.

A small number of plugin configuration options can be toggled:

• VLAD_BIND_MOUNT sets the ability to perform host bind mounts, default false
• VLAD_BIND_PORTS toggles port binding outside the 30000-61000 range, default false

Current configuration can be seen using:

docker plugin inspect -f {{.Settings.Env}} vlad

Development Installation

From your command line:

docker build -t rootfsimage .
docker create --name vlad_container rootfsimage true
mkdir -p rootfs
docker export vlad_container | tar -x -C rootfs
docker plugin create vlad .
docker plugin enable vlad:latest  # Enable our dev plugin
sudo ./scripts/deploy.sh  # Generate docker CA/Node/Client certificates and deploy daemon.json
sudo ./scripts/docker.sh info  # Uses the client certificate via TLS + vlad authz
sudo docker info  # Uses existing unix socket (which is blanket allowed by vlad)

Tests

A small test harness based on the docker-bench-security setup to run through known valid/invalid operations. Runs a docker daemon with vlad under a mktemp directory which is destroyed at the end of testing.

systemctl stop docker  # Can't have another one running
cd test && sudo ./test

Output looks something like

Calling check_tls_volume_bad_bind
> docker volume create --opt=type=bind --opt=device=/tmp testgroup_4711accf0672
Error response from daemon: authorization denied by plugin c45y/vlad:latest: You cannot bind mount.
[PASS][check_tls_volume_bad_bind]

Calling check_tls_volume_bad_ou
> docker volume create badgroup_29d63f46fa7f
Error response from daemon: authorization denied by plugin c45y/vlad:latest: That volume is outside your OU prefix. ('public', 'testgroup')
[PASS][check_tls_volume_bad_ou]

Calling check_tls_volume_ou
> docker volume create testgroup_3c2739947c82
testgroup_3c2739947c82
[PASS][check_tls_volume_ou]


===================
Completed tests: 11
Passed tests:    11

Todo

• work more vampire jokes into readme
• echo OUs back to clients when bad prefix

  standardize response messages

• certificate revocation for clients

  decline via CN= & OU= as docker doesn't handle revocation?

• configuration options

  enable port binding / bind mounts / toggle random allow/block features

Validators

Default Request/Response vladidators all come from vlad.validators, though the list can be mutated at startup if required.

To implemnent custom functionality you can override/append async functions to the list of handlers indexed by make_app.

app = make_app()
app['validators']['request'] = [my_custom_async_func]

Validators have the choice of:

• explicitly allowing a request with a True value
• explicitly denying a request with a str denial message to be passed to the client
• doing absolutely nothing (None)

Requests are default deny, Response is default allow.

Each validator implements either/both the following function templates

@handles.post('configs', 'create')
async def validate_request(req: DockerRequest) -> Union[None, str, bool]:
    pass

async def validate_response(res: DockerResponse) -> Union[None, str]:
    pass

The handles decorator implements structured filtering to the validation functions. Check vlad/validators/ for extensive usage examples.

Handler Index:

• delete:/networks/*
• delete:/services/*
• get:/secrets/*
• get:/configs/*
• get:/plugins
• get:/plugins/privileges
• post:/plugins/pull
• get:/plugins/*/json
• delete:/plugins/*
• post:/plugins/*/enable
• post:/plugins/*/disable
• post:/plugins/*/upgrade
• post:/plugins/create
• post:/plugins/*/push
• post:/plugins/*/set
• get:/secrets
• get:/images/json
• post:/images/create
• get:/images/*/json
• get:/images/*/history
• post:/images/*/push
• post:/images/*/tag
• delete:/images/*
• get:/images/search
• post:/images/prune
• get:/images/*/get
• get:/images/get
• post:/images/load
• post:/commit
• head:/_ping
• get:/_ping
• get:/volumes/*
• post:/secrets/create
• get:/configs
• post:/configs/create
• get:/networks/*
• get:/services/*
• delete:/secrets/*
• get:/tasks/*
• post:/configs/*/update
• get:/containers/json
• post:/containers/create
• get:/containers/*/json
• get:/containers/*/top
• get:/containers/*/logs
• get:/containers/*/changes
• get:/containers/*/export
• get:/containers/*/stats
• post:/containers/*/resize
• post:/containers/*/start
• post:/containers/*/stop
• post:/containers/*/restart
• post:/containers/*/kill
• post:/containers/*/update
• post:/containers/*/rename
• post:/containers/*/pause
• post:/containers/*/unpause
• post:/containers/*/attach
• get:/containers/*/attach/ws
• post:/containers/*/wait
• delete:/containers/*
• head:/containers/*/archive
• put:/containers/*/archive
• get:/containers/*/archive
• post:/containers/prune
• post:/containers/*/exec
• post:/exec/*/start
• post:/exec/*/resize
• get:/exec/*/json
• get:/info
• get:/networks
• post:/networks/create
• get:/nodes
• delete:/nodes/*
• get:/nodes/*
• get:/services
• get:/tasks
• get:/version
• get:/volumes
• post:/volumes/create
• post:/volumes/prune
• post:/nodes/*/update
• get:/swarm
• post:/swarm/init
• post:/swarm/join
• post:/swarm/leave
• post:/swarm/update
• get:/swarm/unlockkey
• post:/swarm/unlock
• post:/services/create
• post:/auth
• post:/build
• post:/build/prune
• post:/networks/prune
• get:/services/*/logs
• delete:/volumes/*
• post:/secrets/*/update
• delete:/configs/*
• post:/services/*/update

We are missing handlers for:

• get:/events
• post:/networks/*/connect
• post:/session
• get:/system/df
• get:/distribution/*/json
• post:/networks/*/disconnect
• get:/tasks/*/logs