Skip to content

Commit 43cf9f5

Browse files
joanasteodorojoanasteodoro
committed
add documentation for dast - api examples part 2
1 parent 21003d5 commit 43cf9f5

2 files changed

Lines changed: 194 additions & 0 deletions

File tree

‎docs/codacy-api/examples/running-dast-scans.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
description: Instructions on how to run DAST/App using the API.
3+
---
4+
5+
# Run DAST/App scans
6+
7+
Thanks to the new app scanning capabilities available on the Security and Risk Management dashboard, it is now possible to automate application scanning via the API. This means that, with little effort, you'll be able to run ZAP on demand every time you deploy a new version of your app or your APIs.
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+
Check your permissions. Only git provider admins and organization managers will be able to Create new targets and run scans (in app and via the API).
12+
Get your API key. All the methods below require you to authenticate via your account's API token.
13+
14+
## Creating targets
15+
16+
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, scan type or open api definition).
17+
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 it and create a new target.
18+
19+
To create a target:
20+
21+
```bash
22+
curl -X POST https://app.codacy.com/api/v3/organizations/{GIT_PROVIDER}/{ORGANIZATION}/dast/targets \
23+
-H "Content-Type: application/json" \
24+
-H "Accept: application/json" \
25+
-H "api-token: {API_KEY}" \
26+
-d '{"url": "https://api.domain.com/v1"}'
27+
```
28+
29+
Replace the placeholders with your own values:
30+
31+
- **API_KEY:** [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API.
32+
- **GIT_PROVIDER:** Git provider hosting of the organization, using one of the values in the table below. For example, `gh` for GitHub Cloud.
33+
34+
| Value | Git provider |
35+
|-------|-------------------|
36+
| `gh` | GitHub Cloud |
37+
| `ghe` | GitHub Enterprise |
38+
| `gl` | GitLab Cloud |
39+
| `gle` | GitLab Enterprise |
40+
| `bb` | Bitbucket Cloud |
41+
| `bbe` | Bitbucket Server |
42+
43+
- **ORGANIZATION:** Name of the organization on the Git provider. For example, `codacy`. You must have admin permissions over the organization on the Git provider.
44+
45+
Once you create the target you'll get the TargetId as a response. That Id will be used later to trigger DAST scans.
46+
47+
## Running DAST analysis scans
48+
49+
Once your targets are created you can trigger an analysis by running the POST /dast/targets/{dastTargetId}/analyze method.
50+
51+
```bash
52+
curl -X POST https://app.codacy.com/api/v3/organizations/{GIT_PROVIDER}/{ORGANIZATION}/dast/targets/{DAST_TARGET_ID}/analyze \
53+
-H "Accept: application/json" \
54+
-H "api-token: {API_KEY}"
55+
```
56+
57+
Replace the placeholders with your own values:
58+
59+
- **API_KEY:** [Account API token](../api-tokens.md#account-api-tokens) used to authenticate on the Codacy API.
60+
- **GIT_PROVIDER:** Git provider hosting of the organization, using one of the values in the table below. For example, `gh` for GitHub Cloud.
61+
62+
| Value | Git provider |
63+
|-------|-------------------|
64+
| `gh` | GitHub Cloud |
65+
| `ghe` | GitHub Enterprise |
66+
| `gl` | GitLab Cloud |
67+
| `gle` | GitLab Enterprise |
68+
| `bb` | Bitbucket Cloud |
69+
| `bbe` | Bitbucket Server |
70+
71+
- **ORGANIZATION:** Name of the organization on the Git provider. For example, `codacy`. You must have admin permissions over the organization on the Git provider.
72+
- **DAST_TARGET_ID:** Identifier of a DAST target to analyze (obtained from the POST endpoint used to create a target or GET endpoint used to get a list of targets). For example, `457`. You must have admin permissions over the organization on the Git provider.
73+
74+
Scans will be asynchronous to your deployment pipeline and the results will be posted within the SRM dashboard within the findings tab.
75+
76+
## Examples to Run scans on Deployment
77+
78+
!!! note
79+
The examples below trigger scans on deployment which may analyze, not the latest, but the previous version of the application. To run DAST post deployment you may explore options such as ...
80+
81+
Github Action:
82+
83+
```bash
84+
name: DAST Scan with Codacy
85+
86+
on:
87+
# Trigger on deployment or push to main branch
88+
deployment:
89+
branches: [ main ]
90+
# Allow manual trigger
91+
workflow_dispatch:
92+
93+
jobs:
94+
dast-scan:
95+
runs-on: ubuntu-latest
96+
steps:
97+
- name: Run DAST scan
98+
env:
99+
CODACY_API_TOKEN: "${CODACY_API_TOKEN}"
100+
PROVIDER: "gh" # Github in Codacy
101+
ORG_NAME: "${REPOSITORY_OWNER}" # Gets repo organization
102+
TARGET_ID: "12590" # Replace with your target ID
103+
run: |
104+
curl -X POST "https://app.codacy.com/api/v3/organizations/${PROVIDER}/${ORG_NAME}/dast/targets/${TARGET_ID}/analyze" \
105+
-H "Accept: application/json" \
106+
-H "api-token: ${CODACY_API_TOKEN}"
107+
```
108+
109+
CircleCI:
110+
111+
```bash
112+
version: 2.1
113+
jobs:
114+
dast-scan:
115+
docker:
116+
- image: cimg/base:2021.04
117+
steps:
118+
- checkout
119+
- run:
120+
name: Run DAST Analysis
121+
command: |
122+
curl -X POST "https://app.codacy.com/api/v3/organizations/${PROVIDER}/${ORG_NAME}/dast/targets/${TARGET_ID}/analyze" \
123+
-H "Accept: application/json" \
124+
-H "api-token: ${CODACY_API_TOKEN}"
125+
126+
workflows:
127+
version: 2
128+
deploy-and-scan:
129+
jobs:
130+
# Your deployment job here
131+
- dast-scan:
132+
requires:
133+
# Require your deployment job to finish first
134+
- deploy
135+
context:
136+
- codacy-credentials # Store your secrets in a context
137+
```
138+
139+
Gitlab CI/CD:
140+
141+
```bash
142+
stages:
143+
- deploy
144+
- security
145+
146+
dast_scan:
147+
stage: security
148+
image: alpine:latest
149+
variables:
150+
PROVIDER: "gitlab"
151+
ORG_NAME: "${CI_PROJECT_NAMESPACE}"
152+
TARGET_ID: "12590" # Replace with your target ID
153+
script:
154+
- apk add --no-cache curl
155+
- |
156+
curl -X POST "https://app.codacy.com/api/v3/organizations/${PROVIDER}/${ORG_NAME}/dast/targets/${TARGET_ID}/analyze" \
157+
-H "Accept: application/json" \
158+
-H "api-token: ${CODACY_API_TOKEN}"
159+
# Run after deployment
160+
needs:
161+
- deploy
162+
```
163+
164+
Jenkins:
165+
166+
```bash
167+
pipeline {
168+
agent any
169+
170+
environment {
171+
PROVIDER = 'github' // or your git provider
172+
ORG_NAME = 'your-organization'
173+
TARGET_ID = '12590' // Replace with your target ID
174+
}
175+
176+
stages {
177+
// Your deployment stage here
178+
179+
stage('DAST Scan') {
180+
steps {
181+
// Use credentials from Jenkins credentials store
182+
withCredentials([string(credentialsId: 'codacy-api-token', variable: 'CODACY_API_TOKEN')]) {
183+
sh '''
184+
curl -X POST "https://app.codacy.com/api/v3/organizations/${PROVIDER}/${ORG_NAME}/dast/targets/${TARGET_ID}/analyze" \
185+
-H "Accept: application/json" \
186+
-H "api-token: ${CODACY_API_TOKEN}"
187+
'''
188+
}
189+
}
190+
}
191+
}
192+
}
193+
```

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -630,6 +630,7 @@ nav:
630630
- codacy-api/examples/obtaining-current-issues-in-repositories.md
631631
- codacy-api/examples/identifying-commits-without-coverage-data.md
632632
- codacy-api/examples/uploading-dast-results.md
633+
- codacy-api/examples/running-dast-scans.md
633634
- Managing Codacy Self-hosted: "!include submodules/chart/mkdocs.yml"
634635
- Troubleshooting and FAQs:
635636
- General:

0 commit comments

Comments
 (0)