README

Trireme

Build Status Code Coverage Twitter URL Slack URL License Documentation

Welcome to Trireme, an open-source library curated by Aporeto to provide segmentation for cloud-native applications. Trireme-lib is a Zero-Trust networking library that makes it possible to setup security policies and segment applications by enforcing end-to-end authentication and authorization without the need for complex control planes or IP/port-centric ACLs and east-west firewalls.

Trireme-lib supports both containers and Linux Processes and allows security policy enforcement between any of these entities.

TL;DR

Trireme-lib is a library. The followin projects use it:

Description

In the Trireme world, a processing unit end-point can be a container, Kubernetes POD, or a general Linux process. We will be referring to processing units as PUs throughout this discussion.

The technology behind Trireme is streamlined, elegant, and simple. It is based on The concepts of Zero-Trust networking:

  1. The identity is the set of attributes and metadata that describes the container as key/value pairs. Trireme provides an extensible interface for defining these identities. Users can choose customized methods appropriate to their environment for establishing PU identity. For example, in a Kubernetes environment, the identity can be the set of labels identifying a POD.
  2. There is an authorization policy that defines when containers with different types of identity attributes can interact or exchange traffic. The authorization policy implements an Attribute-Based Access Control (ABAC) mechanism (https://en.wikipedia.org/wiki/Attribute-Based_Access_Control), where the policy describes relationships between identity attributes.
  3. Every communication between two processes or containers is controlled through a cryptographic end-to-end authentication and authorization step, by overlaying an authorization function over the TCP negotiation. The authorization steps are performed during the SYN/SYNACK/ACK negotiation.

The result of this approach is the decoupling of application segmentation from the underlying network IP addresses because this approach is centered on workload identity attributes and interactions between workloads. Application segmentation can be achieved simply by managing application identity and authorization policy. Segmentation granularity can be adjusted based on the needs of the platform.

Trireme is a node-centric library. Each node participating in the Trireme cluster must spawn one instance of a process that uses this library to transparently insert the authentication and authorization step. Trireme provides the data path functions but does not implement either the identity management or the policy resolution function. Function implementation depends on the particular operational environment. Users have to provide PolicyLogic (ABAC “rules”) to Trireme for well-defined PUs, such as containers.

Existing implementation using Trireme library

Security Model

Trireme is a Zero-Trust networking library. The security model behind Zero-trust networking is:

  • The Network is always untrusted. It doesn't matter if you are inside or outside your enterprise.
  • Every Flow/Connection needs to be authenticated and authorized by the endpoints
  • The network information (IP/Port) is completely irrelevant to the authorization/authentication.

With Trireme, there is no need to define any security rules with IPs, port numbers, or ACLs. Everything is based on identity attributes; your IP and port allocation scheme is not relevant to Trireme and it is compatible with most underlying networking technologies. The end-to-end authentication and authorization approach is also compatible with NATs and IPv4/IPv6 translations.

A PU is a logical unit of control to which you attach identity and authorization policies. It provides a simple mechanism where the identity is derived out of the Docker manifest; however, other mechanisms are possible for more sophisticated identity definition. For instance, you may want to tag your 3-tier container application as "frontend," "backend," and "database." By associating corresponding labels and containers, these labels become "the identity." A policy for the “backend” containers can simply accept traffic only from “frontend” containers. Alternatively, an orchestration system might define a composite identity for each container and implement more sophisticated policies.

PolicyLogic defines the set of authorization rules as a function of the identity of attributes and loads these rules into Trireme when a container is instantiated. Authorization rules describe the set of identities with which a particular container is allowed to interact. We provide an example of this integration logic with Kubernetes here. Furthermore, we provide an example of a simple policy where two containers can only talk to each other if they have matching labels in this example. Each rule defines a match based on the identity attributes. PolicyLogic assumes a whitelist model where everything is dropped unless explicitly allowed by the authorization policy.

PU identities are cryptographically signed with a node specific secret and sent as part of a TCP connection setup negotiation. Trireme supports both mutual and receiver-only authorization. Moreover, it supports two authentication and signing modes: (1) A pre-shared key and (2) a PKI mechanism based on ECDSA. In the case of ECDSA, public keys are either transmitted on the wire or pre-populated through an out-of-band mechanism to improve efficiency. Trireme also supports two identity encoding mechanisms: (1) A signed JSON Web Token (JWT) and (2) a custom binary mapping mechanism.

With these mechanisms, the Trireme run-time on each node will only allow communication after an end-to-end authentication and authorization step is performed between the containers.

Trireme Architecture

Trireme-lib is built as a set of modules (Go packages) that provide a default implementation for each component. It is simple to swap the default implementation of each of those modules with custom-built ones for more complex and specific features.

Conceptually, Trireme acts on PU events. In the default implementation, the PU is a Docker container. Trireme can be extended easily to other PUs such as processes, files, sockets, and so forth.

Trireme Architecture

  • Trireme is the central package providing policy instantiation logic. It receives PU events from the Monitor and dispatches the resulting generated policy to the other modules.
  • The Monitor listens to a well-defined PU creation module. The built-in monitor listens to Docker events and generates a standard Trireme Processing Unit runtime representation. The Monitor hands-over the Processing Unit runtime to Trireme.
  • The PolicyResolver is implemented outside of Trireme. Trireme calls the PolicyResolver to get a PU policy based on a PU runtime. The PolicyResolver depends on the orchestration system used for managing identity and policy. If you plan to implement your own Policy with Trireme, you will essentially need to implement a PolicyResolver
  • The Supervisor implements the policy by redirecting the TCP negotiation packets to user space. The default implementation uses IPTables with LibNetfilter.
  • The Enforcer enforces the policy by analyzing the redirected packets and enforcing the identity and policy rules that are defined by the PolicyResolver in the PU policy. Trireme supports to day a Remote and a local enforcer. The Remote enforcer is advised as it is remotely started into the network namespace of the Processing Unit, therefore not interfering at all with existing Networking implementation on the default/host namespace.

Defining Your Own Policy

Trireme allows you to define any type of identity attributes and policies to associate with PUs. In order to define your own policies and identities, you need to implement a PolicyResolver interface that will receive policy requests from Trireme whenever a policy resolution is required.

PolicyResolver Implementation

A couple of Helpers are provided as part of the configurator packages that loads all of Trireme’s modules with the most common settings:

  • NewPSKTriremeWithDockerMonitor loads Trireme with the default Docker Monitor. A PreSharedKey is used for remote node signature verification.

  • NewPKITriremeWithDockerMonitor loads Trireme with the default Docker Monitor. ECDSA is used for signatures. In this case, a publicKeyAdder interface is returned. This interface is used to populate the certificates of the remote nodes.

In parameter to the helper of your choice, you need to give your own PolicyResolver interface implementation:

type PolicyResolver interface {

	// ResolvePolicy returns the policy.PUPolicy associated with the given contextID using the given policy.RuntimeReader.
	ResolvePolicy(contextID string, RuntimeReader policy.RuntimeReader) (*policy.PUPolicy, error)

	// HandleDeletePU is called when a PU is stopped/killed.
	HandlePUEvent(contextID string, eventType monitor.Event)
}

Each Container event generates a call to HandlePUEvent

The PolicyResolver can then issue explicit calls to the PolicyUpdater in order to push a policyUpdate for an already running ProcessingUnit:

type PolicyUpdater interface {

    // UpdatePolicy updates the policy of the isolator for a container.
    UpdatePolicy(contextID string, newPolicy *policy.PUPolicy) <-chan error
}

Prerequisites

  • Trireme-lib requires IPTables with access to the Mangle module.
  • Trireme-lib requires access to the Docker event API socket (/var/run/docker.sock by default)
  • Trireme-lib requires privileged access.
  • Trireme-lib requires to run in the Host PID namespace.

License

The Trireme package, although written in Go currently uses the libnetfilter-queue library: http://www.netfilter.org/projects/libnetfilter_queue/

This library provides the API to the Linux Kernel for interfacing with the NFQUEUE module that transfers packets to user space for processing. Since this library is provided under the GPL v2 license, and is linked with the rest of the Trireme code through CGO we are also releasing this code with a GPL v2 license.

We are taking this step to protect any users of the library from an accidental violation of the GPL guidelines.

Analytics

Expand ▾ Collapse ▴

Documentation

Overview

    Package trireme needs to be documented here for godoc.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func CleanOldState

    func CleanOldState()

      CleanOldState ensures all state in trireme is cleaned up.

      func GetLogParameters

      func GetLogParameters() (logToConsole bool, logID string, logLevel string, logFormat string)

        GetLogParameters retrieves log parameters for Remote Enforcer.

        func LaunchRemoteEnforcer

        func LaunchRemoteEnforcer(service packetprocessor.PacketProcessor) error

          LaunchRemoteEnforcer launches a remote enforcer instance.

          func NewMonitor

          func NewMonitor(opts ...MonitorOption) *monitor.Config

            NewMonitor provides a configuration for monitors.

            func SetLogParameters

            func SetLogParameters(logToConsole, logWithID bool, logLevel string, logFormat string)

              SetLogParameters sets up environment to be passed to the remote trireme instances.

              func Supervisors

              func Supervisors(t Trireme) []supervisor.Supervisor

                Supervisors returns a slice of all initialized supervisors.

                Types

                type CNIMonitorOption

                type CNIMonitorOption func(*cnimonitor.Config)

                  CNIMonitorOption is provided using functional arguments.

                  func SubOptionMonitorCNIExtractor

                  func SubOptionMonitorCNIExtractor(extractor events.EventMetadataExtractor) CNIMonitorOption

                    SubOptionMonitorCNIExtractor provides a way to specify metadata extractor for CNI monitors.

                    type DockerMonitorOption

                    type DockerMonitorOption func(*dockermonitor.Config)

                      DockerMonitorOption is provided using functional arguments.

                      func SubOptionDockerMonitorMode

                      func SubOptionDockerMonitorMode(mode constants.DockerMonitorMode) DockerMonitorOption

                        SubOptionDockerMonitorMode provides a way to set the mode for docker monitor

                        func SubOptionMonitorDockerExtractor

                        func SubOptionMonitorDockerExtractor(extractor dockermonitor.MetadataExtractor) DockerMonitorOption

                          SubOptionMonitorDockerExtractor provides a way to specify metadata extractor for docker.

                          func SubOptionMonitorDockerFlags

                          func SubOptionMonitorDockerFlags(syncAtStart, killContainerOnPolicyError bool) DockerMonitorOption

                            SubOptionMonitorDockerFlags provides a way to specify configuration flags info for docker.

                            func SubOptionMonitorDockerSocket

                            func SubOptionMonitorDockerSocket(socketType, socketAddress string) DockerMonitorOption

                              SubOptionMonitorDockerSocket provides a way to specify socket info for docker.

                              type LinuxMonitorOption

                              type LinuxMonitorOption func(*linuxmonitor.Config)

                                LinuxMonitorOption is provided using functional arguments.

                                func SubOptionMonitorLinuxExtractor

                                func SubOptionMonitorLinuxExtractor(extractor events.EventMetadataExtractor) LinuxMonitorOption

                                  SubOptionMonitorLinuxExtractor provides a way to specify metadata extractor for linux monitors.

                                  type MonitorOption

                                  type MonitorOption func(*monitor.Config)

                                    MonitorOption is provided using functional arguments.

                                    func OptionMergeTags

                                    func OptionMergeTags(tags []string) MonitorOption

                                      OptionMergeTags provides a way to add merge tags to be used with New().

                                      func OptionMonitorCNI

                                      func OptionMonitorCNI(
                                      	opts ...CNIMonitorOption,
                                      ) MonitorOption

                                        OptionMonitorCNI provides a way to add a cni monitor and related configuration to be used with New().

                                        func OptionMonitorDocker

                                        func OptionMonitorDocker(opts ...DockerMonitorOption) MonitorOption

                                          OptionMonitorDocker provides a way to add a docker monitor and related configuration to be used with New().

                                          func OptionMonitorLinuxHost

                                          func OptionMonitorLinuxHost(
                                          	opts ...LinuxMonitorOption,
                                          ) MonitorOption

                                            OptionMonitorLinuxHost provides a way to add a linux host monitor and related configuration to be used with New().

                                            func OptionMonitorLinuxProcess

                                            func OptionMonitorLinuxProcess(
                                            	opts ...LinuxMonitorOption,
                                            ) MonitorOption

                                              OptionMonitorLinuxProcess provides a way to add a linux process monitor and related configuration to be used with New().

                                              func OptionMonitorUID

                                              func OptionMonitorUID(
                                              	opts ...UIDMonitorOption,
                                              ) MonitorOption

                                                OptionMonitorUID provides a way to add a UID monitor and related configuration to be used with New().

                                                func OptionSynchronizationHandler

                                                func OptionSynchronizationHandler(
                                                	s processor.SynchronizationHandler,
                                                ) MonitorOption

                                                  OptionSynchronizationHandler provides options related to processor configuration to be used with New().

                                                  type Option

                                                  type Option func(*config)

                                                    Option is provided using functional arguments.

                                                    func OptionCollector

                                                    func OptionCollector(c collector.EventCollector) Option

                                                      OptionCollector is an option to provide an external collector implementation.

                                                      func OptionDatapathService

                                                      func OptionDatapathService(s packetprocessor.PacketProcessor) Option

                                                        OptionDatapathService is an option to provide an external datapath service implementation.

                                                        func OptionDisableMutualAuth

                                                        func OptionDisableMutualAuth() Option

                                                          OptionDisableMutualAuth is an option to disable MutualAuth (enabled by default)

                                                          func OptionEnforceFqConfig

                                                          func OptionEnforceFqConfig(f *fqconfig.FilterQueue) Option

                                                            OptionEnforceFqConfig is an option to override filter queues.

                                                            func OptionEnforceLinuxProcess

                                                            func OptionEnforceLinuxProcess() Option

                                                              OptionEnforceLinuxProcess is an option to request support for linux process support.

                                                              func OptionMonitors

                                                              func OptionMonitors(m *monitor.Config) Option

                                                                OptionMonitors is an option to provide configurations for monitors.

                                                                func OptionPacketLogs

                                                                func OptionPacketLogs() Option

                                                                  OptionPacketLogs is an option to enable packet level logging.

                                                                  func OptionPolicyResolver

                                                                  func OptionPolicyResolver(r PolicyResolver) Option

                                                                    OptionPolicyResolver is an option to provide an external policy resolver implementation.

                                                                    func OptionProcMountPoint

                                                                    func OptionProcMountPoint(p string) Option

                                                                      OptionProcMountPoint is an option to provide proc mount point.

                                                                      func OptionSecret

                                                                      func OptionSecret(s secrets.Secrets) Option

                                                                        OptionSecret is an option to provide an external datapath service implementation.

                                                                        func OptionTargetNetworks

                                                                        func OptionTargetNetworks(n []string) Option

                                                                          OptionTargetNetworks is an option to provide target network configuration.

                                                                          type PolicyResolver

                                                                          type PolicyResolver interface {
                                                                          
                                                                          	// ResolvePolicy returns the policy.PUPolicy associated with the given contextID using the given policy.RuntimeReader.
                                                                          	ResolvePolicy(contextID string, RuntimeReader policy.RuntimeReader) (*policy.PUPolicy, error)
                                                                          
                                                                          	// HandleDeletePU is called when a PU is stopped/killed.
                                                                          	HandlePUEvent(contextID string, eventType events.Event)
                                                                          }

                                                                            A PolicyResolver is responsible of creating the Policies for a specific Processing Unit. The PolicyResolver also got the ability to update an already instantiated policy.

                                                                            type PolicyUpdater

                                                                            type PolicyUpdater interface {
                                                                            
                                                                            	// UpdatePolicy updates the policy of the isolator for a container.
                                                                            	UpdatePolicy(contextID string, policy *policy.PUPolicy) error
                                                                            }

                                                                              A PolicyUpdater has the ability to receive an update for a specific policy.

                                                                              type SecretsUpdater

                                                                              type SecretsUpdater interface {
                                                                              	// UpdateSecrets updates the secrets of running enforcers managed by trireme. Remote enforcers will get the secret updates with the next policy push
                                                                              	UpdateSecrets(secrets secrets.Secrets) error
                                                                              }

                                                                                SecretsUpdater provides an interface to update the secrets of enforcers managed by trireme at runtime

                                                                                type Trireme

                                                                                type Trireme interface {
                                                                                
                                                                                	// PURuntime returns a getter for a specific contextID.
                                                                                	PURuntime(contextID string) (policy.RuntimeReader, error)
                                                                                
                                                                                	// Start starts the component.
                                                                                	Start() error
                                                                                
                                                                                	// Stop stops the component.
                                                                                	Stop() error
                                                                                
                                                                                	// Supervisor returns the supervisor for a given PU type
                                                                                	Supervisor(kind constants.PUType) supervisor.Supervisor
                                                                                
                                                                                	// processor.ProcessingUnitsHandler
                                                                                	// CreatePURuntime is called when a monitor detects creation of a new ProcessingUnit.
                                                                                	CreatePURuntime(contextID string, runtimeInfo *policy.PURuntime) error
                                                                                
                                                                                	// HandlePUEvent is called by all monitors when a PU event is generated. The implementer
                                                                                	// is responsible to update all components by explicitly adding a new PU.
                                                                                	HandlePUEvent(contextID string, event events.Event) error
                                                                                
                                                                                	// PolicyUpdater
                                                                                	// UpdatePolicy updates the policy of the isolator for a container.
                                                                                	UpdatePolicy(contextID string, policy *policy.PUPolicy) error
                                                                                
                                                                                	// SecretsUpdater
                                                                                	// UpdateSecrets updates the secrets of running enforcers managed by trireme. Remote enforcers will get the secret updates with the next policy push
                                                                                	UpdateSecrets(secrets secrets.Secrets) error
                                                                                }

                                                                                  Trireme is the main interface to the Trireme package.

                                                                                  func New

                                                                                  func New(serverID string, opts ...Option) Trireme

                                                                                    New returns a trireme interface implementation based on configuration provided.

                                                                                    type UIDMonitorOption

                                                                                    type UIDMonitorOption func(*uidmonitor.Config)

                                                                                      UIDMonitorOption is provided using functional arguments.

                                                                                      func SubOptionMonitorUIDExtractor

                                                                                      func SubOptionMonitorUIDExtractor(extractor events.EventMetadataExtractor) UIDMonitorOption

                                                                                        SubOptionMonitorUIDExtractor provides a way to specify metadata extractor for UID monitors.

                                                                                        Directories

                                                                                        Path Synopsis
                                                                                        cmd
                                                                                        mock
                                                                                        Package mockcollector is a generated GoMock package.
                                                                                        Package mockcollector is a generated GoMock package.
                                                                                        policyenforcer/mock
                                                                                        Package mockpolicyenforcer is a generated GoMock package.
                                                                                        Package mockpolicyenforcer is a generated GoMock package.
                                                                                        proxy
                                                                                        Package enforcerproxy :: This is the implementation of the RPC client It implements the interface of Trireme Enforcer and forwards these requests to the actual remote enforcer instead of implementing locally
                                                                                        Package enforcerproxy :: This is the implementation of the RPC client It implements the interface of Trireme Enforcer and forwards these requests to the actual remote enforcer instead of implementing locally
                                                                                        utils/packet
                                                                                        Package packet support for TCP/IP packet manipulations needed by the Aporeto infrastructure.
                                                                                        Package packet support for TCP/IP packet manipulations needed by the Aporeto infrastructure.
                                                                                        utils/packetgen
                                                                                        Package packetgen "PacketGen" is a Packet Generator library Current version: V1.0, Updates are coming soon
                                                                                        Package packetgen "PacketGen" is a Packet Generator library Current version: V1.0, Updates are coming soon
                                                                                        Package mocktrireme is a generated GoMock package.
                                                                                        Package mocktrireme is a generated GoMock package.
                                                                                        Package policy describes a generic interface for retrieving policies.
                                                                                        Package policy describes a generic interface for retrieving policies.
                                                                                        rpc
                                                                                        processor/mock
                                                                                        Package mockprocessor is a generated GoMock package.
                                                                                        Package mockprocessor is a generated GoMock package.
                                                                                        utils
                                                                                        cgnetcls
                                                                                        Package cgnetcls implements functionality to manage classid for processes belonging to different cgroups
                                                                                        Package cgnetcls implements functionality to manage classid for processes belonging to different cgroups
                                                                                        cgnetcls/mock
                                                                                        Package mockcgnetcls is a generated GoMock package.
                                                                                        Package mockcgnetcls is a generated GoMock package.
                                                                                        contextstore/mock
                                                                                        Package mockcontextstore is a generated GoMock package.
                                                                                        Package mockcontextstore is a generated GoMock package.
                                                                                        internal
                                                                                        monitor/instance/mock
                                                                                        Package mockinstance is a generated GoMock package.
                                                                                        Package mockinstance is a generated GoMock package.
                                                                                        monitor/mock
                                                                                        Package mockmonitor is a generated GoMock package.
                                                                                        Package mockmonitor is a generated GoMock package.
                                                                                        processmon
                                                                                        Package processmon is to manage and monitor remote enforcers.
                                                                                        Package processmon is to manage and monitor remote enforcers.
                                                                                        processmon/mock
                                                                                        Package mockprocessmon is a generated GoMock package.
                                                                                        Package mockprocessmon is a generated GoMock package.
                                                                                        remoteenforcer/internal/statsclient/mock
                                                                                        Package mockstatsclient is a generated GoMock package.
                                                                                        Package mockstatsclient is a generated GoMock package.
                                                                                        remoteenforcer/internal/statscollector/mock
                                                                                        Package mockstatscollector is a generated GoMock package.
                                                                                        Package mockstatscollector is a generated GoMock package.
                                                                                        remoteenforcer/mock
                                                                                        Package mockremoteenforcer is a generated GoMock package.
                                                                                        Package mockremoteenforcer is a generated GoMock package.
                                                                                        supervisor/mock
                                                                                        Package mocksupervisor is a generated GoMock package.
                                                                                        Package mocksupervisor is a generated GoMock package.
                                                                                        supervisor/provider/mock
                                                                                        nolint nolint
                                                                                        nolint nolint
                                                                                        supervisor/proxy
                                                                                        Package supervisorproxy package implements the supervisor interface and forwards the requests on this interface to a remote supervisor over an rpc call.
                                                                                        Package supervisorproxy package implements the supervisor interface and forwards the requests on this interface to a remote supervisor over an rpc call.