Countermeasures
Get all Countermeasures of a project
This endpoint returns a list of Countermeasures resources associated with the project having id "project_id".
GET /api/v2/projects/{project_id}/tasks/
GET /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"facets": {},
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"problem": "P526",
"phase": "X1",
"manually_added_from_library": false,
"project_specific": false,
"relevant": true,
"relevant_via_survey": true,
"accepted": true,
"assigned_to": [],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"updated": "2020-03-26T22:41:17.922809-04:00",
"updater": 7,
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": "none",
"status": "TS2",
"status_updated": "2020-03-26T22:41:17.922809-04:00",
"note_count": 0,
"artifact_proxy": null
}]
}
Expand parameters
See the Expand Parameters section for more details.
| Parameter | Description |
|---|---|
| text | Description field is expanded into content and amendments sub-fields. |
| status | Status field is expanded into id, meaning, icon, name and slug sub-fields. |
| phase | Phase field is expanded into id, name, slug, description and tip sub-fields. |
| problem | Weakness field is expanded into id, title, text, cwe, and risk rating sub-fields. |
| updater | Updater field is expanded into id, first name, last name, email, role, and active status sub-fields. |
| tags | Tags field is expanded into library-level & project-level tags (requires tags to be included). |
GET /api/v2/projects/1/tasks/?include=tags&expand=text,status,phase,problem,updater,tags HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"facets": {},
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"tags": {
"library_tags": ["foo", "bar"],
"project_tags": ["baz"]
},
"title": "Secure forgotten password",
"text": {
"description": "Insecure forgotten password and password reset...",
"amendments": []
},
"priority": 8,
"problem": {
"id": "P526",
"title": "P526: Weak Password Recovery Mechanism...",
"text": "It is common for an application...",
"cwe": [
{
"url": "http://example.com/640",
"id": 640,
"title": "Weak Password Recovery..."
}
],
"risk_rating": 7
},
"phase": {
"id": "X1",
"name": "Requirements",
"slug": "requirements",
"description": "Application security requirements...",
"tip": "One-time Countermeasures that you can verify...",
"ordinal": 2,
"active": true,
"is_custom": false,
"retain": false,
"db_id": 1
},
"manually_added_from_library": false,
"project_specific": false,
"relevant": true,
"relevant_via_survey": true,
"accepted": true,
"assigned_to": [],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"updated": "2020-03-26T22:41:17.922809-04:00",
"updater": {
"first_name": "Hamish",
"last_name": "Stout",
"is_active": true,
"email": "hamish.stout@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 7
},
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": "none",
"status": {
"id": "TS2",
"meaning": "TODO",
"icon": "clock-o",
"name": "Incomplete",
"requires_comment": false,
"slug": "TODO"
},
"status_updated": "2020-03-26T22:41:17.922809-04:00",
"note_count": 0,
"artifact_proxy": null
}]
}
Include parameters
See the Include Parameters section for more details.
| Parameter | Description |
|---|---|
| how_tos | Includes a list of applicable How-tos. |
| last_note | Includes the last Countermeasure note. |
| last_verification | Includes the last verification note. |
| problem | Includes the Weakness that the Countermeasure is related to. |
| related | Includes a list of related Countermeasures. |
| tags | Includes a list of tags associated to the Countermeasure (both Library & project). |
| regulation_sections | Includes a list of regulation sections to which this Countermeasure belongs. |
| references | Includes a list of Countermeasure references linked to this Countermeasure. |
| training | Includes a list of training courses/modules linked to this Countermeasure. |
| reason_for_inclusion | Includes the reason for a Countermeasure's inclusion within a project. |
GET /api/v2/projects/1/tasks/?include=last_note,last_verification,tags,related,problem,how_tos,references,training,reason_for_inclusion HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"facets": {},
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"phase": "Requirements",
"last_note": {
"automatic": false,
"text": "Countermeasure Note",
"id": 2,
"created": "2018-02-21T15:09:26.321072-05:00",
"updater": "admin@example.com",
"updated": "2018-02-21T15:09:26.321072-05:00"
},
"last_verification": {
"id": 2,
"automatic": false,
"created": "2018-02-21T15:09:38.748141-05:00",
"status": "pass",
"finding_ref": "Verification Reference",
"updated": "2018-02-21T15:09:38.748141-05:00",
"updater": "admin@example.com"
},
"manually_added_from_library": false,
"project_specific": false,
"relevant": true,
"relevant_via_survey": true,
"accepted": true,
"assigned_to": [],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"updated": "2015-06-16T19:37:44.710100Z",
"updater": 7,
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": "pass",
"status": "TS2",
"status_updated": null,
"note_count": 2,
"artifact_proxy": null,
"tags": ["tag1", "tag2"],
"related": [
{
"id": "T227",
"phase": "Testing",
"title": "Verify that application's access to database is restricted",
"url": "http://example.com/bunits/test-bu/codebot/bug-fix-81028-rc3/tasks/phase/testing/2-T227"
},
{
"id": "T14",
"phase": "Architecture & Design",
"title": "Enforce the Principle of Least Privilege",
"url": "http://example.com/bunits/test-bu/codebot/bug-fix-81028-rc3/tasks/phase/architecture-design/2-T14"
}
],
"problem": {
"id": "P526",
"title": "P526: Weak Password Recovery Mechanism...",
"text": "It is common for an application...",
"cwe": [
{
"url": "http://example.com/640",
"id": 640,
"title": "Weak Password Recovery..."
}
],
"risk_rating": 7
},
"how_tos": [
{
"id": "I131",
"title": "Manually with browser",
"slug": "test-account-lockout-manually-browser",
"url": "http://a7069ccda519b00c4/....",
"text": "1. Open your web browser ..."
}
],
"regulation_sections": [
{
"description": "Denial of service (DoS) protection and working in a degraded mode during DoS attacks.",
"id": "RS1026",
"name": "CR2.7 (L3 and higher)",
"regulation_id": "CR45",
"regulation_name": "ANSI/ISA 62443-4-2"
},
{
"description": "Denial of service (DoS) protection and working in a degraded mode during DoS attacks.",
"id": "RS642",
"name": "SR2.7 (L3 and higher)",
"regulation_id": "CR39",
"regulation_name": "ANSI/ISA 62443-3-3"
}
],
"references": [
{
"id": 10,
"issue_tracker_connection": 1,
"reference": "47300",
"name": "US451",
"link": "https://sdetest.atlassian.net/rest/api/2/issue/47300"
}
],
"training": [
{
"title": "OWASP Top 10 2013",
"id": "TR1",
"modules": [
{
"title": "Cross-site request forgery (CSRF)",
"id": "M5",
"link": "/training/module/05_CSRF/",
"completed": false
},
{
"title": "Broken authentication and session management",
"id": "M7",
"link": "/training/module/07_Broken_Auth/",
"completed": true
}
]
},
{
"title": "Development",
"id": "TR6",
"modules": [
{
"title": "Software Development, Operation, Maintenance & Disposal",
"id": "M8",
"link": "/training/module/08_Software_dev/",
"completed": true
}
]
}
],
"reason_for_inclusion": {
"reason": "problem_match_and_task_match",
"explanation": "This Countermeasure's rules are satisfied by any of the following block(s) of survey answers",
"relevant_rules": [
[
{
"id": "A734",
"display_text": "Changes to authentication",
"negated": false,
"hidden": true,
"section_slug": null,
"subsection_id": null,
"question_id": null,
"url": null
},
{
"id": "A758",
"display_text": "Features and Functions > Authentication > Authentication Features > Has direct or third party authentication for end users, devices or nodes",
"negated": false,
"hidden": false,
"section_slug": "app-features",
"subsection_id": "Q199",
"question_id": "Q120",
"url": "http://example.com/bunits/test-bu/gigasrc/version-8844-rc2/tasks/survey/questions/app-features/Q199/"
}
]
]
}
}]
}
Filter parameters
You can filter Countermeasures by their relevance and whether or not they have been accepted into a project by a project lead. If no filters are passed, the default is to return accepted Countermeasures to match with the list shown in the web application.
| Parameter | Expected values | Description | Custom Field Lookup support |
|---|---|---|---|
| accepted | true, false | Filter by Countermeasure's accepted state | supports __in only |
| assigned_to | Filter Countermeasures by assigned user's email/username | Yes | |
| category | string | Filter by category name (internal machine tag names) | Yes |
| library_task_id | standard item id (T21) | Filter by library Countermeasure id | Yes |
| phase | phase slug (development, architecture-design) | Filter by phase | Yes |
| priority | priority value (1-10) | Filter by Countermeasure priority | Yes |
| relevant | true, false | Filter by Countermeasure relevance | No |
| relevant_via_survey | true, false | Filter by Countermeasures that were made relevant via survey | No |
| regulation | regulation item ID (REG53) | Filter Countermeasures by regulation they beyond to | Yes |
| risk_relevant | true, false | Filter by Countermeasure risk policy relevance | No |
| source | default, custom, manual, project | Filter by Countermeasure source (built-in Countermeasure, custom Countermeasure, manually added Library Countermeasure, project-specific Countermeasure) | supports __in only |
| status | status item id (TS1) | Filter by Countermeasure status | Yes |
| tag | tag name | Filter by tags on Countermeasure (standard and Countermeasure-level tags). | No |
| verification | no_dynamic, no_static, pass, partial, fail, none | Filter by Countermeasure verification status | No |
The follow table defines how the accepted and relevant fields affect project Countermeasures.
accepted |
relevant |
Result |
|---|---|---|
| false | false | Countermeasure is no longer part of the project. |
| true | false | Countermeasure is part of the project, but not relevant. Will be flagged for removal by the 'new content updates' widget. |
| false | true | Countermeasure is not part of the project, but is relevant. Will be flagged for addition by the 'new content updates' widget. |
| true | true | Countermeasure is part of the project and relevant, the usual case. |
GET /api/v2/projects/1/tasks/?accepted=true&relevant=false HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"facets": {},
"results": [{
"id": "1-T2",
"task_id": "T2",
"url": "http://example.com/bunits/new-business-unit/...",
"title": "Secure forgotten password",
"text": "Insecure forgotten password and password reset...",
"priority": 8,
"problem": "P526",
"phase": "Requirements",
"manually_added_from_library": false,
"project_specific": false,
"relevant": false,
"accepted": true,
"assigned_to": [],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"updated": "2020-03-26T22:41:17.922809-04:00",
"updater": 7,
"library_task_created": "2015-06-16T19:36:57.863684Z",
"library_task_updated": "2015-06-16T19:36:57.836874Z",
"verification_status": "none",
"status": "TS2",
"status_updated": "2020-03-26T22:41:17.922809-04:00",
"note_count": 0,
"artifact_proxy": null
}]
}
Facets parameter
Countermeasures can return facets that correspond to properties of Countermeasures being queried. Currently, the Countermeasure endpoint performs basic faceting: it shows relevant phases and the number of Countermeasures within them based on current query filters. The parameter accepts either include or only as its acceptable values. If no facets parameter is provided, an empty facets object is returned. Facets respect all filters applied to the query, including search.
| Facets Param Value | Description |
|---|---|
| include | Facets object is computed |
| only | Facets object is computed, results are not returned |
GET /api/v2/projects/1/tasks/?facets=only&accepted=true&relevant=false HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"facets": {
"phases": {
"development": 15,
"requirements": 22,
"architecture-design": 10,
"testing": 42,
"deployment": 1
}
},
"results": []
}
Get a specific Countermeasure
This endpoint retrieves a single Countermeasure resource, as specified by the id parameter.
GET /api/v2/projects/{project_id}/tasks/{task_id}/
GET /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": false,
"project_specific": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "Requirements",
"priority": "8",
"problem": "P526",
"relevant": true,
"relevant_via_survey": true,
"status": "TS2",
"status_updated": "2020-03-26T22:41:17.922809-04:00",
"task_id": "T2",
"title": "Secure forgotten password",
"updated": "2020-03-26T22:41:17.922809-04:00",
"updater": 7,
"url": "http://example.com/bunits/bu1/app1/proj1/tasks/phase/requirements/1-T2",
"verification_status": "none"
}
Create a new project-specific Countermeasure
Creates a new Countermeasure resource that is project-specific.
POST /api/v2/projects/{project_id}/tasks/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project the new Countermeasure belongs to |
Payload
| Fields | Required | Description |
|---|---|---|
| artifact_proxy | No | Arbitrary string which identifies a synchronized Issue Tracker issue. |
| assigned_to | No | A list of emails for users that belong to the project. |
| phase | Yes | The id of a phase. |
| priority | Yes | The priority value from 0-10. |
| problem | No | The id of a Weakness applicable to the project. If unspecified, defaults to the Always Applicable Weakness. |
| status | No | The id of a status. |
| text | Yes | The description of the new Countermeasure. |
| title | Yes | The title of the new Countermeasure. |
| tags | No | A list of tags for the Countermeasure. |
POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"artifact_proxy": "ABC-XYZ",
"assigned_to": ["admin@example.com"],
"phase": "X1",
"priority": 9,
"problem": "P526",
"status": "TS1",
"tags": ["tag1", "tag2"],
"text": "Countermeasure description",
"title": "Project-specific Countermeasure"
}
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": false,
"project_specific": true,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"text": "Countermeasure description",
"id": "1-PT1",
"library_task_created": "2015-05-07T18:58:26.732000Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "X1",
"priority": "9",
"problem": "P526",
"relevant": true,
"relevant_via_survey": false,
"status": "TS1",
"status_updated": null,
"tags": ["tag1", "tag2"],
"task_id": "PT1",
"title": "Project-specific Countermeasure",
"updater": 7,
"updated": "2015-05-07T18:58:26.732000Z",
"url": "http://example.com/.../1-PT1",
"verification_status": "none"
}
Create a new Countermeasure from an existing Library Countermeasure
Add a Library Countermeasure to a project. Only Library Countermeasures that aren't applicable to a project can be added.
POST /api/v2/projects/{project_id}/tasks/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project the new Countermeasure belongs to |
Payload
| Fields | Required | Description |
|---|---|---|
| artifact_proxy | No | Arbitrary string which identifies a synchronized Issue Tracker issue |
| assigned_to | No | A list of emails for users that belong to the project |
| status | No | The id of a status |
| task_id | Yes | The id of the Library Countermeasure to add to the project. |
| tags | No | A list of tags that will be added to this Countermeasure for this project only. |
POST /api/v2/projects/1/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"task_id": "T21"
}
HTTP/1.1 201 CREATED
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": true,
"project_specific": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"text": "Countermeasure description",
"id": "1-T21",
"library_task_created": "2015-05-07T18:58:26.732000Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "X1",
"priority": "8",
"problem": "P712",
"relevant": false,
"status": "TS1",
"status_updated": null,
"task_id": "T21",
"title": "Ensure Confidential Data Is Sent Over an Encrypted Channel",
"updater": 7,
"updated": "2015-05-07T18:58:26.732000Z",
"url": "http://example.com/.../1-T21",
"verification_status": "none"
}
Update a specific Countermeasure
Updates a single Countermeasure resource, as specified by the project_id and Countermeasure id parameters.
PATCH /api/v2/projects/{project_id}/tasks/{id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project this Countermeasure belongs to |
| id | The id of the Countermeasure to modify |
Payload
| Fields | Required | Description |
|---|---|---|
| artifact_proxy | No | Arbitrary string which identifies a synchronized Issue Tracker issue. |
| assigned_to | No | A list of emails for users that belong to the project. |
| phase | No | The id of a phase. Available only if the updated Countermeasure is a project-specific Countermeasure. |
| priority | No | The priority value from 0-10. Available only if the updated Countermeasure is a project-specific Countermeasure. |
| problem | No | The id of a Weakness applicable to the project. Available only if the updated Countermeasure is a project-specific Countermeasure. |
| status | No | The id of a status. |
| status_note | No | Create a note related to the status change. |
| tags | No | A list of tags that will be set for this Countermeasure for this project only. |
| text | No | The description of the Countermeasure. Available only if the updated Countermeasure is a project-specific Countermeasure. |
| title | No | The title of the Countermeasure. Available only if the updated Countermeasure is a project-specific Countermeasure. |
PATCH /api/v2/projects/1/tasks/1-T2/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
{
"artifact_proxy": "ABC-XYZ",
"assigned_to": ["user1@example.com", "user2@example.com"],
"problem": "P526",
"status": "TS1",
"tags": ["tag1", "tag2"]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"accepted": true,
"manually_added_from_library": false,
"project_specific": false,
"artifact_proxy": "ABC-XYZ",
"assigned_to": [
{
"first_name": "Admin",
"last_name": "Testerton",
"is_active": true,
"email": "admin@example.com",
"role": {
"id": "UR1",
"name": "User"
},
"id": 1
}
],
"became_relevant": "2016-02-16T16:47:02.997851-05:00",
"text": "Insecure forgotten password.",
"id": "1-T2",
"library_task_created": "2010-10-20T17:46:50Z",
"library_task_updated": "2015-05-07T18:58:26.732000Z",
"note_count": 0,
"phase": "X1",
"priority": "8",
"problem": "P526",
"relevant": true,
"relevant_via_survey": true,
"status": "TS1",
"status_updated": "2020-03-26T22:41:17.922809-04:00",
"task_id": "T2",
"tags": ["tag1", "tag2"],
"title": "Secure forgotten password",
"updated": "2020-03-26T22:41:17.922809-04:00",
"updater": 7,
"url": "http://example.com/.../1-T2",
"verification_status": "none"
}
Delete a Countermeasure
Delete a single Countermeasure resource, as specified by the project_id and Countermeasure id parameters.
Only manually added Library Countermeasures and project-specific Countermeasures may be deleted.
DELETE /api/v2/projects/{project_id}/tasks/{id}/
URL Parameters
| Parameter | Description |
|---|---|
| project_id | The id of the project this Countermeasure belongs to |
| id | The id of the Countermeasure to delete |
DELETE /api/v2/projects/2/tasks/2-T21/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"
HTTP/1.1 204 NO CONTENT