| # -*- coding: utf-8 -*- |
| # Copyright 2015 The Chromium OS Authors. All rights reserved. |
| # Use of this source code is governed by a BSD-style license that can be |
| # found in the LICENSE file. |
| |
| """Logic to generate a SandboxSpec from an appc pod manifest. |
| |
| https://github.com/appc/spec/blob/master/SPEC.md |
| """ |
| |
| from __future__ import print_function |
| |
| import collections |
| import copy |
| import json |
| import os |
| import re |
| |
| from chromite.lib import cros_logging as logging |
| from chromite.lib import json_lib |
| from chromite.lib import osutils |
| from chromite.lib import remote_access |
| from chromite.lib import user_db |
| |
| KEY_ANNOTATIONS_LIST = 'annotations' |
| KEY_ANNOTATION_NAME = 'name' |
| KEY_ANNOTATION_VALUE = 'value' |
| ENDPOINT_NAME_ANNOTATION_PREFIX = 'bruteus-endpoint-' |
| |
| KEY_APPS_LIST = 'apps' |
| KEY_APP_NAME = 'name' |
| KEY_APP_IMAGE = 'image' |
| KEY_APP_IMAGE_NAME = 'name' |
| KEY_APP_ISOLATORS = 'isolators' |
| |
| KEY_APP_SUB_APP = 'app' |
| KEY_SUB_APP_USER = 'user' |
| KEY_SUB_APP_GROUP = 'group' |
| KEY_SUB_APP_EXEC = 'exec' |
| KEY_SUB_APP_PORTS = 'ports' |
| |
| PORT_SPEC_COUNT = 'count' |
| PORT_SPEC_NAME = 'name' |
| PORT_SPEC_PORT = 'port' |
| PORT_SPEC_PROTOCOL = 'protocol' |
| PORT_SPEC_SOCKET_ACTIVATED = 'socketActivated' |
| |
| PROTOCOL_TCP = 'tcp' |
| PROTOCOL_UDP = 'udp' |
| VALID_PROTOCOLS = (PROTOCOL_TCP, PROTOCOL_UDP) |
| |
| ISOLATOR_KEY_NAME = 'name' |
| ISOLATOR_KEY_VALUE = 'value' |
| ISOLATOR_KEY_VALUE_SET = 'set' |
| |
| ISOLATOR_NAME_PREFIX = 'os/linux/capabilities-' |
| ISOLATOR_NAME_RETAIN_SET = 'os/linux/capabilities-retain-set' |
| |
| PortSpec = collections.namedtuple('PortSpec', ('allow_all', 'port_list')) |
| |
| |
| def IsValidAcName(name): |
| """Returns true if |name| adheres to appc's AC Name Type. |
| |
| This roughly means that a string looks like a protocol-less |
| URL (e.g. foo-foo/bar/bar). |
| |
| https://github.com/appc/spec/blob/master/SPEC.md#ac-name-type |
| |
| Args: |
| name: string to validate. |
| |
| Returns: |
| True iff |name| is a valid AC Name. |
| """ |
| return bool(re.match(r'^[a-z0-9]+([-./][a-z0-9]+)*$', name)) |
| |
| |
| class SandboxSpecWrapper(object): |
| """Wrapper that knows how to set fields in a protocol buffer. |
| |
| This makes mocking out our protocol buffer interface much simpler. |
| """ |
| |
| def __init__(self): |
| # In the context of unittests run from outside the chroot, this import |
| # will fail. Tests will mock out this entire class. |
| # pylint: disable=import-error |
| from generated import soma_sandbox_spec_pb2 |
| self.sandbox_spec = soma_sandbox_spec_pb2.SandboxSpec() |
| |
| def SetName(self, name): |
| """Set the name of the runnable brick.""" |
| self.sandbox_spec.name = name |
| self.sandbox_spec.overlay_path = '/bricks/%s' % name |
| |
| def AddExecutable(self, uid, gid, command_line, tcp_ports, udp_ports, |
| linux_caps): |
| """Add an executable to the wrapped SandboxSpec. |
| |
| Args: |
| uid: integer UID of the user to run this executable. |
| gid: integer GID of the group to run this executable. |
| command_line: list of strings to run. |
| tcp_ports: list of PortSpec tuples. |
| udp_ports: list of PortSpec tuples. |
| linux_caps: list of string names of capabilities (e.g. 'CAP_CHOWN'). |
| """ |
| executable = self.sandbox_spec.executables.add() |
| executable.uid = uid |
| executable.gid = gid |
| executable.command_line.extend(command_line) |
| for listen_ports, ports in ((executable.tcp_listen_ports, tcp_ports), |
| (executable.udp_listen_ports, udp_ports)): |
| if ports.allow_all: |
| listen_ports.allow_all = True |
| else: |
| listen_ports.allow_all = False |
| listen_ports.ports.extend(ports.port_list) |
| |
| # Map the names of caps to the appropriate protobuffer values. |
| caps = [self.sandbox_spec.LinuxCaps.Value('LINUX_' + cap_name) |
| for cap_name in linux_caps] |
| executable.capabilities.extend(caps) |
| |
| def AddEndpointName(self, endpoint_name): |
| """Adds the name of an endpoint that'll run inside this sandbox.""" |
| self.sandbox_spec.endpoint_names.append(endpoint_name) |
| |
| |
| def _GetPortList(desired_protocol, appc_port_list): |
| """Get the list of ports opened for |desired_protocol| from |appc_port_list|. |
| |
| Args: |
| desired_protocol: one of VALID_PROTOCOLS. |
| appc_port_list: list of port specifications from a appc pod manifest. |
| |
| Returns: |
| Instance of PortSpec. |
| """ |
| # The port specification is optional. |
| if appc_port_list is None: |
| return PortSpec(False, []) |
| |
| json_lib.AssertIsInstance(appc_port_list, list, 'port specification list') |
| |
| allow_all = False |
| port_list = [] |
| for port_dict in appc_port_list: |
| json_lib.AssertIsInstance(port_dict, dict, 'port specification') |
| port_dict = copy.deepcopy(port_dict) |
| |
| # By default, we open a single specified port. |
| port_dict.setdefault(PORT_SPEC_COUNT, 1) |
| # By default, don't set socket activated. |
| port_dict.setdefault(PORT_SPEC_SOCKET_ACTIVATED, False) |
| |
| # We don't actually use the port name, but it's handy for documentation |
| # and standard adherence to enforce its existence. |
| port_name = json_lib.PopValueOfType( |
| port_dict, PORT_SPEC_NAME, unicode, 'port name') |
| logging.debug('Validating appc specifcation of "%s"', port_name) |
| port = json_lib.PopValueOfType(port_dict, PORT_SPEC_PORT, int, 'port') |
| protocol = json_lib.PopValueOfType( |
| port_dict, PORT_SPEC_PROTOCOL, unicode, 'protocol') |
| |
| count = json_lib.PopValueOfType( |
| port_dict, PORT_SPEC_COUNT, int, 'port range count') |
| |
| # We also don't use the socketActivated flag, but we should tolerate safe |
| # values. |
| socket_activated = json_lib.PopValueOfType( |
| port_dict, PORT_SPEC_SOCKET_ACTIVATED, bool, 'socket activated flag') |
| |
| # Validate everything before acting on it. |
| if protocol not in VALID_PROTOCOLS: |
| raise ValueError('Port protocol must be in %r, not "%s"' % |
| (VALID_PROTOCOLS, protocol)) |
| if protocol != desired_protocol: |
| continue |
| |
| if socket_activated != False: |
| raise ValueError('No support for socketActivated==True in %s' % port_name) |
| |
| if port_dict: |
| raise ValueError('Unknown keys found in port spec %s: %r' % |
| (port_name, port_dict.keys())) |
| |
| if port == -1: |
| # Remember that we're going to return that all ports are opened, but |
| # continue validating all the remaining specifications. |
| allow_all = True |
| continue |
| |
| # Now we know it's not the wildcard port, and that we've never declared |
| # a wildcard for this protocol. |
| port = remote_access.NormalizePort(port) |
| |
| if count < 1: |
| raise ValueError('May only specify positive port ranges for %s' % |
| port_name) |
| if port + count >= 65536: |
| raise ValueError('Port range extends past max port number for %s' % |
| port_name) |
| |
| for effective_port in xrange(port, port + count): |
| port_list.append(effective_port) |
| |
| return PortSpec(allow_all, port_list) |
| |
| |
| def _ExtractLinuxCapNames(app_dict): |
| """Parses the set of Linux capabilities for an executable. |
| |
| Args: |
| app_dict: dictionary defining an executable. |
| |
| Returns: |
| List of names of Linux capabilities (e.g. ['CAP_CHOWN']). |
| """ |
| if KEY_APP_ISOLATORS not in app_dict: |
| return [] |
| |
| isolator_list = json_lib.GetValueOfType( |
| app_dict, KEY_APP_ISOLATORS, list, |
| 'list of isolators for application') |
| linux_cap_isolators = [] |
| |
| # Look for any isolators related to capability sets. |
| for isolator in isolator_list: |
| json_lib.AssertIsInstance(isolator, dict, 'isolator instance') |
| isolator_name = json_lib.GetValueOfType( |
| isolator, ISOLATOR_KEY_NAME, unicode, 'isolator name') |
| if not isolator_name.startswith(ISOLATOR_NAME_PREFIX): |
| continue |
| if isolator_name != ISOLATOR_NAME_RETAIN_SET: |
| raise ValueError('Capabilities may only be specified as %s' % |
| ISOLATOR_NAME_RETAIN_SET) |
| linux_cap_isolators.append(isolator) |
| |
| # We may have only a single isolator. |
| if len(linux_cap_isolators) > 1: |
| raise ValueError('Found two lists of Linux caps for an executable') |
| if not linux_cap_isolators: |
| return [] |
| |
| value = json_lib.GetValueOfType( |
| linux_cap_isolators[0], ISOLATOR_KEY_VALUE, dict, |
| 'Linux cap isolator value') |
| caps = json_lib.GetValueOfType( |
| value, ISOLATOR_KEY_VALUE_SET, list, 'Linux cap isolator set') |
| for cap in caps: |
| json_lib.AssertIsInstance(cap, unicode, 'Linux capability in set.') |
| |
| return caps |
| |
| |
| class SandboxSpecGenerator(object): |
| """Delegate that knows how to read appc manifests and write SandboxSpecs.""" |
| |
| def __init__(self, sysroot): |
| self._sysroot = sysroot |
| self._user_db = user_db.UserDB(sysroot) |
| |
| def _CheckAbsPathToExecutable(self, path_to_binary): |
| """Raises if there is no exectable at |path_to_binary|.""" |
| if not os.path.isabs(path_to_binary): |
| raise ValueError( |
| 'Brick executables must be specified by absolute path, not "%s".' % |
| path_to_binary) |
| return True |
| |
| def _FillInEndpointNamesFromAnnotations(self, wrapper, annotations): |
| """Fill in the SandboxSpec endpoint_names field from |annotations|. |
| |
| An appc pod specification can contain a list of (mostly) arbitrary |
| annotations that projects can use to add their own metadata fields. |
| |annotations| is a list of dicts that each contain a name and value field, |
| and this method looks for 'name' fields that are prefixed with |
| ENDPOINT_NAME_ANNOTATION_PREFIX and treats the associated 'value' as the |
| name of an endpoint that psyched will expect to be registered from within |
| this sandbox. |
| |
| Args: |
| wrapper: instance of SandboxSpecWrapper. |
| annotations: list of dicts, each with a name and value field. |
| """ |
| for annotation in annotations: |
| json_lib.AssertIsInstance(annotation, dict, 'a single annotation') |
| name = json_lib.GetValueOfType( |
| annotation, KEY_ANNOTATION_NAME, unicode, 'annotation name') |
| if not IsValidAcName(name): |
| raise ValueError('Annotation name "%s" contains illegal characters.' % |
| name) |
| if name.startswith(ENDPOINT_NAME_ANNOTATION_PREFIX): |
| endpoint_name = json_lib.GetValueOfType( |
| annotation, KEY_ANNOTATION_VALUE, unicode, 'endpoint name value') |
| if not IsValidAcName(name): |
| raise ValueError('Endpoint name "%s" contains illegal characters.' % |
| endpoint_name) |
| wrapper.AddEndpointName(endpoint_name) |
| |
| def _FillInExecutableFromApp(self, wrapper, app): |
| """Fill in the fields of a SandboxSpec.Executable object from |app|. |
| |
| Args: |
| wrapper: instance of SandboxSpecWrapper. |
| app: dictionary of information taken from the appc pod manifest. |
| """ |
| sub_app = json_lib.GetValueOfType( |
| app, KEY_APP_SUB_APP, dict, 'per app app dict') |
| user = json_lib.GetValueOfType( |
| sub_app, KEY_SUB_APP_USER, unicode, 'app dict user') |
| group = json_lib.GetValueOfType( |
| sub_app, KEY_SUB_APP_GROUP, unicode, 'app dict group') |
| |
| if not self._user_db.UserExists(user): |
| raise ValueError('Found invalid username "%s"' % user) |
| if not self._user_db.GroupExists(group): |
| raise ValueError('Found invalid groupname "%s"' % group) |
| |
| cmd = json_lib.GetValueOfType( |
| sub_app, KEY_SUB_APP_EXEC, list, 'app command line') |
| if not cmd: |
| raise ValueError('App command line must give the executable to run.') |
| self._CheckAbsPathToExecutable(cmd[0]) |
| for cmd_piece in cmd: |
| json_lib.AssertIsInstance(cmd_piece, unicode, 'app.exec fragment') |
| |
| port_list = sub_app.get(KEY_SUB_APP_PORTS, None) |
| wrapper.AddExecutable(self._user_db.ResolveUsername(user), |
| self._user_db.ResolveGroupname(group), |
| cmd, |
| _GetPortList(PROTOCOL_TCP, port_list), |
| _GetPortList(PROTOCOL_UDP, port_list), |
| _ExtractLinuxCapNames(sub_app)) |
| |
| def GetSandboxSpec(self, appc_contents, sandbox_spec_name): |
| """Create a SandboxSpec encoding the information in an appc pod manifest. |
| |
| Args: |
| appc_contents: string contents of an appc pod manifest |
| sandbox_spec_name: string unique name of this sandbox. |
| |
| Returns: |
| an instance of SandboxSpec. |
| """ |
| wrapper = SandboxSpecWrapper() |
| overlay_name = None |
| |
| app_list = json_lib.GetValueOfType( |
| appc_contents, KEY_APPS_LIST, list, 'app list') |
| for app in app_list: |
| json_lib.AssertIsInstance(app, dict, 'app') |
| |
| # Aid debugging of problems in specific apps. |
| app_name = json_lib.GetValueOfType( |
| app, KEY_APP_NAME, unicode, 'app name') |
| if not IsValidAcName(app_name): |
| raise ValueError('Application name "%s" contains illegal characters.' % |
| app_name) |
| logging.debug('Processing application "%s".', app_name) |
| |
| # Get the name of the image, check that it's consistent other image names. |
| image = json_lib.GetValueOfType( |
| app, KEY_APP_IMAGE, dict, 'image specification for app') |
| image_name = json_lib.GetValueOfType( |
| image, KEY_APP_IMAGE_NAME, unicode, 'image name') |
| if not IsValidAcName(image_name): |
| raise ValueError('Image name "%s" contains illegal characters.' % |
| image_name) |
| |
| if overlay_name and overlay_name != image_name: |
| raise ValueError( |
| 'All elements of "apps" must have the same image.name.') |
| overlay_name = image_name |
| |
| # Add the executable corresponding to this app to our SandboxSpec. |
| self._FillInExecutableFromApp(wrapper, app) |
| |
| if not overlay_name: |
| raise ValueError('Overlays must declare at least one app') |
| |
| annotation_list = json_lib.GetValueOfType( |
| appc_contents, KEY_ANNOTATIONS_LIST, list, 'list of all annotations') |
| self._FillInEndpointNamesFromAnnotations(wrapper, annotation_list) |
| |
| wrapper.SetName(sandbox_spec_name) |
| return wrapper.sandbox_spec |
| |
| def WriteSandboxSpec(self, appc_pod_manifest_path, output_path): |
| """Write a SandboxSpec corresponding to |appc_pod_manifest_path| to disk. |
| |
| Args: |
| appc_pod_manifest_path: path to an appc pod manifest file. |
| output_path: path to file to write serialized SandboxSpec. The |
| containing directory must exist, but the file may not. This is not |
| checked atomically. |
| """ |
| if os.path.isfile(output_path): |
| raise ValueError( |
| 'Refusing to write SandboxSpec to file %s which already exists!' % |
| output_path) |
| |
| appc_contents = json.loads(osutils.ReadFile(appc_pod_manifest_path)) |
| # Use the file name without extension as the the name of the sandbox spec. |
| sandbox_name = os.path.basename(appc_pod_manifest_path).rsplit('.', 1)[0] |
| spec = self.GetSandboxSpec(appc_contents, sandbox_name) |
| osutils.WriteFile(output_path, spec.SerializeToString()) |
