diff --git a/docs/chart/whats-available-on-codacy-self-hosted.md b/docs/chart/whats-available-on-codacy-self-hosted.md index 30b52edfdd..5ecdebcbb6 100644 --- a/docs/chart/whats-available-on-codacy-self-hosted.md +++ b/docs/chart/whats-available-on-codacy-self-hosted.md @@ -36,7 +36,7 @@ These features aren't available on Codacy Self-hosted: - **Security:** [Security and risk management](../security/index.md), including [findings](../security/findings.md), [reports](../security/reports.md), [dependencies](../security/dependencies.md), [app scanning](../security/app-scanning.md), and [container scanning](../security/container-scanning.md) - **Codacy AI:** [Codacy AI](../codacy-ai/codacy-ai.md) and the [AI risk hub](../organizations/ai-risk-hub.md) -- **Developer tools:** [Codacy Guardrails](../codacy-guardrails/codacy-guardrails-getting-started.md), the [Visual Studio Code](../getting-started/integrating-codacy-with-visual-studio-code.md) and [IntelliJ](../getting-started/integrating-codacy-with-intellij-ides.md) extensions, the [Codacy Cloud CLI](../codacy-cloud-cli/index.md), [Codacy CLI v2](https://github.com/codacy/codacy-cli-v2), which connects only to Codacy Cloud, and [Codacy Skills](../codacy-skills/index.md) +- **Developer tools:** [Codacy Guardrails](../codacy-guardrails/codacy-guardrails-getting-started.md), the [Visual Studio Code](../getting-started/integrating-codacy-with-visual-studio-code.md) and [IntelliJ](../getting-started/integrating-codacy-with-intellij-ides.md) extensions, the [Codacy Cloud CLI](../codacy-cloud-cli/index.md), and [Codacy Skills](../codacy-skills/index.md) - **Organizations:** [gate policies](../organizations/using-gate-policies.md), [segments](../organizations/segments.md), [audit logs](../organizations/audit-logs-for-organizations.md), [Issues metrics](../organizations/reporting/issues-metrics.md), [Codacy usage](../organizations/reporting/codacy-usage.md), organization-level [Jira](../organizations/integrations/jira-integration.md), [Slack](../organizations/integrations/slack-integration.md), and [webhooks](../organizations/integrations/webhooks.md), and [default Git provider settings](../organizations/integrations/default-git-provider-integration-settings.md) - **Your account:** [user session management](../account/user-session-management.md) - **Enterprise Cloud:** [GitHub Enterprise Cloud](../enterprise-cloud/github-enterprise-cloud.md) diff --git a/docs/codacy-analysis-cli/index.md b/docs/codacy-analysis-cli/index.md index c783c59fd8..b28675c114 100644 --- a/docs/codacy-analysis-cli/index.md +++ b/docs/codacy-analysis-cli/index.md @@ -129,6 +129,8 @@ Configurations created with `init --remote` are always re-synced in full, becaus !!! note `init` and `update-config` read the `exclude_paths` in your [Codacy configuration file](../repositories-configure/codacy-configuration-file.md) and record them in `codacy.config.json`, which is where `analyze` reads them from. Editing `.codacy.yaml` on its own doesn't change what `analyze` covers — run `update-config` afterward. + To check that file for mistakes first, run `codacy-analysis validate-configuration`. + ## Analyze With the configuration in place, analyze the repository: @@ -218,13 +220,18 @@ codacy-analysis analyze --tool-timeout 1800000 # Log every tool invocation to stderr codacy-analysis analyze --log-level debug + +# Analyze files up to 1 MB instead of skipping those over 150 KB +codacy-analysis analyze --max-file-size 1MB ``` +By default `analyze` skips files over 150 KB, like [Codacy Cloud](../faq/troubleshooting/why-is-my-file-over-150-kb-missing.md), and lists them in its output. Dependency manifests and lockfiles are always analyzed, whatever their size. + Logs are written to `~/.codacy/logs/` as JSON lines and rotate at 10 MB. Add `--no-log` to disable file logging, which is worth doing in CI. ## Upload results to Codacy {: id="upload-results-to-codacy"} -`upload` sends a report produced by `analyze` to Codacy and attaches its issues to a commit. Only reports from this CLI are accepted, because they already carry Codacy pattern IDs. +`upload` sends a report to Codacy and attaches its issues to a commit. Reports produced by `analyze` already carry Codacy pattern IDs. A SARIF report from another tool is mapped to the matching Codacy tool by its driver name; if the CLI can't tell which tool produced it, name it with `--tool`. ```bash codacy-analysis analyze --output-format sarif --output results.sarif @@ -239,6 +246,24 @@ With an account API token instead of a repository API token, name the repository codacy-analysis upload results.sarif --repository gh my-org my-repo --commit ``` +## Scan container images {: id="scan-container-images"} + +`container-scan` scans a container image for known vulnerabilities with Trivy, which the CLI downloads on first use. It reads the image from your local Docker daemon first and pulls it from the registry only if it isn't there: + +```bash +codacy-analysis container-scan myorg/app:1.4.2 +``` + +By default it reports `HIGH` and `CRITICAL` vulnerabilities in operating system packages that have a fix available. Change that with `--severity`, `--pkg-types library`, and `--no-ignore-unfixed`. It exits `1` when it finds vulnerabilities, so it can fail a pipeline. + +To have Codacy track the image's vulnerabilities over time instead, `upload-sbom` generates the image's SBOM and uploads it to [Container scanning](../security/container-scanning.md) in one step. It needs an [account API token](../codacy-api/api-tokens.md#account-api-tokens), from `CODACY_API_TOKEN` or `codacy-analysis login`: + +```bash +codacy-analysis upload-sbom myorg/app:1.4.2 -p gh -o my-org -r my-repo -e production +``` + +Add `--tag` to record the SBOM under a different tag from the image's own, such as a rolling `prod` tag. See [How tagging affects your findings](../security/container-scanning.md#how-tagging-affects-your-findings). + ## Inspect and combine configurations `discover` reports the languages, frameworks, libraries, and notable files the CLI finds, which is what `init --auto` bases its selection on: diff --git a/docs/codacy-api/examples/uploading-container-image-sboms.md b/docs/codacy-api/examples/uploading-container-image-sboms.md index 34aa2d5e95..482544ec8d 100644 --- a/docs/codacy-api/examples/uploading-container-image-sboms.md +++ b/docs/codacy-api/examples/uploading-container-image-sboms.md @@ -4,7 +4,7 @@ description: Instructions on how to upload container image SBOMs to Codacy using # Uploading container image SBOMs to Codacy -Codacy scans your container images for known vulnerabilities from an SBOM (Software Bill of Materials) that you upload. If your pipeline already produces an SBOM, or you generate one with a tool other than the [Codacy CLI v2](https://github.com/codacy/codacy-cli-v2), you can upload it directly through the API and monitor the results as findings under [Container scanning](../../security/container-scanning.md). +Codacy scans your container images for known vulnerabilities from an SBOM (Software Bill of Materials) that you upload. If your pipeline already produces an SBOM, or you generate one with a tool other than the [Codacy Analysis CLI](../../codacy-analysis-cli/index.md#scan-container-images), you can upload it directly through the API and monitor the results as findings under [Container scanning](../../security/container-scanning.md). Before you automate this, read [how tagging affects your findings](../../security/container-scanning.md#how-tagging-affects-your-findings). The tag you upload to decides whether Codacy keeps one set of findings for the image or starts a new set with every release, and it's the choice that's hardest to reverse. diff --git a/docs/faq/troubleshooting/why-is-my-file-over-150-kb-missing.md b/docs/faq/troubleshooting/why-is-my-file-over-150-kb-missing.md index 86527efefd..dc457f1b19 100644 --- a/docs/faq/troubleshooting/why-is-my-file-over-150-kb-missing.md +++ b/docs/faq/troubleshooting/why-is-my-file-over-150-kb-missing.md @@ -10,4 +10,15 @@ As a solution to this problem, we placed a size limit to the files that Codacy w ## What if I need to analyze a file that exceeds this limit? -While Codacy will ignore your file by default, you can still analyze it by running the analysis locally using the [Codacy Analysis CLI](https://github.com/codacy/codacy-analysis-cli). The Codacy Analysis CLI doesn't have any limitation on file size. +While Codacy will ignore your file by default, you can still analyze it locally with the [Codacy Analysis CLI](../../codacy-analysis-cli/index.md). The CLI applies the same 150 KB limit by default, so that local results match Codacy Cloud's. Raise it with `--max-file-size`: + +```bash +codacy-analysis analyze --max-file-size 1MB +``` + +To send those results to Codacy, write them to a file and [upload them](../../codacy-analysis-cli/index.md#upload-results-to-codacy): + +```bash +codacy-analysis analyze --max-file-size 1MB --output-format sarif --output results.sarif +codacy-analysis upload results.sarif +``` diff --git a/docs/repositories-configure/codacy-configuration-file.md b/docs/repositories-configure/codacy-configuration-file.md index d101992905..ccf262666f 100644 --- a/docs/repositories-configure/codacy-configuration-file.md +++ b/docs/repositories-configure/codacy-configuration-file.md @@ -72,12 +72,14 @@ To use a Codacy configuration file: - "**/tests/integration/**" ``` -1. Optionally, validate the syntax of your configuration file with the [Codacy Analysis CLI](https://github.com/codacy/codacy-analysis-cli#install) by running the following command in the same folder as the Codacy configuration file: +1. Optionally, validate your configuration file with the [Codacy Analysis CLI](../codacy-analysis-cli/index.md) by running the following command in the same folder as the Codacy configuration file: ```bash - codacy-analysis-cli validate-configuration --directory `pwd` + codacy-analysis validate-configuration ``` + The command lists every setting that doesn't follow the format above, and exits with a non-zero code if it finds any. It also warns about engine and language names it doesn't recognize. + ## Ignoring files using a Codacy configuration file {: id="ignore-files"} The Codacy configuration file gives you more flexibility in [ignoring or excluding files](ignoring-files.md) from the Codacy analysis. diff --git a/docs/repositories-configure/local-analysis/running-dartanalyzer.md b/docs/repositories-configure/local-analysis/running-dartanalyzer.md index 4f229c830b..93c8d7ee5d 100644 --- a/docs/repositories-configure/local-analysis/running-dartanalyzer.md +++ b/docs/repositories-configure/local-analysis/running-dartanalyzer.md @@ -16,68 +16,93 @@ To run Dart Analyzer as a [client-side tool](client-side-tools.md): end="" %} -## Important Concepts +## Dart SDK and dependencies -- **`.codacy/codacy.yaml`**: Configuration file to specify `dart`, or `flutter`, and `dartanalyzer` versions for the CLI. +The [Codacy Analysis CLI](../../codacy-analysis-cli/index.md) runs `dart analyze` from a Dart SDK. It uses the SDK that Codacy manages for you, if you have installed it, and otherwise the `dart` command on your `PATH`: -```yaml -runtimes: - - dart@3.7.2 -tools: - - dartanalyzer@3.7.20 -``` +- **Codacy-managed SDK:** Add `--install-dependencies` to `analyze` and the CLI downloads the pinned Dart SDK, about 210 MB, into `~/.codacy/tools/dartanalyzer/`. +- **Your own SDK:** Install [Dart](https://dart.dev/get-dart), or Flutter, which bundles Dart, and make sure `dart` is on your `PATH`. + +Before analyzing, resolve your project's packages with `dart pub get`, or `flutter pub get` for a Flutter project. The CLI never runs it for you. Without the resolved packages, every `package:` import is unresolvable: the CLI warns and skips the checks that depend on them for that run. -or +## Manual configuration -```yaml -runtimes: - - flutter@3.29.3 -tools: - - dartanalyzer@3.7.20 +Install the Codacy Analysis CLI and initialize the repository. Initialization writes `.codacy/codacy.config.json`, which `analyze` requires: pulling it from Codacy Cloud with `init --remote` means the local run uses the same Dart Analyzer patterns as your repository's **Code patterns** page. + +```bash +npm i -g @codacy/analysis-cli +codacy-analysis init --remote ``` -## Manual configuration +Then resolve your packages, run the analysis, and upload the results: ```bash -codacy-cli install -codacy-cli analyze -t dartanalyzer -o dartanalyzer.sarif -codacy-cli upload -s dartanalyzer.sarif -c $COMMIT_SHA -t CODACY_PROJECT_TOKEN +dart pub get +codacy-analysis analyze --tool dartanalyzer --output-format sarif --output dartanalyzer.sarif +codacy-analysis upload dartanalyzer.sarif --commit $COMMIT_SHA ``` - **If you're using an account API token**, you must also provide the flags `-p`, `-o`, and `-r`. You can obtain the values for these flags from the URL of your repository dashboard on Codacy: + **If you're using an account API token**, you must also provide the `--repository` flag with your provider, organization, and repository name. You can obtain these values from the URL of your repository dashboard on Codacy: ```bash -codacy-cli install -codacy-cli analyze -t dartanalyzer -o dartanalyzer.sarif -codacy-cli analyze -t dartanalyzer -o dartanalyzer.sarif -c $COMMIT_SHA -a CODACY_API_TOKEN -p provider (gh|gl|bb) -o ORGANIZATION -r REPOSITORY +dart pub get +codacy-analysis analyze --tool dartanalyzer --output-format sarif --output dartanalyzer.sarif +codacy-analysis upload dartanalyzer.sarif --commit $COMMIT_SHA --repository ``` +!!! note + `--tool` matches against the tool IDs in your `.codacy/codacy.config.json`, and only tools listed there run. If `--tool dartanalyzer` doesn't match your setup, check that file for the ID it recorded. + ## GitHub Action +The [Codacy Analysis CLI GitHub Action](https://github.com/codacy/analysis-cli-action) runs the same `codacy-analysis` CLI as the manual configuration above. If your repository has no committed `.codacy/codacy.config.json`, the action fetches the repository's configuration from Codacy with your token. + +On `pull_request` events, the action uploads the results for the pull request's head commit. Check out that commit with `ref:` as in the examples below, otherwise line numbers can point at the wrong lines. + +The examples set up Dart and resolve the packages before running the action. For a Flutter project, use a Flutter setup action and `flutter pub get` instead. ### Using a project token + +{% raw %} ```yml -- name: Run Codacy CLI - uses: codacy/codacy-cli-v2-action@main +- uses: actions/checkout@v4 with: - project-token: CODACY_PROJECT_TOKEN + ref: ${{ github.event.pull_request.head.sha || github.sha }} + +- uses: dart-lang/setup-dart@v1 + +- run: dart pub get + +- name: Run Codacy Analysis CLI + uses: codacy/analysis-cli-action@v1 + with: + project-token: ${{ secrets.CODACY_PROJECT_TOKEN }} tool: dartanalyzer - upload_report: true + upload: true ``` +{% endraw %} ### Using an account API token +The action takes the provider, organization, and repository from the workflow. Set `provider`, `owner`, and `repository` only if the repository is on Codacy under different names. + +{% raw %} ```yml -- name: Run Codacy CLI - uses: codacy/codacy-cli-v2-action@main +- uses: actions/checkout@v4 with: - api_token: CODACY_API_TOKEN + ref: ${{ github.event.pull_request.head.sha || github.sha }} + +- uses: dart-lang/setup-dart@v1 + +- run: dart pub get + +- name: Run Codacy Analysis CLI + uses: codacy/analysis-cli-action@v1 + with: + api-token: ${{ secrets.CODACY_API_TOKEN }} tool: dartanalyzer - upload_report: true - provider: gh - owner: codacy-acme - repository: sample-dart-project + upload: true ``` +{% endraw %} !!! warning "Tokens should be stored in the repository secrets." - diff --git a/docs/security/container-scanning.md b/docs/security/container-scanning.md index c41d96eb5b..5e1252bfad 100644 --- a/docs/security/container-scanning.md +++ b/docs/security/container-scanning.md @@ -98,14 +98,14 @@ codacy images gh "${ORGANIZATION_NAME}" You can set up container scanning in one of two ways: by connecting your CI/CD pipeline or by manually uploading your image SBOM. Once configured, your image dependencies are scanned daily and results will appear in the Image card list. ### CI/CD integration -You must authenticate the Codacy CLI so your pipeline can securely send your image SBOM to Codacy. +You must authenticate the [Codacy Analysis CLI](../codacy-analysis-cli/index.md) so your pipeline can securely send your image SBOM to Codacy. ![Security and risk management import container SBOM in CICD](images/security-risk-management-container-upload-cicd.png) In order to do that, you need to: 1. Get the API token and set up the environment variable as shown in the UI; -2. Install and run Codacy CLI in your pipeline to upload results. +2. Install and run the Codacy Analysis CLI in your pipeline to upload results. When CI/CD is configured: @@ -117,38 +117,33 @@ This is the recommended setup for continuous coverage. #### Example pipeline steps -These examples use the [Codacy CLI v2](https://github.com/codacy/codacy-cli-v2), which generates the SBOM from your image and uploads it in a single command. They assume you have already set `CODACY_API_TOKEN` as described above. +These examples use the [Codacy Analysis CLI](../codacy-analysis-cli/index.md), which generates the SBOM from your image with Trivy and uploads it in a single command. They assume you have already set `CODACY_API_TOKEN` as described above: `upload-sbom` only accepts an account API token. !!! note Already generating SBOMs with another tool? [Upload them via the API.](../codacy-api/examples/uploading-container-image-sboms.md) -Install the CLI once per pipeline run: +Install the CLI once per pipeline run. It needs Node.js 20 or later: ```bash -curl -fsSL https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh -o codacy-cli.sh -chmod +x codacy-cli.sh -./codacy-cli.sh init +npm install -g "@codacy/analysis-cli" ``` -`upload-sbom` reads a Codacy configuration from the working directory, which is what `init` creates. Without it the upload stops with `No configuration file was found, execute init command first.` +`upload-sbom` reads the image from your local Docker daemon first, and only pulls it from the registry if it isn't there, so it scans the image your pipeline just built. #### Example: one list, kept up to date {: id="example-one-list"} -For [one list of findings, kept up to date](#how-tagging-affects-your-findings), point your rolling tag at the image you just built and upload that: +For [one list of findings, kept up to date](#how-tagging-affects-your-findings), upload the image you just built under your rolling tag: ```bash -docker tag "${IMAGE_NAME}:${IMAGE_VERSION}" "${IMAGE_NAME}:prod" - -./codacy-cli.sh upload-sbom \ - -a "${CODACY_API_TOKEN}" \ +codacy-analysis upload-sbom "${IMAGE_NAME}:${IMAGE_VERSION}" \ -p gh \ -o "${ORGANIZATION_NAME}" \ -r "${REPOSITORY_NAME}" \ -e production \ - "${IMAGE_NAME}:prod" + --tag prod ``` -The `docker tag` alias stays on the build machine and is never pushed. Without it the CLI resolves `prod` against your registry and scans whatever that tag points at there, rather than the image your pipeline just built. +`--tag` sets the tag Codacy records the SBOM under, independently of the tag of the image that's scanned. You don't need to add a `prod` tag to the image itself. #### Example: a separate list per release {: id="example-per-release"} @@ -161,13 +156,11 @@ npm install -g "@codacy/codacy-cloud-cli" codacy image gh "${ORGANIZATION_NAME}" "${IMAGE_NAME}" \ --delete --keep-latest 10 --skip-confirmation -./codacy-cli.sh upload-sbom \ - -a "${CODACY_API_TOKEN}" \ +codacy-analysis upload-sbom "${IMAGE_NAME}:${IMAGE_VERSION}" \ -p gh \ -o "${ORGANIZATION_NAME}" \ -r "${REPOSITORY_NAME}" \ - -e production \ - "${IMAGE_NAME}:${IMAGE_VERSION}" + -e production ``` Every release adds an image tag, so clean up on every run to stay under your organization limit. Put the cleanup **before** the upload: at the limit the upload is rejected, so a pipeline that uploads first and cleans up later can't make progress. Add `--dry-run` to see which tags would go without deleting anything. @@ -185,15 +178,15 @@ Both examples use these placeholders. Replace them with your own values: | `gl` | GitLab Cloud | | `bb` | Bitbucket Cloud | -- **ORGANIZATION_NAME:** Name of the organization on the Git provider. For example, `codacy`. +- **ORGANIZATION_NAME:** Set with `-o`. Name of the organization on the Git provider. For example, `codacy`. - **IMAGE_NAME:** Name of the container image, without a tag. For example, `myapp`. -- **IMAGE_VERSION:** The tag your pipeline built, such as `1.4.2`. Only used by the per-release example. -- **REPOSITORY_NAME:** Optional. Name of the repository to associate the image with, so findings link back to it. +- **IMAGE_VERSION:** The tag your pipeline built, such as `1.4.2`. The per-release example also records the SBOM under this tag. +- **REPOSITORY_NAME:** Optional, set with `-r`. Name of the repository to associate the image with, so findings link back to it. - **`-e`:** Optional. Environment where the image is deployed, such as `production`. It appears in the tag list. #### If your pipeline already produces an SBOM -The examples above use the Codacy CLI v2 because it generates the SBOM and uploads it in one step. If your pipeline already produces an SBOM in CycloneDX or SPDX format, upload that file directly with the [Codacy Cloud CLI](../codacy-cloud-cli/index.md#manage-container-images) instead. It reads the same `CODACY_API_TOKEN` you set in step 1, and needs version 1.12.1 or later. +The examples above use the Codacy Analysis CLI because it generates the SBOM and uploads it in one step. If your pipeline already produces an SBOM in CycloneDX or SPDX format, upload that file directly with the [Codacy Cloud CLI](../codacy-cloud-cli/index.md#manage-container-images) instead. It reads the same `CODACY_API_TOKEN` you set in step 1, and needs version 1.12.1 or later. ```bash npm install -g "@codacy/codacy-cloud-cli" @@ -240,8 +233,7 @@ To manually upload an image SBOM, you need to: Reuse a tag and each upload replaces the last. A new tag starts its own set of findings, so choose it with care: see [How tagging affects your findings](#how-tagging-affects-your-findings). !!! note - You can use the [Codacy CLI v2](https://github.com/codacy/codacy-cli-v2) to generate and upload your SBOM file to Codacy. - + You can use the [Codacy Analysis CLI](../codacy-analysis-cli/index.md) to generate and upload your SBOM file to Codacy in one step, with `codacy-analysis upload-sbom`. See [CI/CD integration](#cicd-integration). ## Image card list @@ -293,4 +285,4 @@ What happens when you delete an image: If there is no last analysis date for an image tag, it means that the SBOM file was received but the scan hasn't been completed yet. The most likely scenario is that an analysis hasn't been executed yet. !!! note - Remember that scans run nightly (UTC). If you just uploaded the SBOM file, but need results immediately, consider using our [Codacy CLI v2](https://github.com/codacy/codacy-cli-v2) to run a local analysis to scan for any issues. + Remember that scans run nightly (UTC). If you just uploaded the SBOM file, but need results immediately, scan the image locally with the [Codacy Analysis CLI](../codacy-analysis-cli/index.md): `codacy-analysis container-scan :`.