policy

package module
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2025 License: Apache-2.0 Imports: 25 Imported by: 1

README

🔴🟡🟢 AMPEL Policy Framework

This is the Policy Framework used by the The Amazing Multipurpose Policy Engine (and L) (AMPEL) policy engine.

The components housed on this repository include:

Policy and PolicySet Protobuf Definitions

This respository contains the protocol buffers definitions for the AMPEL policies and policy sets. In addition it includes the generated Go code libraries, including methods and other convenience functions.

The definitions and libraries depend on the in-toto/attestation protocol buffers definitions and code.

Policy Tooling

This repository also contains the policy tooling that AMPEL and policyctl depend on. The policy tooling includes:

Policy Compiler

The library that compiles the AMPEL policies from possibly distributed sources.

Policy Fetcher

A high performance utility that fetches policy data from repositories such as HTTP servers, git repositories, etc.

Policy Signer

Handles policy signing and verification.

This project is Copyright © by Carabiner Systems, Inc and released under the terms of the Apache 2.0 license.

Documentation

Index

Constants

View Source 
const (
	AssertModeAND = "AND"
	AssertModeOR  = "OR"

	EnforceOn  = "ON"
	EnforceOff = "OFF"
)

Variables

View Source 
var ErrParseInconsistency = errors.New("internal error: fetched reference ID and policy ID mismatch")

This error is thrown if a fetchedRef lists a policy ID not contained in its policy or policy set. If it's ever thrown it is definitely a bug:

View Source 
var ErrUnsupportedLocationURI = errors.New("unsupported policy location")

Functions

func PolicyOrSet 

func PolicyOrSet(set *api.PolicySet, pcy *api.Policy) any

PolicyOrSet takes a policy or policyset and returns the one that is not nill

Types

type Compiler 

type Compiler struct {
	Options CompilerOptions
	Store   StorageBackend
	// contains filtered or unexported fields
}

Compiler is the policy compiler

func NewCompiler 

func NewCompiler() *Compiler

func (*Compiler) Compile 

func (compiler *Compiler) Compile(data []byte, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, error)

CompileVerify compiles a policy, while verifying its signature

func (*Compiler) CompileFile 

func (compiler *Compiler) CompileFile(path string, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, error)

CompileFile reads data from a local file and returns either a policy set or policy.

func (*Compiler) CompileLocation 

func (compiler *Compiler) CompileLocation(location string, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, error)

func (*Compiler) CompilePolicy 

func (compiler *Compiler) CompilePolicy(p *api.Policy, funcs ...options.OptFn) (*api.Policy, error)

Compile builds a policy set fetching any remote pieces as necessary

func (*Compiler) CompileRemote 

func (compiler *Compiler) CompileRemote(uri string, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, error)

CompileRemote reads a policy or policy set from a remote location. The location URI can be a git VCS locator using HTTPS or SSH as transport or an HTTPS URL.

func (*Compiler) CompileSet 

func (compiler *Compiler) CompileSet(set *api.PolicySet, funcs ...options.OptFn) (*api.PolicySet, error)

Compile builds a policy set fetching any remote pieces as necessary

func (*Compiler) CompileVerify added in v0.2.0 

func (compiler *Compiler) CompileVerify(data []byte, funcs ...options.OptFn) (set *api.PolicySet, pcy *api.Policy, ver attestation.Verification, err error)

CompileVerify is the main method to assemble policies.

Compiling means fetching all the policy references and assembling a policy in memory from the fetched data.

func (*Compiler) CompileVerifyFile added in v0.2.0 

func (compiler *Compiler) CompileVerifyFile(path string, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, attestation.Verification, error)

CompileFile reads data from a local file and returns either a policy set or policy.

func (*Compiler) CompileVerifyLocation added in v0.2.0 

func (compiler *Compiler) CompileVerifyLocation(location string, funcs ...options.OptFn) (set *api.PolicySet, pcy *api.Policy, ver attestation.Verification, err error)

CompileLocaCompileVerifyLocationtion takes a location string and parses a policy or PolicySet as read from it. The location will be tested, if it is a URL or VCS locator, it will be retrieved remotely. If its a local file, it will be read from disk. Anything else throws an error.

This function variant returns the signature verification.

func (*Compiler) CompileVerifyRemote added in v0.2.0 

func (compiler *Compiler) CompileVerifyRemote(uri string, funcs ...options.OptFn) (set *api.PolicySet, pcy *api.Policy, ver attestation.Verification, err error)

CompileRemote reads a policy or policy set from a remote location. The location URI can be a git VCS locator using HTTPS or SSH as transport or an HTTPS URL.

type CompilerOptions 

type CompilerOptions struct {

	// MaxRemoteRecursion captures the maximum recursion level the
	// compiler will do to fetch remote content. Note that this setting
	// causes exponential requests, so be careful when defining a value.
	MaxRemoteRecursion int
}

CompilerOptions are the settings of the compiler itself.

type Fetcher 

type Fetcher struct{}

Fetcher is the ampel policy fetcher. It optimizes retrieval of policy data from repositories and source control systems.

func NewFetcher 

func NewFetcher() *Fetcher

func (*Fetcher) Get 

func (gf *Fetcher) Get(uri string) ([]byte, error)

func (*Fetcher) GetFromGit 

func (gf *Fetcher) GetFromGit(locator string) ([]byte, error)

GetFromGit gets data from a git repository at the specified revision

func (*Fetcher) GetFromHTTP 

func (gf *Fetcher) GetFromHTTP(url string) ([]byte, error)

GetFromHTTP retrieves data from an http endpoint

func (*Fetcher) GetGroup 

func (gf *Fetcher) GetGroup(uris []string) ([][]byte, error)

GetGroup fetches a list of uris that can be HTTP(S) URLs or SPDX VCS locators. The functions uses the vcslocator module and the k8s http agent to fetch in parallel. The returned slice if byte-slices is guarranteed to preserve the URL order. If a request fails, this function returns a single error and discards all data.

Retries are currently not supported but will probably be at a later point once the VCS locator module supports retrying.

type Parser 

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

Parser implements methods to read the policy and policy set json files. Note that the parser only deals with decoding json. Use the policy compiler to assemble policies with external/remote references.

func NewParser 

func NewParser() *Parser

NewParser creates a new policy parser

func (*Parser) Open 

func (p *Parser) Open(location string, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, error)

Open opens a Policy or policySet. This function supports remote locations (https URLs or VCS locators) and will eventually verify signatures after reading and parsing data (still under construction).

func (*Parser) OpenVerify added in v0.2.0 

func (p *Parser) OpenVerify(location string, funcs ...options.OptFn) (set *api.PolicySet, pcy *api.Policy, v attestation.Verification, err error)

Open opens a Policy or policySet. This function supports remote locations (https URLs or VCS locators) and will eventually verify signatures after reading and parsing data (still under construction).

func (*Parser) ParsePolicy 

func (p *Parser) ParsePolicy(data []byte, funcs ...options.OptFn) (*api.Policy, error)

ParsePolicy parses a policy from its JSON representation or an envelope

func (*Parser) ParsePolicyFile 

func (p *Parser) ParsePolicyFile(path string, funcs ...options.OptFn) (*api.Policy, error)

ParsePolicyFile parses a policy from a file

func (*Parser) ParsePolicyOrSet 

func (p *Parser) ParsePolicyOrSet(data []byte, funcs ...options.OptFn) (*api.PolicySet, *api.Policy, error)

ParsePolicyOrSet takes json data and tries to parse a policy or a policy set out of it. Returns an error if the JSON data is none.

func (*Parser) ParsePolicySet 

func (p *Parser) ParsePolicySet(policySetData []byte, funcs ...options.OptFn) (*api.PolicySet, error)

ParseSet parses a policy set.

func (*Parser) ParsePolicySetFile 

func (p *Parser) ParsePolicySetFile(path string, funcs ...options.OptFn) (*api.PolicySet, error)

ParseFile parses a policySet from a file

func (*Parser) ParseVerifyPolicy added in v0.2.0 

func (p *Parser) ParseVerifyPolicy(data []byte, funcs ...options.OptFn) (*api.Policy, attestation.Verification, error)

ParsePolicy parses a policy from its JSON representation or an envelope

func (*Parser) ParseVerifyPolicyOrSet added in v0.2.0 

func (p *Parser) ParseVerifyPolicyOrSet(data []byte, funcs ...options.OptFn) (set *api.PolicySet, pcy *api.Policy, v attestation.Verification, err error)

ParseVerifyPolicyOrSet parses a policy and verifies the signatures. It returns a PolicySet or Policy and the signature verification results object.

func (*Parser) ParseVerifyPolicySet added in v0.2.0 

func (p *Parser) ParseVerifyPolicySet(policySetData []byte, funcs ...options.OptFn) (*api.PolicySet, attestation.Verification, error)

ParseSet parses a policy set.

type PolicyFetcher 

type PolicyFetcher interface {
	Get(string) ([]byte, error)
	GetGroup(uris []string) ([][]byte, error)
}

type Signer 

type Signer struct {
	Options options.SignerOptions
}

Signer is the policy/policy set signer object. Signing is done by wrapping the policies in an in-toto statement and the predicate/* wrappers before passing them to the sigstore signer.

func NewSigner 

func NewSigner(funcs ...options.SignerOptFn) *Signer

NewSigner returns a policy signer with the specified options

func (*Signer) SignPolicyData 

func (ps *Signer) SignPolicyData(data []byte, w io.Writer, funcs ...options.SignerOptFn) error

SignPolicyData signs raw policy data

func (*Signer) SignPolicyFile 

func (ps *Signer) SignPolicyFile(path string, w io.Writer, funcs ...options.SignerOptFn) error

SignBundleToFile signs a policy file and writes it to a filename derived from the original.

type StorageBackend 

type StorageBackend interface {
	StoreReference(*api.PolicyRef) error
	StoreReferenceWithReturn(*api.PolicyRef) (*api.PolicySet, *api.Policy, error)
	GetReferencedPolicy(*api.PolicyRef) (*api.Policy, error)
}

Storage backend is an interface that fronts systems that store and index policies

Source Files

View all Source files

Directories

Path Synopsis
api
v1

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.