Expressions

Expressions are implemented as a way for you to describe the conditional, or to evaluate something based on the context you are in.

Currently, expressions are used in 3 places:

• Scheduling (on.expr, statement defines the expression that should evaluate to a boolean value)
• Conditional step (scans.[ID].steps[].if, allows steps to be conditionally executed. It should evaluate to a boolean value)
• Run expression (Within a run, you can use template expression in form of ${{ expression }}. Expression should evaluate to a string, or an integer value.)

Syntax

We use a language called CEL. If you've ever used languages that look like C, you'll find this one pretty familiar.

In BountyHub, we handle expressions with something we call Context.

Think of Context as a state. State is populated with predefined variables and structures. Then that state is used to evaluate the expression and get a result of some type.

For that reason, it is important that you are aware which expressions should evaluate to boolean values, and which ones should evaluate to a string value.

Context variables

Context variables are variables that are pre-populated by the server at the time the job is sent to the runner.

It allows you to create generic scans and run the command based on your new state. The following context variables are available:

• id: The id of the current job
• name: The name of the scan this job is instance of
• scans: Map of scans and their last 10 jobs for each scan
• project: Trimmed down project object
• workflow: Trimmed down workflow object
• revision: Trimmed down revision object
• vars: Map of project variables defined in your project settings
• always: Evaluates to true. Special purpose variable that allows you to run the step even if the job is about to fail.
• ok: Variable prepended to your expression that holds the current success state of the job. If step fails, the value of ok variable for the next step will be false.

Let's talk about them all:

id

This field is populated as the ID of the current job.

name

Populates the name of the scan that this job is associated to.

scans

This is basically a map, with scan names used as keys, and job contexts used as values. It looks something similar to this:

{
  "scan1": [], // list of scan objects
  "scan2": [],
  "scan3": []
}

The job object contains the following fields:

project

Project is a simple object with the following fields:

It allows you to use the project id in order to fetch some object, like job result, from the BountyHub API.

workflow

Workflow is a simple object with the following fields:

It allows you to use the workflow id in order to fetch some object from the BountyHub API.

revision

Revision is a simple object with the following fields

vars

Vars is the map of key-value pairs that you configured as project variables in your project.

This maps string -> string, and looks something like:

{
  "domain": "bountyhub.org",
  "tool_rate": "5",
  "api_key": "api key for your tools if you need one"
}

ok

This is a variable that has a bool type, and mutates after each step. Every step if is prepended with ok && (YOUR_EXPRESSION_HERE).

That means that if any step fails, the ok will evaluate to false, causing steps to be skipped. You don't need to explicitly use this variable, but you should know that it exists.

Keep in mind, if the step is skipped, the value of ok will not be mutated.

always

This is basically a keyword. It is a constant evaluating to true, but it has a special meaning. If the value of if step expression is always, this step will always be executed. The server will not prepend the ok. Keep in mind that the expression shouldn't be something like: if: always && (steps[0].state == 'succeeded'). There are 2 reasons for this:

1. It doesn't make sense to write something like if: true && (expr). It effectively is the same as writing if: expr.
2. The always only makes sense if you want to always run this 😊.

Functions

As part of the language, CEL supports functions. These functions can be used on context variables to express what you are trying to evaluate. Let's explore what functions are available.

Built-in functions

Built-in functions are general purpose functions regardless of the Context. They operate on objects, and can be used to calculate size, filter lists, etc.

size

Calculates the size of the target, or args, depending on how the function is being called. If the function is called as a method, the object calling that function will be used. The result type is always int

Supported types are:

Examples:

# Use argument
size([1, 3, 3]) == 3
size('test') == 4

# Use method call
[1, 2, 3].size() == 3
'test'.size() == 4

contains

Returns boolean if the target contains the provided argument.

Examples:

[1, 2, 3].contains(2) == true
{"a": 1, "b": 2}.contains("a") == true
"abc".contains("bc") == true
b"abc".contains(b"c") == true

string

Performs type conversion. The following types can be converted to string:

• string
• timestamp
• duration
• int
• uint
• float
• bytes

bytes

Performs type conversion from string to bytes

double

Performs type conversion to double (or float64). The following types are supported:

• string
• float
• int
• uint

uint

Performs type conversion to an unsigned integer. The following types are supported:

• string
• float
• int
• uint

int

Performs type conversion to an integer. The following types are supported:

• string
• float
• int
• uint

matches

Returns true if the string matches the regular expression.

"abc".matches("^[a-z]+$") == true

has

Returns true if argument can be resolved. This is checking if a property exists before resolving it.

map

Maps the provided list by applying expression to each item.

[1, 2, 3].map(x, x * 2) == [2, 4, 6]

filter

Filters the provided list by applying an expression to each input item, and returns a list where item evaluated by the expression returned true.

[1, 2, 3].filter(x, x > 1) == [2, 3]

all

Returns a boolean indicating whether every value in the provided list or map meet the condition provided by an expression.

[1, 2, 3].all(x, x > 0) == true

exists

Returns a boolean value indicating whether a or more values in the provided list or map meet the condition provided by an expression

[1, 2, 3].exists(x, x > 0) == true

exists_one

Returns to boolean value indicating whether exactly one element/key evaluates to true, and the rest to false.

Helper functions

Helper functions are implemented as an extension of CEL language to help easier evaluation for common tasks.

scans.[id].is_available()

This method is used to check if the target scan result is available in context of the current job. It is mostly used in expr or if.

Let's take an example. We want to run httpx when subfinder finishes (i.e. when subfinder is available).

Since subfinder can have many successful executions, is_available() means that:

• subfinder has a succeeded job.
• That job finished after last known invocation of httpx.

scans.[id].has_diff()

This method returns true if:

• There is exactly one successful job and the nonce value is not null
• There exist at least two jobs where latest two successful jobs have different nonce values.