cedar

package module
v0.0.0-...-77c610b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2024 License: Apache-2.0 Imports: 11 Imported by: 0

README

cedar-go

Cedar Logo

Build and Test golangci-lint Nightly Corpus Test

This repository contains source code of the Go implementation of the Cedar policy language.

Cedar is a language for writing and enforcing authorization policies in your applications. Using Cedar, you can write policies that specify your applications' fine-grained permissions. Your applications then authorize access requests by calling Cedar's authorization engine. Because Cedar policies are separate from application code, they can be independently authored, updated, analyzed, and audited. You can use Cedar's validator to check that Cedar policies are consistent with a declared schema which defines your application's authorization model.

Cedar is:

Expressive

Cedar is a simple yet expressive language that is purpose-built to support authorization use cases for common authorization models such as RBAC and ABAC.

Performant

Cedar is fast and scalable. The policy structure is designed to be indexed for quick retrieval and to support fast and scalable real-time evaluation, with bounded latency.

Analyzable

Cedar is designed for analysis using Automated Reasoning. This enables analyzer tools capable of optimizing your policies and proving that your security model is what you believe it is.

Using Cedar

Cedar can be used in your application by importing the github.com/cedar-policy/cedar-go package.

Comparison to the Rust implementation

The Go implementation includes:

  • the core authorizer
  • JSON marshalling and unmarshalling
  • all core and extended types
  • integration test suite

The Go implementation does not yet include:

  • examples and CLI applications
  • schema support and the validator
  • the formatter
  • partial evaluation

Quick Start

Here's a simple example of using Cedar in Go:

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/cedar-policy/cedar-go"
)

const policyCedar = `permit (
	principal == User::"alice",
	action == Action::"view",
	resource in Album::"jane_vacation"
  );
`

const entitiesJSON = `[
  {
    "uid": { "type": "User", "id": "alice" },
    "attrs": { "age": 18 },
    "parents": []
  },
  {
    "uid": { "type": "Photo", "id": "VacationPhoto94.jpg" },
    "attrs": {},
    "parents": [{ "type": "Album", "id": "jane_vacation" }]
  }
]`

func main() {
	ps, err := cedar.NewPolicySet("policy.cedar", []byte(policyCedar))
	if err != nil {
		log.Fatal(err)
	}
	var entities cedar.Entities
	if err := json.Unmarshal([]byte(entitiesJSON), &entities); err != nil {
		log.Fatal(err)
	}
	req := cedar.Request{
		Principal: cedar.EntityUID{Type: "User", ID: "alice"},
		Action:    cedar.EntityUID{Type: "Action", ID: "view"},
		Resource:  cedar.EntityUID{Type: "Photo", ID: "VacationPhoto94.jpg"},
		Context:   cedar.Record{},
	}
	ok, _ := ps.IsAuthorized(entities, req)
	fmt.Println(ok)
}

CLI output:

allow

This request is allowed because VacationPhoto94.jpg belongs to Album::"jane_vacation", and alice can view photos in Album::"jane_vacation".

If you'd like to see more details on what can be expressed as Cedar policies, see the documentation.

Documentation

General documentation for Cedar is available at docs.cedarpolicy.com, with source code in the cedar-policy/cedar-docs repository.

Generated documentation for the latest version of the Go implementation can be accessed here.

If you're looking to integrate Cedar into a production system, please be sure the read the security best practices

Backward Compatibility Considerations

x/exp - code in this subrepository is not subject to the Go 1 compatibility promise.

Security

See CONTRIBUTING for more information.

Contributing

We welcome contributions from the community. Please either file an issue, or see CONTRIBUTING

License

This project is licensed under the Apache-2.0 License.

Documentation

Overview

Package cedar provides an implementation of the Cedar language authorizer.

Index

Constants

View Source 
const (
	Permit = Effect(true)
	Forbid = Effect(false)
)

Each Policy has a Permit or Forbid effect that is determined during parsing.

View Source 
const (
	Allow = Decision(true)
	Deny  = Decision(false)
)

Each authorization results in one of these Decisions.

View Source 
const DecimalPrecision = 10000

DecimalPrecision is the precision of a Decimal.

Variables

This section is empty.

Functions

This section is empty.

Types

type Annotations 

type Annotations map[string]string

An Annotations is a map of key, value pairs found in the policy. Annotations have no impact on policy evaluation.

type Boolean 

type Boolean bool

A Boolean is a value that is either true or false.

func (Boolean) Cedar 

func (v Boolean) Cedar() string

Cedar produces a valid Cedar language representation of the Boolean, e.g. `true`.

func (Boolean) ExplicitMarshalJSON 

func (v Boolean) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the Boolean into JSON.

func (Boolean) String 

func (v Boolean) String() string

String produces a string representation of the Boolean, e.g. `true`.

type Decimal 

type Decimal int64

A Decimal is a value with both a whole number part and a decimal part of no more than four digits. In Go this is stored as an int64, the precision is defined by the constant DecimalPrecision.

func ParseDecimal 

func ParseDecimal(s string) (Decimal, error)

ParseDecimal takes a string representation of a decimal number and converts it into a Decimal type.

func (Decimal) Cedar 

func (v Decimal) Cedar() string

Cedar produces a valid Cedar language representation of the Decimal, e.g. `decimal("12.34")`.

func (Decimal) ExplicitMarshalJSON 

func (v Decimal) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the Decimal into JSON using the explicit form.

func (Decimal) MarshalJSON 

func (v Decimal) MarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the Decimal into JSON using the implicit form.

func (Decimal) String 

func (v Decimal) String() string

String produces a string representation of the Decimal, e.g. `12.34`.

func (*Decimal) UnmarshalJSON 

func (v *Decimal) UnmarshalJSON(b []byte) error

type Decision 

type Decision bool

A Decision is the result of the authorization.

func (Decision) MarshalJSON 

func (a Decision) MarshalJSON() ([]byte, error)

func (Decision) String 

func (a Decision) String() string

func (*Decision) UnmarshalJSON 

func (a *Decision) UnmarshalJSON(b []byte) error

type Diagnostic 

type Diagnostic struct {
	Reasons []Reason `json:"reasons,omitempty"`
	Errors  []Error  `json:"errors,omitempty"`
}

A Diagnostic details the errors and reasons for an authorization decision.

type Effect 

type Effect bool

An Effect specifies the intent of the policy, to either permit or forbid any request that matches the scope and conditions specified in the policy.

func (Effect) MarshalJSON 

func (a Effect) MarshalJSON() ([]byte, error)

func (Effect) String 

func (a Effect) String() string

func (*Effect) UnmarshalJSON 

func (a *Effect) UnmarshalJSON(b []byte) error

type Entities 

type Entities map[EntityUID]Entity

An Entities is a collection of all the Entities that are needed to evaluate authorization requests. The key is an EntityUID which uniquely identifies the Entity (it must be the same as the UID within the Entity itself.)

func (Entities) Clone 

func (e Entities) Clone() Entities

func (Entities) MarshalJSON 

func (e Entities) MarshalJSON() ([]byte, error)

func (*Entities) UnmarshalJSON 

func (e *Entities) UnmarshalJSON(b []byte) error

type Entity 

type Entity struct {
	UID        EntityUID   `json:"uid"`
	Parents    []EntityUID `json:"parents,omitempty"`
	Attributes Record      `json:"attrs"`
}

An Entity defines the parents and attributes for an EntityUID.

type EntityUID 

type EntityUID struct {
	Type string
	ID   string
}

An EntityUID is the identifier for a principal, action, or resource.

func NewEntityUID 

func NewEntityUID(typ, id string) EntityUID

func (EntityUID) Cedar 

func (v EntityUID) Cedar() string

Cedar produces a valid Cedar language representation of the EntityUID, e.g. `Type::"id"`.

func (EntityUID) ExplicitMarshalJSON 

func (v EntityUID) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the EntityUID into JSON using the explicit form.

func (EntityUID) IsZero 

func (a EntityUID) IsZero() bool

IsZero returns true if the EntityUID has an empty Type and ID.

func (EntityUID) MarshalJSON 

func (v EntityUID) MarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the EntityUID into JSON using the implicit form.

func (EntityUID) String 

func (v EntityUID) String() string

String produces a string representation of the EntityUID, e.g. `Type::"id"`.

func (*EntityUID) UnmarshalJSON 

func (v *EntityUID) UnmarshalJSON(b []byte) error

type Error 

type Error struct {
	Policy   int      `json:"policy"`
	Position Position `json:"position"`
	Message  string   `json:"message"`
}

An Error details the Policy index within a PolicySet, the Position within the text document, and the resulting error message.

func (Error) String 

func (e Error) String() string

type IPAddr 

type IPAddr netip.Prefix

An IPAddr is value that represents an IP address. It can be either IPv4 or IPv6. The value can represent an individual address or a range of addresses.

func ParseIPAddr 

func ParseIPAddr(s string) (IPAddr, error)

ParseIPAddr takes a string representation of an IP address and converts it into an IPAddr type.

func (IPAddr) Addr 

func (v IPAddr) Addr() netip.Addr

func (IPAddr) Cedar 

func (v IPAddr) Cedar() string

Cedar produces a valid Cedar language representation of the IPAddr, e.g. `ip("127.0.0.1")`.

func (IPAddr) ExplicitMarshalJSON 

func (v IPAddr) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the IPAddr into JSON using the explicit form.

func (IPAddr) MarshalJSON 

func (v IPAddr) MarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the IPAddr into JSON using the implicit form.

func (IPAddr) Prefix 

func (v IPAddr) Prefix() netip.Prefix

func (IPAddr) String 

func (v IPAddr) String() string

String produces a string representation of the IPAddr, e.g. `127.0.0.1`.

func (*IPAddr) UnmarshalJSON 

func (v *IPAddr) UnmarshalJSON(b []byte) error

type Long 

type Long int64

A Long is a whole number without decimals that can range from -9223372036854775808 to 9223372036854775807.

func (Long) Cedar 

func (v Long) Cedar() string

Cedar produces a valid Cedar language representation of the Long, e.g. `42`.

func (Long) ExplicitMarshalJSON 

func (v Long) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the Long into JSON.

func (Long) String 

func (v Long) String() string

String produces a string representation of the Long, e.g. `42`.

type Policy 

type Policy struct {
	Position    Position    // location within the policy text document
	Annotations Annotations // annotations found for this policy
	Effect      Effect      // the effect of this policy
	// contains filtered or unexported fields
}

A Policy is the parsed form of a single Cedar language policy statement. It includes the following elements, a Position, Annotations, and an Effect.

type PolicySet 

type PolicySet []Policy

A PolicySet is a slice of policies.

func NewPolicySet 

func NewPolicySet(fileName string, document []byte) (PolicySet, error)

NewPolicySet will create a PolicySet from the given text document with the given file name used in Position data. If there is an error parsing the document, it will be returned.

func (PolicySet) IsAuthorized 

func (p PolicySet) IsAuthorized(entities Entities, req Request) (Decision, Diagnostic)

IsAuthorized uses the combination of the PolicySet and Entities to determine if the given Request to determine Decision and Diagnostic.

type Position 

type Position struct {
	Filename string // filename, if any
	Offset   int    // byte offset, starting at 0
	Line     int    // line number, starting at 1
	Column   int    // column number, starting at 1 (character count per line)
}

A Position describes an arbitrary source position including the file, line, and column location.

type Reason 

type Reason struct {
	Policy   int      `json:"policy"`
	Position Position `json:"position"`
}

A Reason details the Policy index within a PolicySet, and the Position within the text document.

type Record 

type Record map[string]Value

A Record is a collection of attributes. Each attribute consists of a name and an associated value. Names are simple strings. Values can be of any type.

func (Record) Cedar 

func (r Record) Cedar() string

Cedar produces a valid Cedar language representation of the Record, e.g. `{"a":1,"b":2,"c":3}`.

func (Record) DeepClone 

func (v Record) DeepClone() Record

DeepClone returns a deep clone of the Record.

func (Record) Equals 

func (r Record) Equals(b Record) bool

Equals returns true if the records are equal.

func (Record) ExplicitMarshalJSON 

func (v Record) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the Record into JSON, the marshaller uses the explicit JSON form for all the values in the Record.

func (Record) MarshalJSON 

func (v Record) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Record into JSON, the marshaller uses the explicit JSON form for all the values in the Record.

func (Record) String 

func (r Record) String() string

String produces a string representation of the Record, e.g. `{"a":1,"b":2,"c":3}`.

func (*Record) UnmarshalJSON 

func (v *Record) UnmarshalJSON(b []byte) error

type Request 

type Request struct {
	Principal EntityUID `json:"principal"`
	Action    EntityUID `json:"action"`
	Resource  EntityUID `json:"resource"`
	Context   Record    `json:"context"`
}

A Request is the Principal, Action, Resource, and Context portion of an authorization request.

type Set 

type Set []Value

A Set is a collection of elements that can be of the same or different types.

func (Set) Cedar 

func (v Set) Cedar() string

Cedar produces a valid Cedar language representation of the Set, e.g. `[1,2,3]`.

func (Set) DeepClone 

func (v Set) DeepClone() Set

DeepClone returns a deep clone of the Set.

func (Set) Equals 

func (s Set) Equals(b Set) bool

Equals returns true if the sets are equal.

func (Set) ExplicitMarshalJSON 

func (v Set) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the Set into JSON, the marshaller uses the explicit JSON form for all the values in the Set.

func (Set) MarshalJSON 

func (v Set) MarshalJSON() ([]byte, error)

MarshalJSON marshals the Set into JSON, the marshaller uses the explicit JSON form for all the values in the Set.

func (Set) String 

func (v Set) String() string

String produces a string representation of the Set, e.g. `[1,2,3]`.

func (*Set) UnmarshalJSON 

func (v *Set) UnmarshalJSON(b []byte) error

type String 

type String string

A String is a sequence of characters consisting of letters, numbers, or symbols.

func (String) Cedar 

func (v String) Cedar() string

Cedar produces a valid Cedar language representation of the String, e.g. `"hello"`.

func (String) ExplicitMarshalJSON 

func (v String) ExplicitMarshalJSON() ([]byte, error)

ExplicitMarshalJSON marshals the String into JSON.

func (String) String 

func (v String) String() string

String produces an unquoted string representation of the String, e.g. `hello`.

type Value 

type Value interface {
	// String produces a string representation of the Value.
	String() string
	// Cedar produces a valid Cedar language representation of the Value.
	Cedar() string
	// ExplicitMarshalJSON marshals the Value into JSON using the explicit (if
	// applicable) JSON form, which is necessary for marshalling values within
	// Sets or Records where the type is not defined.
	ExplicitMarshalJSON() ([]byte, error)
	// contains filtered or unexported methods
}

Source Files

View all Source files

Directories

Path Synopsis
x
exp/parser

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.