From 7d33d93661ecd6da741288992bfe0b0cfbb0329a Mon Sep 17 00:00:00 2001 From: David Mora <82040808+davidgm0@users.noreply.github.com> Date: Tue, 8 Oct 2024 16:52:15 +0200 Subject: [PATCH] [FX-4815] Document new available DAST endpoints (#263) --- versions/v2/content/dast-findings.md | 86 +++++++++++++++++---- versions/v2/content/dast-scans.md | 46 +++++++++++ versions/v2/content/dast-scheduled-scans.md | 62 +++++++++++++++ 3 files changed, 178 insertions(+), 16 deletions(-) create mode 100644 versions/v2/content/dast-scheduled-scans.md diff --git a/versions/v2/content/dast-findings.md b/versions/v2/content/dast-findings.md index 1678dd6..d69b56f 100644 --- a/versions/v2/content/dast-findings.md +++ b/versions/v2/content/dast-findings.md @@ -67,20 +67,7 @@ This endpoint retrieves a list of all DAST findings that belong to the organizat ### Response Fields -| Field | Description | -|-----------------|-------------------------------------------------------------------------------------| -| `id` | A unique ID representing the DAST finding. Starts with `dfi_` | -| `target_id` | A unique ID representing the DAST target. Starts with `dt_` | -| `scan_ids` | An array of unique ID representing the scans that originated the vulnerability finding. Starts with `dsc_` | -| `title` | Name of the vulnerability | -| `last_found_at` | Date and time of when the vulnerability was last found, in ISO 8601 UTC format. | -| `severity` | Severity of the vulnerability finding: `10` is low. `20` is medium. `30` is high. | -| `state` | State of the vulnerability finding: [`notfixed`, `invalid`, `accepted`, `fixed`] | -| `affected_url` |URL affected by the found vulnerability | -| `description` | Description of the vulnerability. | -| `proof_of_concept` | Evidence of the vulnerability finding. | -| `suggested_fix` | Description of how to fix the vulnerability. | -| `http_exchanges` | Pairs of `request` and `response` of the vulnerability finding. | +See [Finding response fields](#finding-response-fields) ## Get a DAST Finding @@ -125,7 +112,13 @@ This endpoint retrieves a specific DAST finding that belongs to the organization `GET https://api.us.cobalt.io/dast/findings/YOUR-DAST-FINDING-IDENTIFIER` -### Response Fields +### URL Parameters + +| Parameter | Description | +|--------------------------------|----------------------------------------------------------| +| `YOUR-DAST-FINDING-IDENTIFIER` | A unique ID representing the finding. Starts with `dfi_` | + +### Finding Response Fields | Field | Description | |-----------------|-------------------------------------------------------------------------------------| @@ -135,9 +128,70 @@ This endpoint retrieves a specific DAST finding that belongs to the organization | `title` | Name of the vulnerability | | `last_found_at` | Date and time of when the vulnerability was last found, in ISO 8601 UTC format. | | `severity` | Severity of the vulnerability finding: `10` is low. `20` is medium. `30` is high. | -| `state` | State of the vulnerability finding: [`notfixed`, `invalid`, `accepted`, `fixed`] | +| `state` | State of the vulnerability finding: [`invalid`, `need_fix`, `wont_fix`, `valid_fix`, `check_fix`] | | `affected_url` | URL affected by the found vulnerability | | `description` | Description of the vulnerability. | | `proof_of_concept` | Evidence of the vulnerability finding. | | `suggested_fix` | Description of how to fix the vulnerability. | | `http_exchanges` | Pairs of `request` and `response` of the vulnerability finding. | + +## Retest DAST finding + +```sh +curl -X POST "https://api.us.cobalt.io/dast/findings/YOUR-DAST-FINDING-IDENTIFIER/retest" \ + -H "Accept: application/vnd.cobalt.v2+json" \ + -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ + -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" +``` + +> The above command returns no data and a `204` response code when successful. + +This endpoint runs a short scan to determine if the finding can still be detected. The state +of the finding will change automatically once the retest finishes. Because DAST findings +are of an automated nature, retesting and passing the scan is the only way to mark it as fixed. + +### HTTP Request + +`POST https://api.us.cobalt.io/dast/findings/YOUR-DAST-FINDING-IDENTIFIER/retest` + +### URL Parameters + +| Parameter | Description | +|--------------------------------|----------------------------------------------------------| +| `YOUR-DAST-FINDING-IDENTIFIER` | A unique ID representing the finding. Starts with `dfi_` | + +## Update Finding State + +```sh +curl -X PATCH "https://api.us.cobalt.io/dast/findings/YOUR-DAST-FINDING-IDENTIFIER" \ + -H "Accept: application/vnd.cobalt.v2+json" \ + -H "Content-Type: application/vnd.cobalt.v2+json" \ + -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ + -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \ + -d '{"state":"need_fix"}' +``` + +> If successful, this command returns `200` and the updated finding + +This endpoint updates the current state of a DAST finding. Note that changing the state to `fixed` or `check_fix` is not +possible with this endpoint. You have to use the [retest endpoint](#retest-dast-finding) for that. + +### HTTP Request + +`PATCH https://api.us.cobalt.io/dast/findings/YOUR-DAST-FINDING-IDENTIFIER` + +### URL Parameters + +| Parameter | Description | +|--------------------------------|----------------------------------------------------------| +| `YOUR-DAST-FINDING-IDENTIFIER` | A unique ID representing the finding. Starts with `dfi_` | + +### Body + +| Field | Description | +|---------|-------------------------------------------------------------------------------------------| +| `state` | The desired next state of the finding. Should be one of [`invalid`, `wont_fix`, `need_fix`] | + +### Response fields + +See [Finding response fields](#finding-response-fields) diff --git a/versions/v2/content/dast-scans.md b/versions/v2/content/dast-scans.md index cf3cd37..1e0f44c 100644 --- a/versions/v2/content/dast-scans.md +++ b/versions/v2/content/dast-scans.md @@ -98,3 +98,49 @@ This endpoint retrieves a specific DAST Scan that belongs to the organization sp | `status` | Possible values: [`canceled`, `canceling`, `completed`, `completed_with_errors`, `failed`, `paused`, `pausing`, `queued`, `resuming`, `started`, `under_review`, `finishing_up`] | | `started_at` | Date and time of when the scan started. | | `completed_at` | Date and time of when the scan was completed. | + +## Create a DAST Scan + +```sh +curl -X POST "https://api.us.cobalt.io/dast/targets/YOUR-DAST-TARGET-IDENTIFIER/scans" \ + -H "Accept: application/vnd.cobalt.v2+json" \ + -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ + -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" +``` + +> The above command returns JSON structured like this: + +```json +{ + "resource": { + "id": "dsc_GZgceqweJUNh6mjNuqsE4T", + "target_id": "dt_GZgcehapJUNh6mjNuqsE4T", + "status": "queued", + "started_at": "2024-07-01T10:19:11.160Z", + "completed_at": "2024-07-01T10:19:11.160Z" + } +} +``` + +This endpoint triggers a new DAST scan on the specified target. The scan will start in the `queued` state and +progress to `completed` or `failed`. + +### HTTP Request + +`POST https://api.us.cobalt.io/dast/scans/targets/YOUR-DAST-TARGET-IDENTIFIER/scans` + +### URL Parameters + +| Parameter | Description | +|--------------------------------|--------------------------------------------------------| +| `YOUR-DAST-TARGET-IDENTIFIER` | A unique ID representing the target. Starts with `dt_` | + +### Response Fields + +| Field | Description | +|-----------------|-------------------------------------------------------------------------------------| +| `id` | A unique ID representing the DAST scan. Starts with `dsc_` | +| `target_id` | A unique ID representing the DAST target. Starts with `dt_` | +| `status` | Possible values: [`canceled`, `canceling`, `completed`, `completed_with_errors`, `failed`, `paused`, `pausing`, `queued`, `resuming`, `started`, `under_review`, `finishing_up`] | +| `started_at` | Date and time of when the scan started. | +| `completed_at` | Date and time of when the scan was completed. | diff --git a/versions/v2/content/dast-scheduled-scans.md b/versions/v2/content/dast-scheduled-scans.md new file mode 100644 index 0000000..4454bd8 --- /dev/null +++ b/versions/v2/content/dast-scheduled-scans.md @@ -0,0 +1,62 @@ +--- +weight: 16 +title: DAST Scheduled Scans +--- + +# DAST Scheduled Scans + +## Create a scheduled DAST Scan + +```sh +curl -X POST "https://api.us.cobalt.io/dast/targets/YOUR-DAST-TARGET-IDENTIFIER/scheduled_scans" \ + -H "Accept: application/vnd.cobalt.v2+json" \ + -H "Content-Type: application/vnd.cobalt.v2+json" \ + -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ + -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \ + --data '{ + "date_time": "2024-07-01T10:19:11.160Z", + "recurrence": "WEEKLY" + }' +``` + +> The above command returns JSON structured like this: + +```json +{ + "resource": { + "id": "dsc_GZgceqweJUNh6mjNuqsE4T", + "target_id": "dt_GZgcehapJUNh6mjNuqsE4T", + "date_time": "2024-07-01T10:19:11.160Z", + "recurrence": "WEEKLY" + } +} +``` + +This endpoint creates a new scheduled DAST scan on the specified target. The scan will start when the `date_time` is reached +or the next time the recurrence would happen. + +### HTTP Request + +`POST https://api.us.cobalt.io/dast/scans/targets/YOUR-DAST-TARGET-IDENTIFIER/scheduled_scans` + +### Body + +| Field | Description | +|--------------|--------------------------------------------------------------------------------------------------------------------------------| +| `recurrence` | Optional; if present, the scan will be triggered every certain time period. Available values: `WEEKLY`, `MONTHLY`, `QUARTERLY` | +| `date_time` | Date and time of when the scan will run | + +### URL Parameters + +| Parameter | Description | +|--------------------------------|--------------------------------------------------------| +| `YOUR-DAST-TARGET-IDENTIFIER` | A unique ID representing the target. Starts with `dt_` | + +### Response Fields + +| Field | Description | +|-----------------|-------------------------------------------------------------------------------------| +| `id` | A unique ID representing the DAST scan. Starts with `dsc_` | +| `target_id` | A unique ID representing the DAST target. Starts with `dt_` | +| `date_time` | Date and time of when the scan will run | +| `recurrence` | How often will the scan run. Possible vaules: `WEEKLY`, `MONTHLY`, `QUARTERLY`. Nullable (no recurrence) |