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 

{{code language="none"}}
<expression> <AND|OR> <expression> <AND|OR> <expression> ...
{{/code}}

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  

{{code language="none" source="string:{{code language=~"none~"~}~}
if <expression> then <expression> else <expression> end
{{/code~}~}"/}}
{{/code}}
)))
|(((
**Example**
)))
|=(((


{{code language="text" theme="Confluence"}}
??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
{{/code}}
)))

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

=== {{id name="Authoringpolicies-Foreachexpressions"/}}Foreach expressions ===

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

|(((
**Syntax**   
)))
|=(((
{{code language="none" source="string:{{code language=~"none~"~}~}
{{code language=~"none~" source=~"string:{{code language=~~~"none~~~"~~}~~}
foreach <loop_variable> IN #<PropertyReference># <expression> end
{{/code~~}~~}~"/~}~}
{{/code~}~}"/}}
)))
|(((
**Example**
)))
|=(((


{{code language="text" theme="Confluence"}}
??store_authors??  assign "$feed.store.book[*].author" AND
    foreach loop_author IN #store_authors#
        loop_author != "Sharad Sinha"
    end
{{/code}}
)))

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

==== {{id name="Authoringpolicies-PolicyDocumentstructure"/}}Policy Document structure ====

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

|(((
**Example policy document
**
)))
|=(((


{{code language="text" theme="Confluence"}}
---
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
{{/code}}
)))

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

==== {{id name="Authoringpolicies-PolicyAuthoring-Samples"/}}Policy Authoring - Samples ====

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

{{expand expanded="false" title="Click here to view."}}
**Example**

{{code language="text" theme="Confluence"}}
{
    "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
            }
        ]
    }
}
{{/code}}
{{/expand}}

The following example demonstrates the use of rule expressions:

{{expand expanded="false" title="Click here to view."}}
**Example**

{{code language="text" theme="Confluence"}}
---
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
{{/code}}
{{/expand}}

\\

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

== {{id name="Authoringpolicies-MatchingResourcestoPolicies"/}}Matching Resources to Policies ==

{{excerpt-include 0="More-Products.Cloud-Security.BMC-Helix-Cloud-Security.PathPol._libraries._excerptLib.WebHome" name="product_name" nopanel="true"/}} 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:



{{toc depth="3" start="3"/}}

=== {{id name="Authoringpolicies-Matchinganincomingfeedwithappropriatepolicies"/}}Matching an incoming feed with appropriate policies ===

{{excerpt-include 0="More-Products.Cloud-Security.BMC-Helix-Cloud-Security.PathPol._libraries._excerptLib.WebHome" name="product_name" nopanel="true"/}} 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, {{excerpt-include 0="More-Products.Cloud-Security.BMC-Helix-Cloud-Security.PathPol._libraries._excerptLib.WebHome" name="product_name" nopanel="true"/}} uses the **selectionHint** attribute in the Policy and Resource feed document to match feeds with policies.

{{expand expanded="false" title="Click here to view the structure of the reference policy document."}}
{{code language="text" theme="Confluence"}}
---
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')]"
{{/code}}
{{/expand}}

{{expand expanded="false" title="Click here to view the structure of the reference resource feed document."}}
{{code language="text" theme="Confluence"}}
{

  "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
{{/code}}
{{/expand}}

\\

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

=== {{id name="Authoringpolicies-DynamicallyidentifyingresourceswithinaJSONfeed"/}}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.

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

==== {{id name="Authoringpolicies-Resourcematchingcriteria"/}}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
)))
|(% rowspan="4" %)(((
(% class="code" %)
(((
originSpec
)))

(% class="code" %)
(((

)))

(% class="code" %)
(((

)))

(% class="code" %)
(((

)))
)))|(((

)))|(((
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.

{{code language="none"}}originSpe{{/code}}c is expressed using the following attributes:

* {{code language="none"}}expression{{/code}}
* {{code language="none"}}nameExpression{{/code}}
* {{code language="none"}}typeExpression{{/code}}
)))|(((
No
)))
|(((
(% class="code" %)
(((
expression
)))
)))|(((
A JSON path expression that corresponds to a JSON node within a JSON feed.

When you write an expression, the {{code language="none"}}expression{{/code}} 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
)))
|(((
(% class="code" %)
(((
nameExpression
)))
)))|(((
A JSON path expression that represents the name of the origin object.

When you write a name expression, the {{code language="none"}}namExpression{{/code}} must evaluate to a string type. If you do not specify a value for this attribute or if the value is null, {{code language="none"}}expression{{/code}} is used as the name.
)))|(((
No
)))
|(((
(% class="code" %)
(((
typeExpression
)))
)))|(((
A JSON path expression that represents the type of the origin object.

When you write a type expression, the {{code language="none"}}typeExpression{{/code}} 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
)))
|(% rowspan="4" %)(((
(% class="code" %)
(((
resourceSpec
)))

(% class="code" %)
(((

)))

(% class="code" %)
(((

)))

(% class="code" %)
(((

)))
)))|(((

)))|(((
An identifier for a resource within a JSON node as represented by {{code language="none"}}originSpec{{/code}}.

Like {{code language="none"}}originSpec{{/code}}, {{code language="none"}}resourceSpec{{/code}} 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

{{code language="none"}}resourceSpec{{/code}} is expressed using the following attributes:

* {{code language="none"}}expression{{/code}}
* {{code language="none"}}nameExpression{{/code}}
* {{code language="none"}}typeExpression{{/code}}
)))|(((
No
)))
|(((
(% class="code" %)
(((
expression
)))
)))|(((
A JSON path expression that corresponds to a JSON node within a resource feed.

When you write an expression, the {{code language="none"}}expression{{/code}} attribute must evaluate to a valid JSON node. Otherwise, policy evaluation is skipped for the incoming resource feed.
)))|(((
Yes
)))
|(((
(% class="code" %)
(((
nameExpression
)))
)))|(((
A JSON path expression that represents the name of the resource object.

When you write a name expression, the {{code language="none"}}nameExpression{{/code}} must evaluate to a string type. If you do not specify a value for this attribute or if the value is null, {{code language="none"}}expression{{/code}} is used as the resource name.

You can specify a fixed string as a {{code language="none"}}nameExpression{{/code}}; 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
)))
|(((
(% class="code" %)
(((
typeExpression
)))
)))|(((
A JSON path expression that represents the type of the resource object.

When you write a type expression, the {{code language="none"}}typeExpression{{/code}} must evaluate to a string type.

If you do not specify a value for this attribute, {{code language="none"}}typeEpression{{/code}} is set to null.

You can specify a fixed string as a {{code language="none"}}typeExpression{{/code}}; the fixed string is used as is for the type of the resource.
)))|(((
No
)))

\\

{{expand expanded="false" title="Click here to view a sample policy document."}}
{{code language="text" theme="Confluence"}}
---
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')]\" "
{{/code}}
{{/expand}}

\\

{{export-ignore}}
,,[[Back to top>>doc:]],,
{{/export-ignore}}

\\

{{success}}
**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.

{{/success}}

== {{id name="Authoringpolicies-Policyseverity"/}}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:

(% class="alternate" %)
* 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

{{info title="Example"}}
{{code language="none"}}
severity: {
{{/code}}

{{code language="none"}}
               low: {
{{/code}}

{{code language="none"}}
                    min: 0,
{{/code}}

{{code language="none"}}
                    max: 3
{{/code}}

{{code language="none"}}
               },
{{/code}}

{{code language="none"}}
               medium: {
{{/code}}

{{code language="none"}}
                    min: 4,
{{/code}}

{{code language="none"}}
                    max: 6
{{/code}}

{{code language="none"}}
               },
{{/code}}

{{code language="none"}}
               high: {
{{/code}}

{{code language="none"}}
                    min: 7,
{{/code}}

{{code language="none"}}
                    max: 9
{{/code}}

{{code language="none"}}
               },
{{/code}}

{{code language="none"}}
               critical: {
{{/code}}

{{code language="none"}}
                    min: 10
{{/code}}

{{code language="none"}}
               }
{{/code}}

{{code language="none"}}
                 }
{{/code}}
{{/info}}

 

 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*