# twistlock-docker-authz
**Repository Path**: wuxler/twistlock-docker-authz
## Basic Information
- **Project Name**: twistlock-docker-authz
- **Description**: The mirror of a basic extendable Docker authorization plugin from https://github.com/twistlock/authz.git
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-20
- **Last Updated**: 2020-12-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Twistlock AuthZ Broker
[](https://travis-ci.org/twistlock/authz)
[](https://godoc.org/github.com/twistlock/authz)
[](https://goreportcard.com/report/github.com/twistlock/authz)
A basic extendable Docker [authorization plugin](https://docs.docker.com/engine/extend/plugins_authorization/) that runs directly on the host or inside a container. The framework depends on [docker authentication plugin support](https://github.com/docker/docker/pull/18514). Basic authorization is provided when Docker daemon is started with `--tlsverify` flag (username is extracted from the certificate common name).
Provided by [Twistlock](https://www.twistlock.com).
## Basic policy enforcement
The authorization broker is delivered as a reference implementation of a basic authorization mechanism, which consists of simple evaluation of user policies. The behavior of the plugin in the basic authorization flow is determined by the policy object:
```go
// BasicPolicy represent a single policy object that is evaluated in the authorization flow.
// Each policy object consists of multiple users and Docker actions, where each user belongs to a single policy.
//
// The policies are evaluated according to the following flow:
// For each policy object check
// If the user belongs to the policy
// If action in request in policy allow otherwise deny
// If no appropriate policy found, return deny
//
// Remark: In basic flow, each user must have a unique policy.
// If a user is used by more than one policy, the results may be inconsistent
type BasicPolicy struct {
Actions []string `json:"actions"` // Actions are the docker actions (mapped to authz terminology) that are allowed according to this policy
// Action are are specified as regular expressions
Users []string `json:"users"` // Users are the users for which this policy apply to
Name string `json:"name"` // Name is the policy name
Readonly bool `json:"readonly"` // Readonly indicates this policy only allow get commands
}
```
For basic authorization flows, all policies reside in a single policy file under `/var/lib/authz-broker/policy.json`. The file is continuously monitored and no restart is required upon changes.
The file format is [one policy JSON object per line](http://jsonlines.org/). There should be no enclosing list or map, just one map per line.
The conversation between [Docker remote API](https://docs.docker.com/engine/reference/api/docker_remote_api_v1.21/) (the URI and method that are passed Docker daemon to AuthZ plugin) to internal action parameters is defined by the [route parser](https://github.com/twistlock/authz/blob/master/core/route_parser.go).
All requests and their associated authorization responses are logged to the standard output. Additional hooks such as syslog and log file is also available. To add additional [logrus hooks](https://github.com/Sirupsen/logrus#hooks), see [extending the authorization plugin].
### Examples
Below are some examples for basic policy scenarios:
1. Alice can run all Docker commands: `{"name":"policy_1","users":["alice"],"actions":[""]}`
2. All users can run all Docker commands: `{"name":"policy_2","users":[""],"actions":[""]}`
3. Alice and Bob can create new containers: `{"name":"policy_3","users":["alice","bob"],"actions":["container_create"]}`
4. Service account can read logs and run container top: `{"name":"policy_4","users":["service_account"],"actions":["container_logs","container_top"]}`
5. Alice can perform anything on containers: `{"name":"policy_5","users":["alice"],"actions":["container"]}`
6. Alice can only perform get operations on containers: `{"name":"policy_5","users":["alice"],"actions":["container"], "readonly":true }`
# Dev environment
## Setting up local dev environment
* Build the binary and image:
```sh
$ make all
```
## Installing the plugin
The authorization plugin can run as a container application or as a host service.
### Running inside a container
1. Install the containerized version of the Twistlock authorization plugin:
```bash
$ docker run -d --restart=always -v /var/lib/authz-broker/policy.json:/var/lib/authz-broker/policy.json -v /run/docker/plugins/:/run/docker/plugins twistlock/authz-broker
```
For auditing using syslog hook add the following settings to the docker command:-e AUDITOR-HOOK:syslog -v /dev/log:/dev/log
For auditing using file add the following settings to the docker command:-e AUDITOR-HOOK:file -v PATH_TO_LOCAL_LOG_FILE:/var/log/authz.log
2. Update Docker daemon to run with authorization enabled.
For example, if Docker is installed as a systemd service:
```bash
$ sudo systemctl edit --full docker.service
```
3. Add authz broker plugin parameter to ExecStart parameter
```bash
ExecStart=/usr/bin/docker daemon -H fd:// --authorization-plugin=authz-broker
```
### Running as a stand-alone service
* Download Twistlock authZ binary (todo:link)
* Install Twistlock as a service
```bash
$ wget xxx | sudo sh
```
* Update Docker daemon to run with authorization enabled.
For example, if Docker is installed as a systemd service:
```bash
$ sudo systemctl edit --full docker.service
```
add authz-plugin parameter to ExecStart parameter
```bash
ExecStart=/usr/bin/docker daemon -H fd:// --authorization-plugin=authz-broker
```
## Extending the authorization plugin
The framework consists of two extendable interfaces: the Authorizer,
which handles the authorization flow; and the Auditor, which audits the request and response in the authorization flow.
```go
// Authorizer handles the authorization of docker requests and responses
type Authorizer interface {
Init() error // Init initialize the handler
AuthZReq(req *authorization.Request) *authorization.Response // AuthZReq handles the request from docker client
// to docker daemon
AuthZRes(req *authorization.Request) *authorization.Response // AuthZRes handles the response from docker deamon to docker client
}
```
```go
// Auditor audits the request and response sent from/to docker daemon
type Auditor interface {
// AuditRequest audit the request sent from docker client and the associated authorization response
// Docker client -> authorization -> audit -> Docker daemon
AuditRequest(req *authorization.Request, pluginRes *authorization.Response)
// AuditRequest audit the response sent from docker daemon and the associated authorization response
// Docker daemon -> authorization -> audit -> Docker client
AuditResponse(req *authorization.Request, pluginRes *authorization.Response)
}
```
## Licensing
Twistlock authorization plugin is licensed under the Apache License, Version 2.0.
See [LICENSE](https://github.com/twistlock/authz/blob/master/LICENSE) for the full license text.