TABLE OF CONTENTS

Overview

Aqua Bench custom compliance checks allow static validation of files or text content within a container image. Aqua Bench custom compliance scripts (compliance checks) are customizable pieces of code in the form of YAML files, supporting a syntax similar to that of the Linux find and grep commands. The scripts must be saved with file type .ab. Aqua Bench is supported in direct scanning mode only.


This topic describes the Aqua Bench script syntax. It is recommended that you view the predefined Aqua Bench scripts at the Policies > Assurance Policies > Compliance Checks page as explained in the Custom Compliance Checks for Image Assurance Policies document.


High-level structure

Following is the high-level structure of an Aqua Bench script file:

description: "< your description >"
groups:
  - id: 1
    checks:
      - id: 1.1
        [ Filesearch or Textsearch syntax ]
      - id: 1.2
      ...
  - id: 2
    ...
  ...
  - id: N        


The first two rows of the script file should have the following parameters:

  • description: followed by free text
  • groups: the first two rows are followed by a two-level structure. The outer level contains one or more groups of rows that start with:
  • id: followed by a first-level sequence number (n)
  • checks: the inner level contains one or more groups of rows under this.
    • The first row is - id: followed by a second-level sequence number (n.m).
    • The innermost loop (id:n.m) should have a specific check in one of the following formats, as explained below:
      • Filesearch: tests for the existence (or absence) of certain files in an image, based on the file name
      • Textsearch: tests for the existence (or absence) of certain text strings within files in an image


Overall evaluation of custom compliance

The structure described above allows for the definition of multiple specific checks, each related to the existence (or absence) of files or text within an image. The Custom Compliance Checks control will pass only if every single check in the script passes. If any of he checks fail, the control will fail the image compliance.


For simplicity, flexibility, and legibility, it is recommended to keep the number of checks within any given Aqua Bench script to as minimum as possible. Note that the Custom Compliance Checks control can include multiple Aqua Bench scripts.


Filesearch

Script overview

The script under the innermost loop row id n.m is of the format shown in the following text box. The script has the following two major sections:

  • audit: This section of a filesearch test specifies the search criteria.
  • tests: section defines the format of the search output, and instructs the filesearch test how to process the output, which is a list of all files that correspond to the search criteria specified. There are two levels under the tests section.

Passing rows that are not mandatory always, are marked as optional for audit and tests sections, in the row description tables below.


Following is the sample script for Aqua Bench - filesearch type, having all of the rows that can be passed:


        audittype: "filesearch"
        audit:
          path: "/"
          fileType: [ "file" | "directory" | "symblink" ]
          searchTerm: "< search term >"
          searchType: [ "exact" | "contains" | "hasPrefix" | "hasSuffix" ]
          perm: "nnn"
          groupId: "nnn"
          userId: "nnn"
        tests:
          test_items:
             - compare:
                 count: [ false | true ]
                 op: [ "eq" | "noteq" | "gt" | "gte" ]
                 value: "< comparison value >"
               set: [ true | false ]
        remediation: "< specify the action to remediate if specified is found >"
        scored: [ true | false ]


Audit section

Following table explains the description to each row that can be passed in the audit section. Some of the rows are marked as optional to mark that passing them is not mandatory always.


Row starting withDescription
audittype: "filesearch"Include this row in the script, exactly as shown in the first column
audit:Include this row in the script, exactly as shown in the first column
path:Specifies, within double quotes, where to perform the file search. It is always within the image
fileType: it defaults to "file" and is optionalChoose one of the following options that you can pass in this row. Values must be in the double quotes.
  • "file": to search for files only
  • "directory": to search for directories only
  • "symblink": to search for symbolic links only
searchTerm:specify the character string within double quotes, to search for within the file names (under the path directory)
searchType:Choose one of these options that you can pass in this row. Values must be in the double quotes.
  • "exact": the file name and the search term are exactly the same
  • "contains": the file name contains the search term
  • "hasPrefix": the file name begins with the search term
  • "hasSuffix": the file name ends with the search term
perm: (optional and for Linux only)

Search only for files with the permissions specified.
Example: perm: "777"

groupId: (optional and for Linux only)Search only for files that belong to the GID specified.
Example: groupId: "2001"
userId: (optional and for Linux only)Search only for files that belong to the UID specified.
Example: userId: "1001"


Tests section

Following table explains the description to each row that can be passed in the tests section. Some of the rows are marked as optional to mark that passing them is not mandatory always.


Row starting withDescription
tests:Include this row in the script, exactly as shown in the first column
test_items:Include this row in the script, exactly as shown in the first column
- compare:Include this row in the script, exactly as shown in the first column
count: (optional and defaults to false)Defines the output format. Passing quotes is not required for this row.
  • false: a list of all files corresponding to the search criteria
  • true: the number of search hits (files corresponding to the search criteria)
op:Specifies the type of operation that compares the output to the value (next parameter). Choose one of these options, including the double quotes:
  • "eq": the output is equal to the value
  • "noteq": the output and value are not equal
  • "gt": the output is greater than the value
  • "gte": the output is greater than or equal to the value
value:

Specifies the value for the comparison describe above

set: (optional and defaults to true)Specify false (without quotes) to disable running this test


Other sections

Following table explains description to the row, scored. Passing this row is optional.


Row starting with
Description
remediation: (optional)specifies the action to remediate/heal/remove the vulnerability, which is found during validation of files / text content within a container image.
scored: (optional and defaults to true)Specify false (without quotes) to disable running this test


Textsearch

Following is the sample script for Aqua Bench - textsearch type, having all of the rows that can be passed:


        audittype: "textsearch"
        audit:
          path: "/"
          fileType: [ "file" | "directory" | "symblink" ]
          searchTerm: "< search term >"
          searchType: [ "exact" | "contains" | "hasPrefix" | "hasSuffix" ]
          perm: "nnn"
          groupId: "nnn"
          userId: "nnn"
        tests:
          test_items:
             - compare:
                 count: [ false | true ]
                 op: [ "eq" | "noteq" | "gt" | "gte" ]
                 value: "< comparison value >"
               set: [ true | false ]
        remediation: "< specify the action to remediate if specified is found >"
        scored: [ true | false ]


Its syntax and semantics are the same as that in the filesearch script, having the following differences:

  • The first row includes the value textsearch instead of filesearch
  • The search term is a character string that will be looked for within the file(s) specified, not within the names of the files
  • Output is as follows in textsearch:
    • When count: false, the number of search hits (files corresponding to the search criteria)
    • When count: true, the list of all lines in the file(s) that correspond to the search criteria


Example: check_netcat_installed_image.ab

This script is predefined in Aqua. It searches for all files (filesearch) in the root directory whose names are exactly "nc". Since count is false, the script compares the list of files corresponding to the search criteria (which means, the list of files named "nc") with the null string. If the test fails (meaning there is at least one file named "nc"), the test and Custom Compliance Checks control will fail. 


description: "This test looks for netcat 'nc' executable and fails if it is found"
groups:
  - id: 1
    checks:
      - id: 1.1
        audittype: "filesearch"
        audit:
          path: "/"
          searchTerm: "nc"
          searchType: "exact"
        tests:
          test_items:
             - compare:
                 op: "eq"
                 value: ""
               set: true
        remediation: "Uninstall netcat"
        scored: true