Syntax Rules and Policy Check Examples

The validation engine of Configuration and Security Analytics is running directly on SAP HANA database level. It is basically using HANA SQL as described in the SAP HANA SQL and System Views Reference. However, not all features are supported. The actual SQL used for validations is generated automatically based on the XML coding of a policy.

This page provides an overview on syntax rules, common check types and useful best practices for creating policy content.

Policy Structure

Policies are written in an xml format. Out of this the SQL coding for the validation is created automatically when the policy is generated. This section provides an overview on the syntax elements that are required in every policy.

Each policy starts with an element containing the attributes related to the used xml version and encoding. When creating a new policy, this element is created automatically. It must not be changed.

<?xml version="1.0" encoding="utf-8"?>

All other elements of a policy are opened and closed. Elements are specified in <>. The closing element starts with </.

<targetsystem> </targetsystem>

A policy must contain at least the following elements:

                                       <targetsystem>

                                              <configstore> 

                                                     <checkitem>
                                                       <compliant>
                                                       </compliant>
                                                       <noncompliant>
                                                        </noncompliant>
                                                 </checkitem>

                                                  </configstore>

                                          </targetsystem>

Some of these mandatory elements do not necessarily need to contain content, e.g the noncompliant rule can remain empty in some cases. In this case the syntax can be shortened:

<noncompliant/>      instead of:      <noncompliant> </noncompliant>

In addition the following elements can be used:

                                           <complianttext> <complianttext/>

                                          <noncomplianttext> <noncomplianttext/>

                                          <joinstore> <joinstore/>

                                          <joincomplianttext> </joincomplianttext>

                                          <joinnoncomplianttext> </joinnoncomplianttext>

You can also add comments to the policy:

                                          <!--        -->

While you can learn many syntax elements by starting your work directly with the use of policies published on the SAP Github, additional documentation may be useful in some cases. Each of the elements given above may contain additional attributes. These are explained on the next sections of this page. After this we provide documentation on typical syntax for check items. At the end we will provide syntax examples from the perspective of typical validation needs (driven by semantics rather than by language).

Create your first policy

This section gives you an example of a simple policy and of basic rules and good practices.Each check contains at least a checkitem description and check id as well as a compliant rule. The following is an example of a very simple check. 

 

Rule example: Password length is compliant if the parameter value is greater equal 8

    <configstore name="ABAP_INSTANCE_PAHI">

       <checkitem desc="First item check " id="1.0.0.0">     
            <compliant>name= 'login/min_password_lng' and value&gt;= 8</compliant>
            <noncompliant>name= 'login/min_password_lng' and not ( value &gt;= 8 )</noncompliant>
      </checkitem>

   </configstore>

 

Note:

  • The correct configstore name must be specified before the first check. Config store name and structure and check content must fit together (bold characters).
  • Names must be put in single quotes, values without quotes are numbers
  • SQL syntax (italic characters) is applied (some syntax like <  > needs be to escaped for XML: &lt; &gt;)
  • Checkitem description should be meaningful. Some customers choose a description that indicates a check group (e.g. "password policy") and the specific check (e.g. "login/min_password_lng")
  • Check id usually corresponds with the id of the specific rule in the hardening guide. The check id must be unique in a policy. 
  • Multiple checks can refer to the same configstore. The group of checks is closed with </configstore>
  • Explicit definition of a noncompliant rule is recommended. This helps to minimize the occurrence of no data found results.
  • You can add additional columns of the configstore to your rule, even when they are not relevant for the validation result. Syntax is like column='%' where % indicates that any value or null value is allowed. 
  • The validation UI shows columns in the order that is specified in the check


The following is an example of a HANA parameter check:

    <configstore name="HDB_PARAMETER">

       <checkitem desc="1.1. sslCryptoProvider" id="001">
            <compliant>FILE_NAME = 'global.ini' and SECT = 'communication' and NAME = 'sslcryptoprovider' and 
                   VALUE = 'commoncrypto' and LAYER like '%' and HOST like '%' and TENANT like '%' </compliant>               
            <noncompliant>FILE_NAME = 'global.ini' and SECT = 'communication' and NAME = 'sslcryptoprovider' and  
                   NOT VALUE = 'commoncrypto' and LAYER like '%' and HOST like '%' and TENANT like '%' </noncompliant>

       </checkitem>

       <checkitem desc="1.1. sslMinProtocolVersion" id="002">
            <compliant>FILE_NAME = 'global.ini' and SECT = 'communication' and NAME = 'sslminprotocolversion' and
                     VALUE = 'TLS12' and LAYER like '%' and HOST like '%' and TENANT like '%' </compliant>
            <noncompliant>FILE_NAME = 'global.ini' and SECT = 'communication' and NAME = 'sslminprotocolversion' and
                    NOT VALUE = 'TLS12' and LAYER like '%' and HOST like '%' and TENANT like '%' </noncompliant>
       </checkitem>

    </configstore>

Figure 1: Validation Result of 2 check examples

Basic Syntax

Compliant or non-compliant rules are defined as a subset of SQL WHERE clause. The following syntax could be used:

Note:

  • You cannot use sub-queries. 
  • You cannot use SQL comments -- or /* */

The following section gives you examples for the use of basic syntax elements. Focus is on checking simple numerical values. 

EQUAL (EQ)

   <checkitem desc="3.1.1.1 System configuration (profile parameters)" id="001">
      <compliant>NAME = 'login/failed_user_auto_unlock' and VALUE = '0'</compliant>
      <noncompliant>NAME = 'login/failed_user_auto_unlock' and NOT VALUE = '0' </noncompliant>
    </checkitem>

 

    <checkitem desc="3.1.1.5. Logging (profile parameters)" id="002">
       <compliant>NAME = 'rec/client' and VALUE = 'ALL' </compliant> 
        <noncompliant>NAME = 'rec/client' and NOT ( VALUE = 'ALL' ) </noncompliant>
    </checkitem>

 

GREATER (GT)

       <checkitem desc="3.1.1.1. login/min_password_lng" id="003">   
            <compliant>name= 'login/min_password_lng' and value&gt; 8</compliant>
            <noncompliant>name= 'login/min_password_lng' and not ( value &gt; 8 )</noncompliant>
      </checkitem>

 

LOWER (LT)

       <checkitem desc="3.1.1.1. login/password_max_idle_initial" id="004">   
            <compliant>name= 'login/password_max_idle_initial' and value &lt; 14</compliant>
            <noncompliant>name= 'login/password_max_idle_initial' and not ( value &lt; 8 )</noncompliant>
      </checkitem>

 

GREATER EQUAL (GE)

    <checkitem desc="System configuration (profile parameters)" id="005">
        <compliant>NAME = 'login/min_password_digits' and VALUE &gt;= 1 </compliant>
        <noncompliant>NAME = 'login/min_password_digits' and NOT (VALUE &gt;= 1) </noncompliant>
    </checkitem>

 

Lower Equal (LE)

       <checkitem desc="3.1.1.1. login/password_max_idle_initial" id="006">   
            <compliant>name= 'login/password_max_idle_initial' and value&lt;= 14</compliant>
            <noncompliant>name= 'login/password_max_idle_initial' and not ( value &lt;= 8 )</noncompliant>
      </checkitem>

 

NOT EQUAL (NE)

     <checkitem desc="3.2.3. DDIC is LOCKED" id="007">
        <compliant>CLIENT like '%' and USERNAME = 'DDIC'  and ( LOCKED  = 'X' or EXISTING &lt;&gt; 'X'  )
                   </compliant>
        <noncompliant>CLIENT  like '%'  and USERNAME = 'DDIC'  and not ( LOCKED  = 'X' or EXISTING &lt;&gt; 'X' )
                  </noncompliant>
    </checkitem>

length(VALUE)

     <checkitem desc="3.2.3. mandatory System Replication" id="008">
        <compliant>FILE_NAME= 'global.ini' and LAYER like '%' and HOST like '%' and TENANT like '%' and 
              SECT = 'system_replication' and NAME = 'site_id' and length(VALUE) gt; '0' </compliant>
        <noncompliant>FILE_NAME = 'global.ini' and LAYER like '%' and HOST like '%' and TENANT like '%' and 
            SECT = 'system_replication' and NAME = 'site_id' and not length(VALUE) gt; '0' </noncompliant>
    </checkitem>

BETWEEN

    <checkitem desc="System configuration (profile parameters)" id="009">
        <compliant>NAME = 'login/fails_to_session_end' and VALUE between 1 and 3 </compliant>
        <noncompliant>NAME = 'login/fails_to_session_end' and NOT (VALUE between 1 and 3) </noncompliant>
    </checkitem>

Advanced Syntax

This section demonstrates some use cases of advanced syntax elements.

Use of Standard LMDB attributes in checkitem description

    <checkitem desc="System configuration (profile parameters) - secret" id="00015" system_roles="PROD">
      <compliant>NAME = 'login/password_max_idle_productive' and VALUE between 1 and 90 </compliant>
      <noncompliant>NAME = 'login/password_max_idle_productive' and NOT (VALUE between 1 and 90) </noncompliant>
    </checkitem>

Targetsystem attributes

Each policy contains exactly one element targetsystem. Tag <targetsystem> is placed in the line directly after the specification of xml version and encoding. Tag </targetsystem> is the corresponding closing bracket. It is placed at the end of the policy.

Attribute "desc" contains the targetsystem description. Each policy must contain exactly one targetsystem description. 

Attribute "id" contains the target system definition Id. Each policy must contain exactly one target system id.

Configstore attributes

Each policy contains at least one configstore.  It is mandatory to specify the name of the config store through the attribute name. All other attributes to this element are optional and only used in exceptional cases.

Tags <configstore>  and </configstore> are the opening and closing bracket for a configstore.

Attribute "name" specifies the technical name of the config store. The attribute is mandatory.

Syntax example: <configstore name = "COMP_LEVEL">

Attribute "name_extended" can be used as further attribute  in case the technical name of a config store is not unique (optional). 
Possible values of attribute "name_extended" can be identified with view CCDB_DIRV.

The attribute "sci_id" must be used in case the technical name of a config_store is not unique (mandatory). 

Attribute "system_type" can be set additional to restrict the system type (e.g. dir.system="JAVA"). This may only be necessary if the same config store is used cross several system types (currently the case for COMP_LEVEL which contains the software components for ABAP and JAVA systems) (optional).

Joinstore attributes

In addition to the attributes of element configstore you can use the following attributes for joinstores. When building a join condition for a check item, the element joinstore allows to implement a join against configuration items from any config store.

Tags <joinstore>  and </joinstore> are the opening and closing bracket for a check.

The elements <joincompliant> and <joinnoncompliant> work the same way as <compliant> and <noncompliant> for a simple check item. They contain the technical rules that the configuration item is checked against.

The elements <joincomplianttext> and <joinnoncomplianttext> work the same way as the elements <complianttext> and <noncomplianttext> for a simple check item. They are used to replace the technical rule with a text describing the rule elements. If used those texts replace the SQL rules in the corresponding fields of the UI (optional).

Attribute "minus" applies only to element "joinstore". It controls the way the non-compliant join is transferred into SQL:

  • Yes: minuend – subtrahend = difference
  • No: non-compliant rule needs to fully specified
    (optional)

Attribute "no_data_found" helps to handle join conditions that do not apply to any configuration item.

The standard behaviour of the validation is that each check generates an SQL statement which returns the status “item not found” in case both statements for the compliant and non-compliant check do not return any results for a system. However, in some cases one of the join statements introduces a validity constraint. In such a case, it is possible to add this validity constraint also to the SQL statement checking “item not found”.

no_data_found="Yes"

Best Practice:

  • If neither the "compliant rule" nor the "noncompliantrule" of a check applies, the operator  no_data_found="Yes" suppresses this check item from the result of a validation run. 
  • If a "data not found" result is expected, you may use the no_data_found="Yes" operator for checking for a compliant setting and combine this with an additional rule for checking if a value exists at all (create another check item using the "EXIST" operator).
  • In current releases (including FRUN 2.0 FP2) this can be useful for avoiding multiple "data not found" records that differ only by the check item description. 

Example 1:

Value of HANA parameter: FILE_NAME = 'global.ini', SECT = 'parallel', and NAME = 'num_cores' should be checked, however, only for HANA systems running a version between 12202 and 12206. To avoid “item not found” results for HANA systems running on a version not between 12202 and 12206 it is necessary to add an attribute to this join to mark it to be used also in the “item not found”-SQL to include only those which are running the correct HANA version (optional).

Use of no_data_found="Yes" operator (Note: The operator can be applied in a join condition or in a check item)

Output of a "data not found" record when no_data_found="Yes" is not set.  

In some cases the columns of the joined config store needs to be suppressed to avoid getting multiple tuples of the join result. This behaviour can be achieved with attribute "not_in_output".

Supported as of FRUN 2.00 SP00 

Checkitem Attributes

Checkitems are the element that contain the actual validation rules for determining compliance and noncompliance of a configuration. A policy can contain multiple checkitems. Checkitems should be grouped by config store. Tags <checkitem>  and </checkitem> are the opening and closing bracket for a check.

Various attributes can be used to control the behaviour of check items in a validation run. This section provides details and some examples.

Attribute "desc" contains a description of the check item. Between " " you can enter any content that helps understanding the meaning of the check.

Attribute "id" contains the check Id of the check item. In most cases it will refer to an identifier that is used in your hardening guide or security procedure.

It is not required to have a numeric id. You can also use characters or special characters.

"store_attribute" allows to restrict the check item to specific records in a Config Store. The original use case for store_attribute was to limit a check item to a specific client, e.g.: "CLIENT:001"

Syntax Example: store_attribute="CLIENT:001"

not_found="negative"

Attribute "not_found"  controls the compliance status of check item in case its rules does not select any config item. 

Effect:

  • If neither the "compliant rule" nor the "noncompliantrule" of a check applies to the selected scope, then the default behaviour of CSA is to rate the check non-compliant and display a record "item = no data found" for this check id.
  • The operator not_found="negative" corresponds to the default behaviour and is not required.

not_found="positive"

Effect:

  • If neither the "compliant rule" nor the "noncompliantrule" of a check applies, the operator no_data_found="positive" turns the validation result into compliant. A "item = no data found" record is displayed in the CSA validation result.

Use of the not_found="positive" operator for a check item

With not_found="positive" a check item is rated compliant when not matching to compliant/noncompliant rules (default: "negative")

The attribute "operator" allows to apply certain predefined operators to the check item. One example are the operators "EXIST" and "NOT_EXIST".

Effect:

  • Checks if a certain configuration item exists at all.
  • Instead of "not found" you get configuration item details, value and rule displayed in the validation result.

For checking obsolete or forbidden parameters you can use the operator "NOT_EXIST"

Note: " Operators "EXIST and "NOT_EXIST" do not support joins.

Syntax for using the "EXIST" operator

Validation output with the "EXIST" operator

The attribute "operator" allows to apply certain predefined operators to the check item.

For ABAP notes checks the "operator" attribute can be set to “check_note” or “check_note:<10 digits note number>”.

  • Operator=”check_note” suppressed the SQL generation of “item note found”. It can be used to suppress item not found for config store ABAP_NOTES. 
  • Operator=”check_note:<10 digits note number>” can be used together with config store COMP_LEVEL to suppress the result in case the note which is checked is already implemented (optional).

Attribute "system_roles" can be used to pin the check item to a specific system role (or IT admin roles).

  • Different values can be concatenated using “:” like system_roles="PROD:QA".
  • Possible values are:

Attribute system_attributes can be used to pin the check item to a specific system attribute.

  • Different values can be concatenated using “;” like system_attributes="DB_TENANT:TRUE;DB_VIRTUAL:FALSE". 
  • The values are the technical values of table COF_RT_TREE_P e.g. where NAME = DB_TENANT. 
  • Not mandatory, if not used in check_items no join with table COF_RT_TREE_P is generated into the policy-SQL (optional).
    In case the of custom landscape attributes (those are stored starting with _LA_) no hierarchy is used.

FAQ

The FAQ section is currently empty.