Ingest custom security events via API

Latest Dynatrace
How-to guide

This page has been updated to align with the new Grail security events table. For the complete list of updates and actions needed to accomplish the migration, follow the steps in the Grail security table migration guide.

In the following, you'll learn how to ingest external security events from custom third-party products into Grail.

A custom third-party product is any product for which Dynatrace doesn't provide an out-of-the-box integration.

Goal

Get insights from Dynatrace for vulnerability findings from any source, provider, or format.

How it works

You ingest your data into Grail via our built-in API endpoint or a custom API endpoint. Then, depending on the ingest option chosen, you can either analyze data in your format or manually map data to the Semantic Dictionary conventions.

Details

Ingest options	Built-in API endpoint	Custom API endpoint
Description	You can use and extend our built-in security events endpoint to ingest custom security events via API.	You can create and configure from scratch a generic endpoint to ingest custom security events via API.
Details	Preset bucket: Security events are stored in a bucket called `default_securityevents` (for details, see: Built-in Grail buckets). Fixed endpoint URL: One URL for all use cases and products. Data enrichment: A static `event.kind == "SECURITY_EVENT"` field is added to the event to mark it as a security event. Mapping: No mapping is applied; data stays in the original format. This means you can analyze data based on your format and create custom dashboards and workflows. Alternatively, you can configure a processing pipeline to map data manually to the Semantic Dictionary conventions. This way you can use our sample dashboard, Jira workflow, and Slack workflow to visualize data and automatize notifications.	Custom bucket: You can select or create the bucket where the security events will be stored. Custom endpoint URL: You can configure dedicated URLs for specific use cases or products. Data enrichment: You can define custom data enrichments. Mapping: You can configure your endpoint to map data to the Semantic Dictionary conventions. This way you can use our sample dashboard, Jira workflow, and Slack workflow to visualize data and automatize notifications. For details, see Configure a processing pipeline.

Prerequisites

Permissions:
- To query ingested data: storage:security.events:read.

Get started

To start ingesting data, use one of the options below.

Endpoint URL	`https://{your-environment-id}.live.dynatrace.com/platform/ingest/v1/security.events`
Method	POST
Authentication	Access token
Scope	`openpipeline.events_security`
Payload	`application/json`

For details on how to perform the API ingest, see Learn more.

Response codes

Code	Description
202	Accepted
400	Bad request (in case of missing body or wrong format)
401	Unauthorized (in case of missing or invalid token)

Examples

[
  {
  "imageId": {
    "imageDigest": "sha256:9282579f5330ae90d22f21b1a9be944f893895f06e3bc1985f14d1cfc084c60c"
  },
  "imageScanFindings": {
    "findingSeverityCounts": {
      "HIGH": 125,
      "MEDIUM": 188,
      "LOW": 30,
      "UNDEFINED": 13,
      "INFORMATIONAL": 353,
      "CRITICAL": 6
    },
    "findings": [
      {
        "attributes": [
          { "key": "CVSS3_SCORE", "value": "9.8" },
          { "key": "package_version", "value": "4.19.269-1" },
          { "key": "package_name", "value": "linux" },
          {
            "key": "CVSS3_VECTOR",
            "value": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
          }
        ],
        "description": "An issue was discovered in drivers/net/ethernet/intel/igb/igb_main.c in the IGB driver in the Linux kernel before 6.5.3. A buffer size may not be adequate for frames larger than the MTU.",
        "name": "CVE-2023-45871",
        "severity": "CRITICAL",
        "uri": "https://security-tracker.debian.org/tracker/CVE-2023-45871 "
      },
      {
        "attributes": [
          { "key": "CVSS3_SCORE", "value": "9.8" },
          { "key": "package_version", "value": "1:7.9p1-10+deb10u2" },
          { "key": "package_name", "value": "openssh" },
          {
            "key": "CVSS3_VECTOR",
            "value": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
          }
        ],
        "description": "The PKCS#11 feature in ssh-agent in OpenSSH before 9.3p2 has an insufficiently trustworthy search path, leading to remote code execution if an agent is forwarded to an attacker-controlled system. (Code in /usr/lib is not necessarily safe for loading into ssh-agent.) NOTE: this issue exists because of an incomplete fix for CVE-2016-10009.",
        "name": "CVE-2023-38408",
        "severity": "CRITICAL",
        "uri": "https://security-tracker.debian.org/tracker/CVE-2023-38408 "
      },
      {
        "attributes": [
          { "key": "CVSS3_SCORE", "value": "9.8" },
          { "key": "package_version", "value": "2.7.16-2+deb10u1" },
          { "key": "package_name", "value": "python2.7" },
          {
            "key": "CVSS3_VECTOR",
            "value": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
          }
        ],
        "description": "An XML External Entity (XXE) issue was discovered in Python through 3.9.1. The plistlib module no longer accepts entity declarations in XML plist files to avoid XML vulnerabilities.",
        "name": "CVE-2022-48565",
        "severity": "CRITICAL",
        "uri": "https://security-tracker.debian.org/tracker/CVE-2022-48565 "
      },
      {
        "attributes": [
          { "key": "CVSS3_SCORE", "value": "9.8" },
          { "key": "package_version", "value": "2.7.16-2+deb10u1" },
          { "key": "package_name", "value": "python2.7" },
          {
            "key": "CVSS3_VECTOR",
            "value": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
          },
          { "key": "CVSS2_VECTOR", "value": "AV:N/AC:L/Au:N/C:P/I:P/A:P" },
          { "key": "CVSS2_SCORE", "value": "7.5" }
        ],
        "description": "Python 3.x through 3.9.1 has a buffer overflow in PyCArg_repr in _ctypes/callproc.c, which may lead to remote code execution in certain Python applications that accept floating-point numbers as untrusted input, as demonstrated by a 1e300 argument to c_double.from_param. This occurs because sprintf is used unsafely.",
        "name": "CVE-2021-3177",
        "severity": "CRITICAL",
        "uri": "https://security-tracker.debian.org/tracker/CVE-2021-3177 "
      }
    ],
    "imageScanCompletedAt": 1698376478,
    "vulnerabilitySourceUpdatedAt": 1698343825
  },
  "imageScanStatus": {
    "description": "The scan was completed successfully.",
    "status": "COMPLETE"
  },
  "nextToken": "ukD72mdD/mC8b5xV3susmJzzaTgp3hKwR9nRUW1yZZ63B5NL+m8CiI+qgoiLO0t5s6Oi9w2CQBANPaxpQTFWXxF/Sq7shr/h//oNXvOJ2XuWPSF3ox6DgxQztXUFyKzeGw+HpbYZAAxpHjJVELVXXnhpxAScZkKhVG85CbbUGfSPyuKcSeeHoNvQPGBdxCWD6CaKl4nFxtXyUeFRs3RV+mkX5FUxosMnBJepE2JbaoM9elE1niY2Rpq3BZrp/QeOyWdmjeuySi+2KZO03915df+6OMIfXtt3zclPZ+BGcdMgWoETrte2fkh2y1RDO3PI4OCohgCbjlTk9X6fYLWrrxwkhfWAIRekqToQq+S8BHEm1o82jxDoyKO0Et9UrZVIEFOofBkvenm5U+8XvgQ4V5kvMZZLa9DZykVDteq28OF+KCgjo7WHTbXMy1yh7jyRJ6A77N12YJfxYgv16JjkVgmDqGjlM3YJEH2o55SYTAnSsiBXiMvvq1RK1hl567SIstgGPMK3c0v7TGDnCE6o3EhP4FC73As6mj2q4uGkLf8eMQLi9ogBJ1UAzKCiCl3bxeTKuMz1W8hokdPauwuAd9uKg0vLdHmM6iftfrVhsgbbioNLy3R5jOon7X61YbIGF7fUOkaj72o37fpPd/JG2g==",
  "registryId": "123456789876",
  "repositoryName": "unguard-frontend"
}
]

[
    {
      "timestamp": "2024-06-17T14:58:36.820000000+02:00",
      "dt.ingest.source": "/platform/ingest/v1/security.events/",
      "event.kind": "SECURITY_EVENT",
      "imageId": "{\"imageDigest\":\"sha256:9282579f5330ae90d22f21b1a9be944f893895f06e3bc1985f14d1cfc084c60c\"}",
      "imageScanFindings": "{\"findingSeverityCounts\":{\"HIGH\":125,\"MEDIUM\":188,\"LOW\":30,\"UNDEFINED\":13,\"INFORMATIONAL\":353,\"CRITICAL\":6},\"findings\":[{\"attributes\":[{\"key\":\"CVSS3_SCORE\",\"value\":\"9.8\"},{\"key\":\"package_version\",\"value\":\"4.19.269-1\"},{\"key\":\"package_name\",\"value\":\"linux\"},{\"key\":\"CVSS3_VECTOR\",\"value\":\"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H\"}],\"description\":\"An issue was discovered in drivers/net/ethernet/intel/igb/igb_main.c in the IGB driver in the Linux kernel before 6.5.3. A buffer size may not be adequate for frames larger than the MTU.\",\"name\":\"CVE-2023-45871\",\"severity\":\"CRITICAL\",\"uri\":\"https://security-tracker.debian.org/tracker/CVE-2023-45871 \"},{\"attributes\":[{\"key\":\"CVSS3_SCORE\",\"value\":\"9.8\"},{\"key\":\"package_version\",\"value\":\"1:7.9p1-10+deb10u2\"},{\"key\":\"package_name\",\"value\":\"openssh\"},{\"key\":\"CVSS3_VECTOR\",\"value\":\"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H\"}],\"description\":\"The PKCS#11 feature in ssh-agent in OpenSSH before 9.3p2 has an insufficiently trustworthy search path, leading to remote code execution if an agent is forwarded to an attacker-controlled system. (Code in /usr/lib is not necessarily safe for loading into ssh-agent.) NOTE: this issue exists because of an incomplete fix for CVE-2016-10009.\",\"name\":\"CVE-2023-38408\",\"severity\":\"CRITICAL\",\"uri\":\"https://security-tracker.debian.org/tracker/CVE-2023-38408 \"},{\"attributes\":[{\"key\":\"CVSS3_SCORE\",\"value\":\"9.8\"},{\"key\":\"package_version\",\"value\":\"2.7.16-2+deb10u1\"},{\"key\":\"package_name\",\"value\":\"python2.7\"},{\"key\":\"CVSS3_VECTOR\",\"value\":\"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H\"}],\"description\":\"An XML External Entity (XXE) issue was discovered in Python through 3.9.1. The plistlib module no longer accepts entity declarations in XML plist files to avoid XML vulnerabilities.\",\"name\":\"CVE-2022-48565\",\"severity\":\"CRITICAL\",\"uri\":\"https://security-tracker.debian.org/tracker/CVE-2022-48565 \"},{\"attributes\":[{\"key\":\"CVSS3_SCORE\",\"value\":\"9.8\"},{\"key\":\"package_version\",\"value\":\"2.7.16-2+deb10u1\"},{\"key\":\"package_name\",\"value\":\"python2.7\"},{\"key\":\"CVSS3_VECTOR\",\"value\":\"CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H\"},{\"key\":\"CVSS2_VECTOR\",\"value\":\"AV:N/AC:L/Au:N/C:P/I:P/A:P\"},{\"key\":\"CVSS2_SCORE\",\"value\":\"7.5\"}],\"description\":\"Python 3.x through 3.9.1 has a buffer overflow in PyCArg_repr in _ctypes/callproc.c, which may lead to remote code execution in certain Python applications that accept floating-point numbers as untrusted input, as demonstrated by a 1e300 argument to c_double.from_param. This occurs because sprintf is used unsafely.\",\"name\":\"CVE-2021-3177\",\"severity\":\"CRITICAL\",\"uri\":\"https://security-tracker.debian.org/tracker/CVE-2021-3177 \"}],\"imageScanCompletedAt\":1698376478,\"vulnerabilitySourceUpdatedAt\":1698343825}",
      "imageScanStatus": "{\"description\":\"The scan was completed successfully.\",\"status\":\"COMPLETE\"}",
      "nextToken": "ukD72mdD/mC8b5xV3susmJzzaTgp3hKwR9nRUW1yZZ63B5NL+m8CiI+qgoiLO0t5s6Oi9w2CQBANPaxpQTFWXxF/Sq7shr/h//oNXvOJ2XuWPSF3ox6DgxQztXUFyKzeGw+HpbYZAAxpHjJVELVXXnhpxAScZkKhVG85CbbUGfSPyuKcSeeHoNvQPGBdxCWD6CaKl4nFxtXyUeFRs3RV+mkX5FUxosMnBJepE2JbaoM9elE1niY2Rpq3BZrp/QeOyWdmjeuySi+2KZO03915df+6OMIfXtt3zclPZ+BGcdMgWoETrte2fkh2y1RDO3PI4OCohgCbjlTk9X6fYLWrrxwkhfWAIRekqToQq+S8BHEm1o82jxDoyKO0Et9UrZVIEFOofBkvenm5U+8XvgQ4V5kvMZZLa9DZykVDteq28OF+KCgjo7WHTbXMy1yh7jyRJ6A77N12YJfxYgv16JjkVgmDqGjlM3YJEH2o55SYTAnSsiBXiMvvq1RK1hl567SIstgGPMK3c0v7TGDnCE6o3EhP4FC73As6mj2q4uGkLf8eMQLi9ogBJ1UAzKCiCl3bxeTKuMz1W8hokdPauwuAd9uKg0vLdHmM6iftfrVhsgbbioNLy3R5jOon7X61YbIGF7fUOkaj72o37fpPd/JG2g==",
      "registryId": "123456789876",
      "repositoryName": "unguard-frontend"
    }
  ]

Use cases

With the ingested data, you can accomplish various use cases, such as