HTTPS REST API call to monitor and analyze network traffic

The HTTPS POST API call is designed to monitor and analyze network traffic. It consists of three primary components - query parameters, metadata, and actual data to be scanned. This section outlines the structure and use of the API for both HTTP and SMTP protocols, along with example requests and responses.

POST request URL

POST/monitor?evidence=1&incident=1&msize=776&need_event_xml=1&reporting_product=REPORTING_PRODUCT_PREVENT&return_rule_info=1

Request Parameters

Use the query parameters to return the incident details.

Parameter name	Description	Required	Values
evidence	Specifies if evidence must be generated.	Required	Boolean
incident	Indicates if an incident must be created for ePO	Required	Boolean
need_decoded_event_xml	Returns a DLP style opg event xml (.OPG is an internal format for storing Trellix DLP events).	Optional	Boolean
msize	Size of the metadata part of the request.	Required	Integer
protocol	SMTP or HTTP protocol type for scanning rules (Email or Web protection).	Required	String
return_rule_info global_event_id result_action incident_severity classifications_triggered rules_triggered	Returns additional information in the response. A globally unique identifier (GUID) for the response event. GUIDs are used to ensure that each event can be uniquely identified across the system. Specifies the Data Loss Prevention (DLP) action taken, as configured in the DLP rules. Indicates the severity of the Data Loss Prevention incident. Contains the GUIDs and names of the classifications that were triggered during a DLP incident. Contains the GUIDs and names of the rules that triggered an incident.	Required	Boolean Strings
need_event_xml		Required	Boolean
reporting_product		Required	REPORTING_PRODUCT_PREVENT

Payload

Element	Description
SMTP	The payload must be the full email in .eml format.
HTTP	The payload must include HTTP data. If sending a plain file, wrap it inside an HTTP POST or PUT request.

Metadata

Metadata is part of the HTTP payload and provides additional details about the data being passed. The size of the metadata is specified by the msize query parameter.

The metadata must be a JSON string, containing at minimum the following fields:

Element	Description
protocol → type:	Specifies an array of network protocols. For example, HTTP, TCP, IP, ETH or SMTP, IP, ETH.
version:	Request version. Currently supported is 1.2.

Common Metadata Fields

Element	Description
dip	Destination IP address.
dport	Destination port.
flowid	A unique identifier representing the conversation.
sip	Source IP address.
sport	Source port.
sproxyip	IP of the web gateway sending the request (for HTTP protocol).
timestamp	Unix timestamp of the request.

HTTP-specific Fields

Element	Description
request → authscheme	Authentication scheme (NTLP, WINNT, Kerberos, LDAP).
request → method	HTTP method (For example, POST, GET).
request → url	HTTP URL.
request → user	User Details Based on Authentication Scheme. For example, For Active Directory (AD) - `DOMAIN/sAMAccountName`. For LDAP Authentication - `CN=User,CN=Users,DC=Domain,DC=COM`
request → version	HTTP version.

SMTP-specific Fields

Element	Description
command → helo	HELO SMTP command.
command → mail	MAIL FROM SMTP command.
command → rcpt	Array of RCPT TO SMTP commands.

Sample Metadata for HTTP

{
    "connection": {
        "dip": "0.0.0.0",
        "dport": "80",
        "flowid": "648e_0659_81b0fca2_e70e_458e_9a33_5dab43bac6dd",
        "id": "648e_0659_81b0fca2_e70e_458e_9a33_5dab43bac6dd",
        "sip": "0.0.0.0",
        "sport": "0",
        "sproxyip": "10.213.65.7",
        "timestamp": 1719904996
    },
    "protocol": {
        "http": {
            "request": {
                "authscheme": "UNKNOWN",
                "method": ["POST"],
                "url": ["http://test/"],
                "version": ["HTTP/1.1"]
            }
        },
        "type": ["HTTP", "TCP"]
    },
    "version": "1.2"
}

Sample Metadata for SMTP

{
    "connection": {
        "flowid": "2984_058e_ba11318b_b9dc_4a6b_8eb6_a103b990248d",
        "id": "2984_058e_ba11318b_b9dc_4a6b_8eb6_a103b990248d",
        "sproxyip": "10.213.65.7",
        "timestamp": 1719904712
    },
    "protocol": {
        "smtp": {
            "command": {
                "helo": ["EHLO mdurga-dev"],
                "mail": ["MAIL FROM:<mdurga@mdurga-dev>"],
                "rcpt": ["RCPT TO:<user@client.std.dom>"]
            }
        },
        "type": ["SMTP", "TCP"]
    },
    "version": "1.2"
}

Response parameters

The response parameters provides detailed information about the scan results and incidents triggered. It can include these fields:

Element	Description
classifications_triggered	An array of classification identifiers and names that were triggered during the request. Each classification is represented by a GUID (Globally Unique Identifier) and its corresponding name, indicating the types of sensitive information that matched the configured rules.
event	A Base64-encoded representation of the DLP (Data Loss Prevention) style OPG event. This is primarily used for internal debugging purposes to capture detailed information about the event for troubleshooting.
incident_severity	Specifies the severity level of the incident. Possible values include severity levels such as `PO_SEVERITY_CRITICAL`. This parameter helps categorize incidents based on their criticality and the risk they pose.
num_attachments	The total number of attachments present in the request. This count is useful for identifying the potential volume of data being transferred and can influence the DLP policy enforcement.
opg_id	The unique identifier (GUID) of the DLP policy that was applied to the request. This parameter helps trace which specific policy was responsible for detecting the incident.
opg_name	The name of the DLP policy as configured in ePO (ePolicy Orchestrator). This descriptive name helps administrators quickly identify and review the policy involved in triggering the incident.
opg_revision	The revision number of the DLP policy that was applied during the request. This value can be cross-referenced with the ePO policy revision history to identify changes that may have affected incident detection.
result	Indicates the outcome of the scan on the request. Possible values include whether the scan was "clean" (no incidents detected) or if it "triggered" (one or more rules were matched).
result_action	Specifies the DLP action that was executed based on the policy configuration. For example, PO_ACTION_BLOCK_AND_RETURN_TO_SENDER `indicates that the content was blocked, and a notification was sent back to the sender.`
rules_triggered	An array of GUIDs and corresponding names of the DLP rules that were triggered during the request. Each rule represents a specific set of conditions or patterns defined in the policy, such as detecting sensitive data types or specific keywords.

Sample response

{
    "all_attachments": "abcxyz",
    "classifications_triggered": [
        {
            "id": "72b693e2-2b45-44a9-a0fe-225b82d48561",
            "name": "Confidential"
        }
    ],
    "event": "abc+xyz",
    "global_event_id": "d0ea53ae-5b39-4060-8779-2e3abb7c4243",
    "incident_severity": "PO_SEVERITY_CRITICAL",
    "num_attachments": "1",
    "opg_id": "dad13ad1-52b9-4a15-9a6e-0ffc804de37b",
    "opg_name": "ETP Policy",
    "opg_revision": "11",
    "result": "trigger",
    "result_action": "PO_ACTION_BLOCK_AND_RETURN_TO_SENDER",
    "rules_triggered": [
        {
            "action": "PO_ACTION_BLOCK_AND_RETURN_TO_SENDER",
            "id": "2d620d4b-5080-4a3b-8570-104aff0f3c29",
            "name": "Jay block and return test 1",
            "revision": 41,
            "ruleset": "ETP Rules"
        }
    ],
    "scan_classifications": [
        "fc9a8477-083b-418c-ae08-2e3ad232685c",
        "e98d11ab-c0c9-4ac5-a82e-45b5c29d13a6",
        "e3a84186-f62f-4b6a-8d78-5f991e533fee",
        "bbad1585-97bc-414c-983a-7df6f77b9df8",
        "b9d43045-c0ab-432e-a0f5-0229196743fa",
        "3208e3cc-b87b-4e76-a495-4c69c9472c91",
        "59e6ac67-095d-4a4d-a9bf-df00767163ca",
        "d2a965e8-4782-4bd3-b191-8ecde3b08ca3",
        "2707be46-da80-4100-8d8a-256ff1c021b2",
        "0e8b9940-d329-42a2-99b9-2e4c101fbc03",
        "7375344d-b7dd-4c99-a556-493494032d55",
        "018d0137-dda4-4a3e-90f5-2347fb47fc57",
        "8b95fc20-affe-496b-bbc7-b273ca95835b",
        "72b693e2-2b45-44a9-a0fe-225b82d48561",
        "671a89a7-6e1e-4ee8-9512-de2db36b23b7",
        "9b588e02-45f6-4eaa-a5f2-9a964653b0e0"
    ],
    "stemoverflow": false
}