Assignment and Equality

# assign variable x to value of field foo.bar.baz in input
x := input.foo.bar.baz

# check if variable x has same value as variable y
x == y

# check if variable x is a set containing "foo" and "bar"
x == {"foo", "bar"}

# OR

{"foo", "bar"} == x

Lookup

Arrays

# lookup value at index 0
val := arr[0]

 # check if value at index 0 is "foo"
"foo" == arr[0]

# find all indices i that have value "foo"
"foo" == arr[i]

# lookup last value
val := arr[count(arr)-1]

Objects

# lookup value for key "foo"
val := obj["foo"]

# check if value for key "foo" is "bar"
"bar" == obj["foo"]

# OR

"bar" == obj.foo

# check if key "foo" exists and is not false
obj.foo

# check if key assigned to variable k exists
k := "foo"
obj[k]

# check if path foo.bar.baz exists and is not false
obj.foo.bar.baz

# check if path foo.bar.baz, foo.bar, or foo does not exist or is false
not obj.foo.bar.bar

Sets

# check if "foo" belongs to the set
a_set["foo"]

# check if "foo" DOES NOT belong to the set
not a_set["foo"]

# check if the array ["a", "b", "c"] belongs to the set
a_set[["a", "b", "c"]]

# find all arrays of the form [x, "b", z] in the set
a_set[[x, "b", z]]

Iteration

Arrays

# iterate over indices i
arr[i]

# iterate over values
val := arr[_]

# iterate over index/value pairs
val := arr[i]

Objects

# iterate over keys
obj[key]

# iterate over values
val := obj[_]

# iterate over key/value pairs
val := obj[key]

Sets

# iterate over values
set[val]

Advanced

# nested: find key k whose bar.baz array index i is 7
foo[k].bar.baz[i] == 7

# simultaneous: find keys in objects foo and bar with same value
foo[k1] == bar[k2]

# simultaneous self: find 2 keys in object foo with same value
foo[k1] == foo[k2]; k1 != k2

# multiple conditions: k has same value in both conditions
foo[k].bar.baz[i] == 7; foo[k].qux > 3

For All

# assert no values in set match predicate
count({x | set[x]; f(x)}) == 0

# assert all values in set make function f true
count({x | set[x]; f(x)}) == count(set)

# assert no values in set make function f true (using negation and helper rule)
not any_match

# assert all values in set make function f true (using negation and helper rule)
not any_not_match

any_match {
    set[x]
    f(x)
}

any_not_match {
    set[x]
    not f(x)
}

Rules

In the examples below ... represents one or more conditions.

Constants

a = {1, 2, 3}
b = {4, 5, 6}
c = a | b

Conditionals (Boolean)

# p is true if ...
p = true { ...}

# OR

p { ... }

Conditionals

default a = 1
a = 5 { ... }
a = 100 { ... }

Incremental

# a_set will contain values of x and values of y
a_set[x] { ... }
a_set[y] { ... }

# a_map will contain key->value pairs x->y and w->z
a_map[x] = y { ... }
a_map[w] = z { ... }

Ordered (Else)

default a = 1
a = 5 { ... }
else = 10 { ... }

Functions (Boolean)

f(x, y) {
    ...
}

# OR

f(x, y) = true {
    ...
}

Functions (Conditionals)

f(x) = "A" { x >= 90 }
f(x) = "B" { x >= 80; x < 90 }
f(x) = "C" { x >= 70; x < 80 }

Tests

# define a rule that starts with test_
test_NAME { ... }

# override input.foo value using the 'with' keyword
data.foo.bar.deny with input.foo as {"bar": [1,2,3]}}

Built-in Functions

The built-in functions for the language provide basic operations to manipulate scalar values (e.g. numbers and strings), and aggregate functions that summarize complex types.

Comparison

Numbers

Aggregates

Arrays

Sets

Objects

• When keys are provided as an object only the top level keys on the object will be used, values are ignored. For example: object.remove({"a": {"b": {"c": 2}}, "x": 123}, {"a": 1}) == {"x": 123} regardless of the value for key a in the keys object, the following keys object gives the same result object.remove({"a": {"b": {"c": 2}}, "x": 123}, {"a": {"b": {"foo": "bar"}}}) == {"x": 123}.

• The json string paths may reference into array values by using index numbers. For example with the object {"a": ["x", "y", "z"]} the path a/1 references y. Nested structures are supported as well, for example: {"a": ["x", {"y": {"y1": {"y2": ["foo", "bar"]}}}, "z"]} the path a/1/y1/y2/0 references "foo".

• The json string paths support ~0, or ~1 characters for ~ and / characters in key names. It does not support - for last index of an array. For example the path /foo~1bar~0 will reference baz in { "foo/bar~": "baz" }.

• The json string paths may be an array of string path segments rather than a / separated string. For example the path a/b/c can be passed in as ["a", "b", "c"].

Strings

Regex

Glob

The following table shows examples of how glob.match works:

Bitwise

Conversions

Units

Types

Encoding

Token Signing

OPA provides two builtins that implement JSON Web Signature RFC7515 functionality.

io.jwt.encode_sign_raw() takes three JSON Objects (strings) as parameters and returns their JWS Compact Serialization. This builtin should be used by those that want maximum control over the signing and serialization procedure. It is important to remember that StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied. Therefore, line breaks and whitespaces are significant.

io.jwt.encode_sign() takes three Rego Objects as parameters and returns their JWS Compact Serialization. This builtin should be used by those that want to use rego objects for signing during policy evaluation.

Note that with io.jwt.encode_sign the Rego objects are serialized to JSON with standard formatting applied whereas the io.jwt.encode_sign_raw built-in will not affect whitespace of the strings passed in. This will mean that the final encoded token may have different string values, but the decoded and parsed JSON will match.

The following algorithms are supported:

ES256       "ES256" // ECDSA using P-256 and SHA-256
ES384       "ES384" // ECDSA using P-384 and SHA-384
ES512       "ES512" // ECDSA using P-521 and SHA-512
HS256       "HS256" // HMAC using SHA-256
HS384       "HS384" // HMAC using SHA-384
HS512       "HS512" // HMAC using SHA-512
PS256       "PS256" // RSASSA-PSS using SHA256 and MGF1-SHA256
PS384       "PS384" // RSASSA-PSS using SHA384 and MGF1-SHA384
PS512       "PS512" // RSASSA-PSS using SHA512 and MGF1-SHA512
RS256       "RS256" // RSASSA-PKCS-v1.5 using SHA-256
RS384       "RS384" // RSASSA-PKCS-v1.5 using SHA-384
RS512       "RS512" // RSASSA-PKCS-v1.5 using SHA-512

Note that the key’s provided should be base64 encoded (without padding) as per the specification (RFC7517). This differs from the plain text secrets provided with the algorithm specific verify built-ins described below.

Token Signing Examples

package jwt

Symmetric Key (HMAC with SHA-256)

io.jwt.encode_sign({
    "typ": "JWT",
    "alg": "HS256"
}, {
    "iss": "joe",
    "exp": 1300819380,
    "aud": ["bob", "saul"],
    "http://example.com/is_root": true,
    "privateParams": {
        "private_one": "one",
        "private_two": "two"
    }
}, {
    "kty": "oct",
    "k": "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
})

"eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJhdWQiOiBbImJvYiIsICJzYXVsIl0sICJleHAiOiAxMzAwODE5MzgwLCAiaHR0cDovL2V4YW1wbGUuY29tL2lzX3Jvb3QiOiB0cnVlLCAiaXNzIjogImpvZSIsICJwcml2YXRlUGFyYW1zIjogeyJwcml2YXRlX29uZSI6ICJvbmUiLCAicHJpdmF0ZV90d28iOiAidHdvIn19.M10TcaFADr_JYAx7qJ71wktdyuN4IAnhWvVbgrZ5j_4"

Symmetric Key with empty JSON payload

io.jwt.encode_sign({
    "typ": "JWT",
    "alg": "HS256"},
    {}, {
    "kty": "oct",
    "k": "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
})

"eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.e30.Odp4A0Fj6NoKsV4Gyoy1NAmSs6KVZiC15S9VRGZyR20"

RSA Key (RSA Signature with SHA-256)

io.jwt.encode_sign({
    "alg": "RS256"
}, {
    "iss": "joe",
    "exp": 1300819380,
    "aud": ["bob", "saul"],
    "http://example.com/is_root": true,
    "privateParams": {
        "private_one": "one",
        "private_two": "two"
    }
},
{
    "kty": "RSA",
    "n": "ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddxHmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMsD1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSHSXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdVMTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ",
    "e": "AQAB",
    "d": "Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97IjlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYTCBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLhBOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ",
    "p": "4BzEEOtIpmVdVEZNCqS7baC4crd0pqnRH_5IB3jw3bcxGn6QLvnEtfdUdiYrqBdss1l58BQ3KhooKeQTa9AB0Hw_Py5PJdTJNPY8cQn7ouZ2KKDcmnPGBY5t7yLc1QlQ5xHdwW1VhvKn-nXqhJTBgIPgtldC-KDV5z-y2XDwGUc",
    "q": "uQPEfgmVtjL0Uyyx88GZFF1fOunH3-7cepKmtH4pxhtCoHqpWmT8YAmZxaewHgHAjLYsp1ZSe7zFYHj7C6ul7TjeLQeZD_YwD66t62wDmpe_HlB-TnBA-njbglfIsRLtXlnDzQkv5dTltRJ11BKBBypeeF6689rjcJIDEz9RWdc",
    "dp": "BwKfV3Akq5_MFZDFZCnW-wzl-CCo83WoZvnLQwCTeDv8uzluRSnm71I3QCLdhrqE2e9YkxvuxdBfpT_PI7Yz-FOKnu1R6HsJeDCjn12Sk3vmAktV2zb34MCdy7cpdTh_YVr7tss2u6vneTwrA86rZtu5Mbr1C1XsmvkxHQAdYo0",
    "dq": "h_96-mK1R_7glhsum81dZxjTnYynPbZpHziZjeeHcXYsXaaMwkOlODsWa7I9xXDoRwbKgB719rrmI2oKr6N3Do9U0ajaHF-NKJnwgjMd2w9cjz3_-kyNlxAr2v4IKhGNpmM5iIgOS1VZnOZ68m6_pbLBSp3nssTdlqvd0tIiTHU",
    "qi": "IYd7DHOhrWvxkwPQsRM2tOgrjbcrfvtQJipd-DlcxyVuuM9sQLdgjVk2oy26F0EmpScGLq2MowX7fhd_QJQ3ydy5cY7YIBi87w93IKLEdfnbJtoOPLUW0ITrJReOgo1cq9SbsxYawBgfp_gh6A5603k2-ZQwVK0JKSHuLFkuQ3U"
})

"eyJhbGciOiAiUlMyNTYifQ.eyJhdWQiOiBbImJvYiIsICJzYXVsIl0sICJleHAiOiAxMzAwODE5MzgwLCAiaHR0cDovL2V4YW1wbGUuY29tL2lzX3Jvb3QiOiB0cnVlLCAiaXNzIjogImpvZSIsICJwcml2YXRlUGFyYW1zIjogeyJwcml2YXRlX29uZSI6ICJvbmUiLCAicHJpdmF0ZV90d28iOiAidHdvIn19.ITpfhDICCeVV__1nHRN2CvUFni0yyYESvhNlt4ET0yiySMzJ5iySGynrsM3kgzAv7mVmx5uEtSCs_xPHyLVfVnADKmDFtkZfuvJ8jHfcOe8TUqR1f7j1Zf_kDkdqJAsuGuqkJoFJ3S_gxWcZNwtDXV56O3k_7Mq03Ixuuxtip2oF0X3fB7QtUzjzB8mWPTJDFG2TtLLOYCcobPHmn36aAgesHMzJZj8U8sRLmqPXsIc-Lo_btt8gIUc9zZSgRiy7NOSHxw5mYcIMlKl93qvLXu7AaAcVLvzlIOCGWEnFpGGcRFgSOLnShQX6hDylWavKLQG-VOUJKmtXH99KBK-OYQ"

Raw Token Signing

If you need to generate the signature for a serialized token you an use the io.jwt.encode_sign_raw built-in function which accepts JSON serialized string parameters.

io.jwt.encode_sign_raw(
    `{"typ":"JWT","alg":"HS256"}`,
     `{"iss":"joe","exp":1300819380,"http://example.com/is_root":true}`,
    `{"kty":"oct","k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"}`
)

"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLCJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.lliDzOlRAdGUCfCHCPx_uisb6ZfZ1LRQa0OJLeYTTpY"

Token Verification

Note that the io.jwt.verify_XX built-in methods verify only the signature. They do not provide any validation for the JWT payload and any claims specified. The io.jwt.decode_verify built-in will verify the payload and all standard claims.

The input string is a JSON Web Token encoded with JWS Compact Serialization. JWE and JWS JSON Serialization are not supported. If nested signing was used, the header, payload and signature will represent the most deeply nested token.

For io.jwt.decode_verify, constraints is an object with the following members:

Exactly one of cert and secret must be present. If there are any unrecognized constraints then the token is considered invalid.

Token Verification Examples

The examples below use the following token:

es256_token = "eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFUzI1NiJ9.eyJuYmYiOiAxNDQ0NDc4NDAwLCAiaXNzIjogInh4eCJ9.lArczfN-pIL8oUU-7PU83u-zfXougXBZj6drFeKFsPEoVhy9WAyiZlRshYqjTSXdaw8yw2L-ovt4zTUZb2PWMg"

Using JWKS

This example shows a two-step process to verify the token signature and then decode it for further checks of the payload content. This approach gives more flexibility in verifying only the claims that the policy needs to enforce.

jwks = `{
    "keys": [{
        "kty":"EC",
        "crv":"P-256",
        "x":"z8J91ghFy5o6f2xZ4g8LsLH7u2wEpT2ntj8loahnlsE",
        "y":"7bdeXLH61KrGWRdh7ilnbcGQACxykaPKfmBccTHIOUo"
    }]
}`

io.jwt.verify_es256(es256_token, jwks)                  # Verify the token with the JWKS
[header, payload, _] := io.jwt.decode(es256_token)      # Decode the token
payload.iss == "xxx"                                    # Ensure the issuer (`iss`) claim is the expected value

+-----------------------------+--------------------------------+
|           header            |            payload             |
+-----------------------------+--------------------------------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} |
+-----------------------------+--------------------------------+

The next example shows doing the token signature verification, decoding, and content checks all in one call using io.jwt.decode_verify. Note that this gives less flexibility in validating the payload content as all claims defined in the JWT spec are verified with the provided constraints.

[valid, header, payload] := io.jwt.decode_verify(es256_token, {
    "cert": jwks,
    "iss": "xxx",
})

+-----------------------------+--------------------------------+-------+
|           header            |            payload             | valid |
+-----------------------------+--------------------------------+-------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} | true  |
+-----------------------------+--------------------------------+-------+

Using PEM encoded X.509 Certificate

The following examples will demonstrate verifying tokens using an X.509 Certificate defined as:

cert = `-----BEGIN CERTIFICATE-----
MIIBcDCCARagAwIBAgIJAMZmuGSIfvgzMAoGCCqGSM49BAMCMBMxETAPBgNVBAMM
CHdoYXRldmVyMB4XDTE4MDgxMDE0Mjg1NFoXDTE4MDkwOTE0Mjg1NFowEzERMA8G
A1UEAwwId2hhdGV2ZXIwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATPwn3WCEXL
mjp/bFniDwuwsfu7bASlPae2PyWhqGeWwe23Xlyx+tSqxlkXYe4pZ23BkAAscpGj
yn5gXHExyDlKo1MwUTAdBgNVHQ4EFgQUElRjSoVgKjUqY5AXz2o74cLzzS8wHwYD
VR0jBBgwFoAUElRjSoVgKjUqY5AXz2o74cLzzS8wDwYDVR0TAQH/BAUwAwEB/zAK
BggqhkjOPQQDAgNIADBFAiEA4yQ/88ZrUX68c6kOe9G11u8NUaUzd8pLOtkKhniN
OHoCIHmNX37JOqTcTzGn2u9+c8NlnvZ0uDvsd1BmKPaUmjmm
-----END CERTIFICATE-----`

This example shows a two-step process to verify the token signature and then decode it for further checks of the payload content. This approach gives more flexibility in verifying only the claims that the policy needs to enforce.

io.jwt.verify_es256(es256_token, cert)                # Verify the token with the certificate
[header, payload, _] := io.jwt.decode(es256_token)    # Decode the token
payload.iss == "xxx"                                  # Ensure the issuer claim is the expected value

+-----------------------------+--------------------------------+
|           header            |            payload             |
+-----------------------------+--------------------------------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} |
+-----------------------------+--------------------------------+

The next example shows doing the same token signature verification, decoding, and content checks but instead with a single call to io.jwt.decode_verify. Note that this gives less flexibility in validating the payload content as all claims defined in the JWT spec are verified with the provided constraints.

[valid, header, payload] := io.jwt.decode_verify(     # Decode and verify in one-step
    es256_token,
    {                                                 # With the supplied constraints:
        "cert": cert,                                 #   Verify the token with the certificate
        "iss": "xxx",                                 #   Ensure the issuer claim is the expected value
    }
)

+-----------------------------+--------------------------------+-------+
|           header            |            payload             | valid |
+-----------------------------+--------------------------------+-------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} | true  |
+-----------------------------+--------------------------------+-------+

Round Trip - Sign and Verify

This example shows how to encode a token, verify, and decode it with the different options available.

Start with using the io.jwt.encode_sign_raw built-in:

raw_result_hs256 := io.jwt.encode_sign_raw(
    `{"alg":"HS256","typ":"JWT"}`,
    `{}`,
    `{"kty":"oct","k":"Zm9v"}`  	# "Zm9v" == base64url.encode_no_pad("foo")
)

# Important!! - Use the un-encoded plain text secret to verify and decode
raw_result_valid_hs256 := io.jwt.verify_hs256(raw_result_hs256, "foo")
raw_result_parts_hs256 := io.jwt.decode_verify(raw_result_hs256, {"secret": "foo"})

+----------------------------------------------------------------------------------------+---------------------------------------+------------------------+
|                                    raw_result_hs256                                    |        raw_result_parts_hs256         | raw_result_valid_hs256 |
+----------------------------------------------------------------------------------------+---------------------------------------+------------------------+
| "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.Duw7jWmGY54yEu6kcqd2w1TKp1EspzboBnx8EeMc-z0" | [true,{"alg":"HS256","typ":"JWT"},{}] | true                   |
+----------------------------------------------------------------------------------------+---------------------------------------+------------------------+

Now encode the and sign the same token contents but with io.jwt.encode_sign instead of the raw varient.

result_hs256 := io.jwt.encode_sign(
    {
        "alg":"HS256",
        "typ":"JWT"
    },
    {},
    {
        "kty":"oct",
        "k":"Zm9v"
    }
)

# Important!! - Use the un-encoded plain text secret to verify and decode
result_parts_hs256 := io.jwt.decode_verify(result_hs256, {"secret": "foo"})
result_valid_hs256 := io.jwt.verify_hs256(result_hs256, "foo")

+--------------------------------------------------------------------------------------------+---------------------------------------+--------------------+
|                                        result_hs256                                        |          result_parts_hs256           | result_valid_hs256 |
+--------------------------------------------------------------------------------------------+---------------------------------------+--------------------+
| "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.e30.h4crob8QjgDq0JlZpf5mtylPvUzULS0XzdbG2-z_YKc" | [true,{"alg":"HS256","typ":"JWT"},{}] | true               |
+--------------------------------------------------------------------------------------------+---------------------------------------+--------------------+

Note that the resulting encoded token is different from the first example using io.jwt.encode_sign_raw. The reason is that the io.jwt.encode_sign function is using canonicalized formatting for the header and payload whereas io.jwt.encode_sign_raw does not change the whitespace of the strings passed in. The decoded and parsed JSON values are still the same.

Time

Multiple calls to the time.now_ns built-in function within a single policy evaluation query will always return the same value.

Timezones can be specified as

• an IANA Time Zone string e.g. “America/New_York”
• “UTC” or “”, which are equivalent to not passing a timezone (i.e. will return as UTC)
• “Local”, which will use the local timezone.

Note that the opa executable will need access to the timezone files in the environment it is running in (see the Go time.LoadLocation() documentation for more information).

Cryptography

Graphs

A common class of recursive rules can be reduced to a graph reachability problem, so graph.reachable is useful for more than just graph analysis. This usually requires some pre- and postprocessing. The following example shows you how to “flatten” a hierarchy of access permissions.

package graph_reachable_example

org_chart_data = {
  "ceo": {},
  "human_resources": {"owner": "ceo", "access": ["salaries", "complaints"]},
  "staffing": {"owner": "human_resources", "access": ["interviews"]},
  "internships": {"owner": "staffing", "access": ["blog"]}
}

org_chart_graph[entity_name] = edges {
  org_chart_data[entity_name]
  edges := {neighbor | org_chart_data[neighbor].owner == entity_name}
}

org_chart_permissions[entity_name] = access {
  org_chart_data[entity_name]
  reachable := graph.reachable(org_chart_graph, {entity_name})
  access := {item | reachable[k]; item := org_chart_data[k].access[_]}
}

org_chart_permissions[entity_name]

+-------------------+-----------------------------------------------+
|    entity_name    |      org_chart_permissions[entity_name]       |
+-------------------+-----------------------------------------------+
| "ceo"             | ["salaries","complaints","interviews","blog"] |
| "human_resources" | ["salaries","complaints","interviews","blog"] |
| "staffing"        | ["interviews","blog"]                         |
| "internships"     | ["blog"]                                      |
+-------------------+-----------------------------------------------+

HTTP

The request object parameter may contain the following fields:

If the Host header is included in headers, its value will be used as the Host header of the request. The url parameter will continue to specify the server to connect to.

When sending HTTPS requests with client certificates at least one the following combinations must be included

• tls_client_cert and tls_client_key
• tls_client_cert_file and tls_client_key_file
• tls_client_cert_env_variable and tls_client_key_env_variable

To validate TLS server certificates, the user must also provide trusted root CA certificates through the tls_ca_cert, tls_ca_cert_file and tls_ca_cert_env_variable fields. If the tls_use_system_certs field is true, the system certificate pool will be used as well as any additional CA certificates.

The response object parameter will contain the following fields:

By default, an error returned by http.send halts the policy evaluation. This behaviour can be altered such that instead of halting evaluation, if http.send encounters an error, it can return a response object with status_code set to 0 and error describing the actual error. This can be activated by setting the raise_error field in the request object to false.

If the cache field in the request object is true, http.send will return a cached response after it checks its freshness and validity.

http.send uses the Cache-Control and Expires response headers to check the freshness of the cached response. Specifically if the max-age Cache-Control directive is set, http.send will use it to determine if the cached response is fresh or not. If max-age is not set, the Expires header will be used instead.

If the cached response is stale, http.send uses the Etag and Last-Modified response headers to check with the server if the cached response is in fact still fresh. If the server responds with a 200 (OK) response, http.send will update the cache with the new response. On a 304 (Not Modified) server response, http.send will update the headers in cached response with their corresponding values in the 304 response.

The force_cache field can be used to override the cache directives defined by the server. This field is used in conjunction with the force_cache_duration_seconds field. If force_cache is true, then force_cache_duration_seconds must be specified and http.send will use this value to check the freshness of the cached response.

Also, if force_cache is true, it overrides the cache field.

http.send uses the Date response header to calculate the current age of the response by comparing it with the current time. This value is used to determine the freshness of the cached response. As per https://tools.ietf.org/html/rfc7231#section-7.1.1.2, an origin server MUST NOT send a Date header field if it does not have a clock capable of providing a reasonable approximation of the current instance in Coordinated Universal Time. Hence, if http.send encounters a scenario where current age of the response is represented as a negative duration, the cached response will be considered as stale.

The table below shows examples of calling http.send:

Net

net.cidr_contains_matches examples

The output := net.cidr_contains_matches(a, b) function allows callers to supply strings, arrays, sets, or objects for either a or b. The output value in all cases is a set of tuples (2-element arrays) that identify matches, i.e., elements of b contained by elements of a. The first tuple element refers to the match in a and the second tuple element refers to the match in b.

package netcidrcontainsmatches

If both operands are string values the function is similar to net.cidr_contains.

net.cidr_contains_matches("1.1.1.0/24", "1.1.1.128")

[
  [
    "1.1.1.0/24",
    "1.1.1.128"
  ]
]

Either (or both) operand(s) may be an array, set, or object.

net.cidr_contains_matches(["1.1.1.0/24", "1.1.2.0/24"], "1.1.1.128")

[
  [
    0,
    "1.1.1.128"
  ]
]

The array/set/object elements may be arrays. In that case, the first element must be a valid CIDR/IP.

net.cidr_contains_matches([["1.1.0.0/16", "foo"], "1.1.2.0/24"], ["1.1.1.128", ["1.1.254.254", "bar"]])

[
  [
    0,
    0
  ],
  [
    0,
    1
  ]
]

If the operand is a set, the outputs are matching elements. If the operand is an object, the outputs are matching keys.

net.cidr_contains_matches({["1.1.0.0/16", "foo"], "1.1.2.0/24"}, {"x": "1.1.1.128", "y": ["1.1.254.254", "bar"]})

[
  [
    [
      "1.1.0.0/16",
      "foo"
    ],
    "x"
  ],
  [
    [
      "1.1.0.0/16",
      "foo"
    ],
    "y"
  ]
]

UUID

Semantic Versions

Rego

OPA

Debugging

Reserved Names

The following words are reserved and cannot be used as variable names, rule names, or dot-access style reference arguments:

as
default
else
false
import
package
not
null
some
true
with

Grammar

Rego’s syntax is defined by the following grammar:

module          = package { import } policy
package         = "package" ref
import          = "import" package [ "as" var ]
policy          = { rule }
rule            = [ "default" ] rule-head { rule-body }
rule-head       = var [ "(" rule-args ")" ] [ "[" term "]" ] [ ( ":=" | "=" ) term ]
rule-args       = term { "," term }
rule-body       = [ "else" [ "=" term ] ] "{" query "}"
query           = literal { ( ";" | ( [CR] LF ) ) literal }
literal         = ( some-decl | expr | "not" expr ) { with-modifier }
with-modifier   = "with" term "as" term
some-decl       = "some" var { "," var }
expr            = term | expr-call | expr-infix
expr-call       = var [ "." var ] "(" [ term { "," term } ] ")"
expr-infix      = [ term "=" ] term infix-operator term
term            = ref | var | scalar | array | object | set | array-compr | object-compr | set-compr
array-compr     = "[" term "|" rule-body "]"
set-compr       = "{" term "|" rule-body "}"
object-compr    = "{" object-item "|" rule-body "}"
infix-operator  = bool-operator | arith-operator | bin-operator
bool-operator   = "==" | "!=" | "<" | ">" | ">=" | "<="
arith-operator  = "+" | "-" | "*" | "/"
bin-operator    = "&" | "|"
ref             = ( var | array | object | set | array-compr | object-compr | set-compr | expr-call ) { ref-arg }
ref-arg         = ref-arg-dot | ref-arg-brack
ref-arg-brack   = "[" ( scalar | var | array | object | set | "_" ) "]"
ref-arg-dot     = "." var
var             = ( ALPHA | "_" ) { ALPHA | DIGIT | "_" }
scalar          = string | NUMBER | TRUE | FALSE | NULL
string          = STRING | raw-string
raw-string      = "`" { CHAR-"`" } "`"
array           = "[" term { "," term } "]"
object          = "{" object-item { "," object-item } "}"
object-item     = ( scalar | ref | var ) ":" term
set             = empty-set | non-empty-set
non-empty-set   = "{" term { "," term } "}"
empty-set       = "set(" ")"

The grammar defined above makes use of the following syntax. See the Wikipedia page on EBNF for more details:

[]     optional (zero or one instances)
{}     repetition (zero or more instances)
|      alternation (one of the instances)
()     grouping (order of expansion)
STRING JSON string
NUMBER JSON number
TRUE   JSON true
FALSE  JSON false
NULL   JSON null
CHAR   Unicode character
ALPHA  ASCII characters A-Z and a-z
DIGIT  ASCII characters 0-9
CR     Carriage Return
LF     Line Feed