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
- type RegoPolicyInterpreter
- 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) GetMetadataMapValue(name string, key string) (interface{}, error)
- func (r *RegoPolicyInterpreter) IsModuleActive(id string) bool
- func (r *RegoPolicyInterpreter) MetadataJSON() (string, error)
- 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) RestoreMetadata(m SavedMetadata) error
- func (r *RegoPolicyInterpreter) SaveMetadata() (s SavedMetadata, err error)
- func (r *RegoPolicyInterpreter) SetLogLevel(level LogLevel)
- func (r *RegoPolicyInterpreter) UpdateData(key string, value interface{}) error
- func (r *RegoPolicyInterpreter) UpdateOSType(os string) error
- type RegoQueryResult
- func (r RegoQueryResult) Array(key string) ([]interface{}, error)
- 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)
- type SavedMetadata
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type RegoModule ¶
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) GetMetadataMapValue ¶ added in v0.15.0
func (r *RegoPolicyInterpreter) GetMetadataMapValue(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) MetadataJSON ¶ added in v0.15.0
func (r *RegoPolicyInterpreter) MetadataJSON() (string, error)
MetadataJSON returns the entire metadata object as a JSON string. The returned JSON is a snapshot (deep-copied via marshal/unmarshal).
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) 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) RestoreMetadata ¶ added in v0.15.0
func (r *RegoPolicyInterpreter) RestoreMetadata(m SavedMetadata) error
Restores a previously saved metadata state.
func (*RegoPolicyInterpreter) SaveMetadata ¶ added in v0.15.0
func (r *RegoPolicyInterpreter) SaveMetadata() (s SavedMetadata, err error)
Saves a copy of the internal policy metadata state.
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.
func (*RegoPolicyInterpreter) UpdateOSType ¶ added in v0.15.0
func (r *RegoPolicyInterpreter) UpdateOSType(os string) error
type RegoQueryResult ¶
type RegoQueryResult map[string]interface{}
The result from a policy query
func (RegoQueryResult) Array ¶ added in v0.15.0
func (r RegoQueryResult) Array(key string) ([]interface{}, error)
Array attempts to interpret the result value as an array.
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.
type SavedMetadata ¶ added in v0.15.0
type SavedMetadata struct {
// contains filtered or unexported fields
}
An immutable, saved copy of the metadata state.
Source Files