Trellix HX Endpoint Security

the trellix hx endpoint security connector enables automated interactions with the trellix hx platform for enhanced endpoint protection and incident response trellix hx endpoint security is a robust platform designed for advanced threat detection and response by integrating with swimlane turbine, users can automate critical security operations tasks such as host containment, detailed searches, file acquisition, and alert management this connector empowers security teams to swiftly isolate threats, conduct comprehensive investigations, and manage alerts efficiently, thereby reducing response times and bolstering overall security posture the trellix hx endpoint security connector is capable of interacting with the trellix hx endpoint security rest api to run various triage, acquisition, alert, and contain tasks prerequisites before you can utilize the trellix hx endpoint security connector for turbine, ensure you have the following http basic authentication with these parameters url the endpoint url for the trellix hx api username your trellix hx account username password your trellix hx account password capabilities this trellix hx endpoint security connector provides the following capabilities contain host containment cancellation create search download file acqusition get alert by id get alert groups get alerted hosts get containment state by agent id get containment status get hosts get list of triages get quarantine by id get search results get triage acquisition by id get triage collection by id and so on asset setup trellix hx endpoint security must be configured to allow access to the api after logging into trellix hx endpoint security as an administrator, navigate to admin > appliance settings > user accounts select the api admin account , change the drop down from local login disabled to password set , type in your new password, and click update user swimlane will expect the username api admin , the password you just set, and the host with the port included ( https //myhost 3000 ) you may also use the api analyst user or any other user for swimlane by following the same process and ensuring the user roll is one of api analyst or api admin there are permissions differences between the two different api roles api admin is less restrictive and allows actions like containing hosts and maintaining custom policy channels configurations trellix hx http basic authentication authenticates using username and password configuration parameters parameter description type required url a url to the target host string required username username string required password password string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions contain host initiates containment of a specified host using its agent id to prevent access to other systems on the network endpoint url /hosts/{{agent id}}/containment method post input argument name type required description agent id string required the agent running on the host the agent id is listed on the host details tab for the host endpoint the agent id is automatically generated when the agent first signs on to the primary hx series appliance output parameter type description status code number http status code of the response reason string response reason phrase details array output field details route string output field route message string response message example \[ { "status code" 202, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "details" \[], "route" "/hx/api/v3/hosts/agent id/containment", "message" "accepted" } } ] containment cancellation release a specific host from containment in trellix hx endpoint security using the agent's id endpoint url /hosts/{{agent id}}/containment method delete input argument name type required description agent id string required the agent running on the host the agent id is listed on the host details tab for the host endpoint the agent id is automatically generated when the agent first signs on to the primary hx series appliance output parameter type description status code number http status code of the response reason string response reason phrase response text string output field response text example \[ { "status code" 204, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "no content", "response text" "" } ] create search initiates an enterprise search in trellix hx endpoint security, with options for quick or exhaustive searches endpoint url /searches method post input argument name type required description host set object optional parameter for create search id number optional unique identifier hosts array optional parameter for create search id string optional unique identifier indicator string optional parameter for create search exhaustive object optional parameter for create search override array optional unique identifier item type string optional type of the resource name string optional name of the resource value boolean optional value for the parameter query array optional parameter for create search field string optional parameter for create search operator string optional parameter for create search value string optional value for the parameter output parameter type description status code number http status code of the response reason string response reason phrase data object response data id number unique identifier state string output field state scripts array output field scripts id number unique identifier url string url endpoint for the request download string output field download platform string output field platform update time string time value create time string time value update actor object output field update actor id number unique identifier username string name of the resource create actor object output field create actor id number unique identifier username string name of the resource error array error message if any revision string output field revision input type string input data for the action url string url endpoint for the request host set object output field host set id number unique identifier url string url endpoint for the request example \[ { "status code" 201, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "string", "details" \[], "route" "string" } } ] download file acqusition initiates the download of a specified file from an endpoint using trellix hx, requiring agent id, path, and filename endpoint url /hosts/{{agent id}}/files method post input argument name type required description agent id string required unique identifier req path string required path of the file that you want to acquire req filename string required name of the file that you want to acquire comment string optional general comment req use api boolean optional whether to use the api or raw external id string optional external correlation id from a siem solution output parameter type description status code number http status code of the response reason string response reason phrase file object attachments file string output field file file name string name of the resource example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "wed, 5 jun 2024 20 37 23 gmt" }, "reason" "ok", "file" \[] } ] get alert by id retrieves a specific alert from trellix hx endpoint security using the provided alert id endpoint url /alerts/{{id}} method get input argument name type required description id string required unique alert id output parameter type description status code number http status code of the response reason string response reason phrase data object response data id number unique identifier agent object output field agent appliance object output field appliance id string unique identifier condition object output field condition id string unique identifier url string url endpoint for the request enabled boolean output field enabled uuid string unique identifier tests string output field tests event type string type of the resource indicator object output field indicator id string unique identifier url string url endpoint for the request name string name of the resource uri name string name of the resource display name string name of the resource signature string output field signature category number output field category event id string unique identifier event type string type of the resource event values object value for the parameter example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "string", "details" \[], "route" "string" } } ] get alert groups retrieve a list of all alert groups from trellix hx endpoint security to streamline incident analysis and response endpoint url /alert groups method get input argument name type required description offset number optional specifies which record to start with in the response the default is 0 limit number optional specifies how many records are returned the default is 50 sort array optional sorts the results by the specified field in ascending or descending order the default is sorting by id in descending order sort fields may be followed by " \ asc " or " \ desc " to indicate ascending or descending order multiple sort fields may be specified id string optional unique alert group id host id string optional unique host id host hostname string optional name of the host host primary ip address string optional primary ip address of the host assessment string optional brief assessment of the potential threat file full path string optional full path of the suspect file acknowledgement acknowledged boolean optional the alert has been acknowledged acknowledgement acknowledged by string optional user who has been acknowledged the alert acknowledgement acknowledged time string optional time alert was acknowledged source string optional source of alert valid values include "ioc" (indicator of compromise), "exd" (exploit detection), and "mal" (malware alert), etc has fp disposition boolean optional identifies which alert groups have an associated fp filter last alert resolution string optional resolution of the most recent alert grouped by md5sum string optional md5 hash from the alert group filter filterquery string optional the filterquery parameter allows for very specific filtering of search results this must be an url encoded json object output parameter type description status code number http status code of the response reason string response reason phrase data object response data total number output field total query object output field query sort object output field sort offset number output field offset limit number output field limit entries array output field entries id string unique identifier url string url endpoint for the request host object output field host id string unique identifier url string url endpoint for the request hostname string name of the resource primary ip address string output field primary ip address assessment string output field assessment file full path string output field file full path acknowledgement object output field acknowledgement acknowledged boolean output field acknowledged acknowledged by string output field acknowledged by acknowledged time string time value stats object output field stats events number output field events first event at string output field first event at example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "string", "details" \[], "route" "string" } } ] get alerted hosts retrieves a list of hosts with alert conditions linked to a specific source alert id in trellix hx endpoint security endpoint url /source alerts/{{id}}/alerted hosts method get input argument name type required description id string required unique alert id offset number optional specifies which record to start with in the response the default is 0 limit number optional specifies how many records are returned the default is 50 sort array optional sorts the results by the specified field in ascending or descending order the default is sorting by id in descending order sort fields may be followed by " \ asc " or " \ desc " to indicate ascending or descending order multiple sort fields may be specified id string optional unique agent id agent version string optional agent version containment queued boolean optional containment requested containment state string optional containment state last audit timestamp string optional time when the most recent system information audit was performed last alert timestamp string optional the time stamp of the most recent alert for the host hostname string optional name of the host domain string optional network domain gmt offset seconds number optional how many seconds the offset is from greenwich mean time (gmt) timezone string optional timezone name os product name string optional operating system name os patch level string optional operating system patch os bitness string optional operating system word size os platform string optional family of operating systems reported clone boolean optional indicates more than one host has this same agent id stats alerting conditions number optional number of alerting conditions stats acqs number optional number of file acquisition requests stats alerts number optional total number of alerts, including exploit detection alerts stats exploit alerts number optional number of exploit alerts, partially blocked exploits, and blocked exploits stats malware alerts number optional the number of malware alerts on the host stats generic alerts number optional the number of generic alerts on the host output parameter type description status code number http status code of the response reason string response reason phrase data object response data total number output field total query object output field query host sets query object output field host sets query operator string output field operator operands array output field operands setid number unique identifier operator string output field operator operands array output field operands sort object output field sort offset number output field offset limit number output field limit entries array output field entries id string unique identifier agent version string output field agent version excluded from containment boolean output field excluded from containment containment missing software boolean output field containment missing software containment queued boolean output field containment queued containment state string output field containment state stats object output field stats acqs number output field acqs malware cleaned count number count value malware quarantined count number count value example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "ok", "details" \[], "route" "/hx/api/v3/host policies/channels/id/hosts" } } ] get containment state by agent id fetches the containment state of a specific agent in trellix hx endpoint security using the agent id endpoint url /hosts/{{agent id}}/containment method get input argument name type required description agent id string required the agent running on the host the agent id is listed on the host details tab for the host endpoint the agent id is automatically generated when the agent first signs on to the primary hx series appliance output parameter type description status code number http status code of the response reason string response reason phrase details array output field details route string output field route data object response data id string unique identifier last sysinfo string output field last sysinfo requested by actor object output field requested by actor requested on object output field requested on contained by actor object output field contained by actor contained on object output field contained on queued boolean output field queued excluded boolean output field excluded missing software boolean output field missing software reported clone boolean output field reported clone state string output field state state update time string time value url string url endpoint for the request message string response message example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "details" \[], "route" "/hx/api/v3/hosts/agent id/containment", "data" {}, "message" "ok" } } ] get containment status fetches the containment state for all known hosts within trellix hx endpoint security endpoint url /containment states method get input argument name type required description state update time string optional retrieves only hosts that have state update time greater than the value specified offset number optional specifies which record to start with in the response the default is 0 limit number optional specifies how many records are returned the default is 50 output parameter type description status code number http status code of the response reason string response reason phrase data object response data total number output field total query object output field query sort object output field sort offset number output field offset limit number output field limit entries array output field entries id string unique identifier last sysinfo string output field last sysinfo requested by actor object output field requested by actor id number unique identifier username string name of the resource requested on string output field requested on contained by actor object output field contained by actor contained on object output field contained on queued boolean output field queued excluded boolean output field excluded missing software boolean output field missing software reported clone boolean output field reported clone state string output field state state update time string time value url string url endpoint for the request message string response message example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "ok", "details" \[], "route" "/hx/api/v3/containment states" } } ] get hosts obtain a list of hosts from the trellix hx endpoint security server for monitoring and management purposes endpoint url /hosts method get input argument name type required description offset number optional specifies which record to start with in the response the default is 0 limit number optional specifies how many records are returned the default is 50 sort array optional sorts the results by the specified field in ascending or descending order the default is sorting by id in descending order sort fields may be followed by " \ asc " or " \ desc " to indicate ascending or descending order multiple sort fields may be specified id string optional unique agent id agent version string optional agent version containment queued boolean optional containment requested containment state string optional containment state last audit timestamp string optional time when the most recent system information audit was performed last alert timestamp string optional the time stamp of the most recent alert for the host hostname string optional name of the host domain string optional network domain gmt offset seconds number optional how many seconds the offset is from greenwich mean time (gmt) timezone string optional timezone name os product name string optional operating system name os patch level string optional operating system patch os bitness string optional operating system word size os platform string optional family of operating systems reported clone boolean optional indicates more than one host has this same agent id stats alerting conditions number optional number of alerting conditions stats acqs number optional number of file acquisition requests stats alerts number optional total number of alerts, including exploit detection alerts stats exploit alerts number optional number of exploit alerts, partially blocked exploits, and blocked exploits stats malware alerts number optional the number of malware alerts on the host stats generic alerts number optional the number of generic alerts on the host stats malware cleaned count number optional the number of cleaned malware on the host output parameter type description status code number http status code of the response reason string response reason phrase data object response data total number output field total query object output field query host sets query object output field host sets query operator string output field operator operands array output field operands setid number unique identifier operator string output field operator operands array output field operands sort object output field sort offset number output field offset limit number output field limit entries array output field entries id string unique identifier agent version string output field agent version excluded from containment boolean output field excluded from containment containment missing software boolean output field containment missing software containment queued boolean output field containment queued containment state string output field containment state stats object output field stats acqs number output field acqs malware cleaned count number count value malware quarantined count number count value example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "ok", "details" \[], "route" "/hx/api/v3/host policies/channels/id/hosts" } } ] get list of triages retrieve a list of triage entries from trellix hx endpoint security, detailing known system issues endpoint url /acqs/triages method get input argument name type required description offset number optional specifies which record to start with in the response the default is 0 limit number optional specifies how many records are returned the default is 50 sort array optional sorts the results by the specified field in ascending or descending order the default is sorting by id in descending order sort fields may be followed by " \ asc " or " \ desc " to indicate ascending or descending order multiple sort fields may be specified search string optional global search value external id string optional filter triage acquisitions by external correlation id from a siem solution host id string optional filter triage acquisitions by host id output parameter type description status code number http status code of the response reason string response reason phrase data object response data total number output field total query object output field query sort object output field sort offset number output field offset limit number output field limit entries array output field entries id number unique identifier revision string output field revision error message object response message state string output field state md5 object output field md5 request time string time value request actor object output field request actor id number unique identifier username string name of the resource req timestamp object output field req timestamp comment string output field comment external id object unique identifier finish time object time value indicator object output field indicator disable cef boolean output field disable cef url string url endpoint for the request example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "ok", "details" \[], "route" "/hx/api/v3/acqs/triages" } } ] get quarantine by id retrieves details of a specific quarantine entry from trellix hx endpoint security using the provided id endpoint url /quarantines/{{id}} method get input argument name type required description id number required unique quarantine id output parameter type description status code number http status code of the response reason string response reason phrase details array output field details file name string name of the resource file string output field file route string output field route data object response data id number unique identifier agent quarantine id string unique identifier hit correlation id string unique identifier file path string output field file path file md5 string output field file md5 file sha1 string output field file sha1 reported at string output field reported at quarantined at string output field quarantined at alert file creation time string time value alert infection name string name of the resource state string output field state update time string time value url string url endpoint for the request host object output field host id string unique identifier url string url endpoint for the request alert object output field alert id number unique identifier example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "details" \[], "route" "/hx/api/v3/quarantines/id", "data" {}, "message" "ok" } } ] get search results retrieve a list of all enterprise searches conducted within trellix hx endpoint security endpoint url /searches method get input argument name type required description offset number optional specifies which record to start with in the response the default is 0 limit number optional specifies how many records are returned the default is 50 sort array optional sorts the results by the specified field in ascending or descending order the default is sorting by id in descending order sort fields may be followed by " \ asc " or " \ desc " to indicate ascending or descending order multiple sort fields may be specified state string optional filter by search state host set id number optional filter searches by host set id update actor id number optional filter searches by user id that last updated searches update actor username string optional filter searches by username that last updated searches create actor id number optional filter searches by user id that created searches create actor username string optional filter searches by username that created searches settings mode string optional filter searches based on the search mode, the value can be host or grid input type string optional filter searches based on how the search started , the value can be ui or api output parameter type description status code number http status code of the response reason string response reason phrase data object response data total number output field total query object output field query sort object output field sort offset number output field offset limit number output field limit entries array output field entries id number unique identifier url string url endpoint for the request state string output field state scripts array output field scripts id number unique identifier url string url endpoint for the request download string output field download platform string output field platform host set object output field host set id number unique identifier url string url endpoint for the request name string name of the resource update time string time value create time string time value update actor object output field update actor id number unique identifier example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "data" {}, "message" "string", "details" \[], "route" "string" } } ] get triage acquisition by id fetches details of a specific triage acquisition from trellix hx endpoint security using the provided id endpoint url /acqs/triages/{{id}} method get input argument name type required description id string required unique acquisition id output parameter type description status code number http status code of the response reason string response reason phrase details array output field details route string output field route data object response data id number unique identifier revision string output field revision error message string response message state string output field state md5 object output field md5 request time string time value request actor object output field request actor id number unique identifier username string name of the resource req timestamp object output field req timestamp comment string output field comment external id object unique identifier finish time string time value indicator object output field indicator disable cef boolean output field disable cef url string url endpoint for the request host object output field host id string unique identifier url string url endpoint for the request alert object output field alert example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "details" \[], "route" "/hx/api/v3/acqs/triages/id", "data" {}, "message" "ok" } } ] get triage collection by id retrieves a specific triage collection (mans file) from trellix hx endpoint security using the provided id endpoint url /acqs/triages/{{id}} mans method get input argument name type required description id string required unique acquisition id output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" {} } ] new triage acquisition initiates a new triage acquisition for a specified agent in trellix hx endpoint security using the agent id endpoint url /hosts/{{agent id}}/triages method post input argument name type required description agent id string required unique agent id req timestamp string optional the triage collection for this time external id string optional external correlation id from a siem solution disable cef boolean optional when "disable cef" is set to false, and when cef logging is enabled, endpoint security will log each triage or bulk acquisition task creation, pickup, and completion when "disable cef" is true, this logging is skipped output parameter type description status code number http status code of the response reason string response reason phrase details array output field details route string output field route data object response data id number unique identifier revision string output field revision error message string response message state string output field state md5 object output field md5 request time string time value request actor object output field request actor id number unique identifier username string name of the resource req timestamp object output field req timestamp comment string output field comment external id object unique identifier finish time string time value indicator object output field indicator disable cef boolean output field disable cef url string url endpoint for the request host object output field host id string unique identifier url string url endpoint for the request alert object output field alert example \[ { "status code" 201, "response headers" { "content length" "140", "content type" "application/json", "date" "mon, 10 jun 2024 20 37 23 gmt" }, "reason" "ok", "json body" { "details" \[], "route" "/hx/api/v3/acqs/triages/id", "data" {}, "message" "ok" } } ] response headers header description example content length the length of the response body in bytes 140 content type the media type of the resource application/json date the date and time at which the message was originated mon, 10 jun 2024 20 37 23 gmt notes trellix doc portal https //docs trellix com/bundle/hx api 2020 2/page/uuid e2c37f22 ed87 8470 e318 90c52ddaafdb htmltrellix hx endpoint security api specs https //fireeye dev/apis/lighthouse/