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.

TypeDescriptionExample
Boolean A binary value: TRUE/FALSE in uppercaseTRUE
IntegerA numeric literal without a decimal point1,2,45
DecimalA numeric literal with a decimal point11.23,2.34,45.00
StringAny string literal enclosed in double quotes"GitHub", "Wiki"
JSON pathA string literal that matches a regular expression "^\$([\w]+)(..?)(.(?:(?:min|max|avg|count)()))?$""$feed" , $feed.lastUpdated , $feed.store.books[*].price.min()
JSON objectsA 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. 
ListA comma-separated list of any of the preceding types enclosed in square braces[1,2,3] , ["NodeJS" , "Rocks"]
RangeA 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.
 
RegExIn-progress 
DateIn-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:

OperatorCardinalityUsageApplicable types
assign2LHS 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.
equals2equals or = , LHS = "GitHub" or LHS equals "GitHub"Any simple type (String, Boolean, Integer, Decimal)
does not equal2does not equal or != , LHS != "GitHub" or LHS does not equal "GitHub"Any simple type (String, Boolean, Integer, Decimal)
starts with2LHS starts with "Git"LHS and RHS must be of String type
is substring of2LHS is substring of "GitHub rocks"LHS and RHS must be of String type
is not substring of2LHS is not substring of "GitHub rocks"LHS and RHS must be of String type
ends with2LHS ends with "rocks"LHS and RHS must be of String type
does not end with2LHS does not end with "rocks"LHS and RHS must be of String tye
is one of2LHS 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 of2LHS 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
contains2LHS contains "GitHubLHS must be a List of any simple type (String, Boolean, Integer, Decimal) and RHS must be any simple type
does not contain2LHS 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)2LHS equals (case sensitive) "GitHub"LHS and RHS mst be of String type
does not equal (case sensitive)2LHS does not equal (case sensitive) "GitHub"LHS and RHS must be of String type
is substring of (case sensitive)2LHS is substring of (case sensitive) "GitHub"LHS and RHS must be of String type
is not substring of (case sensitive)2LHS is not substring of (case sensitive) "GitHub"LHS and RHS must be of String type
contains (case sensitive)2LHS contains (case sensitive) "GitHub"LHS must be a list of String type and RHS must be of String type
does not contain (case sensitive)2LHS 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)2LHS starts with (case sensitive) "GitHub"LHS and RHS must be of String type
does not start with (case sensitive)2LHS does not start with (case sensitive) "GitHub"LHS and RHS must be of String type
ends with (case sensitive)2LHS ends with (case sensitive) "GitHub"LHS and RHS must be of String type
does not end with (case sensitive)2LHS does not end with (case sensitive) "GitHub"LHS and RHS must be of String type
is one of (case sensitive)2LHS 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)2LHS 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)2LHS 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)2LHS 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 than2LHS less than 5 or LHS < 5LHS and RHS must be of Integer or Decimal type
greater than2LHS greater than 5 or LHS > 5LHS and RHS must be of type Integer or Decimal type
less than or equal to2LHS less than or equal to 5 or LHS <= 5LHS and RHS must be of Integer or Decimal type
greater than or equal to2LHS greater than or equal to to 5 or LHS <= 5LHS and RHS must be of Integer or Decimal type
between2LHS between [ 5 AND 10] , A range must have 'AND' as capsLHS must be of Integer or Decimal type and RHS must be of Range type (the same type same as LHS)
NOT1NOT (expression) Eg, NOT (LHS between [ 5 AND 10]) , This operator inverts the evaluation result of an expression(RHS)RHS must be expression
ANDN/*expression AND expression Eg, LHS between [ 5 AND 10] AND LHS = "GitHub", This operator performs logical AND-ING of results of child expressionsAny expression
ORN/*expression OR expression Eg, LHS between [ 5 AND 10] OR LHS = "GitHub", This operator performs logical OR-ING of results of child expressionsAny 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-characterMeaningRequired
\$

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-characterMeaning
\wMatch 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-characterMeaning
\.*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-characterMeaning
\.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 expressionEvaluation
$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 functionDescription
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.

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:

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.

--- 
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')]" 

{

  "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 TypeSpec AttributeDescriptionRequired
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.

originSpec 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 originSpecresourceSpec 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


--- 
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

               }

                 }

Was this page helpful? Yes No Submitting... Thank you

Comments