docker_leash package

Subpackages

• docker_leash.checks package
  • Submodules
  • docker_leash.checks.allow module
    • Allow
  • docker_leash.checks.base module
    • Base
  • docker_leash.checks.deny module
    • Deny
  • Module contents
    • __init__

Submodules

docker_leash.action_mdocker_leasher module

Action

class Action(method, query)

Bases: object

Variables:

• method – HTTP method used
• query – unparsed query
• name – parsed name (i.e.: containersList, imagesBuild, …)
• version – API version call, if present
• querystring – parsed querystring
• namespace_name – (i.e.: containers, images, …)

_Action__namespace = None

_namespace_map = {'images': <class 'docker_leash.action_mapper.Image'>}

_parse()

Raise:InvalidRequestException

_r_parse = <_sre.SRE_Pattern object>

is_readonly()

Can the action affect the state of a resource.

Return type:bool

method = None

name = None

namespace

Initialize and return a Namespace object when required

Return type:Namespace instance

namespace_name = None

classmethod namespace_register(arg)

A decorator to register Namespace for a given namespace name

If no namespace name is provided, it will be derivated from the class name.

Parameters:

• cls (Action) –
• arg (str or Namespace instance) –

query = None

querystring = None

version = None

class Image(action)

Bases: docker_leash.action_mapper.Namespace

Proof of concept for Namespace subclasses

names()

Return type:list or None

class Namespace(action)

Bases: object

Generic namespace

Variables:action – link to (parent) action

action = None

docker_leash.checks_list module

Checks

class Checks

Bases: object

The Checks class is responsible for storing and deduplicating the checks to be launched.

Variables:docker_leash.checks_list.Checks.checks (list) – The check list.

static _structure_convert(data)

An internal helper that will convert structure from the configuration to a better internal format.

Parameters:data (dict) – The check to append. It is a dictionary with a single key / value. Returns:The reformatted test and arguments. Return type:dict

add(data)

Add a check to the list.

If the same check is already in the list, it will silently be discarded.

Parameters:data (dict) – The check to append.

checks = None

list: Internal storage of the checks to be applied.

docker_leash.config module

Config

class Config(groups=None, policies=None)

Bases: object

The Config class is responsible for storing application groups and policies read from the datastore.

It has some handy functions to extract values from the configuration. It can respond to questions such as:

• “Which are the groups for a user?”
• “Which policies user belong to?”
• “Which tests are enabled for a user?”

Variables:

• groups (dict or None) – The groups.
• policies (dict or None) – The policies.

Parameters:

• groups (dict or None) – The groups.
• policies (dict or None) – The policies.

static _default_rule(rule)

Construct a default rule

Parameters:rule (dict) – The current parsed rule Returns:A Checks containing only the default rule Return type:Checks

_get_policy_by_member(username, policies)

Extract the policies for a user name.

Return the concerned policies:

• If the user match in a group
• If the user is None, and “members” contains “Anonymous”
• Else return None

Parameters:

• username (str) – The username
• policies (dict) – The policies to filter

Returns:

The policies for username

Return type:

None or dict

static _match_host(hostname, host_rules)

Validate if a hostname match hosts regex list

Parameters:

• hostname (str) – The hostname
• host_rules (list) – List of hosts regex

Returns:

True if hostname match host rules

Return type:

bool

Raises:

ConfigurationException – if the host rules are invalid.

static _match_rules(action, actions)

Extract the checks for an action.

First match for exact comparison, then for the “any” keyword, and finally for “parents” action name.

Parameters:

• action (docker_leash.action_mapper.Action) – The current action
• actions (dict) – The actions from the policies

Returns:

The filtered actions list

Return type:

~docker_leash.checks_list.Checks

get_rules(payload)

Return the rules for a payload.

Parameters:payload (str) – The current payload. Returns:The rules concerned by the payload. Return type:list

groups = None

The loaded groups

policies = None

The loaded policies

update(groups=None, policies=None)

Update the stored configuration with the provided values.

Parameters:

• groups (dict or None) – The groups.
• policies (dict or None) – The policies.

docker_leash.exceptions module

Exceptions used in Docker Leash Server

exception ConfigurationException(value=None)

Bases: docker_leash.exceptions.DockerLeashException

Exception for configuration errors.

Used when configuration files are invalid.

exception DockerLeashException(value=None)

Bases: exceptions.BaseException

Base for all Leash Server Errors.

json()

Format the exception as dict object.

Returns:the exception as dict Return type:dict

exception InvalidRequestException(value=None)

Bases: docker_leash.exceptions.DockerLeashException

Exception for invalid payload.

Used when payload is invalid or incomplete.

exception NoSuchCheckModuleException(value=None)

Bases: docker_leash.exceptions.DockerLeashException

Exception for non existent check module.

Used when a check is configured by not existent or loadable.

exception UnauthorizedException(value=None)

Bases: docker_leash.exceptions.DockerLeashException

Exception for unauthorized action.

All docker_leash.checks modules must return this exception in order to deny the action to the user.

docker_leash.leash_server module

Leash server plugin for docker.

This module is responsible for dispatching HTTP requests.

activate()

Return implemented event system.

It is used internally by the Docker daemon to indicate which event system is concerned by the plugin. In the case of this plugin, it return authz.

See the official docker documentation.

Request:

GET /Plugin.Activate HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "Implements": ["authz"]
}

Resheader Content-Type:  application/json Status 200:valid response Return type:flask.Response

authz_request()

Process a request for authorization.

This is one of the main feature of this plugin. Depending on the configuration, the system, will allow or deny a request.

For a specific user, if no configuration match the RequestMethod and the RequestUri, then the default action is to deny the request.

See also

Function authz_response() for response authentication.

See also

See official docker documentation.

Request:

GET /AuthZPlugin.AuthZReq HTTP/1.1
Host: example.com
Accept: application/json

{
  "User": "mal",
  "AuthenticationMethod": "TLS",
  "RequestMethod": "POST",
  "RequestUri": "/v1.32/containers/json",
  "RequestHeaders": "<base64 encoded string>",
  "RequestBody": "<base64 encoded string>"
}

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "Allow": "true",
  "Msg": "Authorization granted",
  "Err": "Authorization granted"
}

Reqheader Accept:  application/json <json string User:  The user identification <json string AuthenticationMethod:  The authentication method used <json enum RequestMethod:  The HTTP method (GET/DELETE/POST) <json string RequestUri:  The HTTP request URI including API version (e.g., /v1.32/containers/json) <json map[string]string RequestHeaders:  Request headers as key value pairs (without the authorization header) <json []byte RequestBody:  Raw request body >json bool Allow:  Boolean value indicating whether the request is allowed or denied >json string Msg:  Authorization message (will be returned to the client in case the access is denied) >json string Err:  Error message. Will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information. Resheader Content-Type:  application/json Status 200:valid response Status 400:malformed request Status 422:invalid parameters Return type:flask.Response

authz_response()

Process a response for authorization.

This is one of the main feature of this plugin. Depending on the configuration, the system, will allow or deny a request.

Warning

In the current version, we don’t check any parameter, and always accept the request.

In contrast to authz_response(), this endpoint is called after the action has been processed by the docker daemon. The request payload contains additional fields representing the response from the daemon.

See also

Function authz_request() for request authentication.

See also

Check the official docker documentation.

Request:

GET /AuthZPlugin.AuthZReq HTTP/1.1
Host: example.com
Accept: application/json

{
  "User": "mal",
  "AuthenticationMethod": "TLS",
  "RequestMethod": "POST",
  "RequestUri": "/v1.32/containers/json",
  "RequestHeaders": "<base64 encoded string>",
  "RequestBody": "<base64 encoded string>",
  "ResponseStatusCode": "200",
  "ResponseHeaders": "<base64 encoded string>",
  "ResponseBody": "<base64 encoded string>"
}

Response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "Allow": "true",
  "Msg": "Authorization granted",
  "Err": "Authorization granted"
}

Reqheader Accept:  application/json <json string User:  The user identification <json string AuthenticationMethod:  The authentication method used <json enum RequestMethod:  The HTTP method (GET/DELETE/POST) <json string RequestUri:  The HTTP request URI including API version (e.g., /v1.32/containers/json) <json map[string]string RequestHeaders:  Request headers as key value pairs (without the authorization header) <json []byte RequestBody:  Raw request body <json int ResponseStatusCode:  Status code from the docker daemon <json map[string]string ResponseHeaders:  Response headers as key value pairs <json []byte ResponseBody:  Raw docker daemon response body >json bool Allow:  Boolean value indicating whether the request is allowed or denied >json string Msg:  Authorization message (will be returned to the client in case the access is denied) >json string Err:  Error message. Will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information. Resheader Content-Type:  application/json Status 200:valid response Status 400:malformed request Status 422:invalid parameters Return type:flask.Response

index()

Main entry point. it respond to the GET method for the / uri.

setup_app(application)

Initialize the application

docker_leash.payload module

Payload

class Payload(payload=None)

Bases: object

The Payload class is responsible for decoding and storing the current analyzed request.

Variables:

• data (dict or None) – The full request payload.
• user (str or None) – The connected user.
• method (str or None) – The request HTTP method.
• uri (str or None) – The request URI.
• headers (dict or None) – The request Headers.

Parameters:

payload (dict or None) – The payload to analyze and store.

static _decode_base64(payload)

Decode some parts of the payload from base64 to dict.

Parameters:payload (dict) – The payload to fully base64 decode. Returns:The fully decoded payload. Return type:dict

static _get_headers(payload)

Extract the Headers from the payload.

Parameters:payload (dict) – The payload to extract URI. Returns:The Headers. Return type:dict

static _get_host(payload)

Get the hostname

static _get_method(payload)

Extract the Method from the payload.

Parameters:payload (dict) – The payload to extract method. Returns:The method name. Return type:str or None Raises:InvalidRequestException – if the payload is missing RequestMethod.

static _get_uri(payload)

Extract the URI from the payload.

Parameters:payload (dict) – The payload to extract URI. Returns:The URI. Return type:str or None

static _get_username(payload)

Extract the User from the payload.

If the user is not connected (i.e.: anonymous), the value is an empty string.

Parameters:payload (dict) – The payload to extract username. Returns:The username. Return type:str or None

data = None

The full request payload

get_headers()

Get the headers

get_host()

Get the hostname

headers = None

The request Headers

host = ''

The request Headers

method = None

The request HTTP method

uri = None

The request URI

user = None

The connected user

docker_leash.processor module

Processor

class Processor

Bases: object

The Processor class is responsible for launching all the docker_leash.checks defined in the configuration for the triplet User, RequestMethod and RequestUri.

static _process(payload, check)

Instanciate the requested action and launch docker_leash.checks.base.BaseCheck.run()

Parameters:

• payload (Payload) – The request payload object.
• check (str) – The check name to run.

Raises:

• UnauthorizedException – if the check denied the request.
• NoSuchCheckModuleException – if the check doesn’t exists.

config = None

The currently loaded rules.

load_config()

Load rules from defined files in the global configuration.

Look for path in that order: path in config file, /etc/docker-leash/, /config/ and docker-leash module directory.

run(body=None)

Check if the request is accepted or denied.

The request will be passed to all configured docker_leash.checks for the triplet docker_leash.payload.Payload.user + docker_leash.payload.Payload.method + docker_leash.payload.Payload.uri. If one docker_leash.checks sub-modules deny the action, then the whole request is declared as denied.

Parameters:

body (str or dict or None) – The HTTP request body

Raises:

• UnauthorizedException – if the check denied the request.
• NoSuchCheckModuleException – if the check doesn’t exists.

Module contents

A remote AuthZ plugin to enforce granular rules for a Docker multiuser environment