SIEM Rules

Introduction

Security Information and Event Management (SIEM) rules in the Fastevo Media Protection Platform (Fastevo MP2) allow you to define policies that control access to your media content based on various conditions. These rules can automatically block or adjust the protection level of content delivery based on viewer identifiers, IP addresses, device types, and more.

SIEM rules are essential for enforcing security policies and minimizing unauthorized access or misuse of media content. Understanding how to create, test, and manage these rules is crucial for maintaining a secure media platform.

Understanding SIEM Rules

SIEM rules are processed in order of their priority, from the lowest number to the highest. Rules with a negative priority are considered system or admin-level rules and require special permissions to create or modify.

When a playback request is made, the SIEM rules engine evaluates each rule sequentially based on priority. If a rule's conditions are met, the specified action is taken, and depending on the action, further rule processing may stop.

Rule Actions

The action parameter defines what happens when a rule's conditions are met. The possible actions are:

• "block": Block content delivery.
• "playStandard": Serve content with standard protection level.
• "playEnhanced": Serve content with enhanced protection level.
• "playAdaptive": Serve content with adaptive protection level.
• "break": Stop further rule processing without changing the content delivery.

When to Use SIEM Rules

SIEM rules are useful for:

• Blocking access from specific regions or IP classifications (e.g., VPNs, proxies).
• Adjusting protection levels based on the viewer's device, location, or behavior.
• Preventing access during suspicious activities (e.g., using private browsing mode).

SIEM Rule Structure

Understanding the structure of a SIEM rule is essential for creating, testing, and modifying rules effectively.

Request Body Parameters

• description (optional): A string describing the rule.
• priority (required): A non-negative integer indicating the rule's priority.
• action (required): The action to take when the rule conditions are met. Possible values:
  • "block"
  • "playStandard"
  • "playEnhanced"
  • "playAdaptive"
  • "break"
• isRuleEnabled (required): A boolean indicating whether the rule is active.
• conditions (required): An object defining the conditions under which the rule applies. At least one condition is required.
• propagationSettings (optional): Settings that define how the rule propagates to other identifiers.

Example Request Body

{
  "description": "Block specific viewers in private mode",
  "priority": 1,
  "action": "block",
  "isRuleEnabled": true,
  "conditions": {
    "viewerIdentifierCondition": {
      "operator": "allIn",
      "values": ["blacklistedUser1", "blacklistedUser2"]
    },
    "isInPrivateModeCondition": {
      "operator": "equals",
      "value": true
    }
  },
  "propagationSettings": {
    "propagateToSecurePersistentViewerIdentities": false,
    "propagateToIPv4Addresses": false,
    "propagateToIPv6NetworkPrefixes": false,
    "propagateToViewerIdentifiers": true,
    "deepPropagationLimit": 1000
  }
}

Testing a SIEM Rule

Before deploying a SIEM rule, it's crucial to test how it would affect your system. The testing endpoint allows you to simulate the rule over the last 24 hours of playback sessions.

Endpoint

POST https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/test

Request Body Parameters

• Same as the SIEM Rule Structure.

Example Request

{
  "description": "Test rule for European Union viewers",
  "priority": 1,
  "action": "block",
  "isRuleEnabled": true,
  "conditions": {
    "isInEuropeanUnionCondition": {
      "operator": "equals",
      "value": true
    }
  }
}

API Response

A successful response returns a status code of 200 OK and an array of statistics:

[
  {
    "fromDate": "2023-10-01T12:00:00.000Z",
    "toDate": "2023-10-01T13:00:00.000Z",
    "executionsCount": 150,
    "totalSessions": 1000
  },
  {
    "fromDate": "2023-10-01T13:00:00.000Z",
    "toDate": "2023-10-01T14:00:00.000Z",
    "executionsCount": 200,
    "totalSessions": 1200
  }
  // ...additional hourly data...
]

Response Fields:

• fromDate and toDate: The time range for the data.
• executionsCount: Number of times the rule would have been triggered.
• totalSessions: Total number of playback sessions during that hour.

Error Responses

• 400 Bad Request: Missing required fields or invalid parameters.
• 401 Unauthorized: Invalid or missing authentication token.
• 403 Forbidden: Insufficient permissions to test the rule.
• 500 Internal Server Error: An unexpected error occurred on the server.

Creating a SIEM Rule

After testing and verifying the potential impact, you can proceed to create a new SIEM rule.

Endpoint

POST https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/create

Request Body Parameters

• Same as the SIEM Rule Structure.

Example Request

{
  "description": "Block EU viewers during promotional period",
  "priority": 1,
  "action": "block",
  "isRuleEnabled": true,
  "conditions": {
    "isInEuropeanUnionCondition": {
      "operator": "equals",
      "value": true
    }
  },
  "propagationSettings": {
    "propagateToViewerIdentifiers": true,
    "deepPropagationLimit": 1000
  }
}

API Response

A successful creation returns a status code of 201 Created:

{
  "success": true
}

Error Responses

• 400 Bad Request: Invalid parameters or missing required fields.
• 401 Unauthorized: Invalid or missing authentication token.
• 403 Forbidden: Insufficient permissions to create the rule.
• 409 Conflict: A rule with the same priority already exists.
• 500 Internal Server Error: An unexpected error occurred on the server.

Retrieving SIEM Rules

Get All SIEM Rules

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

Query Parameters

• page (optional): Page number (default 1).
• limit (optional): Records per page (default 10).
• filter (optional): Filter criteria.

Example Request

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules?page=1&limit=5

API Response

{
  "currentPage": 1,
  "totalPages": 1,
  "totalRecords": 2,
  "data": [
    {
      "_id": "60f7ae45d9cde38a23035c90",
      "description": "Block EU viewers during promotional period",
      "priority": 1,
      "action": "block",
      "isRuleEnabled": true,
      "conditions": {
        "isInEuropeanUnionCondition": {
          "operator": "equals",
          "value": true
        }
      },
      "propagationSettings": {
        "propagateToViewerIdentifiers": true,
        "deepPropagationLimit": 1000
      },
      "recentActivity": []
    },
    // ...other rules
  ]
}

Get a Specific SIEM Rule

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/{ruleId}

Replace {ruleId} with the actual rule ID.

Example Request

GET https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/60f7ae45d9cde38a23035c90

API Response

{
  "_id": "60f7ae45d9cde38a23035c90",
  "description": "Block EU viewers during promotional period",
  "priority": 1,
  "action": "block",
  "isRuleEnabled": true,
  "conditions": {
    "isInEuropeanUnionCondition": {
      "operator": "equals",
      "value": true
    }
  },
  "propagationSettings": {
    "propagateToViewerIdentifiers": true,
    "deepPropagationLimit": 1000
  },
  "recentActivity": []
}

Error Responses

• 400 Bad Request: Invalid ruleId.
• 401 Unauthorized: Invalid or missing authentication token.
• 403 Forbidden: Insufficient permissions to access the rule.
• 404 Not Found: Rule does not exist.
• 500 Internal Server Error: An unexpected error occurred on the server.

Modifying a SIEM Rule

Endpoint

PUT https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/{ruleId}

Replace {ruleId} with the actual rule ID.

Required Fields in Request Body

• Same as the SIEM Rule Structure.

Example Request

{
  "description": "Block EU viewers - Updated",
  "priority": 2,
  "action": "block",
  "isRuleEnabled": false,
  "conditions": {
    "isInEuropeanUnionCondition": {
      "operator": "equals",
      "value": true
    }
  },
  "propagationSettings": {
    "propagateToViewerIdentifiers": true,
    "deepPropagationLimit": 500
  }
}

API Response

A successful modification returns a status code of 204 No Content.

Error Responses

• 400 Bad Request: Invalid parameters or missing required fields.
• 401 Unauthorized: Invalid or missing authentication token.
• 403 Forbidden: Insufficient permissions.
• 404 Not Found: Rule does not exist.
• 500 Internal Server Error: An unexpected error occurred on the server.

Important Notes

• Provide All Required Fields: Omitting any required field will result in an error.
• Fields Not Provided May Be Reset: Optional fields not included may be reset to default or removed.
• Cannot Modify Certain Rules: System or propagated rules may not be modifiable.

Enabling or Disabling a SIEM Rule

Endpoint

PATCH https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/{ruleId}

Request Body Parameters

• isRuleEnabled (required): A boolean indicating the new status.

Example Request

{
  "isRuleEnabled": true
}

API Response

A successful operation returns a status code of 204 No Content.

Error Responses

• 400 Bad Request: Missing isRuleEnabled field.
• 401 Unauthorized: Invalid or missing authentication token.
• 403 Forbidden: Insufficient permissions.
• 404 Not Found: Rule does not exist.
• 500 Internal Server Error: An unexpected error occurred on the server.

Deleting a SIEM Rule

Endpoint

DELETE https://api.fastevo.net/api/v1/projects/mediaProtection/siem/rules/{ruleId}

API Response

A successful deletion returns a status code of 204 No Content.

Error Responses

• 400 Bad Request: Invalid parameters.
• 401 Unauthorized: Invalid or missing authentication token.
• 403 Forbidden: Insufficient permissions.
• 404 Not Found: Rule does not exist.
• 500 Internal Server Error: An unexpected error occurred on the server.

Getting SIEM Rule Usage Counts

To monitor your SIEM rule usage:

Endpoint

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

API Response

{
  "usedRules": 3,
  "remainingRuleSlots": 7
}

Error Responses

• 401 Unauthorized: Invalid or missing authentication token.
• 500 Internal Server Error: An unexpected error occurred on the server.

Condition Definitions

SIEM rules use conditions to determine when they should be applied. Each condition checks specific attributes of the playback request or viewer.

Common Operators

Boolean Comparisons

• "equals": Attribute equals the specified value.
• "notEquals": Attribute does not equal the specified value.

String to Array Comparisons

• "allIn": The attribute matches all of the values provided.
• "noneIn": The attribute matches none of the provided values.

Array to Array Comparisons

• "atLeastOneIn": At least one element of the attribute matches any of the values provided.
• "atLeastOneNotIn": At least one element of the attribute does not match any of the values provided.
• "allIn": All elements of the attribute match the provided values.
• "noneIn": None of the elements match any of the provided values.
• "equals": The attribute exactly matches the provided values.
• "notEquals": The attribute does not exactly match the provided values.

Conditions List

Below are detailed descriptions of each condition, including applicable operators and examples.

1. viewerIdentifierCondition

• Description: Checks the viewer's identifier.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of viewer identifiers.

Example:

"viewerIdentifierCondition": {
  "operator": "allIn",
  "values": ["user123"]
}

2. tokenProtectionLevelCondition

• Description: Checks the protection level specified in the playback token.
• Operators: "allIn", "noneIn"
• Possible Values: "standard", "enhanced", "adaptive"
• Fields:
  • operator: Comparison operator.
  • values: Array of protection levels.

Example:

"tokenProtectionLevelCondition": {
  "operator": "noneIn",
  "values": ["standard"]
}

3. clientTypeCondition

• Description: Checks the type of client making the request (e.g., web browser, mobile app).
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of client types.

Example:

"clientTypeCondition": {
  "operator": "allIn",
  "values": ["webBrowser"]
}

4. ipClassificationCondition

• Description: Checks the classification of the IP address (e.g., VPN, proxy).
• Operators: "allIn", "noneIn"
• Possible Values: "crawler", "vpn", "hosting", "education", "government", "enterprise", "nonProfit", "iCloudPrivateRelay", "tor", "banking"
• Fields:
  • operator: Comparison operator.
  • values: Array of IP classifications.

Example:

"ipClassificationCondition": {
  "operator": "noneIn",
  "values": ["VPN", "TOR"]
}

5. isIpAssociatedWithMaliciousEventsRecentlyCondition

• Description: Checks if the IP has been associated with malicious events recently.
• Operators: "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • value: Boolean (true or false)

Example:

"isIpAssociatedWithMaliciousEventsRecentlyCondition": {
  "operator": "equals",
  "value": true
}

6. countryCondition

• Description: Checks the viewer's country based on IP geolocation.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of country codes (ISO 3166-1 alpha-2 codes).

Example:

"countryCondition": {
  "operator": "allIn",
  "values": ["US", "CA", "GB"]
}

7. regionCondition

• Description: Checks the viewer's region or state.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of region names.

Example:

"regionCondition": {
  "operator": "noneIn",
  "values": ["California", "Texas"]
}

8. cityCondition

• Description: Checks the viewer's city.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of city names.

Example:

"cityCondition": {
  "operator": "noneIn",
  "values": ["New York", "Los Angeles"]
}

9. continentCondition

• Description: Checks the viewer's continent based on IP geolocation.
• Operators: "allIn", "noneIn"
• Possible Continent Codes:
  • "AF": Africa
  • "AN": Antarctica
  • "AS": Asia
  • "EU": Europe
  • "NA": North America
  • "OC": Oceania
  • "SA": South America
• Fields:
  • operator: Comparison operator.
  • values: Array of continent codes.

Example:

"continentCondition": {
  "operator": "allIn",
  "values": ["NA", "EU"]
}

10. isInEuropeanUnionCondition

• Description: Checks if the viewer's IP geolocates to a country within the European Union.
• Operators: "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • value: Boolean (true or false)

Example:

"isInEuropeanUnionCondition": {
  "operator": "equals",
  "value": true
}

11. operatingSystemNameCondition

• Description: Checks the operating system's name.
• Operators: "allIn", "noneIn"
• Possible Values: e.g., "Windows", "macOS", "Linux", "Android", "iOS"
• Fields:
  • operator: Comparison operator.
  • values: Array of OS names.

Example:

"operatingSystemNameCondition": {
  "operator": "allIn",
  "values": ["iOS", "Android"]
}

12. operatingSystemVersionCondition

• Description: Checks the operating system's version.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of OS version strings.

Example:

"operatingSystemVersionCondition": {
  "operator": "allIn",
  "values": ["14.0", "15.0"]
}

13. deviceVendorCondition

• Description: Checks the device vendor/manufacturer.
• Operators: "allIn", "noneIn"
• Possible Values: e.g., "Apple", "Samsung", "Google"
• Fields:
  • operator: Comparison operator.
  • values: Array of device vendor names.

Example:

"deviceVendorCondition": {
  "operator": "allIn",
  "values": ["Apple"]
}

14. deviceModelCondition

• Description: Checks the device model.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of device model names.

Example:

"deviceModelCondition": {
  "operator": "allIn",
  "values": ["iPhone12,1", "iPhone12,3"]
}

15. deviceTypeCondition

• Description: Checks the type of device (e.g., smartphone, tablet).
• Operators: "allIn", "noneIn"
• Possible Values: e.g., "smartphone", "tablet", "desktop"
• Fields:
  • operator: Comparison operator.
  • values: Array of device types.

Example:

"deviceTypeCondition": {
  "operator": "allIn",
  "values": ["smartphone"]
}

16. browserNameCondition

• Description: Checks the browser's name.
• Operators: "allIn", "noneIn"
• Possible Values: e.g., "Chrome", "Safari", "Firefox"
• Fields:
  • operator: Comparison operator.
  • values: Array of browser names.

Example:

"browserNameCondition": {
  "operator": "noneIn",
  "values": ["Internet Explorer"]
}

17. browserVersionCondition

• Description: Checks the browser's version.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of browser version strings.

Example:

"browserVersionCondition": {
  "operator": "allIn",
  "values": ["93.0", "94.0"]
}

18. gpuVendorCondition

• Description: Checks the GPU vendor.
• Operators: "allIn", "noneIn"
• Possible Values: e.g., "NVIDIA", "AMD", "Intel"
• Fields:
  • operator: Comparison operator.
  • values: Array of GPU vendor names.

Example:

"gpuVendorCondition": {
  "operator": "allIn",
  "values": ["NVIDIA", "AMD"]
}

19. gpuRendererCondition

• Description: Checks the GPU renderer.
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of GPU renderer names.

Example:

"gpuRendererCondition": {
  "operator": "allIn",
  "values": ["GeForce GTX 1080", "Radeon RX 580"]
}

20. embedContextCondition

• Description: Checks the context in which the player is embedded (e.g., within an iframe, specific domain).
• Operators: "allIn", "noneIn"
• Fields:
  • operator: Comparison operator.
  • values: Array of embed contexts or URLs.

Example:

"embedContextCondition": {
  "operator": "allIn",
  "values": ["https://www.example.com"]
}

21. viewerTagsCondition

• Description: Checks the tags associated with the viewer.
• Operators: "atLeastOneIn", "atLeastOneNotIn", "allIn", "noneIn", "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • values: Array of tags.

Example:

"viewerTagsCondition": {
  "operator": "atLeastOneIn",
  "values": ["premium", "subscriber"]
}

22. mediaProtectionContentTagsCondition

• Description: Checks the tags associated with the media content.
• Operators: "atLeastOneIn", "atLeastOneNotIn", "allIn", "noneIn", "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • values: Array of content tags.

Example:

"mediaProtectionContentTagsCondition": {
  "operator": "atLeastOneNotIn",
  "values": ["internal", "restricted"]
}

23. isInPrivateModeCondition

• Description: Checks if the viewer is using a private or incognito browsing mode.
• Operators: "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • value: Boolean (true or false)

Example:

"isInPrivateModeCondition": {
  "operator": "equals",
  "value": true
}

24. isInsideIframeCondition

• Description: Checks if the player is embedded inside an iframe.
• Operators: "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • value: Boolean (true or false)

Example:

"isInsideIframeCondition": {
  "operator": "equals",
  "value": false
}

25. mediaProtectionPersistentViewerIdentitiesCondition (Reserved)

• Description: Checks the persistent viewer identities (reserved for future use or admin-level rules).
• Operators: "atLeastOneIn", "atLeastOneNotIn", "allIn", "noneIn", "equals", "notEquals"
• Fields:
  • operator: Comparison operator.
  • values: Array of persistent viewer identities.

Example:

"mediaProtectionPersistentViewerIdentitiesCondition": {
  "operator": "equals",
  "values": ["persistentId123"]
}

Propagation Settings

The propagationSettings object defines how a rule propagates to other identifiers when violations are detected.

Fields

• propagateToSecurePersistentViewerIdentities (boolean)
• propagateToIPv4Addresses (boolean)
• propagateToIPv6NetworkPrefixes (boolean)
• propagateToViewerIdentifiers (boolean)
• deepPropagationLimit (number)

Example

"propagationSettings": {
  "propagateToSecurePersistentViewerIdentities": true,
  "propagateToIPv4Addresses": false,
  "propagateToIPv6NetworkPrefixes": false,
  "propagateToViewerIdentifiers": true,
  "deepPropagationLimit": 1000
}

Important Notes

• Always Test Before Deploying: Testing helps prevent unintended access blocks or service disruptions.
• Priority Levels: Negative priorities are reserved for admin-level rules.
• At Least One Condition: Rules must have at least one condition.
• Rule Execution Order: Determined by ascending priority.
• PUT vs. PATCH:
  • PUT: Replaces the entire rule; all fields are required.
  • PATCH: Partial updates; currently supports changing isRuleEnabled.

Error Handling

Ensure all required fields are included and valid. The API returns error messages and status codes for invalid requests.

Common Error Response Format

{
  "error": {
    "code": "ErrorCode",
    "message": "Error message describing the issue."
  }
}

• code: A string representing the error code.
• message: A descriptive message explaining the error.

Authentication

All SIEM rule endpoints require authentication. Include your project API key in the Authorization header:

Authorization: Bearer YOUR_PROJECT_API_KEY

Conclusion

By following this guide, you should be able to effectively test, create, modify, and manage SIEM rules within the Fastevo MP2 platform. Always remember to test new rules before deploying them to ensure they work as intended and do not have unintended consequences on your media delivery.

If you have any questions or need further assistance, please contact Fastevo support.