Guardrails
Guardrails Specification
This is an guardrail specification for Xygeni scanner. Guardrails can be executed at server side (Audit Analysis), for more information read CI/CD Audit Analysis
When specific rules or special exit codes are required by pipelines or security policies, complex conditions can be defined using guardrail expressions.
Guardrails enables users to customize and specify how a Xygeni command should behave in the presence of certain conditions or criteria, thereby allowing for flexible and tailored handling of failure scenarios.
Guardrail specification is a subset of Xygeni™ XyFlow Language, tailored for guardrail conditions.
Guardrail Convention
A guardrail expression consists of a name or string, followed by a pipe that contains actions limited to the set selected.
A pipe processes a stream of events matching a condition then performing actions on each event individually or on the full set of matching events.
ON Clause
The on
clause chooses which items from scan report to process. The following are the recognized names with the report matched and the type of the items to process:
type(s) | report | items |
---|---|---|
inventory, asset, assets | InventoryReport | Asset |
deps, scan-deps, dependencies, sca | ScanReport | Dependency |
suspectdeps | SuspectDepsReport | SuspectDependency |
malware, evidence | MalwareEvidencesReport | MalwareEvidence |
secrets, secret | SecretsReport | PotentialSecret |
iac, iac_flaws | IacFlawsReport | IacFlaw |
cicd, misconf, misconfiguration(s) | MiscReport | Misconfiguration |
codetamper, critical_file_modification | CodeTamperReport | CriticalFileModification |
compliance | ComplianceReport | Compliance |
entry, entries, item, items | Collection, Array, Map | Object or Map.Entry |
any | <Any of the above> | <Corresponding type> |
Closed Issues
are removed from the item list before processing by the guardrails. It require an available connection to xygeni server to retrieve the list of closed issues for the current project if exits at server side. It applies to secrets, misconfigurations, suspectdeps, malware and iac issue types.
Examples:
WHEN Clause
The when
clause defines the condition for each item to be processed.
A list of matched items will be passed to the then
clause. In case an else clause is provided, a list of unmatched items will be passed to the else
clause.
See Expressions for more details.
THEN Clause
The then
clause defines the actions to be executed on the matched items.
If some items are found (issues or evidence) but none is matched neither else
clause is provided, an exitcode will be set to 127 to force a non zero exit.
ELSE Clause
The else
clause defines the actions to be executed on the unmatched items.
ALSO Clause
The also
clause allows to define a nested when-then-else
clause that will be evaluated over the matched items.
General Syntax
Keywords
guardrail
: Indicates the beginning of a guardrail definition.on
: Specifies the triggering events.when
: Defines the condition for event processing.then
: Specifies the actions to be performed.also
: Optional keyword for additional conditions and actions.
Identifiers
Represent variable names or properties and follow the standard naming conventions similar to Java identifiers. They can start with a letter or underscore (_), followed by any combination of letters, digits, and underscores.
Delimiters
[]
: Square brackets used for Array elements[:]
: Square brackets with a colon used for Maps elements()
: Parentheses used for function calls,
: Comma used to separate arguments:
: Colon used on function calls to identify named arguments
Literals
Include integers
, floating-point numbers
, strings
(enclosed in double quotes "…"), and booleans
(true, false).
Operators
Arithmetic operators:
+
,-
,*
,/
,%
++
,--
Comparison operators:
<
,>
⇐
,>=
=
,!=
,<>
Logical operators:
and
,&&
or
,||
not
,!
String operators
starts-with
,ends-with
,matches
,contains
Collection operators
in
,contains
Object operators
instanceOf
,exists
Examples of operators expressions
Comments
Comments can be included to provide clarity and documentation within guardrail definitions. Only Single-line comments are provided, it start with #
.
Functions
Functions are invoked using the @
symbol followed by the function name and a list of arguments enclosed in parentheses, e.g., @functionName(arg1, arg2)
.
Dot Notation
Dot notation can be used to access object properties and allows for specifying conditions or actions based on properties of objects within the guardrail execution context.
Interpolation and Expression Embedding
Variables can be referenced using the $
symbol followed by the variable name, e.g., $report.baseline
.
$
alone references the current item, e.g., @print($)
.
$Variable
can be use to interpolate values in a string, e.g., "Report is baseline: $report.baseline"
.
${}
can used to interpolate an expression in a string, e.g., "Total number of secrets: ${@count(report.secrets)}"
.
Context Objects
Some object are saved to global context and can be accessed implicitly from expressions:
report
a reference to the current analysis report generated.metadata
a direct reference to report.metadata properties if presentcontext
the context itself is saved to global context
Examples:
Expressions
Expressions can include variables, literals, functions, and operators combined to evaluate to a Truth in XyFlow. An expression is Truth when y resolved as:
a true boolean
a non-zero number
a non-blank string
a non-empty array, map or collection
a non-null object
Actions
Actions are evaluated over each matched item (default) or over the complete list of matched items.
To evaluate over the complete list use a kind name with the _all
suffix.
To select a specific action, use the @
symbol followed by the name of the action.
Example:
Built-in Functions
Aggregate Functions Available aggregate functions like
count
,sum
,avg
,min
,max
, andsort
, which can operate on collections or arrays. These functions are crucial for data manipulation within guardrails.@count(collection): Returns the number of elements in a collection, map, array, or the length of a string.
@sum(collection): Calculates the sum of numeric values within a collection or array.
@avg(collection): Computes the average of numeric values in a collection or array.
@min(collection): Finds the minimum numeric value in a collection or array.
@max(collection): Identifies the maximum numeric value in a collection or array.
@sort(collection): Returns a new collection with elements sorted in their natural order.
Exitcode Allow the specification of exit codes for guardrails, which can be used to indicate success or failure states in a customizable manner.
@exitcode(code): Sets the exit code of the guardrail, enabling custom exit statuses to communicate outcomes to the CI/CD pipeline.
@fail(): Sets exit code of the guardrail to value 1, to force an exit with error. It is a simplified version of the
@exitcode(1)
function.
Print/Debug Functions Enables printing messages to different outputs (stdout, stderr, or a file), which can be used for logging or debugging within guardrails.
@print(expression): Allows printing of specified messages to stdout, stderr, or a file, useful for logging and debugging purposes. Parameters:
item: The text to print
output:
stdout
,stderr
, or a file path. Defaults tostdout
.
@dump(msg): Dumps the message to stdout, typically for debugging. Used during dry-run testing of guardrails.
Scm Functions Functions for interacting with Source Control Management (SCM) systems, currently GitHub, through functions like github.status_check and github.commit_comment. These functions are used for reporting the results of guardrail checks back to SCM systems.
@github.status_check(…): Creates a GitHub commit status, useful for reporting the outcome of a guardrail evaluation directly within a GitHub repository. Parameters:
repo: name of the repo (owner/name)
sha: commit sha (default last commit)
state: error, failure(default), pending, success
description: A short description of the status
@github.commit_comment(…): Posts a comment on a specific commit in GitHub, allowing for inline feedback on guardrail checks. Parameters:
repo: name of the repo (owner/name
sha: commit sha (default last commit)
state: error, failure(default), pending, success
body: The body of the comment
path: Optional path of the file to comment on
Position: Optional position in the file to comment on
Guardrails Examples
Exit on Critical Issues
Condition: Break the build on any issue with a 'critical' severity level.
Action: Exit with a specific exit code only when 'critical' severity level found.
Exit on Critical Files
Condition: Break the build on any issue on critical files.
Action: Exit with a specific exit code only when issue found on critical files.
Critical Secrets Exposure
Condition: Any issue where the kind is a 'secret', with a 'critical' severity level.
Action: Break the build with a specific exit code and set commit status failure
High Confidence Misconfigurations
Condition: Issues categorized under 'misconfiguration' with 'high' or 'critical' confidence and 'high' or 'highest' .
Condition: Issues categorized under 'misconfiguration' with 'high' or 'critical' severity and 'high' or 'highest' confidence.
Action: Break the build with a specific exit code and open a ticket for the relevant team
This guardrail must be run server-side, as a CI/CD Audit.
Last updated