regopolicyinterpreter

README

Rego Policy Interpreter

This module provides a general purpose Rego Policy interpreter. This is used both by the security_policy package, as well as the policy engine simulator.

Metadata

Each rule in a policy can optionally return a series of metadata commands in addition to allowed which will then be made available in the data.metadata namespace for use by the policy in future rule evaluations. A metadata command has the following format:

{
    {
        "name": "<metadata key>",
        "action": "<add|update|remove>",
        "key": "<key>",
        "value": "<optional value>"
    }
}

Metadata values can be any Rego object, i.e. arbitrary JSON. Importantly, the Go code does not need to understand what they are or what they contain, just place them in the specified point in the hierarchy such that the policy can find them in later rule evaluations. To give a sense of how this works, here are a sequence of rule results and the resulting metadata state:

Initial State

{
    "metadata": {}
}

Result 1

{
    "allowed": true,
    "metadata": [{
        "name": "devices",
        "action": "add",
        "key": "/dev/layer0",
        "value": "5c5d1ae1aff5e1f36d5300de46592efe4ccb7889e60a4b82bbaf003c2248f2a7"
    }]
}

State 1

{
    "metadata": {
        "devices": {
            "/dev/layer0": "5c5d1ae1aff5e1f36d5300de46592efe4ccb7889e60a4b82bbaf003c2248f2a7"
        }
    }
}

Result 2

{
    "allowed": true,
    "metadata": [{
        "name": "matches",
        "action": "add",
        "key": "container1",
        "value": [{<container>}, {<container>}, {<container>}]
    }]
}

State 2

{
    "metadata": {
        "devices": {
            "/dev/layer0": "5c5d1ae1aff5e1f36d5300de46592efe4ccb7889e60a4b82bbaf003c2248f2a7"
        },
        "matches": {
            "container1": [{<container>}, {<container>}, {<container>}]
        }
    }
}

Result 3

{
    "allowed": true,
    "metadata": [{
        "name": "matches",
        "action": "update",
        "key": "container1",
        "value": [{<container>}]
    }]
}

State 3

{
    "metadata": {
        "devices": {
            "/dev/layer0": "5c5d1ae1aff5e1f36d5300de46592efe4ccb7889e60a4b82bbaf003c2248f2a7"
        },
        "matches": {
            "container1": [{<container>}]
        }
    }
}

Result 4

{
    "allowed": true,
    "metadata": [{
        "name": "devices",
        "action": "remove",
        "key": "/dev/layer0"
    }]
}

State 4

{
    "metadata": {
        "devices": {},
        "matches": {
            "container1": [{<container>}]
        }
    }
}

Documentation

Index

• func ModuleID(issuer string, feed string) string
• type LogLevel
• type RegoModule
  • func (f RegoModule) ID() string
• type RegoPolicyInterpreter
  • func NewRegoPolicyInterpreter(code string, inputData map[string]interface{}) (*RegoPolicyInterpreter, error)
  • func (r *RegoPolicyInterpreter) AddModule(id string, module *RegoModule)
  • func (r *RegoPolicyInterpreter) Compile() error
  • func (r *RegoPolicyInterpreter) DisableLogging() error
  • func (r *RegoPolicyInterpreter) EnableLogging(path string, level LogLevel) error
  • func (r *RegoPolicyInterpreter) GetData(key string) (interface{}, error)
  • func (r *RegoPolicyInterpreter) GetMetadata(name string, key string) (interface{}, error)
  • func (r *RegoPolicyInterpreter) IsModuleActive(id string) bool
  • func (r *RegoPolicyInterpreter) Query(rule string, input map[string]interface{}) (RegoQueryResult, error)
  • func (r *RegoPolicyInterpreter) RawQuery(rule string, input map[string]interface{}) (rego.ResultSet, error)
  • func (r *RegoPolicyInterpreter) RemoveModule(id string)
  • func (r *RegoPolicyInterpreter) SetLogLevel(level LogLevel)
  • func (r *RegoPolicyInterpreter) UpdateData(key string, value interface{}) error
• type RegoQueryResult
  • func (r RegoQueryResult) Bool(key string) (bool, error)
  • func (r RegoQueryResult) Float(key string) (float64, error)
  • func (r RegoQueryResult) Int(key string) (int, error)
  • func (r RegoQueryResult) IsEmpty() bool
  • func (r RegoQueryResult) Object(key string) (map[string]interface{}, error)
  • func (r RegoQueryResult) String(key string) (string, error)
  • func (r RegoQueryResult) Union(other RegoQueryResult) RegoQueryResult
  • func (r RegoQueryResult) Value(key string) (interface{}, error)

Functions

func ModuleID

func ModuleID(issuer string, feed string) string

ModuleID computes a unique ID for a Module from its issuer and feed.

Types

type LogLevel

type LogLevel int

const (
	LogNone LogLevel = iota
	// Logs the output of Rego print() statements in the policy
	LogInfo
	// Logs the result objects returned from each query
	LogResults
	// Logs the full metadata state after each query
	LogMetadata
)

type RegoModule

type RegoModule struct {
	// The Rego namespace of the module
	Namespace string
	// The feed from which the module was obtained
	Feed string
	// The issuer of the module
	Issuer string
	// The module Rego code
	Code string
}

func (RegoModule) ID

func (f RegoModule) ID() string

ID is the unique ID of a module.

type RegoPolicyInterpreter

type RegoPolicyInterpreter struct {
	// contains filtered or unexported fields
}

func NewRegoPolicyInterpreter

func NewRegoPolicyInterpreter(code string, inputData map[string]interface{}) (*RegoPolicyInterpreter, error)

NewRegoPolicyInterpreter creates a new RegoPolicyInterpreter, using the code provided. inputData is the Rego data which should be used as the initial state of the interpreter. A deep copy is performed on it such that it will not be modified.

func (*RegoPolicyInterpreter) AddModule

func (r *RegoPolicyInterpreter) AddModule(id string, module *RegoModule)

AddModule adds the specified module to the interpreter such that it will be loaded along with the policy during query execution. The provided id should be used to refer to it for other methods. This will also invalidate the compliation artifact (i.e. Compile must be called again)

func (*RegoPolicyInterpreter) Compile

func (r *RegoPolicyInterpreter) Compile() error

Compile compiles the policy and its modules. This will increase the speed of policy execution.

func (*RegoPolicyInterpreter) DisableLogging

func (r *RegoPolicyInterpreter) DisableLogging() error

DisableLogging disables logging and closes the underlying log file.

func (*RegoPolicyInterpreter) EnableLogging

func (r *RegoPolicyInterpreter) EnableLogging(path string, level LogLevel) error

EnableLogging enables logging to the provided path at the specified level.

func (*RegoPolicyInterpreter) GetData

func (r *RegoPolicyInterpreter) GetData(key string) (interface{}, error)

GetData attempts to retrieve and return a copy of the data value with the specified key.

func (*RegoPolicyInterpreter) GetMetadata

func (r *RegoPolicyInterpreter) GetMetadata(name string, key string) (interface{}, error)

GetMetadata retrieves a copy of a single metadata item from the policy.

func (*RegoPolicyInterpreter) IsModuleActive

func (r *RegoPolicyInterpreter) IsModuleActive(id string) bool

IsModuleActive returns whether the specified module is currently active, i.e. being loaded along with the policy.

func (*RegoPolicyInterpreter) Query

func (r *RegoPolicyInterpreter) Query(rule string, input map[string]interface{}) (RegoQueryResult, error)

Query queries the policy with the given rule and input data and returns the result.

func (*RegoPolicyInterpreter) RawQuery

func (r *RegoPolicyInterpreter) RawQuery(rule string, input map[string]interface{}) (rego.ResultSet, error)

func (*RegoPolicyInterpreter) RemoveModule

func (r *RegoPolicyInterpreter) RemoveModule(id string)

RemoveModule removes the specified module such that it will no longer be loaded. This will also invalidate the compliation artifact (i.e. Compile must be called again)

func (*RegoPolicyInterpreter) SetLogLevel

func (r *RegoPolicyInterpreter) SetLogLevel(level LogLevel)

SetLogLevel sets the logging level. To actually produce a log, however, EnableLogging must be called first.

func (*RegoPolicyInterpreter) UpdateData

func (r *RegoPolicyInterpreter) UpdateData(key string, value interface{}) error

UpdateData will perform an update to a value which is already within the data A deep copy will be performed on the value.

type RegoQueryResult

type RegoQueryResult map[string]interface{}

The result from a policy query

func (RegoQueryResult) Bool

func (r RegoQueryResult) Bool(key string) (bool, error)

Bool attempts to interpret a result value as a boolean.

func (RegoQueryResult) Float

func (r RegoQueryResult) Float(key string) (float64, error)

Float attempts to interpret the result value as a floating point number.

func (RegoQueryResult) Int

func (r RegoQueryResult) Int(key string) (int, error)

Int attempts to interpret the result value as an integer.

func (RegoQueryResult) IsEmpty

func (r RegoQueryResult) IsEmpty() bool

IsEmpty tests if the query result is empty.

func (RegoQueryResult) Object

func (r RegoQueryResult) Object(key string) (map[string]interface{}, error)

Object attempts to interpret the result value as an object

func (RegoQueryResult) String

func (r RegoQueryResult) String(key string) (string, error)

String attempts to interpret the result value as a string.

func (RegoQueryResult) Union

func (r RegoQueryResult) Union(other RegoQueryResult) RegoQueryResult

Union creates a new result object which is the union of this result with another result, in which the results of the other will take precedence.

func (RegoQueryResult) Value

func (r RegoQueryResult) Value(key string) (interface{}, error)

Value returns the raw value from a Rego query result.