Skip to content

feat: document DAST api scanning TAROT-3391 #2411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jun 30, 2025
Merged

feat: document DAST api scanning TAROT-3391 #2411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0e4a6a7
feat: add info on API scanning
claudiacodacy Jun 17, 2025
abdccfa
feat: API definition docs
claudiacodacy Jun 17, 2025
3dcb231
clean: slight fixes in api request table
claudiacodacy Jun 17, 2025
15a668d
clean: formating and ponctuation
claudiacodacy Jun 17, 2025
a9ca058
Apply suggestions from code review
claudiacodacy Jun 17, 2025
74d0b12
Merge branch 'master' into document-dast-auth-TAROT-3391
claudiacodacy Jun 17, 2025
72b1045
Apply suggestions from code review
claudiacodacy Jun 24, 2025
48d0972
Merge branch 'master' into document-dast-auth-TAROT-3391
claudiacodacy Jun 24, 2025
f2ff57e
Update docs/organizations/managing-security-and-risk.md
claudiacodacy Jun 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 25 additions & 17 deletions docs/codacy-api/examples/triggering-dast-scans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,37 +14,45 @@

## 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.
Before the automation process itself, you need to create a target. Targets are individual configurations that define what Codacy will scan, including the target URL, its type (API or web application), and other type-dependent fields like OpenAPI specification and optional authentication details for API targets.

To create a target:
Targets only need to be created once. Note that **targets are immutable** — if you need to change the URL, definition, or authentication, you'll need to delete the target and create a new one.

Check failure on line 19 in docs/codacy-api/examples/triggering-dast-scans.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Dashes] Remove the spaces around ' — '.

Raw Output:
{"message": "[Microsoft.Dashes] Remove the spaces around ' — '.", "location": {"path": "docs/codacy-api/examples/triggering-dast-scans.md", "range": {"start": {"line": 19, "column": 74}}}, "severity": "ERROR"}

To create a target, use the following API request:

```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"}'
-d '{
"url": {TARGET_URL},
"targetType": {TARGET_TYPE},
"apiDefinitionUrl": {API_DEFINITION_URL},
"apiAuthHeaders": {
"{HEADER_NAME}": "{HEADER_VALUE}"
}
}'
```

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.
| Field | Required | Description |
|-------|----------|-------------|
| **API_KEY** | true | [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API |
| **GIT_PROVIDER** | true | Git provider hosting of the organization, using one of the values in the table below. <br/>**Options:** `gh` (GitHub Cloud), `ghe`(GitHub Enterprise), `gl` (Gitlab Cloud), `gle` (Gitlab Enterprise), `bb` (Bitbucket Cloud), `bbe` (Bitbucket Server) |

Check failure on line 43 in docs/codacy-api/examples/triggering-dast-scans.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'GitLab' instead of 'Gitlab'.

Raw Output:
{"message": "[Vale.Terms] Use 'GitLab' instead of 'Gitlab'.", "location": {"path": "docs/codacy-api/examples/triggering-dast-scans.md", "range": {"start": {"line": 43, "column": 208}}}, "severity": "ERROR"}

Check failure on line 43 in docs/codacy-api/examples/triggering-dast-scans.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'GitLab' instead of 'Gitlab'.

Raw Output:
{"message": "[Vale.Terms] Use 'GitLab' instead of 'Gitlab'.", "location": {"path": "docs/codacy-api/examples/triggering-dast-scans.md", "range": {"start": {"line": 43, "column": 186}}}, "severity": "ERROR"}
| **ORGANIZATION** | true | Name of the organization on the Git provider. You must have admin permissions over the organization on the Git provider.<br/>For example, `codacy` |
| **TARGET_URL** | true | URL of the Web app or API that will be scanned. <br/>Must start with `http://` or `https://`<br/>For example, `https://api.codacy.com/v1`|
| **TARGET_TYPE** | false | Type of target to be scanned <br/> **Options:** `webapp` (default), `openapi` or `graphql`|
| **API_DEFINITION_URL** | false * | The URL to a publicly accessible OpenAPI specification.<br/>*** Required for OpenAPI targets**|
| **HEADER_NAME** | false | Name of the authentication header. <br/>For example, `Authentication`|
| **HEADER_VALUE** | false | Value of the authentication header. <br/>For example, a token or API key|

Once you create the target you'll get the target `id` as a response. You will use it to trigger DAST scans in the next section.

!!! important
Currently we only support one authentication header. If you need more, please let us know via support or your account representative.

## 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.
Expand Down
61 changes: 45 additions & 16 deletions docs/organizations/managing-security-and-risk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -562,46 +562,75 @@
!!! 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.
The **Security and risk management > App scanning** page allows organizations to scan Web Applications and APIs for security vulnerabilities. This feature is part of Codacy's Dynamic Application Security Testing (DAST) capabilities, powered by ZAP.

Check failure on line 565 in docs/organizations/managing-security-and-risk.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'APIs'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'APIs'?", "location": {"path": "docs/organizations/managing-security-and-risk.md", "range": {"start": {"line": 565, "column": 108}}}, "severity": "ERROR"}

To access the app scanning page, access the [overview page](#dashboard) and click the **App scanning** tab.
To access the App scanning page, go to 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.
App scanning analyzes applications in production or production-like environments to help identify vulnerabilities such as misconfigurations, insecure authentication, or other security issues that occur in real-world usage. Because it doesn't rely on access to source code, it’s language-agnostic and useful for validating security across your entire stack.

Check failure on line 571 in docs/organizations/managing-security-and-risk.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'misconfigurations'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'misconfigurations'?", "location": {"path": "docs/organizations/managing-security-and-risk.md", "range": {"start": {"line": 571, "column": 123}}}, "severity": "ERROR"}

In concrete, when you start a scan, Codacy runs a baseline scan using ZAP. This is a non-intrusive scan that identifies common security issues without actively attacking your application.
It’s safe to run for production applications and helps detect problems like missing security headers, information disclosure through HTTP response headers, insecure cookie configurations, and others.
Codacy supports two types of scanning:

- **Web application scans** perform baseline, non-intrusive analysis. These scans are safe for production environments and detect surface-level issues such as:
- Missing security headers
- Insecure cookie configurations
- Information disclosure through HTTP response headers
- Exposure of sensitive or misconfigured files

Check failure on line 579 in docs/organizations/managing-security-and-risk.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'misconfigured'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'misconfigured'?", "location": {"path": "docs/organizations/managing-security-and-risk.md", "range": {"start": {"line": 579, "column": 30}}}, "severity": "ERROR"}

- **API scans** simulate real-world attacks against your API endpoints. These are more aggressive and best suited for **non-production environments**, such as staging or development. API scans provide deeper insights into runtime behavior and potential vulnerabilities, such as:
- Broken authentication or authorization controls
- Injection vulnerabilities (SQL or command injection)
- Exposure of sensitive data in API responses
- Insecure CORS or HTTP method configurations

!!! 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.
## Creating an App Scanning target

When creating a scan target, you'll be able to choose between a Web App or an API. Configuring a Web App will only require a target URL, while APIs will have other requirements:

Check failure on line 592 in docs/organizations/managing-security-and-risk.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'APIs'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'APIs'?", "location": {"path": "docs/organizations/managing-security-and-risk.md", "range": {"start": {"line": 592, "column": 144}}}, "severity": "ERROR"}

- **REST APIs**, which require a publicly accessible OpenAPI specification URL.
- **GraphQL APIs**, where the schema is inferred from the default path `{targetUrl}/graphql`.

API targets optionally support **header-based authentication**. As you create a target, keep in mind you may not be able to view or change certain fields later (to change your configurations you may need to delete and create a new target).

!!! important
Avoid running API scans on production enviroments as our API scanners may cause potential downtime.

Check failure on line 600 in docs/organizations/managing-security-and-risk.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'enviroments'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'enviroments'?", "location": {"path": "docs/organizations/managing-security-and-risk.md", "range": {"start": {"line": 600, "column": 43}}}, "severity": "ERROR"}

!!! 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).
If exposing your API specification isn't feasible for your team, let us know via support or your account representative.


### How to scan a target

You can initiate scans in two ways:
- From the **App scanning** tab in the Security and risk management dashboard
- By automating scans using [Codacy's API](../codacy-api/examples/triggering-dast-scans.md)

!!! important
Only [admins and organization managers](../organizations/roles-and-permissions-for-organizations.md) can create targets and start scans, both in-app and via the API.

<div>
<iframe width="100%" height="472" src="https://www.youtube.com/embed/qPwHlIGJYXs?autoplay=1&mute=1&showinfo=0&loop=1" title="DAST targets" frameborder="0"
allowfullscreen>
</iframe>
</div>

Each organization can have up to **6 active scan targets**. If you need additional capacity, contact your customer success representative.

Scans are triggered manually through the UI and are queued before execution. You can queue one single scan per target — it will run sequentially. There is no limit to the number of scans you can run on a target, in order to support your deployment needs.

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**.
Once a scan completes, results will be available under the **Findings** tab. Use the **Scan types > DAST/App scanning** filter to view relevant findings.

!!! important
Depending on the application being scanned, a DAST analysis can take a very long time to complete.
To guarantee the stability of Codacy's platform and fair access to analysis slots, DAST analysis can timeout when running for too long.
Depending on the complexity of the target, DAST scans can take a significant amount of time to complete. Codacy may enforce timeouts to ensure platform stability and fair resource distribution.

!!! important
Failed analysis are retried a number of times according to their failure reason. A retry will re-enqueue the analysis, to be executed as soon as possible, while respecting the available analysis slots.
Failed scans are retried based on the failure reason. Retries are added back to the queue automatically and processed when capacity allows.

!!! note
Currently, DAST issues are only visible to admin and organization admin roles.
Currently, DAST findings are only visible to admin and organization admin roles.

Follow our [roadmap](https://roadmap.codacy.com) for the upcoming updates on this feature.
Follow our [roadmap](https://roadmap.codacy.com) for updates on this feature.
Loading