Authoring policies
To access the latest information about this topic and all Cloud Security releases, check out the Release notes and notices.
Before you begin authoring policies, it is important to understand that you must write policies so that a resource that is being evaluated for compliance, does evaluate to be complaint. Do not write policies that check whether a resource is non-compliant. You cannot write a policy without a feed.
To be able to support any JSON files as resource feeds, the Policy Engine of BMC Helix Cloud Security is JSON-aware. In other words, the Policy Engine provides constructs for evaluating rule expressions based on any JSON objects. You can broadly classify the constructs that the Policy Engine supports into the following categories:
Types
The Policy Engine is type-aware. Typically, when a rule expression is evaluated, you must ensure correct types in LHS and RHS. Different types are represented differently, and to be able to write correct rule expressions, you must know these representations. The following table shows a list of types that you can use when working with any JSON feeds.
Type | Description | Example |
---|---|---|
Boolean | A binary value: TRUE/FALSE in uppercase | TRUE |
Integer | A numeric literal without a decimal point | 1,2,45 |
Decimal | A numeric literal with a decimal point | 11.23,2.34,45.00 |
String | Any string literal enclosed in double quotes | "GitHub", "Wiki" |
JSON path | A string literal that matches a regular expression "^\$([\w]+)(..?)(.(?:(?:min|max|avg|count)()))?$" | "$feed" , $feed.lastUpdated , $feed.store.books[*].price.min() |
JSON objects | A policy document does not support defining JSON objects. Therefore, JSON objects do not have any special representation. This type is hidden from a policy author but understanding its existence is important for policy authoring. | |
List | A comma-separated list of any of the preceding types enclosed in square braces | [1,2,3] , ["NodeJS" , "Rocks"] |
Range | A pair of values enclosed in square braces. Note: This type is only supported for Integer and Decimal types. | [8.0 AND 9.0] |
Property Reference | ??reference_name?? represents a reference to any of the supported types except .Authoring policies vall_releases#JsonPathValue. Property references provide a link between Policy Engine rule evaluation and external data on which rules are evaluated. Property references are variables/references on which rule expressions are evaluated. Note: Property References are always on the RHS of a binary expression. | |
RegEx | In-progress | |
Date | In-progress |
Operators
Operators form the basic building blocks for constructing a rule expression. The results of a rule expression can be further combined with other operators to construct complex expressions consisting of many simple expressions. The following operators are supported when working with any JSON feeds:
Operator | Cardinality | Usage | Applicable types |
---|---|---|---|
assign | 2 | LHS assign "GitHub" | LHS is PropertReference and RHS can be any of the supported types. This operation assigns the effective(evaluated) value of the RHS to the property reference. We will discuss more about RHS evaluation when we discuss expression evaluation. |
equals | 2 | equals or = , LHS = "GitHub" or LHS equals "GitHub" | Any simple type (String, Boolean, Integer, Decimal) |
does not equal | 2 | does not equal or != , LHS != "GitHub" or LHS does not equal "GitHub" | Any simple type (String, Boolean, Integer, Decimal) |
starts with | 2 | LHS starts with "Git" | LHS and RHS must be of String type |
is substring of | 2 | LHS is substring of "GitHub rocks" | LHS and RHS must be of String type |
is not substring of | 2 | LHS is not substring of "GitHub rocks" | LHS and RHS must be of String type |
ends with | 2 | LHS ends with "rocks" | LHS and RHS must be of String type |
does not end with | 2 | LHS does not end with "rocks" | LHS and RHS must be of String tye |
is one of | 2 | LHS is one of ["GitHub, "Wiki"] | LHS must be any simple type (String, Boolean, Integer, Decimal) and RHS must be a List of the same type as LHS |
is not one of | 2 | LHS is not one of ["GitHub, "Wiki"] | LHS must be any simple type (String, Boolean, Integer, Decimal) and RHS must be a List of the same type as LHS |
contains | 2 | LHS contains "GitHub | LHS must be a List of any simple type (String, Boolean, Integer, Decimal) and RHS must be any simple type |
does not contain | 2 | LHS does not contain "GitHub" | LHS must be a List of any simple type (String, Boolean, Integer, Decimal) and RHS must be any simple type |
equals (case sensitive) | 2 | LHS equals (case sensitive) "GitHub" | LHS and RHS mst be of String type |
does not equal (case sensitive) | 2 | LHS does not equal (case sensitive) "GitHub" | LHS and RHS must be of String type |
is substring of (case sensitive) | 2 | LHS is substring of (case sensitive) "GitHub" | LHS and RHS must be of String type |
is not substring of (case sensitive) | 2 | LHS is not substring of (case sensitive) "GitHub" | LHS and RHS must be of String type |
contains (case sensitive) | 2 | LHS contains (case sensitive) "GitHub" | LHS must be a list of String type and RHS must be of String type |
does not contain (case sensitive) | 2 | LHS does not contain (case sensitive) "GitHub" | LHS must be a list of String type and RHS must be of String type |
starts with (case sensitive) | 2 | LHS starts with (case sensitive) "GitHub" | LHS and RHS must be of String type |
does not start with (case sensitive) | 2 | LHS does not start with (case sensitive) "GitHub" | LHS and RHS must be of String type |
ends with (case sensitive) | 2 | LHS ends with (case sensitive) "GitHub" | LHS and RHS must be of String type |
does not end with (case sensitive) | 2 | LHS does not end with (case sensitive) "GitHub" | LHS and RHS must be of String type |
is one of (case sensitive) | 2 | LHS is one of (case sensitive) ["GitHub","NodeJs", "Rocks" ] | LHS must be of String type and RHS must be a list of String type |
is not one of (case sensitive) | 2 | LHS is not one of (case sensitive) ["GitHub","NodeJs", "Rocks" ] | LHS must be of String type and RHS must be a list of String type |
equals (ignore extra white spaces) | 2 | LHS equals (ignore extra white spaces) " NodeJs Rocks" | LHS and RHS must be of String type. Ignore any additional spaces either on edges or within a string |
equals (case sensitive and ignore extra white spaces) | 2 | LHS equals (case sensitive and ignore extra white spaces) " NodeJs Rocks" | LHS and RHS must be of String type. Ignore any additional spaces either on edges or within a string. Case sensitive version of above |
less than | 2 | LHS less than 5 or LHS < 5 | LHS and RHS must be of Integer or Decimal type |
greater than | 2 | LHS greater than 5 or LHS > 5 | LHS and RHS must be of type Integer or Decimal type |
less than or equal to | 2 | LHS less than or equal to 5 or LHS <= 5 | LHS and RHS must be of Integer or Decimal type |
greater than or equal to | 2 | LHS greater than or equal to to 5 or LHS <= 5 | LHS and RHS must be of Integer or Decimal type |
between | 2 | LHS between [ 5 AND 10] , A range must have 'AND' as caps | LHS must be of Integer or Decimal type and RHS must be of Range type (the same type same as LHS) |
NOT | 1 | NOT (expression) Eg, NOT (LHS between [ 5 AND 10]) , This operator inverts the evaluation result of an expression(RHS) | RHS must be expression |
AND | N/* | expression AND expression Eg, LHS between [ 5 AND 10] AND LHS = "GitHub", This operator performs logical AND-ING of results of child expressions | Any expression |
OR | N/* | expression OR expression Eg, LHS between [ 5 AND 10] OR LHS = "GitHub", This operator performs logical OR-ING of results of child expressions | Any expression |
JsonPathValue
JsonPathValue is usually represented as "$feed.store.book[*].min()"
and must exactly match the regular expression
"^\$([\w]+)(\.*.*?)(\.(?:(?:min|max|avg|count)\(\)))?$"
Meta-character | Meaning | Required | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
\$ | Matches the character $ literally | |||||||||||||||
([\w]+) | This is the first capturing group that captures PropertyReference on which JSONPath is applied. This group includes the following meta-characters:
| Yes | ||||||||||||||
(\.*.*?) | This is the second capturing group that captures JSONPath, which is applied to the PropertyReference identified by the preceding match. This group includes the following meta-characters:
| No | ||||||||||||||
(\.(?:(?:min|max|avg|count)\(\)))? | This is the third capturing group that includes the Aggregation function to be applied to the result of applying JSONPath to PropertyReference. This group includes the following meta-characters:
Note: A repeated capturing group only captures the last iterations. | No |
Thus, a JsonPathValue is a triplet as shown in the following example:
<PropertyReference> <Json path expression> <aggregation function>
Let us explore each one in detail:
PropertyReference
PropertyReference represents the name of the property reference on which the JSON path expression is applied. The property reference can be passed externally ($feed
) or can hold the result of the assignment operation of an expression. You can create a valid PropertyReference in the following ways:
- Passed externally: In this case, you can refer to the PropertyReference by using
$feed.
- Assignment operation: The evaluation of an assignment expression (
??variable?? assign "$feed.*"
) creates a valid PropertyReference with the namevariable
. The same can be referred to in subsequent JsonPathValue expressions as$variable
- Loop variable reference: You can access loop variable references as PropertyReferences.
The following example illustrates the usage of loop variable references:
foreach loop_book IN #store_books#
??book_tags?? assign "$loop_book.tags"
end
JSON path expressions
JSON path expressions are similar to XPath expressions in XML, except that JSON paths work on JSON objects. The Policy Engine is not responsible for evaluating JSON path expressions. It makes use of Json path - Jayway library for JSON path evaluations. As a policy author, you must understand what JSON path is for a given JsonPathValue expression. Also, as a policy author, you must understand the result of a JSON path evaluation. The following table lists some examples:
JsonPathValue expression | Evaluation |
---|---|
$feed | Evaluates JSON path $. on PropertyReference feed |
$feed.store.book | Evaluates JSON path $.store.book on PropertyReference feed |
$feed.store.book[*].price | Evaluates JSON path $.store.book[*].price on PropertyReference feed |
$feed.store.book[*].price.max() | Evaluates JSON path $.store.book[*].price on PropertyReference feed and the Policy Engine applies the aggregation function max() to the result |
Aggregation functions
The Policy Engine supports the following aggregation functions to be applied to the results of JSON path evaluations:
Aggregation function | Description |
---|---|
min() | Requires that result on which the function is applied is a list of Integer or Decimal values. Returns the minimum of all the values in the list. |
max() | Requires that result on which the function is applied is a list of Integer or Decimal values. Returns the maximum of all the values in the list. |
avg() | Requires that result on which the function is applied is a list of Integer or Decimal values. Returns the average of all the values in the list. |
count() | Requires that result on which the function is applied is a list of any type. Returns the number of items in the list. |
Note
A JsonPathValue is always on the RHS of an expression. Also, a JsonPathValue can only be part of an assignment expression.
Expressions
Expressions are constructed by combining operands (of the supported types) and operators. In the Policy Engine, every expression evaluates to a Boolean result.
Rule expressions can be of the following types:
Simple Expressions
These type of expressions are the simplest and are the building blocks for more complex rule expressions.
Syntax |
<PropertyReference> <Operator> <Type> |
---|
Examples |
|
n-nary expressions
These types of expressions are a combination of two or more expressions. Almost all rule expressions are expressed as n-nary expressions.
Syntax |
|
---|
Examples |
|
Conditional expressions
Conditional expressions enable conditional evaluation of expressions.
Syntax |
|
---|
Example |
|
Foreach expressions
Foreach expressions enable repeated evaluation of rules for each item in a list.
Syntax |
|
---|
Example |
|
Policy Document structure
A policy document is a YAML file, which contains rule expressions.
Example policy document |
|
---|
Policy Authoring - Samples
The following example demonstrates a JSON feed representing book store details. This sample contains constructs that are used for policy authoring.
The following example demonstrates the use of rule expressions:
Matching Resources to Policies
BMC Helix Cloud Security supports "any data any policy".
- Any data: Implies any JSON document as a resource feed, which might contain data for multiple resources.
- Any policy: Implies that you can author any policies that test different aspects of the incoming feed.
Support for "any data any policy" results in the following key challenges:
Matching an incoming feed with appropriate policies
BMC Helix Cloud Security uses special hint fields in the Policy and Resource feed. These fields are captured as a part of the metadata section of both the documents.
As shown in the following excerpts, BMC Helix Cloud Security uses the selectionHint attribute in the Policy and Resource feed document to match feeds with policies.
Dynamically identifying resources within a JSON feed
When supporting any arbitrary JSON as a resource feed, it is difficult to ascertain whether a specific section within a JSON document must be treated as a resource or whether the entire JSON document must be treated as a single resource.
Resource matching criteria
The resource matching criteria mechanism enables a policy author to define which sections of a feed should constitute a resource, which must be applied to the policy. Occasionally, the resource matching criteria might not map to any JSON node in the feed and would therefore result in no policy being evaluated against the feed.
The resource policy document can contain the following attributes:
Spec Type | Spec Attribute | Description | Required |
---|---|---|---|
originSpec | A source/origin or a resource. You can have multiple origins in a given resource feed document. Examples:
Although an origin can be modeled as a resource, currently, origin is a textual attribute of a resource that is used mainly for the purpose of reporting.
| No | |
expression | A JSON path expression that corresponds to a JSON node within a JSON feed. When you write an expression, the | Yes | |
nameExpression | A JSON path expression that represents the name of the origin object. When you write a name expression, the | No | |
typeExpression | A JSON path expression that represents the type of the origin object. When you write a type expression, the The type of an origin is not important because its value is not currently used. Therefore, you may not specify the type in the policy or leave it blank. | No | |
resourceSpec | An identifier for a resource within a JSON node as represented by Like
| No | |
expression | A JSON path expression that corresponds to a JSON node within a resource feed. When you write an expression, the | Yes | |
nameExpression | A JSON path expression that represents the name of the resource object. When you write a name expression, the You can specify a fixed string as a | No | |
typeExpression | A JSON path expression that represents the type of the resource object. When you write a type expression, the If you do not specify a value for this attribute, You can specify a fixed string as a | No |
Recommendations for policy authoring
Policy severity
The severity level across all CIS policies are standardized with a minimum (low) severity of 4, and a maximum (high) severity of 9. A critical severity cannot exceed a value of 10.
These levels are common across the following policies:
- Out of the Box (OOTB) Policies
- AWS CIS Policies
- CIS Windows 2012 Policies
- CIS AWS Three-tier Web Policies
- CIS Docker Policies
- Beta Policies
- CIS Azure Policies
Example
severity: {
low: {
min: 0,
max: 3
},
medium: {
min: 4,
max: 6
},
high: {
min: 7,
max: 9
},
critical: {
min: 10
}
}
Comments
Log in or register to comment.