diff --git a/docs/codacy-api/examples/triggering-dast-scans.md b/docs/codacy-api/examples/triggering-dast-scans.md new file mode 100644 index 0000000000..4b8ae3c3d3 --- /dev/null +++ b/docs/codacy-api/examples/triggering-dast-scans.md @@ -0,0 +1,74 @@ +--- +description: Instructions on how to trigger DAST/App using the API. +--- + +# Trigger Dynamic Application Security Testing (DAST) scans + +Thanks to the new app scanning capabilities available on the Security and risk management dashboard, it's now possible to automate application scanning via Codacy's API. This means that, with little effort, you'll be able to trigger app scanning on demand every time you deploy a new version of your app. + +!!! important + App scanning is a business feature. If you are a Codacy Pro customer, contact our customer success team to access a short trial. + Check your [permissions](../../organizations/roles-and-permissions-for-organizations.md). Only git provider admins and organization managers will be able to create new targets and trigger scans (in app and via the API). + Get your API key. All the methods below require you to authenticate via your [account's API token](../api-tokens.md#account-api-tokens). + +## Creating targets + +Before the automation process itself, you need to create a target. Targets are single units that contain all the configurations of your scan, in this case the URL (and later on other configurations, like authentication details and OpenAPI definition). +Targets only need to be defined once. The target's URL is immutable, so, if you need to change it, you'll need to delete the target and create a new one. + +To create a target: + +```bash +curl -X POST https://app.codacy.com/api/v3/organizations/{GIT_PROVIDER}/{ORGANIZATION}/dast/targets \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "api-token: {API_KEY}" \ + -d '{"url": "https://api.domain.com/v1"}' +``` + +Replace the placeholders with your own values: + +- **API_KEY:** [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API. +- **GIT_PROVIDER:** Git provider hosting of the organization, using one of the values in the table below. For example, `gh` for GitHub Cloud. + + | Value | Git provider | + |-------|-------------------| + | `gh` | GitHub Cloud | + | `ghe` | GitHub Enterprise | + | `gl` | GitLab Cloud | + | `gle` | GitLab Enterprise | + | `bb` | Bitbucket Cloud | + | `bbe` | Bitbucket Server | + +- **ORGANIZATION:** Name of the organization on the Git provider. For example, `codacy`. You must have admin permissions over the organization on the Git provider. + +Once you create the target you'll get the 'Target Id' as a response. That id will be used to trigger DAST scans in the next section. + +## Trigger DAST analysis scans + +Once your targets are created you can trigger an analysis by calling the '[Analyze DAST target](https://api.codacy.com/api/api-docs#analyzedasttarget)' endpoint. + +```bash +curl -X POST https://app.codacy.com/api/v3/organizations/{GIT_PROVIDER}/{ORGANIZATION}/dast/targets/{DAST_TARGET_ID}/analyze \ + -H "Accept: application/json" \ + -H "api-token: {API_KEY}" +``` + +Replace the placeholders with your own values: + +- **API_KEY:** [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API. +- **GIT_PROVIDER:** Git provider hosting of the organization, using one of the values in the table below. For example, `gh` for GitHub Cloud. + + | Value | Git provider | + |-------|-------------------| + | `gh` | GitHub Cloud | + | `ghe` | GitHub Enterprise | + | `gl` | GitLab Cloud | + | `gle` | GitLab Enterprise | + | `bb` | Bitbucket Cloud | + | `bbe` | Bitbucket Server | + +- **ORGANIZATION:** Name of the organization on the Git provider. For example, `codacy`. You must have admin permissions over the organization on the Git provider. +**DAST_TARGET_ID:** Identifier of a DAST target to analyze (obtained in the [previous section](./triggering-dast-scans.md#creating-targets). For example, `457`. You must have admin permissions over the organization on the Git provider. + +Scans occur asynchronously. To monitor an ongoing scan you can use the [target management page in Codacy](../../organizations/managing-security-and-risk.md#app-scanning). Once completed, you can access all scan results by navigating to the **Security dashboard**, selecting the **Findings tab** and filtering by **Scan types > DAST/App scanning**. \ No newline at end of file diff --git a/docs/getting-started/configuring-your-repository.md b/docs/getting-started/configuring-your-repository.md index 2d199ac1e0..8c4738e9c4 100644 --- a/docs/getting-started/configuring-your-repository.md +++ b/docs/getting-started/configuring-your-repository.md @@ -25,7 +25,7 @@ To configure your repository, follow these steps: ## 2. Configuring code patterns {: id="configuring-code-patterns"} -[Configure the tools and code patterns](../repositories-configure/configuring-code-patterns.md) that Codacy uses to analyze your repository. If security is important for your team, review the [security and risk management dashboard](../organizations/managing-security-and-risk.md) to ensure that your configuration detects potential security issues. +[Configure the tools and code patterns](../repositories-configure/configuring-code-patterns.md) that Codacy uses to analyze your repository. If security is important for your team, review the [Security and risk management dashboard](../organizations/managing-security-and-risk.md) to ensure that your configuration detects potential security issues. !!! tip To ensure that multiple repositories consistently follow the same global tool and code pattern configurations, [use an organization coding standard](../organizations/using-coding-standards.md). diff --git a/docs/organizations/images/security-risk-management-app-scanning.png b/docs/organizations/images/security-risk-management-app-scanning.png new file mode 100644 index 0000000000..2295212a8c Binary files /dev/null and b/docs/organizations/images/security-risk-management-app-scanning.png differ diff --git a/docs/organizations/managing-security-and-risk.md b/docs/organizations/managing-security-and-risk.md index 98cda99a4d..a30d4f6f82 100644 --- a/docs/organizations/managing-security-and-risk.md +++ b/docs/organizations/managing-security-and-risk.md @@ -522,9 +522,9 @@ Security and risk management supports checking the languages and infrastructure- The dependency tab is a business-tier feature. If you are a Codacy Pro customer interested in upgrading to gain access to this feature, contact our customer success team. -The **Security and risk management dependencies** page displays a unified view of all dependencies used by your repositories. +The **Security and risk management Dependencies** page displays a unified view of all dependencies used by your repositories. -To access the dependencies page, access the [overview page](#dashboard) and click the **Findings** tab. +To access the dependencies page, access the [overview page](#dashboard) and click the **Dependencies** tab. ![Security and risk management dependencies page](images/security-risk-management-dependencies-list.png) @@ -534,7 +534,7 @@ You're also able to click any dependency to find out more information about it. ![Security and risk management dependency page](images/security-risk-management-dependencies-single.png) - The dependency overview page offers a quick birds-eye view of that particular dependency. You'll be able to see all different versions that are being used, including which repository is using them, the oldest and most recent versions you're leveraging, as well as the highest criticality of security issues and the license 6 applied to any particular version of that dependency. + The dependency overview page offers a quick bird's-eye view of that particular dependency. You'll be able to see all different versions that are being used, including which repository is using them, the oldest and most recent versions you're leveraging, as well as the highest criticality of security issues and the license 6 applied to any particular version of that dependency. 1: Semgrep supports additional security rules when signing up for [Semgrep Pro](https://semgrep.dev/pricing/). @@ -542,4 +542,44 @@ You're also able to click any dependency to find out more information about it. 3: Supported as a [client-side tool](../repositories-configure/local-analysis/client-side-tools.md). 4: Includes the plugin [Find Security Bugs](https://find-sec-bugs.github.io/). 5: Includes the plugins [no-unsanitized](https://www.npmjs.com/package/eslint-plugin-no-unsanitized), [security](https://www.npmjs.com/package/eslint-plugin-security), [security-node](https://www.npmjs.com/package/eslint-plugin-security-node), and [xss](https://www.npmjs.com/package/eslint-plugin-xss). -6: Visit the [supported languages and tools](../getting-started/supported-languages-and-tools.md#supported-languages-and-tools) page for a list of supported languages. \ No newline at end of file +6: Visit the [supported languages and tools](../getting-started/supported-languages-and-tools.md#supported-languages-and-tools) page for a list of supported languages. + + +## App scanning {: id="app-scanning"} + +!!! important + App scanning is a business feature. If you are a Codacy Pro customer, contact our customer success team to access a short trial. + +The **Security and risk management app scanning** page allows organizations to scan APIs and Web Applications for security vulnerabilities. This is part of our DAST (Dynamic Application Security Testing) capabilities, powered by ZAP. + +To access the app scanning page, access the [overview page](#dashboard) and click the **App scanning** tab. + +![Security and risk management app scanning page](images/security-risk-management-app-scanning.png) + +App scanning tests applications in real-world scenarios, making it possible to find configuration and authentication issues or other runtime vulnerabilities that may impact your application’s functionality and security. It’s also a good method for preventing regressions and doesn’t depend on a specific programming language. As long as the application can be accessed through a browser, a DAST tool can typically scan it for vulnerabilities. + +!!! note + Already using ZAP? [Upload your results via the API.](../codacy-api/examples/uploading-dast-results.md) + +### How to scan a target +To scan a target, you can either go to the Security and risk management dashboard and access the App Scanning tab, or set it up for automation using our API. + +!!! important + Only [admins and organization managers](../organizations/roles-and-permissions-for-organizations.md) will be able to create new targets and run scans (both in-app and via the API). + + +
+ +
+ + +From within the tab, you're able to configure a new target by inputting the URL of the app you'd like to scan. You can configure up to 6 targets within your organization (if you need more, talk to your customer success representative). +Scans can be triggered manually via Codacy's UI. As you click to start a scan, it will be first added to a queue and eventually executed. You can also queue a scan for a target that is already being scanned, and it will eventually execute after the current scan finishes. There are no limits to how many scans an organization can run per target, so this should accommodate all your deployment needs. +Once a scan is complete, its findings will be added to the findings tab, where you can review them using the filter **Scan types > DAST/App scanning**. + +!!! note + Currently, DAST issues are only visible to admin and organization admin roles. + +Follow our [roadmap](https://roadmap.codacy.com) for the upcoming updates on this feature. \ No newline at end of file diff --git a/docs/organizations/roles-and-permissions-for-organizations.md b/docs/organizations/roles-and-permissions-for-organizations.md index 6b52c00bff..56d7e8e7af 100644 --- a/docs/organizations/roles-and-permissions-for-organizations.md +++ b/docs/organizations/roles-and-permissions-for-organizations.md @@ -35,6 +35,7 @@ To change this, open your organization **Settings**, page **Roles and permission - [Configure languages](../repositories-configure/languages.md) - [Manage branches](../repositories-configure/managing-branches.md) - [Reanalyze branches and pull requests](../faq/repositories/how-do-i-reanalyze-my-repository.md) +- [Create targets and run Dynamic Application Security Testing scans](../organizations/managing-security-and-risk.md#app-scanning) ![Configuring repository management permissions](images/roles-permissions-repo-management.png) diff --git a/mkdocs.yml b/mkdocs.yml index e4d6c973e2..09125c72d1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -630,6 +630,7 @@ nav: - codacy-api/examples/obtaining-current-issues-in-repositories.md - codacy-api/examples/identifying-commits-without-coverage-data.md - codacy-api/examples/uploading-dast-results.md + - codacy-api/examples/triggering-dast-scans.md - Managing Codacy Self-hosted: "!include submodules/chart/mkdocs.yml" - Troubleshooting and FAQs: - General: