Library Threats

⚠️ Breaking Changes for the Library Threats API endpoint (/api/v2/library/threats/) in 2025.1:

  • The 'thread_id' field will be renamed to 'id'
  • The 'description' field will be renamed to 'text'
  • The 'created_at' field will be renamed to 'created_date'
  • The 'updated_at' field will be renamed to 'last_updated_date'

Get All Library Threats

This endpoint retrieves a list of Library Threat resources.

GET /api/v2/library/threats/

Query parameters

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

Parameter Description
search Filter Library Threats by performing a textual search on its id, title or text.
ordering Sort Library Threats by the specified field. Prefix field name with minus to sort descending. Sortable fields: id, title, active, last_update_date, last_updated_by.
type__in Returns all Library Threats which are either built-in, built-in modified or custom
active Filter Library Threats based on whether they are active or not. Valid values: true, false.
show_original Whether to return to the original content for a Built-In Modified Library Threat (default is False).
capec__in Given CAPEC ids, returns all Library Threats with any of the specified 
GET /api/v2/library/threats/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

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

{
    "results": [
        {
            "db_id": 1,
            "id": "TH1",
            "title": "Exploitation of Trusted Identifiers",
            "text": "An adversary guesses, obtains a trusted identifier ...",
            "severity": 6,
            "type": "Built-in",
            "active": true,
            "capecs": [ 21 ],
            "problems": [ "P956" ],
            "created_date": "2022-07-29T10:22:30.746000-04:00",
            "created_by": {
                "id": 5,
                "email": "no-reply+content_admin@localhost",
                "first_name": "SD",
                "last_name": "Elements"
            },
            "last_updated_by": {
                "id": 5,
                "email": "no-reply+content_admin@localhost",
                "first_name": "SD",
                "last_name": "Elements"
            },
            "last_updated_date": "2022-09-01T16:21:32.845000-04:00"
        }
    ]
}

Expand parameters

See the Expand Parameters section for more details.

Parameter Description
capecs Expands the CAPECs field in the Library Threat response object.
problems Expands the Weaknesses field in the Library Threat response object. 
GET /api/v2/library/threats/?expand=capecs,problems HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

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

{
    "results": [
        {
            "db_id": 1,
            "id": "TH1",
            "title": "Exploitation of Trusted Identifiers",
            "text": "An adversary guesses, obtains a trusted identifier ...",
            "severity": 6,
            "type": "Built-in",
            "active": true,
            "capecs": [
                {
                    "capec_id": 21,
                    "title": "Exploitation of Trusted Identifiers",
                    "url": "https://capec.mitre.org/data/definitions/21"
                }
             ],
            "problems": [
                {
                    "id": "P956",
                    "risk_rating": 9,
                    "title": "Cookies are not set with HttpOnly attribute (Microsoft IIS)",
                    "text": "When cookies are not set with the `HttpOnly` flag ...",
                    "cwe": [],
                    "db_id": 956,
                    "related_tasks": [
                        {
                            "id": "T914",
                            "title": "Ensure cookies are set with HttpOnly attribute (Microsoft IIS)",
                            "text": "Set the `httpOnlyCookies` attribute to `true` ...",
                            "priority": 9,
                            "phase": "X5",
                            "db_id": 914,
                            "active": true
                        }
                    ]
                }
            ],
            "created_date": "2022-07-29T10:22:30.746000-04:00",
            "created_by": {
                "id": 5,
                "email": "no-reply+content_admin@localhost",
                "first_name": "SD",
                "last_name": "Elements"
            },
            "last_updated_by": {
                "id": 5,
                "email": "no-reply+content_admin@localhost",
                "first_name": "SD",
                "last_name": "Elements"
            },
            "last_updated_date": "2022-09-01T16:21:32.845000-04:00"
        }
    ]
}

Get a specific Library Threat

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

GET /api/v2/library/threats/{threat_id}/

Query Parameters

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

URL Parameters

Parameter Description
threat_id The id of the Library Threat to retrieve

All of the expand for the 'Get all Library Threats' endpoint apply here as well.

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

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

{
    "db_id": 1,
    "id": "TH1",
    "title": "Exploitation of Trusted Identifiers",
    "text": "An adversary guesses, obtains a trusted identifier ...",
    "severity": 6,
    "type": "Built-in",
    "active": true,
    "capecs": [ 21 ],
    "problems": [ "P956" ],
    "created_date": "2022-07-29T10:22:30.746000-04:00",
    "created_by": {
        "id": 5,
        "email": "no-reply+content_admin@localhost",
        "first_name": "SD",
        "last_name": "Elements"
    },
    "last_updated_by": {
        "id": 5,
        "email": "no-reply+content_admin@localhost",
        "first_name": "SD",
        "last_name": "Elements"
    },
    "last_updated_date": "2022-09-01T16:21:32.845000-04:00"
}

Create a Library Threat

This endpoint creates a new Library Threat resource.

POST /api/v2/library/threats/

Payload

Fields Required Description
title Yes The title of the Library Threat.
text Yes The description text of the Library Threat.
severity Yes The severity of the Library Threat.
capecs No A number array that represents the CAPECs assigned to the Library Threat.
problems No The list of Weaknesses the Library Threat can cause.
active No The active status of the Library Threat. If no value is provided the new Threat will be active. 
POST /api/v2/library/threats/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "title": "A New Threat",
    "text": "Threat Description",
    "severity": 9,
    "capecs": [21, 87],
    "problems": ["P1", "P2"],
    "active": true
}

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

{
    "db_id": -1,
    "id": "CTH1",
    "title": "A New Threat",
    "text": "Threat Description",
    "severity": 9,
    "capecs": [21, 87],
    "problems": ["P1", "P2"],
    "type": "Custom",
    "active": true,
    "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"
    }
}

Update a Library Threat

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

PATCH /api/v2/library/threats/{threat_id}/

URL Parameters

Parameter Description
threat_id The id of the Library Threat to update.

Payload

Fields Required Description
title No The title of the Library Threat.
text No The description text of the Library Threat.
severity No The severity of the Library Threat.
capecs No A number array that represents the CAPECs assigned to the Library Threat.
problems No The list of Weaknesses the Library Threat can cause.
active No The active status of the Library Threat. If no value is provided the new Threat will be active. 
PATCH /api/v2/library/threats/TH1/ HTTP/1.1
Accept: application/json
Authorization: Token "YOUR SDE ACCESS TOKEN"

{
    "title": "Updated Threat",
    "text": "Updated Threat Description",
    "severity": 4,
    "capecs": [17],
    "problems": ["P3"],
    "active": false
}

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

{
    "db_id": -1,
    "id": "TH1",
    "title": "Updated Threat",
    "text": "Updated Threat Description",
    "severity": 4,
    "capecs": [17],
    "problems": ["P3"],
    "type": "Built-in Modified",
    "active": false,
    "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"
    }
}

Delete a Library Threat

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

DELETE /api/v2/library/threats/{threat_id}/

URL Parameters

Parameter Description
threat_id The id of the Library Threat to delete. 
DELETE /api/v2/library/threats/CTH1/ 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 ""