parser

Documentation

Overview

Package parser contains a parser for Pomerium Policy Language.

The Pomerium Policy Language is a JSON or YAML document containing rules, actions, logical operators and criteria.

The document contains zero or more rules.

A rule has an action and zero or more logical operators.

An action is either "allow" or "deny".

The logical operators are "and", "or" and "not" and contain zero or more criteria.

A criterion has a name and arbitrary JSON data.

An example policy:

allow:
  and:
  - domain: example.com
  - group: admin
deny:
  or:
  - user: user1@example.com
  - user: user2@example.com

The JSON Schema for the language:

{
  "$ref": "#/definitions/policy",
  "definitions": {
    "policy": {
      "anyOf": [
        { "$ref": "#/definitions/rules" },
        {
          "type": "array",
          "items": { "$ref": "#/definitions/rules" }
        }
      ]
    },
    "rules": {
      "type": "object",
      "properties": {
        "allow": { "$ref": "#/definitions/rule_body" },
        "deny": { "$ref": "#/definitions/rule_body" }
      }
    },
    "rule_body": {
      "type": "object",
      "properties": {
        "and": {
          "type": "array",
          "items": { "$ref": "#/definitions/criteria" }
        },
        "not": {
          "type": "array",
          "items": { "$ref": "#/definitions/criteria" }
        },
        "or": {
          "type": "array",
          "items": { "$ref": "#/definitions/criteria" }
        }
      },
      "additionalProperties": false
    },
    "criteria": {
      "type": "object",
      "additionalProperties": true,
      "minProperties": 1,
      "maxProperties": 1
    }
  }
}

Index

• type Action
  • func ActionFromValue(value Value) (Action, error)
• type Array
  • func (a Array) Clone() Value
  • func (a Array) RegoValue() ast.Value
  • func (a Array) String() string
• type Boolean
  • func (b Boolean) Clone() Value
  • func (b Boolean) RegoValue() ast.Value
  • func (b Boolean) String() string
• type Criterion
  • func CriteriaFromArray(a Array) ([]Criterion, error)
  • func CriteriaFromValue(v Value) ([]Criterion, error)
  • func CriterionFromObject(o Object) (*Criterion, error)
  • func (c *Criterion) MarshalJSON() ([]byte, error)
  • func (c *Criterion) String() string
  • func (c *Criterion) ToJSON() Value
• type Null
  • func (Null) Clone() Value
  • func (Null) RegoValue() ast.Value
  • func (Null) String() string
• type Number
  • func (n Number) Clone() Value
  • func (n Number) Float64() float64
  • func (n Number) Int64() int64
  • func (n Number) MarshalJSON() ([]byte, error)
  • func (n Number) RegoValue() ast.Value
  • func (n Number) String() string
• type Object
  • func (o Object) Clone() Value
  • func (o Object) Falsy(field string) bool
  • func (o Object) RegoValue() ast.Value
  • func (o Object) String() string
  • func (o Object) Truthy(field string) bool
• type Parser
  • func New() *Parser
  • func (p *Parser) ParseJSON(r io.Reader) (*Policy, error)
  • func (p *Parser) ParseYAML(r io.Reader) (*Policy, error)
• type Policy
  • func ParseJSON(r io.Reader) (*Policy, error)
  • func ParseYAML(r io.Reader) (*Policy, error)
  • func PolicyFromValue(v Value) (*Policy, error)
  • func (p *Policy) AddDefaultClientCertificateRule()
  • func (p *Policy) MarshalJSON() ([]byte, error)
  • func (p *Policy) String() string
  • func (p *Policy) ToJSON() Value
• type Rule
  • func RulesFromArray(a Array) ([]Rule, error)
  • func RulesFromObject(o Object) ([]Rule, error)
  • func RulesFromValue(v Value) ([]Rule, error)
  • func (r *Rule) MarshalJSON() ([]byte, error)
  • func (r *Rule) String() string
  • func (r *Rule) ToJSON() Value
• type String
  • func (s String) Clone() Value
  • func (s String) RegoValue() ast.Value
  • func (s String) String() string
• type Value
  • func ParseValue(r io.Reader) (Value, error)

Types

type Action

type Action string

An Action describe what to do when a rule matches, either "allow" or "deny".

const (
	ActionAllow Action = "allow"
	ActionDeny  Action = "deny"
)

Actions

func ActionFromValue

func ActionFromValue(value Value) (Action, error)

ActionFromValue converts a Value into an Action.

type Array

type Array []Value

An Array is a slice of values.

func (Array) Clone

func (a Array) Clone() Value

Clone clones the array.

func (Array) RegoValue

func (a Array) RegoValue() ast.Value

RegoValue returns the Array as a rego Value.

func (Array) String

func (a Array) String() string

String returns the JSON representation of the Array.

type Boolean

type Boolean bool

A Boolean is either true or false.

func (Boolean) Clone

func (b Boolean) Clone() Value

Clone clones the boolean.

func (Boolean) RegoValue

func (b Boolean) RegoValue() ast.Value

RegoValue returns the Boolean as a rego Value.

func (Boolean) String

func (b Boolean) String() string

String returns the JSON representation of the Boolean.

type Criterion

type Criterion struct {
	Name    string
	SubPath string
	Data    Value
}

A Criterion is used by a rule to determine if the rule matches or not.

Criteria RegoRulesGenerators are registered based on the specified name. Data is arbitrary JSON data sent to the generator.

func CriteriaFromArray

func CriteriaFromArray(a Array) ([]Criterion, error)

CriteriaFromArray converts an Array into Criteria. Each element of the Array is converted using CriterionFromObject.

func CriteriaFromValue

func CriteriaFromValue(v Value) ([]Criterion, error)

CriteriaFromValue converts a Value into Criteria. Only Arrays are supported.

func CriterionFromObject

func CriterionFromObject(o Object) (*Criterion, error)

CriterionFromObject converts an Object into a Criterion.

One form is supported:

1. An object where the keys are the names with a sub path and the values are the corresponding data for each Criterion: `{ "groups": "group1" }`

func (*Criterion) MarshalJSON

func (c *Criterion) MarshalJSON() ([]byte, error)

MarshalJSON marshals the criterion as JSON.

func (*Criterion) String

func (c *Criterion) String() string

String converts the criterion to a string.

func (*Criterion) ToJSON

func (c *Criterion) ToJSON() Value

ToJSON converts the criterion to JSON.

type Null

type Null struct{}

A Null is the nil value.

func (Null) Clone

func (Null) Clone() Value

Clone clones the null.

func (Null) RegoValue

func (Null) RegoValue() ast.Value

RegoValue returns the Null as a rego Value.

func (Null) String

func (Null) String() string

String returns JSON null.

type Number

type Number string

A Number is an integer or a floating point value stored in string representation.

func (Number) Clone

func (n Number) Clone() Value

Clone clones the number.

func (Number) Float64

func (n Number) Float64() float64

Float64 returns the number as a float64.

func (Number) Int64

func (n Number) Int64() int64

Int64 returns the number as an int64.

func (Number) MarshalJSON

func (n Number) MarshalJSON() ([]byte, error)

MarshalJSON marshals the number as JSON.

func (Number) RegoValue

func (n Number) RegoValue() ast.Value

RegoValue returns the Number as a rego Value.

func (Number) String

func (n Number) String() string

String returns the JSON representation of the Number.

type Object

type Object map[string]Value

An Object is a map of strings to values.

func (Object) Clone

func (o Object) Clone() Value

Clone clones the Object.

func (Object) Falsy

func (o Object) Falsy(field string) bool

Falsy returns true if the value is considered Javascript falsy:

https://developer.mozilla.org/en-US/docs/Glossary/Falsy.

If the field is not found in the object it is *not* falsy.

func (Object) RegoValue

func (o Object) RegoValue() ast.Value

RegoValue returns the Object as a rego Value.

func (Object) String

func (o Object) String() string

String returns the JSON representation of the Object.

func (Object) Truthy

func (o Object) Truthy(field string) bool

Truthy returns the opposite of Falsy, however if the field is not found in the object it is neither truthy nor falsy.

type Parser

type Parser struct{}

A Parser parses raw policy definitions into a Policy.

func New

func New() *Parser

New creates a new Parser.

func (*Parser) ParseJSON

func (p *Parser) ParseJSON(r io.Reader) (*Policy, error)

ParseJSON parses a raw JSON document into a policy.

func (*Parser) ParseYAML

func (p *Parser) ParseYAML(r io.Reader) (*Policy, error)

ParseYAML parses a raw YAML document into a policy.

type Policy

type Policy struct {
	Rules []Rule
}

A Policy is a policy made up of multiple allow or deny rules.

func ParseJSON

func ParseJSON(r io.Reader) (*Policy, error)

ParseJSON creates a parser and calls ParseJSON on it.

func ParseYAML

func ParseYAML(r io.Reader) (*Policy, error)

ParseYAML creates a parser and calls ParseYAML on it.

func PolicyFromValue

func PolicyFromValue(v Value) (*Policy, error)

PolicyFromValue converts a value into a Policy.

func (*Policy) AddDefaultClientCertificateRule

func (p *Policy) AddDefaultClientCertificateRule()

AddDefaultClientCertificateRule adds a deny rule to the policy with the criterion invalid_client_certificate.

func (*Policy) MarshalJSON

func (p *Policy) MarshalJSON() ([]byte, error)

MarshalJSON marshals the policy as JSON.

func (*Policy) String

func (p *Policy) String() string

String converts the policy to a string.

func (*Policy) ToJSON

func (p *Policy) ToJSON() Value

ToJSON converts the policy to JSON.

type Rule

type Rule struct {
	Action Action
	And    []Criterion
	Or     []Criterion
	Not    []Criterion
	Nor    []Criterion
}

A Rule is a policy rule with a corresponding action ("allow" or "deny"), and conditionals to determine if the rule matches or not.

func RulesFromArray

func RulesFromArray(a Array) ([]Rule, error)

RulesFromArray converts an Array into a slice of Rules. Each element of the Array is converted using RulesFromObject and merged together.

func RulesFromObject

func RulesFromObject(o Object) ([]Rule, error)

RulesFromObject converts an Object into a slice of Rules.

One form is supported:

1. An object where the keys are the actions and the values are an object with "and", "or", or "not" fields: `{ "allow": { "and": [ {"groups": "group1"} ] } }`

func RulesFromValue

func RulesFromValue(v Value) ([]Rule, error)

RulesFromValue converts a Value into a slice of Rules. Only Arrays or Objects are supported.

func (*Rule) MarshalJSON

func (r *Rule) MarshalJSON() ([]byte, error)

MarshalJSON marshals the rule as JSON.

func (*Rule) String

func (r *Rule) String() string

String converts the rule to a string.

func (*Rule) ToJSON

func (r *Rule) ToJSON() Value

ToJSON converts the rule to JSON.

type String

type String string

A String is a wrapper around a string.

func (String) Clone

func (s String) Clone() Value

Clone clones the string.

func (String) RegoValue

func (s String) RegoValue() ast.Value

RegoValue returns the String as a rego Value.

func (String) String

func (s String) String() string

String returns the JSON representation of the String.

type Value

type Value interface {
	Clone() Value
	RegoValue() ast.Value
	// contains filtered or unexported methods
}

A Value is a JSON value. Either an object, array, string, number, boolean or null.

func ParseValue

func ParseValue(r io.Reader) (Value, error)

ParseValue parses JSON into a value.