Skip to content
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

Jump to bottom

[FX-4815] Document new available DAST endpoints #263

Merged
merged 20 commits into from
Oct 8, 2024
Merged

[FX-4815] Document new available DAST endpoints #263

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
9d750d6
Add retest finding
davidgm0 Oct 1, 2024
b2b7065
Add dast findings retest
davidgm0 Oct 1, 2024
9d75805
Add create dast scan
davidgm0 Oct 1, 2024
ccbcb40
Add dast scheduled scans
davidgm0 Oct 1, 2024
d2d62fa
Fix scheduled scans title
davidgm0 Oct 1, 2024
af5e5b9
Reword
davidgm0 Oct 1, 2024
3b5f396
Link
davidgm0 Oct 1, 2024
29b3bb2
Merge branch 'main' into chore/FX-4815/update-dast-docs
davidgm0 Oct 1, 2024
e5c527c
Update versions/v2/content/dast-scheduled-scans.md
davidgm0 Oct 1, 2024
4ced799
Update versions/v2/content/dast-scans.md
davidgm0 Oct 1, 2024
7b93ea8
Merge branch 'main' into chore/FX-4815/update-dast-docs
davidgm0 Oct 1, 2024
83861b8
Update to reflect that transition returns the finding
davidgm0 Oct 2, 2024
da46dd4
Try to ignore markdown
davidgm0 Oct 4, 2024
65fc367
Try linking again
davidgm0 Oct 4, 2024
b734411
Fix DAST Scheduled scans title
davidgm0 Oct 8, 2024
d2a40de
Add missing backslash
davidgm0 Oct 8, 2024
a5b2cb8
Add content type to dast scheduled scans
davidgm0 Oct 8, 2024
cdaba73
Correct finding states
davidgm0 Oct 8, 2024
b8df733
Wording
davidgm0 Oct 8, 2024
8523fb2
Merge branch 'main' into chore/FX-4815/update-dast-docs
davidgm0 Oct 8, 2024
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
86 changes: 70 additions & 16 deletions versions/v2/content/dast-findings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since these docs are manually curated, I think it makes more sense to link to avoid duplication and that some parts get outdated


## Get a DAST Finding

Expand Down Expand Up @@ -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 |
|-----------------|-------------------------------------------------------------------------------------|
Expand All @@ -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`] |
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These were not correct. "our" states are correctly listed now.

| `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" \
Copy link

@wolfgangbecker wolfgangbecker Oct 1, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this endpoint exist already?

Copy link
Contributor Author

@davidgm0 davidgm0 Oct 1, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a pending update to change that.

(Note that this repo is public)

-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)
46 changes: 46 additions & 0 deletions versions/v2/content/dast-scans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
62 changes: 62 additions & 0 deletions versions/v2/content/dast-scheduled-scans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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" \
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

needs content-type header
Screenshot 2024-10-07 at 4 57 23 PM

-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) |