cloudarmor

package
v0.0.0-...-42e70da Latest Latest
Warning

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

Go to latest
Published: Jan 12, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package cloudarmor provides a CEL environment for local validation and evaluation of Cloud Armor expressions.

Index

Constants

View Source
const (
	// VCurrent supports the attributes currently available in Cloud Armor
	VCurrent uint32 = 1
	// VNext supports the next set of variables and functions to be enabled in Cloud Armor
	VNext uint32 = 2
)

Variables

View Source
var File_proto_vendor_ruleset_collection_proto protoreflect.FileDescriptor

Functions

This section is empty.

Types

type Headers

type Headers map[string]string

Headers represents a map of HTTP headers.

func HTTPHeaders

func HTTPHeaders(headers map[string]string) Headers

HTTPHeaders converts a map of headers to a Headers type.

The keys are converted to lower case to match the behavior of the Cloud Armor expression language.

type Origin

type Origin struct {
	IP                string `yaml:"ip"`
	RegionCode        string `yaml:"region_code"`
	ASN               int64  `yaml:"asn"`
	UserIP            string `yaml:"user_ip"`
	TLSJA3Fingerprint string `yaml:"tls_ja3_fingerprint"`
	TLSJA4Fingerprint string `yaml:"tls_ja4_fingerprint"`
}

Origin represents the origin attributes available to the Cloud Armor expression.

type RecaptchaAction

type RecaptchaAction struct {
	Score         float64 `yaml:"score"`
	CaptchaStatus string  `yaml:"captcha_status"`
	Action        string  `yaml:"action"`
	Valid         bool    `yaml:"valid"`
}

RecaptchaAction represents the reCaptcha action attributes available to the Cloud Armor expression.

type RecaptchaExemption

type RecaptchaExemption struct {
	Valid bool `yaml:"valid"`
}

RecaptchaExemption represents the reCaptcha exemption attributes available to the Cloud Armor expression.

type RecaptchaSession

type RecaptchaSession struct {
	Score float64 `yaml:"score"`
	Valid bool    `yaml:"valid"`
}

RecaptchaSession represents the reCaptcha session attributes available to the Cloud Armor expression.

type Request

type Request struct {
	Method  string            `yaml:"method"`
	Headers map[string]string `yaml:"headers"`
	Path    string            `yaml:"path"`
	Query   string            `yaml:"query"`
	Scheme  string            `yaml:"scheme"`
	Params  map[string]any    `yaml:"params"`
	Body    string            `yaml:"body"`
}

Request represents the request attributes available to the Cloud Armor expression.

type Rules

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

Rules represents a Cloud Armor rules environment.

func NewRules

func NewRules(options ...RulesOption) (*Rules, error)

NewRules creates a new CloudArmorRules instance.

The options are used to configure the environment and the library version. As new functionality is added, the library version must be incremented.

The standard flow of execution is to Compile() and ast and prepare it for execution by converting the AST to a Program(). The program can then be invoked against a series of inputs using program.Eval(vars).

Compiled cel.Ast values can be serialized and restored to a CEL program by using the cel.AstToCheckedExpr() and cel.CheckedExprToAst() functions. Program instances are concurrency-safe and can be cached.

func (*Rules) Compile

func (r *Rules) Compile(expr string) (*cel.Ast, error)

Compile compiles the given expression into a cel.Ast or returns a set of issues.

func (*Rules) Env

func (r *Rules) Env() *cel.Env

Env returns the cel.Env object for the Rules object.

func (*Rules) Program

func (r *Rules) Program(ast *cel.Ast, prgOpts ...cel.ProgramOption) (cel.Program, error)

Program creates a new program from the given cel.Ast and accepts an optional set of CEL program options which can be used to alter how the expression evaluates to capture information like intermediate evaluation results.

func (*Rules) RunRuleValidation

func (r *Rules) RunRuleValidation(prg cel.Program, testCases []*TestCase) []TestStatus

RunRuleValidation runs a test suite against the an expression.

The test suite is expected to contain a set of test cases which are executed in sequence. Each test case is expected to contain an expression to compile, the variables to bind to the expression, and the expected output or error.

The return value is a slice of test statuses, one for each test case in the suite.

type RulesOption

type RulesOption func(*Rules) (*Rules, error)

RulesOption is a functional operator for configuring the Cloud Armor rules environment.

func Version

func Version(version uint32) RulesOption

Version sets the version of the Cloud Armor rules environment.

type TestCase

type TestCase struct {
	Name         string     `yaml:"name"`
	When         *Variables `yaml:"when"`
	ExpectOutput bool       `yaml:"expect"`
	ExpectError  string     `yaml:"error"`
}

TestCase represents a single test case for a Cloud Armor rule expression.

func SafeTestCase

func SafeTestCase(t *TestCase) *TestCase

SafeTestCase ensures that all of the variables are initialized to their default values.

type TestStatus

type TestStatus struct {
	Name string
	Pass bool
	Fail string
}

TestStatus represents the result of a single test case.

type TestSuite

type TestSuite struct {
	Name  string      `yaml:"name"`
	Expr  string      `yaml:"expr"`
	Tests []*TestCase `yaml:"tests"`
}

TestSuite represents a set of tests for a Cloud Armor rule expression.

func TestSuiteFromYAML

func TestSuiteFromYAML(yamlBytes []byte) (*TestSuite, error)

TestSuiteFromYAML converts a YAML representation of a test suite to a TestSuite type.

The YAML representation is expected to be a map of test suite name to a list of test cases.

The return value is the TestSuite type or an error if the YAML is invalid.

type Token

type Token struct {
	RecaptchaExemption *RecaptchaExemption `yaml:"recaptcha_exemption"`
	RecaptchaAction    *RecaptchaAction    `yaml:"recaptcha_action"`
	RecaptchaSession   *RecaptchaSession   `yaml:"recaptcha_session"`
}

Token represents the token attributes available to the Cloud Armor expression.

type Variables

type Variables struct {
	Request *Request `yaml:"request"`
	Origin  *Origin  `yaml:"origin"`
	Token   *Token   `yaml:"token"`
}

Variables serves as a container for all of the variables that are available to the Cloud Armor expression.

func SafeVariables

func SafeVariables(v *Variables) *Variables

SafeVariables ensures that all of the variables are initialized to their default values.

func VariablesFromYAML

func VariablesFromYAML(yamlBytes []byte) (*Variables, error)

VariablesFromYAML converts a YAML representation of the variables to a Variables type.

The YAML representation is expected to be a map of variable names to values. The variable names are expected to match the names that are defined in the Cloud Armor expression language.

The return value is the Variables type or an error if the YAML is invalid.

func (*Variables) Parent

func (v *Variables) Parent() interpreter.Activation

Parent returns nil as hierarchical context building is not supported within Cloud Armor.

func (*Variables) ResolveName

func (v *Variables) ResolveName(name string) (any, bool)

ResolveName resolves the given name to a value in the variables container.

The name is expected to be in the format of the variables that are defined in the Cloud Armor language. For example, "request.method" or "token.recaptcha_action.score".

The return value is the resolved value and a boolean indicating if the name was resolved.

type VendorRuleSet

type VendorRuleSet struct {

	// Next ID: 7
	// Name of the ruleset provided by Vendor
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// Version of the ruleset provided by Vendor, if any.
	Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
	// Category of the ruleset, e.g. SQLi, XSS
	Category string `protobuf:"bytes,3,opt,name=category,proto3" json:"category,omitempty"`
	// Release notes corresponding to the rulesets
	ChangeLog *VendorRuleSet_ChangeLog `protobuf:"bytes,4,opt,name=change_log,json=changeLog,proto3" json:"change_log,omitempty"`
	// Transformations should be applied sequentially to the input request
	// before evaluating CEL Expression
	// Rule shall be evaluated only once all the transformations were applied.
	Transformations []string `protobuf:"bytes,5,rep,name=transformations,proto3" json:"transformations,omitempty"`
	// collection of rules under the ruleset
	Rules []*VendorRuleSet_VendorRule `protobuf:"bytes,6,rep,name=rules,proto3" json:"rules,omitempty"`
	// contains filtered or unexported fields
}

Vendor rulesets containing rules for specific category, e.g. sqli, xss

func (*VendorRuleSet) Descriptor deprecated

func (*VendorRuleSet) Descriptor() ([]byte, []int)

Deprecated: Use VendorRuleSet.ProtoReflect.Descriptor instead.

func (*VendorRuleSet) GetCategory

func (x *VendorRuleSet) GetCategory() string

func (*VendorRuleSet) GetChangeLog

func (x *VendorRuleSet) GetChangeLog() *VendorRuleSet_ChangeLog

func (*VendorRuleSet) GetName

func (x *VendorRuleSet) GetName() string

func (*VendorRuleSet) GetRules

func (x *VendorRuleSet) GetRules() []*VendorRuleSet_VendorRule

func (*VendorRuleSet) GetTransformations

func (x *VendorRuleSet) GetTransformations() []string

func (*VendorRuleSet) GetVersion

func (x *VendorRuleSet) GetVersion() string

func (*VendorRuleSet) ProtoMessage

func (*VendorRuleSet) ProtoMessage()

func (*VendorRuleSet) ProtoReflect

func (x *VendorRuleSet) ProtoReflect() protoreflect.Message

func (*VendorRuleSet) Reset

func (x *VendorRuleSet) Reset()

func (*VendorRuleSet) String

func (x *VendorRuleSet) String() string

type VendorRuleSet_ChangeLog

type VendorRuleSet_ChangeLog struct {

	// This will be used to surface changelog information through
	// documentation
	Description string `protobuf:"bytes,1,opt,name=description,proto3" json:"description,omitempty"`
	// this determines whether the ruleset description should be public
	// e.g. Included in the release notes
	AlwaysPublic bool `protobuf:"varint,2,opt,name=always_public,json=alwaysPublic,proto3" json:"always_public,omitempty"`
	// this is set if it should be included in a CVE release
	UseForCve bool `protobuf:"varint,3,opt,name=use_for_cve,json=useForCve,proto3" json:"use_for_cve,omitempty"`
	// contains filtered or unexported fields
}

ChangeLog for the ruleset

func (*VendorRuleSet_ChangeLog) Descriptor deprecated

func (*VendorRuleSet_ChangeLog) Descriptor() ([]byte, []int)

Deprecated: Use VendorRuleSet_ChangeLog.ProtoReflect.Descriptor instead.

func (*VendorRuleSet_ChangeLog) GetAlwaysPublic

func (x *VendorRuleSet_ChangeLog) GetAlwaysPublic() bool

func (*VendorRuleSet_ChangeLog) GetDescription

func (x *VendorRuleSet_ChangeLog) GetDescription() string

func (*VendorRuleSet_ChangeLog) GetUseForCve

func (x *VendorRuleSet_ChangeLog) GetUseForCve() bool

func (*VendorRuleSet_ChangeLog) ProtoMessage

func (*VendorRuleSet_ChangeLog) ProtoMessage()

func (*VendorRuleSet_ChangeLog) ProtoReflect

func (x *VendorRuleSet_ChangeLog) ProtoReflect() protoreflect.Message

func (*VendorRuleSet_ChangeLog) Reset

func (x *VendorRuleSet_ChangeLog) Reset()

func (*VendorRuleSet_ChangeLog) String

func (x *VendorRuleSet_ChangeLog) String() string

type VendorRuleSet_VendorRule

type VendorRuleSet_VendorRule struct {

	// Next ID: 7
	// Unique ID associated with each rule
	// For incremental updates, the rule ID remains unchanged but follows a
	// versioning format. Example: id191190.0 to id191190.1
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// CEL expression
	// Defines the rule logic in CEL string format using Cloud Armor (CA)
	// attributes.
	CelExpression string `protobuf:"bytes,2,opt,name=cel_expression,json=celExpression,proto3" json:"cel_expression,omitempty"`
	// Array of Key value pairs of tags and additional info associated
	// with the tag separated by ':'
	Tags []string `protobuf:"bytes,3,rep,name=tags,proto3" json:"tags,omitempty"`
	// Curl commands that would generate the matching expression for rule
	E2ETestCommand []string `protobuf:"bytes,4,rep,name=e2e_test_command,json=e2eTestCommand,proto3" json:"e2e_test_command,omitempty"`
	// By default, it would be false.
	// If true, the rule shall only be evaluated if enabled by customers.
	OptIn bool `protobuf:"varint,6,opt,name=opt_in,json=optIn,proto3" json:"opt_in,omitempty"`
	// contains filtered or unexported fields
}

Rule from the Vendor ruleset. It would only exist in the initial set of rules provided by the Vendor.

func (*VendorRuleSet_VendorRule) Descriptor deprecated

func (*VendorRuleSet_VendorRule) Descriptor() ([]byte, []int)

Deprecated: Use VendorRuleSet_VendorRule.ProtoReflect.Descriptor instead.

func (*VendorRuleSet_VendorRule) GetCelExpression

func (x *VendorRuleSet_VendorRule) GetCelExpression() string

func (*VendorRuleSet_VendorRule) GetE2ETestCommand

func (x *VendorRuleSet_VendorRule) GetE2ETestCommand() []string

func (*VendorRuleSet_VendorRule) GetId

func (x *VendorRuleSet_VendorRule) GetId() string

func (*VendorRuleSet_VendorRule) GetOptIn

func (x *VendorRuleSet_VendorRule) GetOptIn() bool

func (*VendorRuleSet_VendorRule) GetTags

func (x *VendorRuleSet_VendorRule) GetTags() []string

func (*VendorRuleSet_VendorRule) ProtoMessage

func (*VendorRuleSet_VendorRule) ProtoMessage()

func (*VendorRuleSet_VendorRule) ProtoReflect

func (x *VendorRuleSet_VendorRule) ProtoReflect() protoreflect.Message

func (*VendorRuleSet_VendorRule) Reset

func (x *VendorRuleSet_VendorRule) Reset()

func (*VendorRuleSet_VendorRule) String

func (x *VendorRuleSet_VendorRule) String() string

type VendorRulesetCollection

type VendorRulesetCollection struct {

	// Next ID: 4
	// Unique ID associated with the ruleset collection
	Uuid string `protobuf:"bytes,1,opt,name=uuid,proto3" json:"uuid,omitempty"`
	// Metadata for the ruleset
	RulesetMetadata *VendorRulesetCollection_RulesetMetadata `protobuf:"bytes,2,opt,name=ruleset_metadata,json=rulesetMetadata,proto3" json:"ruleset_metadata,omitempty"`
	// Collection of vendor rulesets
	RuleSets []*VendorRuleSet `protobuf:"bytes,3,rep,name=rule_sets,json=ruleSets,proto3" json:"rule_sets,omitempty"`
	// contains filtered or unexported fields
}

Vendor ruleset collection initially provided by Vendor This represents the initial set of data provided by the Vendor. For further details, please refer to shared(Google and Imperva) design doc: go/imperva-google-mgdrules-integration

func (*VendorRulesetCollection) Descriptor deprecated

func (*VendorRulesetCollection) Descriptor() ([]byte, []int)

Deprecated: Use VendorRulesetCollection.ProtoReflect.Descriptor instead.

func (*VendorRulesetCollection) GetRuleSets

func (x *VendorRulesetCollection) GetRuleSets() []*VendorRuleSet

func (*VendorRulesetCollection) GetRulesetMetadata

func (*VendorRulesetCollection) GetUuid

func (x *VendorRulesetCollection) GetUuid() string

func (*VendorRulesetCollection) ProtoMessage

func (*VendorRulesetCollection) ProtoMessage()

func (*VendorRulesetCollection) ProtoReflect

func (x *VendorRulesetCollection) ProtoReflect() protoreflect.Message

func (*VendorRulesetCollection) Reset

func (x *VendorRulesetCollection) Reset()

func (*VendorRulesetCollection) String

func (x *VendorRulesetCollection) String() string

type VendorRulesetCollection_RulesetMetadata

type VendorRulesetCollection_RulesetMetadata struct {

	// Next ID: 6
	// ruleset creation date
	CreationDate *timestamppb.Timestamp `protobuf:"bytes,1,opt,name=creation_date,json=creationDate,proto3" json:"creation_date,omitempty"`
	// ruleset modification date
	UpdationDate *timestamppb.Timestamp `protobuf:"bytes,2,opt,name=updation_date,json=updationDate,proto3" json:"updation_date,omitempty"`
	// Name of the owner of the rulesets, e.g.   Imperva
	Owner string `protobuf:"bytes,3,opt,name=owner,proto3" json:"owner,omitempty"`
	// A description of the ruleset's purpose
	Description string `protobuf:"bytes,4,opt,name=description,proto3" json:"description,omitempty"`
	// Encryption key identifier
	EncryptionkeyId string `protobuf:"bytes,5,opt,name=encryptionkey_id,json=encryptionkeyId,proto3" json:"encryptionkey_id,omitempty"`
	// contains filtered or unexported fields
}

Metadata shared across Rulesets

func (*VendorRulesetCollection_RulesetMetadata) Descriptor deprecated

func (*VendorRulesetCollection_RulesetMetadata) Descriptor() ([]byte, []int)

Deprecated: Use VendorRulesetCollection_RulesetMetadata.ProtoReflect.Descriptor instead.

func (*VendorRulesetCollection_RulesetMetadata) GetCreationDate

func (*VendorRulesetCollection_RulesetMetadata) GetDescription

func (x *VendorRulesetCollection_RulesetMetadata) GetDescription() string

func (*VendorRulesetCollection_RulesetMetadata) GetEncryptionkeyId

func (x *VendorRulesetCollection_RulesetMetadata) GetEncryptionkeyId() string

func (*VendorRulesetCollection_RulesetMetadata) GetOwner

func (*VendorRulesetCollection_RulesetMetadata) GetUpdationDate

func (*VendorRulesetCollection_RulesetMetadata) ProtoMessage

func (*VendorRulesetCollection_RulesetMetadata) ProtoReflect

func (*VendorRulesetCollection_RulesetMetadata) Reset

func (*VendorRulesetCollection_RulesetMetadata) String

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL