Library Countermeasures

⚠️ Breaking Changes for the Library Countermeasures API endpoint (/api/v2/library/tasks/) in 2024.3:

  • The 'active' field for Library Countermeasures will always be included in the API response. Previously the 'active' field was only included if 'include=active' param was specified.
  • The include param 'active' has been deprecated and will be removed.
  • The API endpoint will now include deactivated Library Countermeasures in the API response by default. Previously it only returned active Library Countermeasures and required the use of the hidden param 'show_inactive=true' to include deactivated Library Countermeasures in the API response.
  • The 'show_inactive' param has been deprecated and will be removed. To filter by active or inactive Library Countermeasures, use the new 'active' query parameter

Get all Library Countermeasures

This endpoint retrieves a list of Library Countermeasure resources.

GET /api/v2/library/tasks/

Query parameters

The following parameters may be used to filter the Library Countermeasure resources in the response.

Parameter Description
ordering Sort Countermeasures by the specified field. Prefix field name with minus to sort descending. Sortable fields: last_update_date, last_updated_by.
priority Given a priority 0-10, returns all Countermeasures matching specified priority
priority__in Given a list of priorities 0-10 separated by ,s, returns all Countermeasures matching specified priorities
phase Given a Phase id, returns all Countermeasures in specified Phase
phase__in Given a list of Phase ids separated by ,s, returns all Countermeasures in specified Phases
tag Given a tag, returns all Countermeasures with the specified tag (multiple tags can be provided, e.g. ?tag=tag1&tag=tag2)
type__in Returns all Weaknesses which are either built-in, built-in modified or custom
active Filter Countermeasures based on whether they are active or not. Valid values: true, false.
absolute_urls Whether to use absolute or relative urls (default is False)
to_html Whether to convert markdown to html (default is False)
show_inactive Whether to show inactive Countermeasures (default is False). Removed in 2024.3, use ?active=True to show only active Countermeasures.
show_original Whether to return to the original content for a Built-In Modified Countermeasure (default is False).
last_updated_date_from Returns all Countermeasures updated at or after the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime.
last_updated_date_to Returns all Countermeasures updated at or before the specified date. Note that if you would like to filter the date by UTC time, add a 'Z' to the end of the time. Otherwise, it is assumed you are filtering using local time. This is consistent with the ISO format, which we use for our dates. An example of the format can be found here: https://www.w3.org/TR/NOTE-datetime.
last_updated_by Given a specific User id, returns all Countermeasures updated by the User matching the specified id
last_updated_by__in Given a list of User ids separated by ,s, returns all Countermeasures updated by any of the Users matching the specified ids
regulation Given a Compliance Regulation id, returns all Library Countermeasures with Compliance Regulations matching specified id
regulation__in Given a list of Compliance Regulation ids separated by ,s, returns all Library Countermeasures with Compliance Regulations matching specified ids
regulation__isnull Whether to return Library Countermeasures with empty or non-empty regulation sections (default is False)
problem Given a Weakness id, returns all Library Countermeasures with specified Weakness id 
GET /api/v2/library/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "db_id": 1,
        "url": "http://example.com/library/tasks/T179/",
        "problem": "P1",
        "title": "Allow access for users to remove their data from the system",
        "text": "Some example description",
        "phase": "X1",
        "id": "T179",
        "active": true,
        "type": "Built-in",
        "created_by": {
            "id": 1,
            "email": "admin@example.com",
            "first_name": "Admin",
            "last_name": "Testerton"
        },
        "created_date": "2019-05-15T16:52:17.415000-04:00",
        "last_updated_date": "2021-06-25T14:47:43.788000-04:00",
        "last_updated_by": {
            "id": 1,
            "email": "admin@example.com",
            "first_name": "Admin",
            "last_name": "Testerton"
        }
    }]
}

Expand parameters

See the Expand Parameters section for more details.

Parameter Description
problem Expands the Weakness fields in the Countermeasure response object
phase Expands the phase field
answers The answers field is expanded. 
GET /api/v2/library/tasks/?expand=problem HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "db_id": 1,
        "tags": [],
        "url": "http://example.com/library/tasks/T179/",
        "problem": {
        "risk_rating": 5,
                "text": "This is some example content.",
                "cwe": [{
                    "url": "http://cwe.mitre.org/data/definitions/359",
                    "title": "Exposure of Private Information ('Privacy Violation')",
                    "cwe_id": 359
                }],
            "id": "P257",
            "db_id": 257,
            "title": "P257: Privacy Violation"
        },
        "title": "Allow access for users to remove their data from the system",
        "text": "Some example description",
        "phase": "X1",
        "id": "T179",
        "active": true,
        "type": "Built-in",
        "created_by": {
            "id": 1,
            "email": "admin@example.com",
            "first_name": "Admin",
            "last_name": "Testerton"
        },
        "created_date_time": "2019-05-15T16:52:17.415000-04:00",
        "last_updated_date": "2021-06-25T14:47:43.788000-04:00",
        "last_updated_by": {
            "id": 1,
            "email": "admin@example.com",
            "first_name": "Admin",
            "last_name": "Testerton"
        }
    }]
}

Include Parameters

See the Include Parameters section for more details.

Parameter Description
amendments Includes a list of amendments on each Countermeasure
categories Includes a list of categories that apply to each Countermeasure
how_tos Includes a list of How-Tos for each Countermeasure. These are language specific examples of how to implement the Countermeasure
tags Includes a list of tags attached to each Countermeasure
match_conditions Includes a list of match conditions attached to each Countermeasure and if combined with the expand problem param will also show the match conditions for the problem
verification_coverage Includes a list of verification coverages of each Countermeasure
active Returns a Boolean indicating whether the Countermeasure is active. Removed in 2024.3, the active field will always be included. 
GET /api/v2/library/tasks/?include=verification_coverage,categories,tags,how_tos,amendments HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [{
        "priority": 8,
        "db_id": 1,
        "tags": ["tag1", "tag2", "tag3"],
        "url": "http://example.com/library/tasks/T179/",
        "problem": "P1",
        "title": "Allow access for users to remove their data from the system",
        "text": "Some example description",
        "phase": "X1",
        "id": "T179",
        "active": true,
        "categories": [
            "Authorization"
        ],
        "amendments": [{
            "id": "TA123",
            "title": "TA123",
            "text": "Some additional information about this Countermeasure..."
        }],
        "verification_coverage": [
            "No Automated Static Analysis Coverage"
        ],
        "how_tos": [{
            "id": "I131",
            "title": "I131: Manually with browser",
            "slug": "test-account-lockout-manually-browser",
            "url": "http://a7069ccda519b00c4/....",
            "text": "1. Open your web browser ..."
        }],
        "type": "Built-in",
        "created_by": {
            "id": 1,
            "email": "admin@example.com",
            "first_name": "Admin",
            "last_name": "Testerton"
        },
        "created_date_time": "2019-05-15T16:52:17.415000-04:00",
        "last_updated_date": "2021-06-25T14:47:43.788000-04:00",
        "last_updated_by": {
            "id": 1,
            "email": "admin@example.com",
            "first_name": "Admin",
            "last_name": "Testerton"
        },
        "match_conditions": [{
            "db_id": 523,
            "id": "MC523",
            "required": ["A19"],
            "excluded": ["A713"]
        }]
    }]
}

Get a specific Library Countermeasure

This endpoint retrieves a single Library Countermeasure resource, as specified by the id parameter.

GET /api/v2/library/tasks/{task_id}/

GET /api/v2/library/problems/{problem_id}/

Query Parameters

Parameter Description
show_original Whether to return to the original content for a Built-In Modified Countermeasure (default is False).

URL Parameters

Parameter Description
task_id The id of the Library Countermeasure to retrieve

All of the expand and include parameters for the 'Get all Library Countermeasures' endpoint apply here as well.

GET /api/v2/library/tasks/T3/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json

{
    "priority": 8,
    "db_id": 1,
    "tags": [],
    "url": "http://example.com/library/tasks/T3/",
    "problem": "P1",
    "title": "Example Library Countermeasure",
    "text": "Some example description",
    "phase": "X1",
    "id": "T3",
    "active": true,
    "type": "Built-in",
    "created_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "created_date": "2019-05-15T16:52:17.415000-04:00",
    "last_updated_date": "2021-06-25T14:47:43.788000-04:00",
    "last_updated_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    }
}

Create a Library Countermeasure

This endpoint creates a new Library Countermeasure resource.

POST /api/v2/library/tasks/

Payload

Fields Required Description
title Yes The title of the Library Countermeasure.
text Yes The description text of the Library Countermeasure.
problem Yes The Weakness the Library Countermeasure is trying to solve.
priority Yes The priority of the Library Countermeasure.
phase Yes The phase in which the Library Countermeasure will appear in a project.
match_conditions No The match conditions for the Library Countermeasure.
tags No The list of tags associated with the Library Countermeasure.
active No The active status of the Library Countermeasure. If no value is provided the new Countermeasure will be active. 
POST /api/v2/library/tasks/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "title": "A New Countermeasure",
    "text": "Countermeasure Description",
    "problem": "P1",
    "priority": 9,
    "phase": "X1",
    "match_conditions": [{
        "required": ["A19"],
        "excluded": ["A713"]
    }],
    "tags": ["tag1", "tag2"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "CT1",
    "title": "A New Countermeasure",
    "text": "Countermeasure Description",
    "created_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "created_date_time": "2024-07-11T12:28:35.779232-04:00",
    "last_updated_date": "2024-07-11T12:28:35.779259-04:00",
    "last_updated_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "url": "http://example.com/library/tasks/CT1/",
    "problem": "P1",
    "priority": 9,
    "phase": "X1",
    "db_id": -1,
    "type": "Custom",
    "active": true,
    "match_conditions": [{
        "db_id": 523,
        "id": "MC523",
        "required": ["A19"],
        "excluded": ["A713"]
    }],
    "tags": ["tag1", "tag2"]
}

Update a Library Countermeasure

This endpoint updates a specific Library Countermeasure resource, as specified by the id parameter.

PATCH /api/v2/library/tasks/{task_id}/

URL Parameters

Parameter Description
task_id The id of the Library Countermeasure to update.

Payload

Fields Required Description
title No The title of the Library Countermeasure.
text No The description text of the Library Countermeasure.
problem No The Weakness the Library Countermeasure is trying to solve.
priority No The priority of the Library Countermeasure.
phase No The phase in which the Library Countermeasure will appear in a project.
match_conditions No The match conditions for the Library Countermeasure.
active No The active status of the Library Countermeasure.
tags No The tags associated with the Library Countermeasure. 
PATCH /api/v2/library/tasks/CT1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "title": "Updated Countermeasure",
    "text": "Updated Countermeasure Description",
    "problem": "P2",
    "priority": 4,
    "phase": "X2",
    "active": false,
    "match_conditions": [{
        "required": ["A19"],
        "excluded": ["A713"]
    }],
    "tags": ["tag1", "tag2"]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "CT16",
    "title": "Updated Countermeasure",
    "text": "Updated Countermeasure Description",
    "created_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "created_date_time": "2024-07-11T12:28:35.779232-04:00",
    "last_updated_date": "2024-07-11T12:39:37.250027-04:00",
    "last_updated_by": {
        "id": 1,
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "Testerton"
    },
    "url": "http://localhost:3000/library/tasks/CT1/",
    "problem": "P2",
    "priority": 4,
    "phase": "X2",
    "db_id": -1,
    "type": "Custom",
    "active": false,
    "match_conditions": [{
        "required": ["A19"],
        "excluded": ["A713"]
    }],
    "tags": ["tag1", "tag2"]
}

Delete a Library Countermeasure

This endpoint deletes a specific Library Countermeasure resource, as specified by the id parameter.

DELETE /api/v2/library/tasks/{task_id}/

URL Parameters

Parameter Description
task_id The id of the Library Countermeasure to delete. 
DELETE /api/v2/library/tasks/CT1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

results matching ""

    No results matching ""