Add support for suppression criteria (#25)

Adding support for custom `.codeguru-ignore.yml` with different criteria to suppress recommendations.

Author: martinschaef

.codeguru-ignore.yml

@@ -0,0 +1,11 @@
+version: 1.0
+
+ExcludeById:
+  - 'security-764ea718423ce472134805f16e2616a36c3636fab21927453102041'
+
+ExcludeTags:
+  - 'maintainability'
+
+excludeFiles:
+  - "tst/**"
+  - "test-data/**"

.github/workflows/cicd-demo.yml

@@ -0,0 +1,51 @@
+name: Demo of how to use a CodeGuru Reviewer CLI release in CICD.
+
+on: [ push, pull_request, workflow_dispatch ]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  RunDemo:
+    name: Run CodeGuru Reviewer CLI in CICD
+    runs-on: ubuntu-latest
+    steps:
+      # Setup Java 8 or higher.
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+
+      # To configure this role, use this CDK example:
+      # https://github.com/aws-samples/aws-codeguru-reviewer-cicd-cdk-sample
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        continue-on-error: true
+        id: iam-role
+        with:
+          role-to-assume: arn:aws:iam::048169001733:role/GuruGitHubCICDRole
+          aws-region: us-west-2
+
+      # Only continue if fetching the AWS credentials was successful.
+      - uses: actions/checkout@v2
+        if: steps.iam-role.outcome == 'success'
+        with:
+          fetch-depth: 0 # the fetch depth needs to be provided if we only want to check a certain commit range.
+      - name: Build project
+        if: steps.iam-role.outcome == 'success'
+        run: ./gradlew clean installDist
+
+      # Download a release of the CodeGuru Reviewer CLI.
+      - name: Download CodeGuru Reviewer CLI
+        shell: bash
+        env:
+          VERSION: 0.1.0
+        run: curl -OL "https://github.com/martinschaef/aws-codeguru-cli/releases/download/$VERSION/aws-codeguru-cli.zip"
+      - run: unzip aws-codeguru-cli.zip
+
+       # Run CodeGuru Reviewer on the current project and use the --fail-on-recommendations option to fail
+       # if any recommendations are reported.
+      - name: Run Code Guru
+        if: steps.iam-role.outcome == 'success'
+        run: ./aws-codeguru-cli/bin/aws-codeguru-cli --region us-west-2 -r ./ -s ./src/main/java -b ./build/classes/java/main -c "${{ github.event.before }}:${{ github.event.after }}" --no-prompt  --fail-on-recommendations

.github/workflows/guru-reviewer.yml

@@ -1,11 +1,11 @@
-# Created using https://github.com/aws-samples/aws-codeguru-reviewer-cicd-cdk-sample
+
 name: Self-test and release
 
 on: [push, pull_request, workflow_dispatch]
 
 permissions:
     id-token: write
-    contents: read
+    contents: write # write permissions are needed to upload the release
 
 jobs:
   SelfTestPython:
@@ -141,7 +141,7 @@ jobs:
         if: steps.iam-role.outcome == 'success'
         shell: bash
         env:
-          EXPECTED: 15
+          EXPECTED: 16
         run: |
           [[ $(jq -r '.runs[0].results[].ruleId' code-guru/recommendations.sarif.json | wc -l) -eq $EXPECTED ]] || { echo "Expected $EXPECTED recommendations but got $(jq -r '.runs[0].results[].ruleId' code-guru/recommendations.sarif.json | wc -l)"; exit 1; }
 
@@ -187,12 +187,10 @@ jobs:
         run: ./gradlew clean installDist distZip
 
       - name: Get Release Version
-        run: |
-          echo "::set-output name=TAG_NAME::$(./gradlew properties -q | grep "version:" | awk '{print $2}')"
+        run: echo "::set-output name=TAG_NAME::$(./gradlew properties -q | grep "version:" | awk '{print $2}')"
         id: version
 
       - name: Release
-        if: steps.iam-role.outcome == 'success'
         uses: softprops/action-gh-release@v1
         with:
           tag_name: ${{ steps.version.outputs.TAG_NAME }}

.github/workflows/self-test-and-release.yml

@@ -1,12 +1,24 @@
 # CodeGuru Reviewer CLI Wrapper
 Simple CLI wrapper for CodeGuru reviewer that provides a one-line command to scan a local clone of a repository and
-receive results. This CLI wraps the [AWS CLI](https://aws.amazon.com/cli/) commands to communicated with 
+receive results. This CLI wraps the [AWS CLI](https://aws.amazon.com/cli/) commands to communicate with 
 [AWS CodeGuru Reviewer](https://aws.amazon.com/codeguru/). Using CodeGuru Reviewer may generate metering fees
 in your AWS account. See the [CodeGuru Reviewer pricing](https://aws.amazon.com/codeguru/pricing/) for details.
 
+### Table of Contents
+- [Installation](#installation)
+- [Using the CLI](#using-the-cli)
+- [Suppressing Recommendations](#suppressing-recommendations)
+- [Running from CI/CD](#running-from-cicd)
+- [Security](#security)
+- [License](#license)
+
+## Installation
+
 ### Prerequisites
 
-To run the CLI, we need to have a version of git, Java (e.g., [Amazon Corretto](https://aws.amazon.com/corretto/?filtered-posts.sort-by=item.additionalFields.createdDate&filtered-posts.sort-order=desc)) and the [AWS Command Line interface](https://aws.amazon.com/cli/) installed. Verify that both application are installed on our machine by running:
+To run the CLI, we need to have a version of git, Java (e.g., [Amazon Corretto](https://aws.amazon.com/corretto/?filtered-posts.sort-by=item.additionalFields.createdDate&filtered-posts.sort-order=desc)) 
+and the [AWS Command Line interface](https://aws.amazon.com/cli/) installed. 
+Verify that both applications are installed on our machine by running:
 
 ```
 java -version
@@ -15,8 +27,11 @@ aws --version
 git --version
 ```
 
-We will also need working credentials on our machine to interact with our AWS account. Learn more about setting up credentials for AWS here: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html. 
-The credentials must have at least the following permissions:
+We will also need working credentials on our machine to interact with our AWS account. 
+Learn more about setting up credentials for AWS here: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html.
+
+You can always use the CLI with *Admin* credentials but if you want to have a specific role to use the CLI, your
+ credentials must have at least the following permissions:
 
 ```json
 {
@@ -55,17 +70,21 @@ The credentials must have at least the following permissions:
 ```
 
 
-### Download the CLI and scan an Example
+## Using the CLI
 
 You can download the [aws-codeguru-cli](https://github.com/aws/aws-codeguru-cli/releases/latest) from the releases section.
 Download the latest version and add it to your `PATH`:
 ```
-curl -OL https://github.com/aws/aws-codeguru-cli/releases/download/0.0.1/aws-codeguru-cli.zip
+curl -OL https://github.com/aws/aws-codeguru-cli/releases/download/0.1.0/aws-codeguru-cli.zip
 unzip aws-codeguru-cli.zip
 export PATH=$PATH:./aws-codeguru-cli/bin
 ```
 
-Now, lets download an example project (requires Maven):
+
+
+### Scan an Example
+
+Now, let's download an example project (requires Maven):
 ```
 git clone https://github.com/aws-samples/amazon-codeguru-reviewer-sample-app
 cd amazon-codeguru-reviewer-sample-app
@@ -129,19 +148,71 @@ from not using a key to using a key, you need to delete the existing association
 then trigger a new scan with the CLI where you provide the key.
 
 
-### Running from CI/CD
+## Suppressing Recommendations
+
+The CodeGuru Reviewer CLI searches for a file named `.codeguru-ignore.yml` where users can specify criteria
+based on which recommendations should be suppressed. Suppressed recommendations will not be returned by the CLI,
+but still show up in the AWS console.
+
+The `.codeguru-ignore.yml` file can use any of the filter criteria shown below:
+
+```yaml
+version: 1.0  # The Version field is mandatory. All other fields are optional. 
+
+# The CodeGuru Reviewer CLI produces a recommendations.json file which contains deterministic IDs for each
+# recommendation. This ID can be excluded so that this recommendation will not be reported in future runs of the
+# CLI.
+ExcludeById:
+- '4d2c43618a2dac129818bef77093730e84a4e139eef3f0166334657503ecd88d'
 
-You can use this CLI to run CodeGuru from inside your CI/CD pipeline. See [this action](.github/workflows/self-test-and-release.yml#L30-L41) as an example. First, you need credentials for a role with the permissions mentioned above. If you already scanned
-the repository once with the CLI, the S3 bucket has been created, and the you do not need the `s3:CreateBucket*` permission anymore.
+# We can tell the CLI to exclude all recommendations below a certain severity. This can be useful in CI/CD integration.
+ExcludeBelowSeverity: 'HIGH'
 
-Then you can run the CLI in non-interactive mode using the `--no-prompt` option. Further, you can specify a region and 
-AWS profile using the `--region` and `--profile` options as needed:
+# We can exclude all recommendations that have a certain tag. Available Tags can be found here:
+# https://docs.aws.amazon.com/codeguru/detector-library/java/tags/
+# https://docs.aws.amazon.com/codeguru/detector-library/python/tags/
+ExcludeTags:
+  - 'maintainability'
+
+# We can also exclude recommendations by Detector ID. Detector IDs can be found here:
+# https://docs.aws.amazon.com/codeguru/detector-library
+ExcludeRecommendations:
+# Ignore all recommendations for a given Detector ID 
+  - detectorId: 'java/[email protected]'
+# Ignore all recommendations for a given Detector ID in a provided set of locations.
+# Locations can be written as Unix GLOB expressions using wildcard symbols.
+  - detectorId: 'java/[email protected]'
+    Locations:
+      - 'src/main/java/com/folder01/*.java'
+
+# Excludes all recommendations in the provided files. Files can be provided as Unix GLOB expressions.
+ExcludeFiles:
+  - tst/**
+
+```
+
+Only the `version` field is mandatory in the `.codeguru-ignore.yml` file. All other entries are optional, and
+the CLI will understand any combination of those entries.
+
+An example of such a configuration file can be found [here](https://github.com/aws/aws-codeguru-cli/blob/main/.codeguru-ignore.yml).
+
+## Running from CI/CD
+
+You can use this CLI to run CodeGuru from inside your CI/CD pipeline. 
+See [this action](.github/workflows/cicd-demo.yml) as an example. To use the CLI in CI/CD, you need working credentials.
+You can use this [CDK template](https://github.com/aws-samples/aws-codeguru-reviewer-cicd-cdk-sample) to set up OIDC credentials for Github Actions.
+
+Then you can run the CLI in non-interactive mode using the `--no-prompt` option, and use the option
+`--fail-on-recommendations` to return a non-zero exit code if recommendations are reported.
+You can specify a region and  AWS profile using the `--region` and `--profile` options as needed:
 ```
-aws-codeguru-cli --region [BUCKET REGION] --no-prompt -r ./ ...
+aws-codeguru-cli --region [BUCKET REGION] --no-prompt  --fail-on-recommendations -r ./ ...
 ```
 obtain the commit range works differently for different CI/CD providers. For example, GitHub provides the relevant
 commits via environment variables such as `${{ github.event.before }}` and `${{ github.event.after }}`.
 
+An end-to-end example is provided in [this action](.github/workflows/cicd-demo.yml).
+
 ### Build from Source
 
 To build the project, you need Java 8 or later. Checkout this repository and run:

README.md

@@ -23,7 +23,7 @@ repositories {
 
 defaultTasks 'clean', 'check', 'installDist'
 
-version = '0.0.5'
+version = '0.1.0'
 jar.archiveName = "${jar.baseName}.${jar.extension}"
 distZip.archiveName = "${jar.baseName}.zip"
 
@@ -39,6 +39,7 @@ dependencies {
 
     implementation 'com.fasterxml.jackson.core:jackson-databind:2.13.0'
     implementation 'com.fasterxml.jackson.core:jackson-core:2.13.0'
+    implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.13.0'
 
     implementation 'com.beust:jcommander:1.81'
 

aws-codeguru-reviewer.yml

@@ -35,7 +35,10 @@
 import com.amazonaws.gurureviewercli.model.ErrorCodes;
 import com.amazonaws.gurureviewercli.model.GitMetaData;
 import com.amazonaws.gurureviewercli.model.ScanMetaData;
+import com.amazonaws.gurureviewercli.model.configfile.CustomConfiguration;
 import com.amazonaws.gurureviewercli.util.Log;
+import com.amazonaws.gurureviewercli.util.RecommendationPrinter;
+import com.amazonaws.gurureviewercli.util.RecommendationsFilter;
 
 public class Main {
     private static final String REVIEWER_ENDPOINT_PATTERN = "https://codeguru-reviewer.%s.amazonaws.com";
@@ -60,6 +63,11 @@ public class Main {
                required = false)
     private boolean noPrompt;
 
+    @Parameter(names = {"--fail-on-recommendations"},
+               description = "Return error code 5 if CodeGuru reports recommendations.",
+               required = false)
+    private boolean failOnRecommendations;
+
     @Parameter(names = {"--root-dir", "-r"},
                description = "The root directory of the project that should be analyzed.",
                required = true)
@@ -140,6 +148,15 @@ public static void main(String[] argv) {
                 }
             }
 
+            val customConfigFile = config.getRootDir().resolve(".codeguru-ignore.yml");
+            if (customConfigFile.toFile().isFile()) {
+                Log.info("Using customer provided config: " + customConfigFile.toAbsolutePath());
+                int originalResultsCount = results.size();
+                results = RecommendationsFilter.filterRecommendations(results,
+                                                                      CustomConfiguration.load(customConfigFile));
+                Log.info("%d recommendations were suppressed.", originalResultsCount - results.size());
+            }
+
             val outputPath = Paths.get(main.outputDir);
             if (!outputPath.toFile().exists()) {
                 if (!outputPath.toFile().mkdirs()) {
@@ -148,6 +165,12 @@ public static void main(String[] argv) {
             }
             ResultsAdapter.saveResults(outputPath, results, scanMetaData);
             Log.info("Analysis finished.");
+            if (main.failOnRecommendations && !results.isEmpty()) {
+                RecommendationPrinter.print(results);
+                Log.error("Exiting with code 5 because %d recommendations were found and --fail-on-recommendations"
+                         + " is used.", results.size());
+                System.exit(5);
+            }
         } catch (GuruCliException e) {
             Log.error("%s: %s", e.getErrorCode(), e.getMessage());
             e.printStackTrace();