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

_{Back to top}

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

_{Back to top}

JsonPathValue

JsonPathValue is usually represented as "$feed.store.book[*].min()" and must exactly match the regular expression

"^\$([\w]+)(\.*.*?)(\.(?:(?:min&#124;max&#124;avg&#124;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:

Meta-character	Meaning
`\w`	Match any character in the range 0 - 9, A - Z, a - z and punctuation
`+`	Match when the preceding character occurs 1 or more times

Yes

(\.*.*?)

This is the second capturing group that captures JSONPath, which is applied to the PropertyReference identified by the preceding match.
If nothing is captured in this group, JSONPath '$.' is applied.

This group includes the following meta-characters:

Meta-character	Meaning
`\.*`	Match the character . literally zero or more times (*)
`.*?`	Match any character (except newline) zero or more times (*)

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.
If no function is found, the result of applying JSONPath to PropertyReference is returned as is.

This group includes the following meta-characters:

Meta-character	Meaning
`\.`	Match the character . literally
`?`	Match when the preceding character occurs 0 or 1 times only
`(?:(?:min\|max\|avg\|count))`	Non-capturing group
`\(`	Match the character ( literally
`\)`	Match the character ) literally
$	Assert position at the end of the string

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 name variable. 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

_{Back to top}

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

_{Back to top}

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.

_{Back to top}

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

??variable?? assign "Github"
??average_price?? less than 20.00
??book_count?? >= 3

_{Back to top}

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

<expression> <AND|OR> <expression> <AND|OR> <expression> ...

Examples

??book_count?? assign "$feed.store.book.count()" AND
??book_count?? >= 3
??var_store?? assign "$feed.store" AND
??var_store?? != null AND 
??var_books?? assign "$var_store.book" AND
??var_authors?? assign "$var_books.[*].author" AND 
??var_authors?? != null AND 
??var_authors?? contains "NIGEL REES" AND
??var_authors?? does not contain "Alex"

_{Back to top}

Conditional expressions

Conditional expressions enable conditional evaluation of expressions.

Syntax

if 
   <expression>
then
   <expression>
else
   <expression>
end

Example

??book_tags?? assign "$loop_book.tags" AND
??book_price?? assign "$loop_book.price" AND 
if 
   ??book_tags?? contains "fiction" 
then
   ??book_price?? >= 9.0
else
   if 
     ??book_tags?? contains "oreilly"
   then 
     ??book_price?? >= 11.0
   else 
     ??book_price?? between [2.0 AND 30.0]
   end
end

_{Back to top}

Foreach expressions

Foreach expressions enable repeated evaluation of rules for each item in a list.

Syntax

foreach <loop_variable> IN #<PropertyReference>#
       <expression>
    end

Example

??store_authors??  assign "$feed.store.book[*].author" AND
    foreach loop_author IN #store_authors#
        loop_author != "Sharad Sinha"
    end

_{Back to top}

Policy Document structure

A policy document is a YAML file, which contains rule expressions.

Example policy document

--- 
author: "BMC Software"
dateOfCreation: "Thu Feb 18 02:47:49 PST 2016"
name: "Book store Policy"
rulesCount: 18
groups: 
  - 
    description: ""
    id: 1
    name: "My book store Local Policies group0"
    rules:
     - 
        description: "There must be atleast 3 books in store at all times"
        id: 1
        name: "book store book count"
        refNumber: ~
        ruleExpression: |-
            ??book_count?? assign "$feed.store.book.count()" AND
            ??book_count?? >= 3
     - 
        description: "average prices of books must be less than 20"
        id: 2
        name: "book avg price "
        refNumber: ~
        ruleExpression: |-
            ??average_price?? assign "$feed.store.book[*].price.avg()" AND
            ??average_price?? less than 20.00

_{Back to top}

Policy Authoring - Samples

The following example demonstrates a JSON feed representing book store details. This sample contains constructs that are used for policy authoring.

Click here to view.

Example

{
    "name" : "my-book-store",
    "guid" : "0503bd2e-816f-42c4-8011-38c9dcb01e28",
    "type" : "store",
    "collectionStartTime": 1463661952595,
    "collectionEndTime": 1463662072595, 
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95,
                "id" : 1,
                "review" : {
                    "rating" : 5,
                    "summary" : "Excellent" 
                },
                "tags" : ["oxford","reference"],
                "requiresRefresh" : false
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99,
                "id" :2,
                "review" : {
                    "rating" : 3,
                    "summary" : "Good"  
                },
                "tags" : ["oreilly","fiction"],
                "requiresRefresh" : true
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99,
                "id" : 3,
                "review" : {
                    "rating" : 4,
                    "summary" : "Very Good" 
                },
                "tags" : ["fiction" , "Moby", "Dick"],
                "requiresRefresh" : true
            },
            {
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99,
                "id" : 4,
                "review" : {
                    "rating" : 5,
                    "summary" : "Excellent" 
                },
                "tags" : ["fiction" , "Excellent"],
                "requiresRefresh" : true
            }
        ]
    }
}

The following example demonstrates the use of rule expressions:

Click here to view.

Example

--- 
author: "BMC Software"
dateOfCreation: "Thu Feb 18 02:47:49 PST 2016"
groups: 
  - 
    description: ""
    id: 1
    name: "My book store Local Policies group0"
    rules:
     - 
        description: "There must be atleast 3 books in store at all time"
        id: 1
        name: "book store book count"
        refNumber: ~
        ruleExpression: |-
            ??book_count?? assign "$feed.store.book.count()" AND
            ??book_count?? >= 3
     - 
        description: "average prices of books must be less than 20"
        id: 2
        name: "book avg price "
        refNumber: ~
        ruleExpression: |-
            ??average_price?? assign "$feed.store.book[*].price.avg()" AND
            ??average_price?? less than 20.00
     - 
        description: "there must be atleast 2 books with category 'fiction' at all times"
        id: 4
        name: "there must be atleast 2 books with category 'fiction' at all times"
        refNumber: ~
        ruleExpression: |-
            ??var_fiction_count?? assign "$feed.store.book[?(@.category == 'fiction')].count()" AND
            ??var_fiction_count?? >= 2
     - 
        description: "There are no banned books in my store"
        id: 5
        name: "There are no banned books in my store"
        refNumber: ~
        ruleExpression: |-
            ??banned_book_count?? assign "$feed.store.book[?(@.category == 'banned')].count()" AND
            ??banned_book_count?? = 0 
     - 
        description: "All authours must be from a given list"
        id: 6
        name: "All authours must be from a given list"
        refNumber: ~
        ruleExpression: |-
            ??store_authors??  assign "$feed.store.book[*].author" AND
            foreach loop_author IN #store_authors#
              loop_author != "Sharad Sinha"
            end
     - 
        description: "there must be a book with author 'Nigel Rees'"
        id: 7
        name: "book nested attributes reference , there must be a book with author 'Nigel Rees' "
        refNumber: ~
        ruleExpression: |-
            ??var_store?? assign "$feed.store" AND
            ??var_store?? != null AND 
            ??var_books?? assign "$var_store.book" AND
            ??var_authors?? assign "$var_books.[*].author" AND 
            ??var_authors?? != null AND 
            ??var_authors?? contains "NIGEL REES" AND
            ??var_authors?? does not contain "Alex"   
     - 
        description: "Demonstrate nested for loops"
        id: 8
        name: "Demonstrate nested for loops"
        refNumber: ~
        ruleExpression: |-
            ??store_books?? assign "$feed.store.book" AND
            foreach loop_book IN #store_books#
              loop_book != null AND 
              ??book_tags?? assign "$loop_book.tags" AND 
              ??book_tags?? != null AND 
              foreach loop_tag IN #book_tags#
                loop_tag != null AND
                loop_tag is one of ["oxford","reference","oreilly","fiction","fiction" , "Moby", "Dick", "Excellent"] AND
                loop_tag is not one of ["Alex" , "john", "fernando"] AND
                loop_tag is one of (case sensitive) ["oxford","reference","oreilly","fiction","Moby", "Dick","Excellent"] AND
                loop_tag is not one of (case sensitive)  ["OXFORD","REFERENCE","OREILLY","FICTION","FICTION" , "MOBY", "DICK", "EXCELLENT"] 
              end  
            end
     - 
        description: "Demonstrate misc string operations"
        id: 9
        name: "Demonstrate misc string operations"
        refNumber: ~
        ruleExpression: |-
            ??store_book_author?? assign "$feed.store.book[0].author" AND
            ??store_book_author?? assign "$feed.store.book[0].author" AND
            ??store_book_author?? starts with "NIGEL" AND
            ??store_book_author?? does not start with "ALEX" AND
            ??store_book_author?? ends with "REES" AND 
            ??store_book_author?? does not end with "ALEX" AND
            ??store_book_author?? is substring of "NIGEL REES HAS COME BACK WITH A BANG" AND
            ??store_book_author?? is not substring of "HAS COME BACK WITH A BANG" AND
            ??store_book_author?? does not equal "ALEX" AND
            ??store_book_author?? equals "NIGEL REES" AND
            ??store_book_author?? = "NIGEL REES" AND
            ??store_book_author?? != "Alex" AND
            ??store_book_author?? is one of ["NIGEL REES" , "SHARAD SINHA"] AND
            ??store_book_author?? equals (ignore extra white spaces) " NIGEL   REES    " AND
            ??store_book_author?? starts with (case sensitive) "Nigel" AND
            ??store_book_author?? does not start with (case sensitive) "Alex" AND
            ??store_book_author?? equals (case sensitive) "Nigel Rees" AND
            ??store_book_author?? ends with (case sensitive) "Rees" AND 
            ??store_book_author?? does not end with (case sensitive) "REES" AND
            ??store_book_author?? is substring of (case sensitive) "Nigel Rees has come back with a bang" AND
            ??store_book_author?? is not substring of (case sensitive) "NIGEL REES HAS COME BACK WITH A BANG" AND
            ??store_book_author?? does not equal (case sensitive) "NIGEL REES" AND
            ??store_book_author?? is one of (case sensitive) ["Nigel Rees" , "Sharad Sinha"] AND
            ??store_book_author?? equals (case sensitive and ignore extra white spaces) " Nigel   Rees    " 
     - 
        description: "Demonstrate 'contains' variations'"
        id: 10
        name: "Demonstrate 'contains' variations'"
        refNumber: ~
        ruleExpression: |-
            ??var_authors?? assign "$feed.store.book[*].author" AND
            ??var_authors?? contains "HERMAN MELVILLE" AND 
            ??var_authors?? does not contain (case sensitive) "HERMAN MELVILLE" AND
            ??var_authors?? contains (case sensitive) "Nigel Rees"
     - 
        description: "Demonstrate 'contains' in integer list variations"
        id: 11
        name: "Demonstrate 'contains' in integer list variations"
        refNumber: ~
        ruleExpression: |-
            ??var_ids?? assign "$feed.store.book[*].id" AND
            ??var_ids?? contains 2 AND
            ??var_ids?? does not contain 999
     - 
        description: "Demonstrate 'contains' in double list variations"
        id: 12
        name: "Demonstrate 'contains' in double list variations"
        refNumber: ~
        ruleExpression: |-
            ??var_ids?? assign "$feed.store.book[*].price" AND
            ??var_ids?? contains 12.99 AND
            ??var_ids?? does not contain 999.99
     - 
        description: "Demonstrate numeric operators on double values"
        id: 13
        name: "Demonstrate numeric operators on double values"
        refNumber: ~
        ruleExpression: |-
            ??var_price?? assign "$feed.store.book[0].price" AND
            ??var_price?? = 8.95 AND
            ??var_price?? equals 8.95 AND
            ??var_price?? != 9.0 AND
            ??var_price?? does not equal 9.0 AND
            ??var_price?? >= 8.95 AND
            ??var_price?? greater than or equal to 8.95 AND
            ??var_price?? > 8.00 AND
            ??var_price?? greater than 8.00 AND
            ??var_price?? < 10.00 AND
            ??var_price?? less than 10.00 AND 
            ??var_price?? <= 8.95 AND
            ??var_price?? less than or equal to 8.95 AND
            ??var_price?? between [8.0 AND 9.0]
     - 
        description: "Demonstrate numeric operators on integer values"
        id: 14
        name: "Demonstrate numeric operators on double values"
        refNumber: ~
        ruleExpression: |-
            ??var_price?? assign "$feed.store.book[0].review.rating" AND
            ??var_price?? = 5 AND
            ??var_price?? equals 5 AND
            ??var_price?? != 5.0 AND
            ??var_price?? does not equal 5.0 AND
            ??var_price?? >= 5 AND
            ??var_price?? greater than or equal to 5 AND
            ??var_price?? > 2 AND
            ??var_price?? greater than 2 AND
            ??var_price?? < 10 AND
            ??var_price?? less than 10 AND 
            ??var_price?? <= 5 AND
            ??var_price?? less than or equal to 5 AND
            ??var_price?? between [2 AND 10]
     - 
        description: "Demonstrate operations on boolean values"
        id: 15
        name: "Demonstrate operations on boolean values, Cautions boolean values must be in CAPS"
        refNumber: ~
        ruleExpression: |-
            ??var_requiresRefresh?? assign "$feed.store.book[0].requiresRefresh" AND
            ??var_requiresRefresh?? = FALSE AND
            ??var_requiresRefresh?? != TRUE AND
            ??var_requiresRefresh?? != 5 AND 
            ??var_requiresRefresh?? equals FALSE
     - 
        description: "Demonstrate conditional evaluations with basic if else expressions"
        id: 16
        name: "Demonstrate conditional evaluations"
        refNumber: ~
        ruleExpression: |-
            ??store_books?? assign "$feed.store.book" AND
            foreach loop_book IN #store_books#
              ??book_tags?? assign "$loop_book.tags" AND
              ??book_price?? assign "$loop_book.price" AND 
              if 
                ??book_tags?? contains "fiction" 
              then 
                ??book_price?? >= 9.0
              else 
                ??book_price?? between [2.0 AND 30.0]
              end                 
            end
     - 
        description: "Demonstrate conditional evaluations with if else ladder"
        id: 17
        name: "Demonstrate conditional evaluations"
        refNumber: ~
        ruleExpression: |-
            ??store_books?? assign "$feed.store.book" AND
            foreach loop_book IN #store_books#
              ??book_tags?? assign "$loop_book.tags" AND
              ??book_price?? assign "$loop_book.price" AND 
              if 
                ??book_tags?? contains "fiction" 
              then
                ??book_price?? >= 9.0
              else
                if 
                  ??book_tags?? contains "oreilly"
                then 
                  ??book_price?? >= 11.0
                else 
                  ??book_price?? between [2.0 AND 30.0]
                end
              end                 
            end
     - 
        description: "Demonstrate 'NOT' usage'"
        id: 18
        name: "Demonstrate 'contains' variations'"
        refNumber: ~
        ruleExpression: |-
            ??var_authors?? assign "$feed.store.book[*].author" AND
            NOT (??var_authors?? contains (case sensitive) "HERMAN MELVILLE") AND
            ??var_authors?? contains (case sensitive) "Nigel Rees"
name: "Book store Policy"
rulesCount: 18

_{Back to top}

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.

Click here to view the structure of the reference policy document.

--- 
author: "BMC Software"
dateOfCreation: "Thu Feb 18 02:47:49 PST 2016"
name: "cfn policy"
selectionHint: cfn , aws lambda , s3
groups: 
  - 
    description: "cfn rules"
    id: 1
    name: "cfn rules"
    rules: 
     - 
        description: "check memorysize"
        id: 112
        refNumber: ~
        ruleExpression: |-
            ??all_resource?? assign "$feed.Resources.*" AND
            ??all_lambda?? assign "$all_resource.[?(@.Type == 'AWS::Lambda::Function')]"

Click here to view the structure of the reference resource feed document.

{

  "Description": "BMC CaaS policy engine template",
  "selectionHint" : "cfn , aws lambda"  
  "AWSTemplateFormatVersion": "2010-09-09",
  "Resources": {
    "PolicyEngineLambdaExecutionRole": {
      "Type": "AWS::IAM::Role",
      "Properties": {
        "AssumeRolePolicyDocument": {

         ... Rest of the document

_{Back to top}

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.

_{Back to top}

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: A dependency checker feed can have projects as origin A cfn feed can have a project or a microservice as origin 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. `originSpe`c is expressed using the following attributes: `expression` `nameExpression` `typeExpression`	No
	expression	A JSON path expression that corresponds to a JSON node within a JSON feed. When you write an expression, the `expression` attribute must evaluate to a valid JSON node. Otherwise, the policy on which the origin field is defined is not evaluated against the incoming resource feed. In other words, evaluation is skipped for the incoming resource feed.	Yes
	nameExpression	A JSON path expression that represents the name of the origin object. When you write a name expression, the `namExpression` must evaluate to a string type. If you do not specify a value for this attribute or if the value is null, `expression` is used as the name.	No
	typeExpression	A JSON path expression that represents the type of the origin object. When you write a type expression, the `typeExpression` must evaluate to a string type. 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 `originSpec`. Like `originSpec`, `resourceSpec` have the following properties: Can only be defined at the policy document level If not specified, the entireresource feed is treated as a single origin `resourceSpec` is expressed using the following attributes: `expression` `nameExpression` `typeExpression`	No
	expression	A JSON path expression that corresponds to a JSON node within a resource feed. When you write an expression, the `expression` attribute must evaluate to a valid JSON node. Otherwise, policy evaluation is skipped for the incoming resource feed.	Yes
	nameExpression	A JSON path expression that represents the name of the resource object. When you write a name expression, the `nameExpression` must evaluate to a string type. If you do not specify a value for this attribute or if the value is null, `expression` is used as the resource name. You can specify a fixed string as a `nameExpression`; the fixed string is used as is for the name of the resource. However, this type of expression is not recommended for a single resource per resource feed.	No
	typeExpression	A JSON path expression that represents the type of the resource object. When you write a type expression, the `typeExpression` must evaluate to a string type. If you do not specify a value for this attribute, `typeEpression` is set to null. You can specify a fixed string as a `typeExpression`; the fixed string is used as is for the type of the resource.	No

Click here to view a sample policy document.

--- 
author: "BMC Software"
dateOfCreation: "Thu Feb 18 02:47:49 PST 2016"
name: "cfn policy"
originSpec: 
  expression: $.*.Resources
  nameExpression: $.name
  typeExpression: "$.[@.Type='AWS Lambda']"
resourceSpec: 
  expression: $.*.Resources
  nameExpression: $.name
  typeExpression: "$.[@.Type='AWS Lambda']"
selectionHint: "cfn , aws lambda , s3"
groups: 
  - 
    description: "cfn rules"
    id: 1
    name: "cfn rules"
    rules: 
      - 
        description: "check memorysize"
        id: 112
        refNumber: ~
        ruleExpression: "??all_resource?? assign \"$feed.Resources.*\" AND\n\
            ??all_lambda?? assign \"$all_resource.[?(@.Type == 'AWS::Lambda::Function')]\" "

_{Back to top}

Recommendations for policy authoring

Although you can author policies for any number of resources and any resource types for a given resource feed, BMC recommends that you create separate policies for each resource type. This improves the readability of the report results and also allows greater flexibility when you perform various aggregations on the results.

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

}

Authoring policies

Types

Operators

JsonPathValue

PropertyReference

JSON path expressions

Aggregation functions

Expressions

Simple Expressions

n-nary expressions

Conditional expressions

Foreach expressions

Policy Document structure

Policy Authoring - Samples

Matching Resources to Policies

Matching an incoming feed with appropriate policies

Dynamically identifying resources within a JSON feed

Resource matching criteria

Policy severity

Comments