{"id":15710466,"url":"https://github.com/aws/aws-codeguru-cli","last_synced_at":"2025-10-20T03:32:55.515Z","repository":{"id":39963640,"uuid":"439319434","full_name":"aws/aws-codeguru-cli","owner":"aws","description":"Command line wrapper to interact with CodeGuru Reviewer","archived":false,"fork":false,"pushed_at":"2024-09-03T21:00:31.000Z","size":200,"stargazers_count":22,"open_issues_count":3,"forks_count":8,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-01-28T19:48:23.803Z","etag":null,"topics":["aws","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-17T12:06:38.000Z","updated_at":"2024-08-02T02:23:11.000Z","dependencies_parsed_at":"2022-09-06T11:22:10.643Z","dependency_job_id":null,"html_url":"https://github.com/aws/aws-codeguru-cli","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-codeguru-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-codeguru-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-codeguru-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Faws-codeguru-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/aws-codeguru-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237261476,"owners_count":19281240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","static-analysis"],"created_at":"2024-10-03T21:08:13.291Z","updated_at":"2025-10-20T03:32:50.453Z","avatar_url":"https://github.com/aws.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeGuru Reviewer CLI Wrapper\nSimple CLI wrapper for CodeGuru reviewer that provides a one-line command to scan a local clone of a repository and\nreceive results. This CLI wraps the [AWS CLI](https://aws.amazon.com/cli/) commands to communicate with \n[AWS CodeGuru Reviewer](https://aws.amazon.com/codeguru/). Using CodeGuru Reviewer may generate metering fees\nin your AWS account. See the [CodeGuru Reviewer pricing](https://aws.amazon.com/codeguru/pricing/) for details.\n\n### Table of Contents\n- [Installation](#installation)\n- [Using the CLI](#using-the-cli)\n- [Suppressing Recommendations](#suppressing-recommendations)\n- [Running from CI/CD](#running-from-cicd)\n- [Security](#security)\n- [License](#license)\n\n## Installation\n\n### Prerequisites\n\nTo 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\u0026filtered-posts.sort-order=desc)) \nand the [AWS Command Line interface](https://aws.amazon.com/cli/) installed. \nVerify that both applications are installed on our machine by running:\n\n```\njava -version\nmvn --version\naws --version\ngit --version\n```\n\nWe will also need working credentials on our machine to interact with our AWS account. \nLearn more about setting up credentials for AWS here: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html.\n\nYou can always use the CLI with *Admin* credentials but if you want to have a specific role to use the CLI, your\n credentials must have at least the following permissions:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Action\": [\n                \"codeguru-reviewer:ListRepositoryAssociations\",\n                \"codeguru-reviewer:AssociateRepository\",\n                \"codeguru-reviewer:DescribeRepositoryAssociation\",\n                \"codeguru-reviewer:CreateCodeReview\",\n                \"codeguru-reviewer:DescribeCodeReview\",\n                \"codeguru-reviewer:ListRecommendations\",\n                \"iam:CreateServiceLinkedRole\"\n            ],\n            \"Resource\": \"*\",\n            \"Effect\": \"Allow\"\n        },\n        {\n            \"Action\": [\n                \"s3:CreateBucket\",\n                \"s3:GetBucket*\",\n                \"s3:List*\",\n                \"s3:GetObject\",\n                \"s3:PutObject\",\n                \"s3:DeleteObject\"\n            ],\n            \"Resource\": [\n                \"arn:aws:s3:::codeguru-reviewer-cli-*\",\n                \"arn:aws:s3:::codeguru-reviewer-cli-*/*\"\n            ],\n            \"Effect\": \"Allow\"\n        }\n    ]\n}\n```\n\n\n## Using the CLI\n\nYou can download the [aws-codeguru-cli](https://github.com/aws/aws-codeguru-cli/releases/latest) from the releases section.\nDownload the latest version and add it to your `PATH`:\n```\ncurl -OL https://github.com/aws/aws-codeguru-cli/releases/download/0.1.0/aws-codeguru-cli.zip\nunzip aws-codeguru-cli.zip\nexport PATH=$PATH:./aws-codeguru-cli/bin\n```\n\n\n\n### Scan an Example\n\nNow, let's download an example project (requires Maven):\n```\ngit clone https://github.com/aws-samples/amazon-codeguru-reviewer-sample-app\ncd amazon-codeguru-reviewer-sample-app\nmvn clean compile\n```\nAfter compiling, we can run CodeGuru with:\n```\naws-codeguru-cli --root-dir ./ --build target/classes --src src --output ./output\nopen output/codeguru-report.html \n```\nwhere `--root-dir .` specifies that the root of the project that we want to analyze. The option `--build target/classses` states that the build artifacts are located under `./target/classes` and `--src` says that we only want to analyze source files that are\nlocated under `./src`. The option `--output ./output` specifies where CodeGuru should write its recommendations to. By default,\nCodeGuru produces a Json and Html report.\n\nYou can provide your own bucket name using the `--bucket-name` option. Note that, currently, CodeGuru Reviewer only\nsupports bucket names that start with the prefix `codeguru-reviewer-` out of the box. If you choose a different naming\npattern for your bucket you need to:\n1. Grant `S3:GetObject` permissions on the S3 bucket to `codeguru-reviewer.amazonaws.com`\n2. If you are using SSE in the S3 bucket, grant `KMS::Decrypt` permissions to `codeguru-reviewer.amazonaws.com`\n\n### Using Encryption\n\nCodeGuru Reviewer allows you to use a customer managed key (CMCMK) to encrypt the contents of the S3 bucket that is used \nto store source and build artifacts, and all metadata and recommendations that are produced by CodeGuru Reviewer. \nFirst, create a customer managed key in KMS.\nYou will need to grant CodeGuru Reviewer permission to decrypt artifacts with this key by adding the \nfollowing Statement to your Key policy:\n\n```json\n{\n    \"Sid\": \"Allow CodeGuru to use the key to decrypt artifacts\",\n    \"Effect\": \"Allow\",\n    \"Principal\": {\n        \"AWS\": \"*\"\n    },\n    \"Action\": [\n        \"kms:Decrypt\",\n        \"kms:DescribeKey\"\n    ],\n    \"Resource\": \"*\",\n    \"Condition\": {\n        \"StringEquals\": {\n            \"kms:ViaService\": \"codeguru-reviewer.amazonaws.com\",\n            \"kms:CallerAccount\": [Your AWS ACCOUNT ID]\n        }\n    }\n}\n```\nThen, enable server-side encryption for the bucket that you are using with CodeGuru Reviewer. The bucket name should be\n`codeguru-reviewer-cli-[YOUR ACCOUNT]-[YOUR REGION]`, unless you provided a custom name. For encryption, use the\nKMS key that you created in the previous step.\n\nNow you can analyze a repository by providing the KMS key ID (not the alias). For example:\n```\n aws-codeguru-cli -r ./ -kms 12345678-abcd-abcd-1234-1234567890ab\n```\nThe first time you analyze a repository with the CodeGuru Reviewer CLI, a new association will be created and\nthe provided key will be associated with this repository. Fur subsequent scans, you do not need to provide the \nkey again. Note that you can start using a key after the repository is already associated. If you want to switch\nfrom not using a key to using a key, you need to delete the existing association first in the AWS Console and\nthen trigger a new scan with the CLI where you provide the key.\n\n\n## Suppressing Recommendations\n\nThe CodeGuru Reviewer CLI searches for a file named `.codeguru-ignore.yml` where users can specify criteria\nbased on which recommendations should be suppressed. Suppressed recommendations will not be returned by the CLI,\nbut still show up in the AWS console.\n\nThe `.codeguru-ignore.yml` file can use any of the filter criteria shown below:\n\n```yaml\nversion: 1.0  # The Version field is mandatory. All other fields are optional. \n\n# The CodeGuru Reviewer CLI produces a recommendations.json file which contains deterministic IDs for each\n# recommendation. This ID can be excluded so that this recommendation will not be reported in future runs of the\n# CLI.\nExcludeById:\n- '4d2c43618a2dac129818bef77093730e84a4e139eef3f0166334657503ecd88d'\n\n# We can tell the CLI to exclude all recommendations below a certain severity. This can be useful in CI/CD integration.\nExcludeBelowSeverity: 'HIGH'\n\n# We can exclude all recommendations that have a certain tag. Available Tags can be found here:\n# https://docs.aws.amazon.com/codeguru/detector-library/java/tags/\n# https://docs.aws.amazon.com/codeguru/detector-library/python/tags/\nExcludeTags:\n  - 'maintainability'\n\n# We can also exclude recommendations by Detector ID. Detector IDs can be found here:\n# https://docs.aws.amazon.com/codeguru/detector-library\nExcludeRecommendations:\n# Ignore all recommendations for a given Detector ID \n  - detectorId: 'java/aws-region-enumeration@v1.0'\n# Ignore all recommendations for a given Detector ID in a provided set of locations.\n# Locations can be written as Unix GLOB expressions using wildcard symbols.\n  - detectorId: 'java/aws-region-enumeration@v1.0'\n    Locations:\n      - 'src/main/java/com/folder01/*.java'\n\n# Excludes all recommendations in the provided files. Files can be provided as Unix GLOB expressions.\nExcludeFiles:\n  - tst/**\n\n```\n\nOnly the `version` field is mandatory in the `.codeguru-ignore.yml` file. All other entries are optional, and\nthe CLI will understand any combination of those entries.\n\nAn example of such a configuration file can be found [here](https://github.com/aws/aws-codeguru-cli/blob/main/.codeguru-ignore.yml).\n\n## Running from CI/CD\n\nYou can use this CLI to run CodeGuru from inside your CI/CD pipeline. \nSee [this action](.github/workflows/cicd-demo.yml) as an example. To use the CLI in CI/CD, you need working credentials.\nYou can use this [CDK template](https://github:com/aws-samples/aws-codeguru-reviewer-cicd-cdk-sample) to set up OIDC credentials for Github Actions.\n\nThen you can run the CLI in non-interactive mode using the `--no-prompt` option, and use the option\n`--fail-on-recommendations` to return a non-zero exit code if recommendations are reported.\nYou can specify a region and  AWS profile using the `--region` and `--profile` options as needed:\n```\naws-codeguru-cli --region [BUCKET REGION] --no-prompt  --fail-on-recommendations -r ./ ...\n```\nobtain the commit range works differently for different CI/CD providers. For example, GitHub provides the relevant\ncommits via environment variables such as `${{ github.event.before }}` and `${{ github.event.after }}`.\n\nAn end-to-end example is provided in [this action](.github/workflows/cicd-demo.yml).\n\n### Build from Source\n\nTo build the project, you need Java 8 or later. Checkout this repository and run:\n```\n./gradlew installDist\n```\nand now run your local build with:\n```\n./build/install/aws-codeguru-cli/bin/aws-codeguru-cli\n```\nYou can run a self-test with:\n```\n./build/install/aws-codeguru-cli/bin/aws-codeguru-cli -r . -s src/main/java -b build/libs -c HEAD^:HEAD\n```\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-codeguru-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Faws-codeguru-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Faws-codeguru-cli/lists"}