|
| 1 | +--- |
| 2 | +description: Instructions on how to trigger DAST/App using the API. |
| 3 | +--- |
| 4 | + |
| 5 | +# Trigger Dynamic Application Security Testing (DAST) scans |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +!!! important |
| 10 | + **App scanning is a business feature.** If you are a Codacy Pro customer, contact our customer success team to access a short trial. |
| 11 | + |
| 12 | + **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). |
| 13 | + |
| 14 | + |
| 15 | +## Creating targets |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +!!! important |
| 22 | + **Do not run API scans on production enviroments as our API scanners may cause potential downtime.** |
| 23 | + |
| 24 | + Our DAST API scanner performs active security testing by sending a large number of requests to your application. When using authenticated API scanning, this activity can be even more intensive, as ZAP explores and probes more of your API surface. |
| 25 | + |
| 26 | + Depending on how your target environment is configured, this may: |
| 27 | + |
| 28 | + - Trigger rate limiting or throttling |
| 29 | + - Appear as a high volume of traffic, similar to a load test |
| 30 | + - Lead to incomplete scan results if key endpoints are blocked or limited |
| 31 | + |
| 32 | + We recommend running scans in a **test or staging environment**, or coordinating with your infrastructure team to ensure that your environment can safely handle the load. |
| 33 | + |
| 34 | +To create a target, use the following API request: |
| 35 | + |
| 36 | +```bash |
| 37 | +curl -X POST https://app.codacy.com/api/v3/organizations/{GIT_PROVIDER}/{ORGANIZATION}/dast/targets \ |
| 38 | + -H "Content-Type: application/json" \ |
| 39 | + -H "Accept: application/json" \ |
| 40 | + -H "api-token: {API_KEY}" \ |
| 41 | + -d '{ |
| 42 | + "url": {TARGET_URL}, |
| 43 | + "targetType": {TARGET_TYPE}, |
| 44 | + "apiDefinitionUrl": {API_DEFINITION_URL}, |
| 45 | + "apiAuthHeaders": { |
| 46 | + "{HEADER_NAME}": "{HEADER_VALUE}" |
| 47 | + } |
| 48 | + }' |
| 49 | +``` |
| 50 | + |
| 51 | +Replace the placeholders with your own values: |
| 52 | + |
| 53 | +| Field | Required | Description | |
| 54 | +|-------|----------|-------------| |
| 55 | +| **API_KEY** | true | [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API | |
| 56 | +| **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) | |
| 57 | +| **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` | |
| 58 | +| **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`| |
| 59 | +| **TARGET_TYPE** | false | Type of target to be scanned <br/> **Options:** `webapp` (default), `openapi` or `graphql`| |
| 60 | +| **API_DEFINITION_URL** | false * | The URL to a publicly accessible OpenAPI specification.<br/>*** Required for OpenAPI targets**| |
| 61 | +| **HEADER_NAME** | false | Name of the authentication header. <br/>For example, `Authentication`| |
| 62 | +| **HEADER_VALUE** | false | Value of the authentication header. <br/>For example, a token or API key| |
| 63 | + |
| 64 | +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. |
| 65 | + |
| 66 | +!!! important |
| 67 | + Currently we only support one authentication header. If you need more, please let us know via support or your account representative. |
| 68 | + |
| 69 | +## Trigger DAST analysis scans |
| 70 | + |
| 71 | +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. |
| 72 | + |
| 73 | +```bash |
| 74 | +curl -X POST https://app.codacy.com/api/v3/organizations/{GIT_PROVIDER}/{ORGANIZATION}/dast/targets/{DAST_TARGET_ID}/analyze \ |
| 75 | + -H "Accept: application/json" \ |
| 76 | + -H "api-token: {API_KEY}" |
| 77 | +``` |
| 78 | + |
| 79 | +Replace the placeholders with your own values: |
| 80 | + |
| 81 | +- **API_KEY:** [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API. |
| 82 | +- **GIT_PROVIDER:** Git provider hosting of the organization (check the table on the example above). For example, `gh` for GitHub Cloud. |
| 83 | +- **ORGANIZATION:** Name of the organization on the Git provider. For example, `codacy`. You must have admin permissions over the organization on the Git provider. |
| 84 | +- **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. |
| 85 | + |
| 86 | +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**. |
0 commit comments