Merge pull request #311 from hlxsites/app-sec-jb-secrets

Revised Secrets documentation and added CLI flags

docs/en/enterprise-edition/content-collections/application-security/risk-management/monitor-and-manage-code-build/secrets-scanning.adoc

@@ -1,67 +1,92 @@
 == Secrets Scanning
 
-You can use Application Security to detect and block secrets in files in your IDEs, VCS repositories, and CI/CD pipelines.
+Application Security scan capability detects secrets ^*^ in files within your version control system (VCS) repositories and CI/CD executions. This functionality is accessible through the Prisma Cloud console, IDE, or CLI, allowing you to address and fix the issues that led to the exposure of secrets, such as removing the secrets from configuration files or storing them in dedicated files or secure storage mechanisms. The results of Secrets scanning are displayed on the Projects page.
 
-A secret is a programmatic access key that provides systems with access to information, services or assets. Developers use secrets such as API keys, encryption keys, OAuth tokens, certificates, PEM files, passwords, and passphrases to enable their application to securely communicate with other cloud services.
+*Limitation*: Secrets scanning in integrated version control systems supports repositories up to 4GB in size.
 
-For identifying secrets, Prisma Cloud provides default policies that use domain-specific and generic syntax to match on specific signatures and patterns to validate the likelihood or entropy of a string being a secret. You can view the scan results directly on *Application Security > Projects*, on the CLI if using Checkov, or in the IDE such as VSCode.
+Prisma Cloud provides default policies designed to identify secrets that leverage both domain-specific and generic syntax. These policies match specific signatures and patterns to validate the likelihood or entropy of a string being a secret. For more information on Secrets policies refer to xref:../../../../policy-reference/secrets-policies/secrets-policies.adoc[Secrets Policies]. 
 
-image::application-security/scan-results-secrets-ide.png[]
+* A secret is a programmatic access key that provides systems with access to information, services or assets. Developers use secrets such as API keys, encryption keys, OAuth tokens, certificates, PEM files, passwords, and passphrases to enable their application to securely communicate with other cloud services.
+
+=== Prerequisite
+
+You must enable the Secrets module in order to scan for secrets: In *Application Security*, go to *Settings* > *Application Security* in the left menu under *Configuration* > enable *Secrets Security*.
+
+For more information refer to xref:../../get-started/application-security-license-types.adoc[Application Security License Types].
+
+=== Advanced Secrets Scanner Configurations
+
+In addition to the default settings for the Secrets scanner, you can configure the following advanced settings: *Validate Secrets* and *Scan Git History for Secrets*.
+
+image::application-security/secrets-advanced-settings.png[]
 
 [#validate-secrets]
-=== Validate Secrets
+==== Validate Secrets
 
-When scanning for secrets, Prisma Cloud can validate secrets against public APIs to verify if the secret is still active so that you can prioritize and handle exposed secrets quickly.
+Prisma Cloud can validate detected secrets against public APIs to verify their current activity status. This enables you to prioritize and promptly address exposed secrets. “Secrets” validation scanning can be executed through the Prisma Cloud console and IDE by extension, or through your CLI. 
 
-By default the  validation of secrets is disabled and you can choose to enable the validation for secrets scan from *Settings > Application Security Configuration > Validate Secrets*.
+By default, the Secrets validation functionality is disabled. To enable validation scanning:
 
-Additionally, you can choose to run Checkov on your repositories to filter valid secrets that may be potentially exposed. To see a list of potentially exposed secrets you need to add an environment variable `CKV_VALIDATE_SECRETS=true` after enabling Validate Secrets.
+* On *Prisma Cloud console*
++
+. In *Application Security*, select *Settings*.
+. Select *Application Security* in the left menu under *Configuration* > enable the *Validate Secrets* setting.
 
-In this example, you see a secret that is valid and requires to be prioritized in the repository after running Checkov on the terminal.
+* Through the *CLI*
++
+. Enable the *Validate Secrets* setting on the Prisma Cloud console (see above).
+. Add the environment variable `CKV_VALIDATE_SECRETS=true`.
+
+EXAMPLE
+
+In the following example, a valid secret has been identified in the repository after conducting a Checkov scan in the CLI terminal. It is crucial to prioritize addressing this issue.
 
 image::application-security/secrets-validate-3.png[]
 
-You can see the scan results of secrets after validation on *Projects > Secrets* and then use *Resource Explorer* to prioritize a valid secret by either a *Suppress* or by performing a *Manual Fix* on the secret.
+==== Scan Git History for Secrets
 
-//image::application-security/secrets-validate-4.gif[]
+Prisma Cloud can scan through the git history of a repository to identify secrets that may have been deleted from a file but still exist in the historical records, and notify you about such secrets even if they are no longer present in the most recent commit. This helps to mitigate the risk of potential abuse of those credentials as they may still be compromised if found in history. This scan can be executed through the Prisma Cloud console and IDE by extension, or through your CLI.
 
+By default, git history scanning is disabled. 
 
-=== Git History for Secrets
+==== Enable git history scanning on Prisma Cloud
 
-Secrets deleted from a file can still be found in the git history of the repository and abused. Prisma Cloud can search through git history for those secrets and notify you even when the secret is no longer in the most recent commit.
+. In *Application Security*, select *Settings*.
+. Select *Application Security* in the left menu under *Configuration* > enable the *Scan Git History for Secrets* setting.
 
-By default git history scanning is disabled and you can choose to enable the validation for secrets scan from *Settings > Application Security Configuration > Scan Git History for Secrets*.
+==== Enable git history scanning through the CLI
 
-image::application-security/secrets-history-1.png[]
+Scan your git history locally using Checkov CLI by executing the command with the `--scan-secrets-history` flag.  By default, timeouts are not set, but you can specify one using the `--secrets-history-timeout TIME` flag. 
 
-Results of secrets scanning will show up on the *Projects*.
+NOTE: Scans are performed in chunks and partial scans of chunks will not be saved. Additionally, results will not be saved on the Prisma Cloud platform.
 
-NOTE: Git history scanning through the VCS integrations is only supported for repositories up to 4GB in size.
+=== Scan Options
 
-Additionally, you can scan your git history without saving the results to the Prisma Cloud platform using Checkov locally by using the `--scan-secrets-history` flag. By default, there is not a timeout, but one can be set with `--secrets-history-timeout TIME`. Scans are performed in chunks and partial scans of chunks will not be saved.
+Prisma Cloud provides the following options for scanning secrets in your files.
 
+*Automatic scans*:  
 
-[.task]
-=== Suppress Secret Notifications
+* *Integration*: Scans are automatically initiated as soon as you integrate your repositories through the Prisma Cloud console  
+* *CI/CD runs*: Event driven scans are performed during runs in your CI/CD pipeline
+* *IDE interaction*: *Opening or *saving files* in your integrated IDE triggers an automatic scan
+* *Pull Requests*: Submitting a pull request in your version control system prompts an automatic scan
 
-By suppressing a notification for secrets you are choosing to no longer receive any information on a violation related to the suppressed secret. To suppress a notification you are required to define a suppression rule by adding a justification with an expiration time.
+*Manual scans*:
 
-[.procedure]
+* *IDE*: You can trigger scans manually in your IDE. For more information refer to xref:../../get-started/connect-code-and-build-providers/ides/ides.adoc[IDE]
+* *CLI commands*: By default, Checkov does not scan files for secrets. To enable Secrets scanning, execute the command with the `--enable-secret-scan-all-files flag` or set the `CKV_SECRETS_SCAN_ENABLE_ALL` environment variable. For more information on CLI based scanning, refer to the https://www.checkov.io/1.Welcome/Quick%20Start.html[CLI documentation]
 
-. Select *Application Security > Projects* and then select *Secrets* view.
 
-. Configure a suppression rule for a secret.
+=== Manage Scan Results  
 
-.. Select a secret and then on the side panel select *Issues* and then select *Suppress*.
-+
-In this example, `Azure Storage Account Access Keys (Error)` is the policy violation.
-+
-image::application-security/secrets-validate-1.png[]
+You can view, analyze and manage scan results, as well as prioritize remediation efforts, and implement effective fixes, or suppress findings, directly on the Prisma Cloud console, through your Checkov CLI, or directly within your IDE. Note that Secrets scanning does not support automatic fixes.
 
-.. Add a *Justification* with the *Expiration Time*.
-+
-Optionally, you can choose a *Manual Fix* to resolve the secret violation.
+For information on fixing Secrets issues, refer to xref:fix-code-issues.adoc[Fix Code Security Issues]. For information on suppressing Secrets issues, refer to xref:suppress-code-issues.adoc[Suppress Code Issues].
 
-. Select *Save*.
+NOTE: To fix or suppress Secrets issues, ensure that you select *Secrets* as the code category on the *Projects* page. This allows you to quickly identify secret-related issues.
 
+For more information on Secrets scan management across the different platforms refer, to the documentation:
 
+* *Prisma Cloud console* documentation: see xref:monitor-and-manage-code-build.adoc[Monitor and Manage Code Build Issues]
+* xref:../../get-started/connect-code-and-build-providers/ides/ides.adoc[IDE] documentation 
+* https://www.checkov.io/1.Welcome/What%20is%20Checkov.html[CLI] documentation