--- title: "Pentests" description: "Get All Pentests" canonical_url: "https://cobalt-io.brainfish.ai/articles/pentests-u7hbZA15Ha" md_url: "https://cobalt-io.brainfish.ai/articles/pentests-u7hbZA15Ha.md" --- # Pentests ## **Get All Pentests** This endpoint retrieves a list of all pentests that belong to the organization specified in the `X-Org-Token` header. ### **HTTP Request** `GET https://api.us.cobalt.io/pentests` ### **URL Parameters** | **Parameter** | **Default** | **Description** | |----|----|----| | `asset` | N/A | If specified, returns pentests scoped to this asset id. Example: `https://api.us.cobalt.io/pentests?asset=as_GZgcehapJUNh6mjNuqsE4T` or 404 if asset not found | | `cursor` | N/A | Used for [pagination](https://docs.cobalt.io/en-us/articles/pagination-vzZ5elaKl7). Example: `https://api.us.cobalt.io/pentests?cursor=a1b2c3d4` | | `limit` | 10 | If specified, returns only a specified amount of pentests. Example: `https://api.us.cobalt.io/pentests?limit=5` | | `sort` | N/A | If specified, returns pentests sorted by one of the chosen properties: `start_date,` or `end_date.` When defined, pentests are sorted in ascending order by the sort property. To sort in descending order, use a `-` before the sort property. Example: `https://api.us.cobalt.io/pentests?sort=-start_date.` | | `state` | N/A | If specified, returns pentests that match `state.` See Response Fields below for example `state` values. Example: `https://api.us.cobalt.io/pentests?state=new`. Returns an empty list if no pentests match the `state` filter. | | `testing_type` | N/A | If specified, returns pentests that match `testing_type.` See Response Fields below for example `testing_type` values. Example: `https://api.us.cobalt.io/pentests?testing_type=agile.` Returns an empty list if no pentests match the `testing_type` filter. | | `platform_tags_contains_all[]` | N/A | If specified, returns pentests that contain all specified platform tags. This query parameter can be specified multiple times. Returns an empty list if no matches are found. Example: `https://api.us.cobalt.io/pentests?platform_tags_contains_all[]=Kotlin&platform_tags_contains_all[]=AWS` | | `start_date_lte` | N/A | If specified, returns pentests where the start_date is less than or equal to the input date. Input format: `YYYY-MM-DD.` Returns an empty list if no pentests match the filter. Example: `https://api.us.cobalt.io/pentests?start_date_lte=2021-04-16` | | `start_date_gte` | N/A | If specified, returns pentests where the start_date is greater than or equal to the input date. Input format: `YYYY-MM-DD.` Returns an empty list if no pentests match the filter. Example: `https://api.us.cobalt.io/pentests?start_date_gte=2021-04-16` | | `end_date_lte` | N/A | If specified, returns pentests where the end_date is less than or equal to the input date. Input format: `YYYY-MM-DD`. Returns an empty list if no pentests match the filter. Example: `https://api.us.cobalt.io/pentests?end_date_lte=2021-04-16` | | `end_date_gte` | N/A | If specified, returns pentests where the end_date is greater than or equal to the input date. Input format: `YYYY-MM-DD.` Returns an empty list if no pentests match the filter. Example: `https://api.us.cobalt.io/pentests?end_date_gte=2021-04-16` | ### **Response Fields** | **Field** | **Description** | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_` | | `title` | The title of the returned pentest. | | `objectives` | The objectives of the pentest, for example, “Coverage of OWASP Top 10” | | `asset_id` | ID of the asset that the returned pentest belongs to | | `testing_type` | Pentest testing type, where can be: agile or comprehensive | | `platform_tags ` | Tech stack of the target, for example, Java, Kotlin, Ruby, or AWS. | | `methodology` | Pentest methodology. Web, API, Web+API, Mobile, External Network and so on. | | `targets` | Targetted IP addresses, domains, services, and so on. | | `start_date` | The starting date of the pentest. Format: Dec 11 2019 | | `end_date` | The ending date of the pentest. Format: Dec 11 2019 | | `state` | `new`, `in_review`, `planned`, `cancelled`, `live`, `remediation`, `or closed` | | `links.ui.url` | A link to redirect an authorized user to this pentest in the Cobalt web application | ```javascript curl -X GET "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER" \ -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: ```javascript { "data": { "resource": { "id": "pt_JQJpAAMjyc8sVtXW2X2Aq5", "title": "HR System Security Test 2022-Q4", "objectives": "Coverage of OWASP top 10, ASVS and application logic.", "state": "new", "tag": "#PT5940", "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL", "testing_type": "agile", "platform_tags": [ "rails", "ruby", "aws" ], "methodology": "web", "targets": [ "https://cobalt.io", "192.168.1.1" ], "start_date": "Dec 11 2019", "end_date": "Dec 25 2019" }, "links": { "ui": { "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz=" } } } } ``` :::info Remember - you can only request pentests scoped to the organization specified in the `X-Org-Token` header. ::: --- ## **Get a Pentest** This endpoint retrieves a specific pentest that belongs to the organization specified in the `X-Org-Token` header. ### **HTTP Request** `GET https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE` ### **Response Fields** | **Field** | **Description** | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_` | | `title` | The title of the returned pentest. | | `objectives` | The objectives of the pentest. for example “Coverage of OWASP Top 10” | | `asset_id` | ID of the asset that the returned pentest belongs to | | `testing_type` | Pentest testing type, where can be: agile or comprehensive | | `platform_tags` | Tech stack of the target. for example java, kotlin, ruby, aws, and so on. | | `methodology` | Pentest methodology. Web, API, Web+API, Mobile, External Network and so on. | | `targets` | Targetted IP addresses, domains, services, and so on. | | `start_date` | The starting date of the pentest. Format: Dec 11 2019 | | `end_date` | The ending date of the pentest. Format: Dec 11 2019 | | `state` | `new`, `in_review`, `planned`, `cancelled`, `live`, `remediation`, `or closed` | | `links.ui.url ` | A link to redirect an authorized user to this pentest in the Cobalt web application | ```javascript curl -X GET "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER" \ -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: ```javascript { "data": { "resource": { "id": "pt_JQJpAAMjyc8sVtXW2X2Aq5", "title": "HR System Security Test 2022-Q4", "objectives": "Coverage of OWASP top 10, ASVS and application logic.", "state": "new", "tag": "#PT5940", "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL", "testing_type": "agile", "platform_tags": [ "rails", "ruby", "aws" ], "methodology": "web", "targets": [ "https://cobalt.io", "192.168.1.1" ], "start_date": "Dec 11 2019", "end_date": "Dec 25 2019" }, "links": { "ui": { "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz=" } } } } ``` :::info Remember - you can only request a pentest scoped to the organization specified in the `X-Org-Token` header. ::: --- ## **Get a Pentest Report** This endpoint retrieves the report for a specific pentest that belongs to the organization specified in the `X-Org-Token `header. The pentest must be in one of the states `live`, `remediation`, or `closed`. Note that being able to view a pentest does not equal the ability to view a pentest report. Pentest report visibility depends on a number of factors: * Whether or not the pentest report has been finalized. * The role within the organization of the user who owns the API token. If this endpoint returns a `404` but the underlying pentest is viewable, it’s likely a permissions issue. ### **HTTP Request** `GET https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE/report` ### **Response Fields** | **Field** | **Description** | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_`. | | `title` | Optional; if present, the title of the returned pentest. | | `state` | One of `live`, `remediation`, or `closed` (reports can not be generated for pentests in other states). | | `asset` | Optional; if present, an object representing the asset associated with this pentest. | | `asset.id` | The unique ID representing the asset associated with this pentest. Starts with `as_`. | | `pentesters` | Optional; if present, a list of the pentesters who performed this pentest. | | `report` | Optional; if present, a summary of this pentest’s findings and recommendations. | | `findings` | A list of the findings broken down by both `severity` and `state`. `severity` is not a required field so some findings may appear in the state section but not in `severity`. For a list of the valid `severity` keys, refer to the table in the [Calculations](https://docs.cobalt.io/en-us/articles/findings-D4kEiuzfAW#h-get-all-findings) section. For a list of valid `state` keys refer to the [States](https://docs.cobalt.io/en-us/articles/findings-D4kEiuzfAW#h-states) section. | | `accepted_risks` | Optional; if present, a list of the accepted risk findings. For details, refer to the [Accepted Risk Response Fields](https://docs.cobalt.io/en-us/articles/pentests-u7hbZA15Ha#h-accepted-risk-response-fields) section below. | | `links.ui.url` | A link to redirect an authorized user to this pentest in the Cobalt web application. | ### **Pentester Response Fields** | **Field** | **Description** | |----|----| | `username` | The username of the pentester. | | `full_name` | The full name of the pentester; can be `null`. | ### **Report Response Fields** | **Field** | **Description** | |----|----| | `report_state` | Optional; if present, one of `new_state`, `draft, in_review`, or `final`. | | `title` | Optional; if present, the title of the pentest. | | `starts_at` | Optional; if present, the date the pentest starts. | | `ends_at` | Optional; if present, the date the pentest ends. | | `executive_summary` | Optional; if present, a high-level overview of the pentest. | | `executive_analysis` | Optional; if present, a high-level analysis of the pentest. | | `scope_of_work` | Optional; if present, a description of the scope of work. | | `summary_of_findings` | Optional; if present, a high-level summary of the findings. | | `summary_of_recommendations` | Optional; if present, a high-level summary of the recommendations. | ### **Accepted Risk Response Fields** | **Field** | **Description** | |----|----| | `finding_id` | A unique ID representing the finding. Starts with `vl_`. | | `accepted_risk_reason` | One of `low_severity`, `mitigated_by_waf`, `mitigated_by_other`, `no_longer_relevant`, `third_party_dependencies`, `internal_dependencies`, `intended_functionality`, or `other`. | | `state` | The state of the finding. | ```javascript ``` Remember - you can only request the report for a pentest scoped to the organization specified in the `X-Org-Token` header. --- ## **Duplicate a Pentest** This endpoint creates a duplicate pentest based on the identifier provided. The pentest to be duplicated must exist and belong to the organization specified in the `X-Org-Token` header. Note there is **no Request** **body** required for this endpoint. Note that you **cannot** duplicate a pentest that is in Draft state. The new pentest will be in **Draft state** and will have the same brief as the pentest provided in the identifier. ### **HTTP Request** `POST https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE/duplicate` ### **Response** You get a `201` response code for a successful request. The `Location` response header contains the URL of the new pentest within the Cobalt API. | **Field** | **Description** | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_` | | `title` | The title of the returned pentest. | | `objectives` | The objectives of the pentest. for example “Coverage of OWASP Top 10” | | `asset_id` | ID of the asset that the returned pentest belongs to | | `testing_type` | Pentest testing type, where can be: agile or comprehensive | | `platform_tags` | Tech stack of the target. for example java, kotlin, ruby, aws, and so on. | | `methodology` | Pentest methodology. Web, API, Web+API, Mobile, External Network and so on. | | `targets` | Targetted IP addresses, domains, services, and so on. | | `start_date` | The starting date of the pentest. Format: Dec 11 2019 | | `end_date` | The ending date of the pentest. Format: Dec 11 2019 | | `state` | `new`, `in_review`, `planned`, `cancelled`, `live`, `remediation`, or `closed` | | `links.ui.url` | A link to redirect an authorized user to this pentest in the Cobalt web application | ```javascript curl -X GET "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER/report" \ -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: ```javascript { "data": { "resource": { "id": "pt_JQJpAAMjyc8sVtXW2X2Aq5", "title": "Pentest Title", "state": "live", "asset": { "id": "as_4L4ZjKgfzP7VBwUmqCZmmL", }, "pentesters": [ { "username": "user1", "full_name": "User One" }, { "username": "user2", "full_name": null } ], "report": { "report_state": "final", "title": "Pentest Title", "starts_at": "2022-06-09", "ends_at": "2022-06-13", "executive_summary": "A pentest.", "executive_analysis": "A pentest.", "scope_of_work": "Everything.", "summary_of_findings": "Some findings were found.", "summary_of_recommendations": "Fix some things." }, "findings": { "severity": { "informational": [ { "id": "vl_3sP2RCWWUajc3oRXmbQ4j2", }, { "id": "vl_3sP2RCWWUajc3oRXmbQ4j3", } ], "low": [ { "id": "vl_3sP2RCWWUajc3oRXmbQ4j4", } ], "medium": [], "high": [ { "id": "vl_3sP2RCWWUajc3oRXmbQ4j5", } ], "critical": [] }, "state": { "new": [], "triaging": [ { "id": "vl_3sP2RCWWUajc3oRXmbQ4j5", } ], "invalid": [ { "id": "vl_3sP2RCWWUajc3oRXmbQ4j3", } ], "duplicate": [], "out_of_scope": [ { "id": "vl_3sP2RCWWUajc3oRXmbQ4j2", } ], "need_fix": [], "wont_fix": [], "check_fix": [], "valid_fix": [] } }, "accepted_risks": [ { "finding_id": "vl_VuLnerabiLityVuLnerab4", "accepted_risk_reason": "internal_dependencies", "state": "wont_fix" } ] }, "links": { "ui": { "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz=" } } } } ``` :::info Remember - you can only duplicate a pentest within the organization specified in the `X-Org-Token` header. ::: --- ## **Duplicate a Pentest** This endpoint creates a duplicate pentest based on the identifier provided. The pentest to be duplicated must exist and belong to the organization specified in the `X-Org-Token` header. Note there is **no Request body** required for this endpoint. Note that you **cannot** duplicate a pentest that is in Draft state. The new pentest will be in **Draft state** and will have the same brief as the pentest provided in the identifier. ### **HTTP Request** `POST https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE/duplicate` ### **Response** You get a `201` response code for a successful request. The `Location` response header contains the URL of the new pentest within the Cobalt API. | Field | Description | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_` | | `title` | The title of the returned pentest. | | `objectives` | The objectives of the pentest. for example “Coverage of OWASP Top 10” | | `asset_id` | ID of the asset that the returned pentest belongs to | | `testing_type` | Pentest testing type, where can be: agile or comprehensive | | `platform_tags` | Tech stack of the target. for example java, kotlin, ruby, aws, and so on. | | `methodology` | Pentest methodology. Web, API, Web+API, Mobile, External Network and so on. | | `targets` | Targetted IP addresses, domains, services, and so on. | | `start_date` | The starting date of the pentest. Format: Dec 11 2019 | | `end_date` | The ending date of the pentest. Format: Dec 11 2019 | | `state` | `new, in_review`, `planned`, `cancelled`, `live,` `remediation`, or `closed` | | `links.ui.url` | A link to redirect an authorized user to this pentest in the Cobalt web application | ```javascript curl -X POST "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER/duplicate" \ -H "Accept: application/vnd.cobalt.v2+json" \ -H "Content-Type: application/vnd.cobalt.v2+json" \ -H "Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION" \ -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" ``` The above command returns the new duplicate pentest and a `201` response code when successful. There will be a `Location` header pointing at the newly created pentest. ```javascript { "data": { "resource": { "id": "pt_MsZGgJW55dJZxAs2AgXAF5", "title": "[COPY] foobar - September 2023", "objectives": "", "state": "new", "tag": "#PT83653", "asset_id": "as_7PFxAamzsqDNixMcQoR723", "platform_tags": [ "rails" ], "methodology": "web", "targets": [ "127.0.0.1" ], "start_date": null, "end_date": null, "testing_type": "agile" }, "links": { "ui": { "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoiUEVOVEVTVCIsIm9yZ1NsdWciOiJna3VobnMtdGVzdC1vcmciLCJwZW50ZXN0VGFnIjoiY29weS1mb29iYXItc2VwdGVtYmVyLTIwMjMtcHQ4MzY1MyIsImZpbmRpbmdJZCI6IiIsImFzc2V0VGFnIjoiIn0=" } } } } ``` --- ## **Create a Pentest** This endpoint creates a new pentest from the information provided. The pentest will belong to the organization specified in the `X-Org-Token` header. The pentest will be in the **Draft state**. ### **HTTP Request** `POST https://api.us.cobalt.io/pentests` ### **Body** | **Field** | **Description** | |----|----| | `asset_id` | The ID of the asset being pentested; this asset must exist and belong to the organization specified in the `X-Org-Token` header. | | `title` | The title of the pentest. | | `description` | A description of the pentest. | | `technology_stack` | A comma separated list of technologies in use; for example, “Ruby, Go, C#” | | `instructions` | Optional; if present, instructions for the pentesters. | | `additional_requests` | Optional; if present, special requests or instructions for the pentesters. | | `test_credentials` | Optional; if present, credentials to be used by the pentesters. | | `test_credentials_option ` | Optional; if present, additional information about the credentials. Must be one of the following: `provided`, `distributed`, `not_required` | | `targets` | Optional; if present, the URLs, endpoints, etc. being targeted by the pentest. A comma separated list; `"1.1.1.1, https://cobalt.io"` | | `testing_type` | Optional; If present, this will be the type of the pentest. Must be one of the following: `agile`, `comprehensive`. Default: `comprehensive` | | `scoping` | Optional; if present, information about the size of the pentest. For details, refer to the [Scoping Body Fields](https://docs.cobalt.io/en-us/articles/pentests-u7hbZA15Ha#h-scoping-body-fields) section below. | ### **Scoping Body Fields** If scoping data is provided, it must match the type of the asset being pentested. For example, if the asset being pentested is of type `API`, the API-related scoping fields should be filled in. | **Field** | **Description** | |----|----| | `api.num_of_endpoints` | The number of API endpoints to be pentested. | | `api.num_of_roles` | The number of roles to be pentested per API endpoint. | | `cloud_config.num_of_services` | The number of cloud services to be pentested. | | `cloud_config.num_of_accounts` | The number of roles to be pentested per cloud service. | | `mobile.num_of_views` | The number of mobile app views to be pentested. | | `mobile.num_of_roles` | The number of roles to be pentested per mobile app view. | | `mobile.num_of_operating_systems ` | The number of operating systems to be pentested per mobile app. | | `network.num_of_ips` | The number of network IP addresses to be pentested. | | `web.num_of_pages` | The number of web pages to be pentested. | | `web.num_of_roles` | The number of roles to be pentested per web page. | ### **Response** You get a `201` response code for a successful request. The `Location` response header contains the URL of the new pentest within the Cobalt API. | **Field** | **Description** | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_` | | `title` | The title of the returned pentest. | | `objectives` | The objectives of the pentest. for example “Coverage of OWASP Top 10” | | `asset_id` | ID of the asset that the returned pentest belongs to | | `testing_type` | Pentest testing type, where can be: agile or comprehensive | | `platform_tags ` | Tech stack of the target. for example java, kotlin, ruby, aws, and so on. | | `methodology` | Pentest methodology. Web, API, Web+API, Mobile, External Network and so on. | | `targets` | Targetted IP addresses, domains, services, and so on. | | `start_date` | The starting date of the pentest. Format: Dec 11 2019 | | `end_date` | The ending date of the pentest. Format: Dec 11 2019 | | `state` | `new`, `in_review`, `planned`, `cancelled`, `live`, `remediation`, or `closed` | | `links.ui.url` | A link to redirect an authorized user to this pentest in the Cobalt web application | ```javascript curl -X POST "https://api.us.cobalt.io/pentests" \ -H "Accept: application/vnd.cobalt.v2+json" \ -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ -H "Content-Type: application/vnd.cobalt.v2+json" \ -H "Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION" \ -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \ --data '{ "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL", "title": "Pentest Title", "description": "Pentest description.", "technology_stack": "ruby,golang,rails,kotlin", "instructions": "The pentest target is the v1 endpoints", "additional_requests": "Do not test webhook endpoints.", "test_credentials": "Account: foobar, password: foobar", "test_credentials_option": "provided", "targets": "1.1.1.1,https://google.com", "testing_type": "comprehensive", "scoping": { "api": { "num_of_endpoints": 1, "num_of_roles": 1 } } }' ``` The above command returns the created pentest and a `201` response code when successful. There will be a `Location` header pointing at the newly created pentest. ```javascript "data": { "resource": { "id": "pt_G8kBTQUR3Nrmv3mWzYvzxT", "title": "Pentest Title", "objectives": "", "state": "new", "tag": "#PT83597", "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL", "platform_tags": [ "ruby", "golang", "rails", "kotlin" ], "methodology": "api", "targets": [ "1.1.1.1", "https://google.com" ], "start_date": null, "end_date": null, "testing_type": "comprehensive" }, "links": { "ui": { "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoiUEVOVEVTVCIsIm9yZ1NsdWciOiJna3VobnMtdGVzdC1vcmciLCJwZW50ZXN0VGFnIjoicGVudGVzdC10aXRsZS1wdDgzNTk3IiwiZmluZGluZ0lkIjoiIiwiYXNzZXRUYWciOiIifQ==" } } } } ``` :::info Remember - you can only create a pentest within the organization specified in the `X-Org-Token` header. ::: --- ## **Update a Pentest** This endpoint updates a pentest from the information provided. ### **HTTP Request** `PUT https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER` ### **Body** | **Field** | **Description** | |----|----| | `asset_id` | The ID of the asset being pentested; this asset must exist and belong to the organization specified in the `X-Org-Token` header. | | `title` | The title of the pentest. | | `description` | A description of the pentest. | | `technology_stack` | A description of the technology stacks in use; for example, C# or Ruby on Rails. | | `instructions` | Optional; if present, instructions for the pentesters. | | `additional_requests` | Optional; if present, special requests or instructions for the pentesters. | | `test_credentials` | Optional; if present, credentials to be used by the pentesters. | | `test_credentials_option` | Optional; if present, additional information about the credentials. | | `targets` | Optional; if present, the URLs, endpoints, etc being targeted by the pentest. | | `testing_type` | Optional; If present, this will be the new type of the pentest. Must be one of the following: `agile`, `comprehensive`. | | `scoping` | Optional; if present, information about the size of the pentest. For details, refer to the [Scoping Body Fields](https://docs.cobalt.io/en-us/articles/pentests-u7hbZA15Ha#h-scoping-body-fields) section below. | ### **Scoping Body Fields** If scoping data is provided, it must match the type of the asset being pentested. For example, if the asset being pentested is of type `API`, the API-related scoping fields should be filled in. | **Field** | **Description** | |----|----| | `api.num_of_endpoints` | The number of API endpoints to be pentested. | | `api.num_of_roles` | The number of roles to be pentested per API endpoint. | | `cloud_config.num_of_services` | The number of cloud services to be pentested. | | `cloud_config.num_of_accounts` | The number of roles to be pentested per cloud service. | | `mobile.num_of_views` | The number of mobile app views to be pentested. | | `mobile.num_of_roles` | The number of roles to be pentested per mobile app view. | | `mobile.num_of_operating_systems` | The number of operating systems to be pentested per mobile app. | | `network.num_of_ips` | The number of network IP addresses to be pentested. | | `web.num_of_pages` | The number of web pages to be pentested. | | `web.num_of_roles` | The number of roles to be pentested per web page. | ### **Response** On success, a `200` response code will be returned. | **Field** | **Description** | |----|----| | `id` | A unique ID representing the pentest. Starts with `pt_` | | `title` | The title of the returned pentest. | | `objectives` | The objectives of the pentest. for example “Coverage of OWASP Top 10” | | `asset_id` | ID of the asset that the returned pentest belongs to | | `testing_type` | Pentest testing type, where can be: agile or comprehensive | | `platform_tags` | Tech stack of the target. for example java, kotlin, ruby, aws, and so on. | | `methodology` | Pentest methodology. Web, API, Web+API, Mobile, External Network and so on. | | `targets` | Targetted IP addresses, domains, services, and so on. | | `start_date` | The starting date of the pentest. Format: Dec 11 2019 | | `end_date` | The ending date of the pentest. Format: Dec 11 2019 | | `state` | `new`, `in_review`, `planned`, `cancelled`, `live`, `remediation`, or `closed` | | `links.ui.url` | A link to redirect an authorized user to this pentest in the Cobalt web application | ```javascript curl -X PUT "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER" \ -H "Accept: application/vnd.cobalt.v2+json" \ -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \ -H "Content-Type: application/vnd.cobalt.v2+json" \ -H "Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION" \ -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \ --data '{ "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL", "title": "Pentest Title", "description": "Pentest description.", "technology_stack": "ruby,golang,rails,kotlin", "instructions": "The pentest target is the v1 endpoints", "additional_requests": "Do not test webhook endpoints.", "test_credentials": "Account: foobar, password: foobar", "test_credentials_option": "provided", "targets": "1.1.1.1,https://google.com", "testing_type": "comprehensive", "scoping": { "api": { "num_of_endpoints": 1, "num_of_roles": 1 } } }' ``` The above command returns the updated pentest and a `204` response code when successful. ```javascript { "data": { "resource": { "id": "pt_8T215LptHHFKhdRENjm8Ka", "title": "Pentest Title", "objectives": "Pentest description.", "state": "new", "tag": "#PT83652", "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL", "platform_tags": [ "ruby", "golang", "rails", "kotlin" ], "methodology": "api", "targets": [ "1.1.1.1", "https://google.com" ], "start_date": null, "end_date": null, "testing_type": "comprehensive" }, "links": { "ui": { "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoiUEVOVEVTVCIsIm9yZ1NsdWciOiJna3VobnMtdGVzdC1vcmciLCJwZW50ZXN0VGFnIjoicGVudGVzdC10aXRsZS1wdDgzNjUyIiwiZmluZGluZ0lkIjoiIiwiYXNzZXRUYWciOiIifQ==" } } } } ``` :::info Remember - you can only update a pentest within the organization specified in the `X-Org-Token` header. ::: --- ## **Delete a Pentest** This endpoint deletes a pentest belonging to the organization specified in the header. Note that you **can** only delete a pentest when it is in draft or review state. ### **HTTP Request** `DELETE https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER` ### **Response** On successful deletion, a `204` response code will be returned. ```javascript curl -X DELETE 'https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER' \ -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. Remember - you can only delete a pentest within the organization specified in the `X-Org-Token` header.