From 8e5e75a8a797996b51b61eb5c5264300b98dada6 Mon Sep 17 00:00:00 2001 From: Faye Date: Thu, 5 Sep 2024 15:10:15 +0200 Subject: [PATCH 1/2] Update sonar webhook docs for SonarCloud automatic analysis and include link to CLI command --- docs.kosli.com/content/integrations/sonar.md | 21 +++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs.kosli.com/content/integrations/sonar.md b/docs.kosli.com/content/integrations/sonar.md index 029d75ce..62389148 100644 --- a/docs.kosli.com/content/integrations/sonar.md +++ b/docs.kosli.com/content/integrations/sonar.md @@ -47,7 +47,8 @@ In [SonarCloud](https://sonarcloud.io/) or [SonarQube](https://sonarqube.org): ## Setting up the SonarScanner -In order for Kosli to know where the scan results should be attested, certain parameters must be passed to the SonarScanner. Note that this does NOT work for SonarCloud's Automatic Analysis. +In order for Kosli to know where the scan results should be attested, certain parameters can be passed to the SonarScanner. Note that parameters cannot be passed with SonarCloud's Automatic Analysis - in this case, Kosli determines the relevant Flow and Trail as described below. + These parameters can be passed to the scanner in three ways: - As part of the sonar-project.properties file used in CI analysis - As arguments to the scanner in your CI pipeline's YML file @@ -66,19 +67,25 @@ $ sonar scanner \ -Dsonar.analysis.kosli_trail= ``` -### Required scanner parameters: -- `sonar.analysis.kosli_flow=` -The name of the Flow relevant to your project. -### Optional scanner parameters: +### Possible scanner parameters: +- `sonar.analysis.kosli_flow=` + - The name of the Flow relevant to your project. If a Flow does not already exist with the given name, it is created. If no Flow name is provided, the project key of your project in SonarCloud/SonarQube is used as the name (with any invalid symbols replaced by '-'). - `sonar.analysis.kosli_trail=` - - The name of the Trail to attest the scan results. If a trail does not already exist with the given name it is created. If no Trail name is provided, the revision ID of the Sonar project (typically defaulted to the Git SHA) is used as the name. + - The name of the Trail to attest the scan results. If a Trail does not already exist with the given name it is created. If no Trail name is provided, the revision ID of the Sonar project (typically defaulted to the Git SHA) is used as the name. - `sonar.analysis.kosli_attestation=` - The name you want to give to the attestation. If not provided, a default name "sonar" is used. - `sonar.analysis.kosli_artifact_fingerprint=` - The fingerprint of the artifact you want the attestation to be attached to. Requires that the artifact has already been reported to Kosli. +- `sonar.analysis.kosli_flow_description=` + - The description for the Kosli Flow being created by this webhook. This will not be used if attesting to an already-existing Flow (i.e. will not change any existing descriptions). +- `sonar.analysis.kosli_trail_description=` + - The description for the Kosli Trail being created by this webhook. This will not be used if attesting to an already-existing Trail (i.e. will not change any existing descriptions). ## Testing the integration To test the webhook once configured, simply scan a project in SonarCloud or SonarQube. If successful, the results of the scan will be attested to the relevant Flow and Trail (and artifact, if applicable) as a sonar attestation.
-If the webhook fails, check that you have passed the parameters to the scanner correctly, and that the flow name and artifact fingerprint are valid. \ No newline at end of file +If the webhook fails, check that you have passed the parameters to the scanner correctly, and that the trail name, attestation name and artifact fingerprint are valid. + +## Alternatives: +If you'd rather not use webhooks, or they don't quite fit your use-case, we also have a [CLI command](/client_reference/kosli_attest_sonar/) for attesting Sonar scan results to Kosli. \ No newline at end of file From 84616abd591f9d573d7ce03c313da56d062abfe4 Mon Sep 17 00:00:00 2001 From: Faye Date: Thu, 26 Sep 2024 14:06:50 +0200 Subject: [PATCH 2/2] Add live docs links to sonar webhook docs page --- cmd/kosli/attestSonar.go | 5 ++++- docs.kosli.com/content/integrations/sonar.md | 7 ++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/cmd/kosli/attestSonar.go b/cmd/kosli/attestSonar.go index 7394ade3..b04e8b39 100644 --- a/cmd/kosli/attestSonar.go +++ b/cmd/kosli/attestSonar.go @@ -34,12 +34,15 @@ Retrieves results for the specified scan from SonarCloud or SonarQube and attest The results are parsed to find the status of the project's quality gate which is used to determine the attestation's compliance status. The scan to be retrieved can be specified in two ways: -1. Using metadata created by the Sonar scanner. By default this is located within a temporary .scannerwork folder in the repo base directory. +1. (Default) Using metadata created by the Sonar scanner. By default this is located within a temporary .scannerwork folder in the repo base directory. If you have overriden the location of this folder by passing parameters to the Sonar scanner, or are running Kosli's CLI locally outside the repo's base directory, you can provide the correct path using the --sonar-working-dir flag. This metadata is generated by a specific scan, allowing Kosli to retrieve the results of that scan. 2. Providing the Sonar project key and the revision of the scan (plus the SonarQube server URL if relevant). If running the Kosli CLI in some CI/CD pipeline, the revision is defaulted to the commit SHA. If you are running the command locally, or have overriden the revision in SonarCloud/SonarQube via parameters to the Sonar scanner, you can provide the correct revision using the --sonar-revision flag. Kosli then finds the scan results for the specified project key and revision. + +Note that if your project is very large and you are using SonarCloud's automatic analysis, it is possible for the attest sonar command to run before the SonarCloud scan is completed. +In this case, we recommend using Kosli's Sonar webhook integration ( https://docs.kosli.com/integrations/sonar/ ) rather than the CLI to attest the scan results. ` + attestationBindingDesc const attestSonarExample = ` diff --git a/docs.kosli.com/content/integrations/sonar.md b/docs.kosli.com/content/integrations/sonar.md index 62389148..9ac556f4 100644 --- a/docs.kosli.com/content/integrations/sonar.md +++ b/docs.kosli.com/content/integrations/sonar.md @@ -68,7 +68,7 @@ $ sonar scanner \ ``` -### Possible scanner parameters: +### Scanner parameters: - `sonar.analysis.kosli_flow=` - The name of the Flow relevant to your project. If a Flow does not already exist with the given name, it is created. If no Flow name is provided, the project key of your project in SonarCloud/SonarQube is used as the name (with any invalid symbols replaced by '-'). - `sonar.analysis.kosli_trail=` @@ -87,5 +87,10 @@ $ sonar scanner \ To test the webhook once configured, simply scan a project in SonarCloud or SonarQube. If successful, the results of the scan will be attested to the relevant Flow and Trail (and artifact, if applicable) as a sonar attestation.
If the webhook fails, check that you have passed the parameters to the scanner correctly, and that the trail name, attestation name and artifact fingerprint are valid. +## Live Example in CI system +View an example of a sonar attestation via webhook in Github. + +In [this YAML file](https://app.kosli.com/api/v2/livedocs/cyber-dojo/yaml?ci=github&command=-Dsonar.analysis.kosli_flow), which created [this Kosli event](https://app.kosli.com/api/v2/livedocs/cyber-dojo/event?ci=github&command=-Dsonar.analysis.kosli_flow). + ## Alternatives: If you'd rather not use webhooks, or they don't quite fit your use-case, we also have a [CLI command](/client_reference/kosli_attest_sonar/) for attesting Sonar scan results to Kosli. \ No newline at end of file