Security Events API

This page describes how to query the MediaProtection Security Events endpoint, what data you can retrieve, and how to interpret the results.

Overview

Security Events allow you to detect and monitor potential illicit or suspicious activities during media playback. For example, the system can flag attempts to debug or screen-capture, indicate player hijacking attempts, or highlight usage of unsafe features.

Endpoint

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/securityEvents

Query Parameters

Parameter	Type	Description
`page`	Number	The page of results to fetch. Default is `1`.
`limit`	Number	The number of records to return per page. Maximum `1000`. Default is `10`.
`orderBy`	String	The field used to order results. Possible values: `"_id"`, `"createdAt"`, `"contentType"`, `"viewerIdentifier"`. Default is `"createdAt"`.
`order`	String	The sort direction. Possible values: `"asc"`, `"desc"`. Default is `"desc"`.
`_id`	String	Filter by Security Event unique identifier.
`viewerIdentifier`	String	Filter by the viewer identifier (a custom identifier for the viewer/session).
`createdAfter`	String (date-time)	Filter events created after this datetime (ISO-8601).
`createdBefore`	String (date-time)	Filter events created before this datetime (ISO-8601).

Example Request

curl -X GET "https://api.fastevo.net/api/v1/projects/mediaProtection/siem/securityEvents?page=1&limit=2&orderBy=_id&order=asc&createdAfter=2023-01-01T00:00:00.000Z&createdBefore=2024-01-01T00:00:00.000Z" \
  -H "Authorization: Bearer <YOUR_PROJECT_API_KEY>"

Response

The response is a paginated list of security events. The structure is:

{
  "currentPage": 1,
  "totalPages": 5,
  "totalRecords": 50,
  "data": [
    {
      "_id": "65049fedee5d8ae3fa498757",
      "viewerIdentifier": "user123",
      "createdAt": "2023-10-20T15:30:00.000Z",
      "contentType": "video",
      "ipClassification": "residential",
      "location": {
        "country": "US",
        "region": "California",
        "city": "Los Angeles",
        "zipCode": "90001",
        "metroCode": "803",
        "latitude": "34.0522",
        "longitude": "-118.2437"
      },
      "clientDetails": {
        "ua": "Mozilla/5.0 ...",
        "browser": {
          "name": "Chrome",
          "version": "108.0.0.0",
          "major": "108"
        },
        "cpu": {
          "architecture": "amd64"
        },
        "device": {
          "type": "desktop",
          "model": null,
          "vendor": null
        },
        "engine": {
          "name": "Blink",
          "version": "108.0.0.0"
        },
        "os": {
          "name": "Windows",
          "version": "10"
        },
        "gpuDetails": {
          "vendor": "Intel",
          "renderer": "Intel(R) UHD Graphics"
        },
        "timeZone": "America/Los_Angeles",
        "language": "en-US",
        "hardwareConcurrency": 8,
        "deviceMemory": 16,
        "maxTouchPoints": 0,
        "isInsideIframe": false,
        "isInPrivateMode": false,
        "referer": "https://example.com"
      },
      "event": "playerHijacking"
    }
  ]
}

currentPage: The page of results returned.
totalPages: The total number of available pages.
totalRecords: The total number of events matching the filters.
data: An array of security events containing relevant details about each event.

Security Event Types

During media playback, various events can be captured. The event field can include (but is not limited to):

undefined: An event that does not match known categories.
playerHijacking: Events indicating attempted DOM manipulation, out-of-bounds HTML overlay, or suspicious tampering with player elements.
debugging: Events indicating console debugger or dev-tools usage.
screenCapture: Events indicating attempts to screen capture or record the browser tab.
suspiciousPlayback: Events that indicate a suspicious looking playback that might be an attempt of capturing content.
unsafeNetworkInterception: Events indicating network tampering or inability to fetch required security resources.
drmHacking: Events indicating a mismatch or tampering in the DRM device environment.
unsafeFeatureUse: Events indicating usage of features not allowed under strict security.

Notes

Pagination: You can iterate over currentPage from 1 through totalPages to fetch all records.
Response Limits: The limit parameter is capped at 1000 to protect the system from requests for extremely large result sets.
Filtering: Combine filters (like viewerIdentifier, createdAfter, createdBefore) to narrow down the results to specific time ranges or playback sessions.

Summary

This API provides a way to retrieve and analyze security events triggered by your media protection system. By leveraging these events, you can detect illicit attempts at tampering or unauthorized usage, and use these insights to improve the security posture of your media streaming application.

Apple FairPlay Device playback capabilities