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,
                        "implying_answers": []
                    },
                    {
                        "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/",
                        "implying_answers": [
                            {
                                "id": "A4",
                                "text": "Web application",
                                "url": "http://example.com/bunits/test-bu/gigasrc/version-8844-rc2/tasks/survey/questions/app-general/Q199/",
                                "selecting_user_name": "John Doe"
                            }
                        ]
                    }
                ]
            ],
            "component_reason": "component_added_task",
            "component_explanation": "This countermeasure is mapped to the following Diagram components.",
            "introducing_components": [
                {
                    "id": "SC29",
                    "title": "Web Application - Backend",
                    "mapped_answer": {
                        "id": "A4",
                        "text": "Web application",
                        "url": "http://example.com/bunits/test-bu/gigasrc/version-8844-rc2/tasks/survey/questions/app-general/Q199/",
                        "selecting_user_name": "John Doe"
                    }
                }
            ]
        }
    }]
}

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

results matching ""

    No results matching ""