操作模式

cfn-guard 有五种操作模式

验证

validate（如上例所示）验证数据与规则。

Usage: cfn-guard validate [OPTIONS] <--rules [<rules>...]|--payload>

Options:
  -r, --rules [<rules>...]
          Provide a rules file or a directory of rules files. Supports passing multiple values by using this option repeatedly.
          Example:
           --rules rule1.guard --rules ./rules-dir1 --rules rule2.guard
          For directory arguments such as `rules-dir1` above, scanning is only supported for files with following extensions: .guard, .ruleset
  -d, --data [<data>...]
          Provide a data file or directory of data files in JSON or YAML. Supports passing multiple values by using this option repeatedly.
          Example:
           --data template1.yaml --data ./data-dir1 --data template2.yaml
          For directory arguments such as `data-dir1` above, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template
  -i, --input-parameters [<input-parameters>...]
          Provide a data file or directory of data files in JSON or YAML that specifies any additional parameters to use along with data files to be used as a combined context. All the parameter files passed as input get merged and this combined context is again merged with each file passed as an argument for `data`. Due to this, every file is expected to contain mutually exclusive properties, without any overlap. Supports passing multiple values by using this option repeatedly.
          Example:
           --input-parameters param1.yaml --input-parameters ./param-dir1 --input-parameters param2.yaml
          For directory arguments such as `param-dir1` above, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template
  -t, --type <type>
          Specify the type of data file used for improved messaging - ex: CFNTemplate [possible values: CFNTemplate]
  -o, --output-format <output-format>
          Specify the format in which the output should be displayed [default: single-line-summary] [possible values: json, yaml, single-line-summary, junit, sarif]
  -S, --show-summary <show-summary>
          Controls if the summary table needs to be displayed. --show-summary fail (default) or --show-summary pass,fail (only show rules that did pass/fail) or --show-summary none (to turn it off) or --show-summary all (to show all the rules that pass, fail or skip) [default: fail] [possible values: none, all, pass, fail, skip]
  -s, --show-clause-failures
          Show clause failure along with summary
  -a, --alphabetical
          Validate files in a directory ordered alphabetically
  -m, --last-modified
          Validate files in a directory ordered by last modified times
  -v, --verbose
          Verbose logging
  -p, --print-json
          Print output in json format
  -P, --payload
          Provide rules and data in the following JSON format via STDIN,
          {"rules":["<rules 1>", "<rules 2>", ...], "data":["<data 1>", "<data 2>", ...]}, where,
          - "rules" takes a list of string version of rules files as its value and
          - "data" takes a list of string version of data files as it value.
          When --payload is specified --rules and --data cannot be specified.
  -z, --structured
          Print out a list of structured and valid JSON/YAML. This argument conflicts with the following arguments:
          verbose
           print-json
           show-summary: all/fail/pass/skip
          output-format: single-line-summary
  -h, --help
          Print help

规则生成

rulegen 接收一个 JSON 或 YAML 格式的 CloudFormation 模板文件，并自动生成一组与资源属性匹配的 cfn-guard 规则。这是一种从已知良好的模板开始编写规则或创建可立即使用的规则的有用方法。

cfn-guard-rulegen
Autogenerate rules from an existing JSON- or YAML- formatted data. (Currently works with only CloudFormation templates)

USAGE:
    cfn-guard rulegen [OPTIONS] --template <template>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -o, --output <output>        Write to output file
    -t, --template <template>    Provide path to a CloudFormation template file in JSON or YAML

例如，使用上述示例中的相同模板（template.json）

$ cfn-guard rulegen --template template.json
let aws_ec2_volume_resources = Resources.*[ Type == 'AWS::EC2::Volume' ]
rule aws_ec2_volume when %aws_ec2_volume_resources !empty {
    %aws_ec2_volume_resources.Properties.Size IN [500, 100]
    %aws_ec2_volume_resources.Properties.AvailabilityZone IN ["us-west-2b", "us-west-2c"]
    %aws_ec2_volume_resources.Properties.Encrypted == false
}

考虑到可能产生数百甚至数千条规则，我们建议使用 --output 标志将生成的规则写入文件

cfn-guard rulegen --template template.json --output rules.guard

解析树

parse-tree 命令用于生成规则文件中定义的规则解析树。使用 --output 标志将生成的树写入文件。

cfn-guard-parse-tree
Prints out the parse tree for the rules defined in the file.

Usage: cfn-guard parse-tree [OPTIONS]

Options:
  -r, --rules <rules>    Provide a rules file
  -o, --output <output>  Write to output file
  -p, --print-json       Print output in JSON format. Use -p going forward, as the short flag -j is on deprecation path.
  -y, --print-yaml       Print output in YAML format
  -h, --help             Print help

测试

使用 test 命令以 JSON 或 YAML 格式为您的规则编写单元测试。

cfn-guard-test
Built in unit testing capability to validate a Guard rules file against
unit tests specified in YAML format to determine each individual rule's success
or failure testing.

Usage: cfn-guard test [OPTIONS]

Options:
  -r, --rules-file <rules-file>  Provide a rules file
  -t, --test-data <test-data>    Provide a file or dir for data files in JSON or YAML
  -d, --dir <dir>                Provide the root directory for rules
  -a, --alphabetical             Sort alphabetically inside a directory
  -m, --last-modified            Sort by last modified times within a directory
  -v, --verbose                  Verbose logging
  -h, --help                     Print help
  -o, --output-format <output-format>
          Specify the format in which the output should be displayed [default: single-line-summary] [possible values: json, yaml, single-line-summary, junit]

例如，给定一个规则文件（rules.guard）如下：

rule assert_all_resources_have_non_empty_tags {
    when Resources.* !empty {
        Resources.*.Properties.Tags !empty
    }
}

您可以编写一个 YAML 格式的单元测试文件（test.yml），如下所示：

---
- input:
    Resources: {}
   expectations:
   rules:
     assert_all_resources_have_non_empty_tags: SKIP
- input:
  Resources:
    nonCompliant:
      Type: Consoto::Network::VPC
      Properties: {}
  expectations:
  rules:
    assert_all_resources_have_non_empty_tags: FAIL

然后，您可以使用 test 命令来测试您的规则文件，如下所示：

$ cfn-guard test -r rules.guard -t test.yml
PASS Expected Rule = assert_all_resources_have_non_empty_tags, Status = SKIP, Got Status = SKIP
PASS Expected Rule = assert_all_resources_have_non_empty_tags, Status = FAIL, Got Status = FAIL

自动补全

要设置自动补全，您需要遵循特定shell的说明。

目前 guard 只支持 zsh、bash 和 fish shell 的自动补全。如果您希望特定 shell 有自动补全功能，请随时在 GitHub 上提交一个新的 issue。

自动补全仅适用于版本 >= 3.0

zsh

    cfn-guard completions --shell='zsh' > /usr/local/share/zsh/site-functions/_cfn-guard && compinit

bash

    cfn-guard completions --shell='bash' > ~/cfn-guard.bash && source ~/cfn-guard.bash

fish

    cfn-guard completions --shell='fish' > ~/cfn-guard.fish
    cd ~
    ./ ./cfn-guard.fish

注意：对于 bash 和 fish shell，您可以将补全脚本输出到任何位置的任何文件，只需确保输出的文件和源文件相同。对于 bash shell，如果您不想每次打开新终端时都这样做，一旦您有了脚本，可以将 source ~/cfn-guard.bash 添加到您的 .bashrc。