WithSecure Elements Endpoint Security

the withsecure elements endpoint security connector enables streamlined security automation for incident management and device monitoring within an organization's network withsecure elements endpoint security offers a robust platform for endpoint protection and response, safeguarding against sophisticated cyber threats this connector enables swimlane turbine users to integrate seamlessly with withsecure's capabilities, allowing for automated incident commenting, response action creation, device management, and user information retrieval by leveraging this integration, security teams can efficiently manage incidents, respond to threats proactively, and maintain visibility over their security posture, all within the swimlane turbine environment withsecure elements connector can be deployed in a security events forwarder role to pull data from withsecure elements and forward it to almost any siem using syslog, common event format (cef) or log event extended format (leef) elements connector is fully managed from the withsecure elements security center specifically, you can configure the use of the forwarding feature for the whole partner scope or limit it to a certain company see the https //www withsecure com/userguides/product html#business/connector/latest/en for more details prerequisites to utilize the withsecure elements endpoint security connector with swimlane turbine, ensure you have the following prerequisites custom authentication with the following parameters url the endpoint url for the withsecure api client id your unique identifier for withsecure api access client secret a secret key associated with your client id to authenticate api requests capabilities the withsecure elements endpoint security connector provides the following capabilities add comment to incidents create new response actions delete devices get current user information list created response actions list detection for incident in organization scope list device operations list incidents in organization scope list organizations query devices query epp, edr and collaboration security events read list of security events trigger new remote operation on devices update devices update status of incidents asset setup login to the withsecure elements security center https //elements withsecure com/ goto management > organization settings > api clients and create an new api client copy th client id, client secret use it for asset setup tasks setup query devices the query devices endpoint can be used for following usecases list devices get statistics about devices get histogram with device statistics for the last 30 days first use case is supported when accept header is set to application/json second use case requires accept header equal to application/vnd withsecure aggr+json and count parameter to be set third use case requires accept header equal to application/vnd withsecure aggr+json and histogram parameter to be set with application/json accept header endpoint returns list of devices for given organization retrieves devices matching all filters that are used in query when query contains "deviceid" parameter then other used filters are ignored with application/vnd withsecure aggr+json accept header endpoint returns aggregations aggregations provide useful statistical overview for the broader picture of organization's assets devices are first filtered according to the provided query parameters and then grouped and counted use count query parameter to select the property by which values devices will be counted histogram query parameter works exactly the same as count, with only difference that histogram will return aggregations data for the last 30 days count and histogram parameters can't be used together in a single query filters supported with count and histogram parameters organizationid, type, name, online, label, clientversion, protectionstatusoverview trigger new remote operation on devices triggering has two stages operation is created in the internal backend operation is triggered on the remote host successful response only means that the operation was created in the internal backend (first stage) client can query operations for the device to check status from the remote host (second stage) depending on an operation type, additional arguments might be required they should be sent in the body parameters map like object operation specific information in the response may be returned in the metadataparameters map like object check the list of supported operations https //connect withsecure com/api reference/elements#post /devices/v1/operations update devices endpoint may be used to change device state change device subscription can find more details about above scenarios https //connect withsecure com/api reference/elements#patch /devices/v1/devices query epp, edr and collaboration protection security events this endpoint supports following response formats items page (default) endpoint return security events matching filter parameters as page of items where each item represents security event object client iterate over search results using page anchor and it can decide about page size and items ordering aggregation endpoint groups and counts security events matching filter parameters by property selected by the client to select this mode client must add http header accept application/vnd withsecure aggr+json to the request additionally it has to add parameter count={property name} the request parameters usage and examples can be found https //connect withsecure com/api reference/elements#post /security events/v1/security events read list of security events this endpoint is kept in maintenance mode which means it will receive only bugfixes and any new feature won't be added in the future create new response action check the supported action types and parameters https //connect withsecure com/api reference/elements#post /response actions/v1/response actions before choosing this connector action notes https //connect withsecure com/api reference/elements configurations withsecure edr oauth2 0 authentication authentication using client id and client secret configuration parameters parameter description type required url a url to the target host string required verify ssl verify ssl certificate boolean optional token url string optional client id the client id string required client secret the client secret string required http proxy a proxy to route requests through string optional actions add comment to incidents adds a specified comment to selected incidents in withsecure elements endpoint security using target identifiers endpoint url /incidents/v1/comments method post input argument name type required description targets array optional list of incident ids to comment min items 1 max items 10 comment string optional comment to add to the target incidents input example {"json body" {"targets" \["2c902c73 e2a6 40fd 9532 257ee102e1c1"],"comment" "ticket 1234"}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items incidentid string unique identifier items comment string output field items comment output example {"status code" 200,"response headers" {},"reason" "ok","json body" {"items" \[{},{}]}} create new response action initiates a response action on specified targets within withsecure elements endpoint security using organizationid, type, and targets endpoint url /response actions/v1/response actions method post input argument name type required description organizationid string optional id of organization to which target devices belong type string optional type of action targets array optional list of targets (device identifiers) on which action is created min items 1 max items 10 comment string optional additional comment for action parameters maxfilehash number optional maximum file size to hash, in mb prevents excessive delays when hashing large files (required in netstat) parameters threadid number optional thread id (required in killthread) parameters match string optional strategy used to match processes (required in killprocess) parameters processmemorydump boolean optional run memory dump on process before killing it required in killprocess memory dump can be run only if processname or processid strategy is used parameters memorydumpflag string optional flag that will be used when dumping the process memory required in killprocess full memory dump includes all accessible memory of process, pmem only information necessary to capture process' stack traces parameters processmatchvalues array optional list of values that are used to match process to kill (required in killprocess) depending on selected strategy it might be list of identifiers, names or regular expressions min items 1 max items 6 parameters capturememory boolean optional take capture of system's memory required in fullmemorydumpwhen linux devices are selected as targets parameters collectprofile boolean optional collect files required to build a kernel profile required in fullmemorydump when linux devices are selected as targets parameters winpmemversion string optional version of winpmem to use required in fullmemorydump when windows devices are selected as targets input example {"json body" {"organizationid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad","type" "killthread","targets" \["ec8a0100 d313 4896 b3cb 02188e060bf3","01898f1e d32d 40fe b3c5 9f039c1eac04"],"comment" "string","parameters" {"maxfilehash" 10,"threadid" 23435,"match" "processname","processmemorydump"\ false,"memorydumpflag" "full","processmatchvalues" "killprocess","capturememory"\ true,"collectprofile"\ true,"winpmemversion" "v1 6"}}} output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier output example {"status code" 200,"response headers" {"date" "mon, 09 sep 2024 10 11 29 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 d425d30e3a4a4a79","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "ok","json body" {"id" "string"}} delete devices removes specified devices from withsecure elements endpoint security, freeing up subscription seats and hiding them from the device list endpoint url /devices/v1/devices method delete input argument name type required description parameters deviceid array required list of device id's to be deleted up to 20 items input example {"parameters" {"deviceid" \["string"]}} output parameter type description status code number http status code of the response reason string response reason phrase devices array output field devices output example {"status code" 200,"response headers" {"date" "mon, 09 sep 2024 07 12 50 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 cac6b1b18e344010","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "ok","json body" {"devices" \["ec8a0100 d313 4896 b3cb 02188e060bf3","01898f1e d32d 40fe b3c5 9f039c1eac04"]}} get current user information retrieve details about the currently authenticated user in withsecure elements endpoint security endpoint url /whoami/v1/whoami method get output parameter type description status code number http status code of the response reason string response reason phrase clientid string unique identifier organizationid string unique identifier output example {"status code" 200,"response headers" {"date" "wed, 11 sep 2024 09 51 32 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 ba65dbf08940468b","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "","json body" {"clientid" "fusion df13a6b8f1314e549b539930","organizationid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad"}} list created response actions retrieve a list of response actions created for rdr sensors in withsecure elements endpoint security, requiring an organizationid endpoint url /response actions/v1/responses method get input argument name type required description parameters organizationid string required uuid of an organization parameters order string optional sorting order parameters anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page parameters type string optional filter by response action type parameters actionid string optional filter by response action id parameters state string optional filter by response action state parameters comment string optional filter by comment matches any part of the comment parameters author string optional filter by author username parameters result string optional filter by response action result parameters deviceid string optional uuid of a device parameters limit number optional the size of the single batch value defines upper bound for number of items, that are sent in single response however it doesn't guarantee, that response will contain exact number of items if next page exist client that reads all items matching query parameters should depend only on nextanchor property, which contain link to next result client can stop iteration when nextanchor is missing in response input example {"parameters" {"organizationid" "ec8a0100 d313 4896 b3cb 02188e060bf3","order" "desc","anchor" "no value","type" "","actionid" "","state" "","comment" "","author" "","result" "succeeded","deviceid" "","limit" 10}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items id string unique identifier items type string type of the resource items state string output field items state items progress object output field items progress items progress devicescount number count value items progress pendingtaskscount number count value items progress errortaskscount number error message if any items progress activetaskscount number count value items progress completedtaskscount number count value items progress successfullycompletedtaskscount number whether the operation was successful items createdtimestamp string output field items createdtimestamp items updatedtimestamp string output field items updatedtimestamp items devices array output field items devices items devices deviceid string unique identifier items author object output field items author items author id string unique identifier items author source string output field items author source items author username string name of the resource items comment string output field items comment items result string result of the operation nextanchor string output field nextanchor output example {"status code" 200,"response headers" {"date" "mon, 09 sep 2024 10 59 03 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 8ea252f7eaa348b7","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "","json body" {"items" \[{}],"nextanchor" "string"}} list detections for incident in organization scope retrieve a list of detections for a specified incident within an organization's scope, ordered by time in descending order endpoint url /incidents/v1/detections method get input argument name type required description parameters organizationid string optional uuid of an organization if organizationid is missing, default organization of authenticated client is used parameters incidentid string required id of an incident client can find that value in details of edr security event incident id must match uuid format parameters anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page parameters createdtimestampstart string optional lower, inclusive bound for createdtimestamp in the returned list cannot be used with updatedtimestamp filters parameters createdtimestampend string optional upper, exclusive bound for createdtimestamp in the returned list cannot be used with updatedtimestamp filters parameters limit number optional maximal number of items in response min > 1, max > 100 input example {"parameters" {"organizationid" "ec8a0100 d313 4896 b3cb 02188e060bf3","incidentid" "ec8a0100 d313 4896 b3cb 02188e060bf3","anchor" "no value","createdtimestampstart" "2023 03 22t13 34 51 097z","createdtimestampend" "2023 03 22t13 34 51 097z","limit" "20"}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items detectionid string unique identifier items incidentid string unique identifier items deviceid string unique identifier items name string name of the resource items detectionclass string output field items detectionclass items severity string output field items severity items risklevel string output field items risklevel items exepath string output field items exepath items exename string name of the resource items exehash string output field items exehash items cmdl string output field items cmdl items pid number unique identifier items createdtimestamp string output field items createdtimestamp items initialreceivedtimestamp string output field items initialreceivedtimestamp items username string name of the resource items privileges string output field items privileges items activitycontext array output field items activitycontext items activitycontext type string type of the resource items activitycontext description string output field items activitycontext description items activitycontext detectionavgcount number count value items activitycontext detectionmaxcount number count value items activitycontext detectionavgsensors number output field items activitycontext detectionavgsensors output example {"status code" 200,"reason" "ok","json body" {"items" \[{}],"nextanchor" "next page ref"}} list device operations retrieves a list of operations triggered on a specified device within withsecure elements endpoint security; returns empty for inactive devices endpoint url /devices/v1/operations method get input argument name type required description parameters deviceid string required uuid of a device input example {"parameters" {"deviceid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad"}} output parameter type description items array output field items items id string unique identifier items status string status value items operationname string name of the resource items startedtimestamp string output field items startedtimestamp items lastupdatedtimestamp string output field items lastupdatedtimestamp items expirationtimestamp string output field items expirationtimestamp items metadata object response data items metadata profileid string response data output example {"items" \[{"id" "7243413413490181","status" "pending","operationname" "isolatefromnetwork","startedtimestamp" "2023 04 01t15 08 17z","lastupdatedtimestamp" "2023 04 01t15 08 17z","expirationtimestamp" "2023 04 15t15 08 17z","metadata" {}},{"id" "7243413413490193","status" "pending","operationname" "assignprofile","startedtimestamp" "2023 04 01t15 08 17z","lastupdatedtimestamp" "2023 04 01t15 08 17z","expirationtimestamp" "2023 04 15t15 08 17z","metadata" {}}]} list incidents in organization scope retrieve a list of incidents within a specified organization and time frame using withsecure elements endpoint security endpoint url /incidents/v1/incidents method get input argument name type required description parameters anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page parameters organizationid string optional uuid of an organization if organizationid is missing, default organization of authenticated client is used parameters incidentid string optional uuid of the incident parameters createdtimestampstart string optional lower, inclusive bound for createdtimestamp in the returned list cannot be used with updatedtimestamp filters parameters createdtimestampend string optional upper, exclusive bound for createdtimestamp in the returned list cannot be used with updatedtimestamp filters parameters updatedtimestampstart string optional lower, inclusive bound for updatedtimestamp in the returned list cannot be used with createdtimestamp filters parameters updatedtimestampend string optional upper, exclusive bound for updatedtimestamp in the returned list cannot be used with createdtimestamp filters parameters exclusivestart boolean optional if equals "true", then createdtimestampstart and updatedtimestampstart are used as exclusive lower bound otherwise, createdtimestampstart and updatedtimestampstart are inclusive parameters status string optional status of the incidents to return to filter by multiple statuses add this parameter repeatedly parameters resolution string optional resolution of the incident to return to filter by multiple resolutions add this parameter repeatedly parameters risklevel string optional filters by risk level to filter by multiple risk levels add this parameter repeatedly parameters archived boolean optional specify whether archived incidents should be send in response it is advised to query only not archived incidents as it might have positive impact on query performance it is strongly advised to add archived=false parameters limit number optional maximal number of items in response min 1 to max 50 parameters order string optional specifies sorting order input example {"parameters" {"anchor" "no value","organizationid" "ec8a0100 d313 4896 b3cb 02188e060bf3","incidentid" "2c902c73 e2a6 40fd 9532 257ee102e1c1","createdtimestampstart" "","createdtimestampend" "","updatedtimestampstart" "","updatedtimestampend" "","exclusivestart"\ false,"status" "new","resolution" "unconfirmed","risklevel" "info","archived"\ false,"limit" 20,"order" "desc"}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items organizationid string unique identifier items severity string output field items severity items risklevel string output field items risklevel items riskscore number score value items incidentpublicid string unique identifier items createdtimestamp string output field items createdtimestamp items name string name of the resource items incidentid string unique identifier items initialreceivedtimestamp string output field items initialreceivedtimestamp items resolution string output field items resolution items updatedtimestamp string output field items updatedtimestamp items status string status value items categories array output field items categories nextanchor string output field nextanchor output example {"status code" 200,"response headers" {"date" "mon, 09 sep 2024 10 35 40 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 4baa6e30943a485f","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "","json body" {"items" \[{},{}],"nextanchor" "next page ref"}} list organizations retrieve a list of organizations associated with the specified withsecure elements endpoint security organization, including the organization itself endpoint url /organizations/v1/organizations method get input argument name type required description parameters organizationid string optional uuid of an organization if organizationid is missing, default organization of authenticated client is used parameters anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page parameters type string optional filter by organization type matches all organizations of this type parameters limit number optional the size of the single batch value defines upper bound for number of items, that are sent in single response however it doesn't guarantee, that response will contain exact number of items if next page exist client that reads all items matching query parameters should depend only on nextanchor property, which contain link to next result client can stop iteration when nextanchor is missing in response input example {"parameters" {"organizationid" "ec8a0100 d313 4896 b3cb 02188e060bf3","anchor" "no value","type" "company","limit" "200"}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items name string name of the resource items id string unique identifier items type string type of the resource output example {"status code" 200,"response headers" {"date" "wed, 04 sep 2024 11 10 18 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 dccdc640d48c4c10","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "","json body" {"items" \[{}]}} query devices executes a query to retrieve information about the organization's devices within withsecure elements endpoint security endpoint url /devices/v1/devices method get input argument name type required description parameters anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page parameters organizationid string optional uuid of an organization if organizationid is missing, default organization of authenticated client is used parameters deviceid string optional uuid of a device parameters type string optional filter by device type matches all devices of this type if type is missing, all types of devices are included in response parameters state string optional filter by device state matches all devices of this state if state is missing, only active devices are included in response parameters name string optional filter devices by device name (exact match) parameters serialnumber string optional filter devices by device serial number (exact match) parameters online boolean optional filter devices by online state parameters label string optional filter by single label matches all devices that contains at least this label parameters clientversion string optional filter devices by client version (exact match) parameters protectionstatusoverview string optional filter devices by protection status overview parameters patchoverallstate string optional filter devices by protection status overview parameters publicipaddress string optional public ip address of the device parameters organizationname string optional name of organization (company or partner) parameters osname string optional name of the operating system that is installed on the device parameters activedirectorygroup string optional name of the active directory group parameters subscriptionkey string optional filter by subscription key that device registered with only devices in given subscription key are returned required format is xxxx xxxx xxxx xxxx xxxx where x is either a digit or an uppercase letter parameters count string optional name of the property to use in aggregation when count parameter is provided and accept header is set to application/vnd withsecure aggr+json then response contains aggregation data devices matching query parameters are grouped and counted by selected property values count and histogram parameters can't be used together in a single query parameters histogram string optional name of the property to use in histogram type aggregation when histogram parameter is provided and accept header is set to application/vnd withsecure aggr+json then response contains aggregation data in the histogram form aggregation data is returned for every date from last 30 days devices matching query parameters are grouped and counted by selected property values count and histogram parameters can't be used together in a single query parameters limit number optional the size of the single batch value defines upper bound for number of items, that are sent in single response however it doesn't guarantee, that response will contain exact number of items if next page exist client that reads all items matching query parameters should depend only on nextanchor property, which contain link to next result client can stop iteration when nextanchor is missing in response headers object optional http headers for the request headers accept string optional http headers for the request input example {"parameters" {"anchor" "no value","organizationid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad","deviceid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad","type" "computer","state" "active","name" "","serialnumber" "","online"\ false,"label" "","clientversion" "","protectionstatusoverview" "isolated","patchoverallstate" "missingcriticalupdates","publicipaddress" "","organizationname" "","osname" "","activedirectorygroup" "","subscriptionkey" "","count" "protectionstatus","histogram" "protectionstatus","limit" 20},"headers" {"accept" "application/json"}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items file name string name of the resource items file string output field items file output example {"status code" 200,"response headers" {"date" "wed, 11 sep 2024 08 43 53 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 62bdff98fa4c42f1","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "","json body" {"items" \[]}} query epp, edr and collaboration security events executes a search query against epp, edr, and collaboration protection security events in withsecure elements endpoint security, returning results in json includes events from child companies for partners endpoint url /security events/v1/security events method post input argument name type required description headers object required http headers for the request headers content type string required http header that defines format of request body headers accept string required htp header defines expected format of response body client should use header application/vnd withsecure aggr+json to receive aggregated results security events grouped and counted by selected property data body object optional response data data body organizationid string optional id of an organization if organizationid is missing, default organization of authenticated client is used data body persistencetimestampstart string optional lower bound for persistence timestamp in the returned security events minimum allowed value is 2022 08 01t00 00 01z data body persistencetimestampend string optional upper, exclusive bound for persistence timestamp in the returned security events data body engine array optional response data data body enginegroup array optional engine that triggered event data body severity array optional event's severity data body targetid string optional id of event's target either id of device or e mail address when parameter is present response contains all events related to epp device or office 365 entity data body acknowledged boolean optional filter security events by acknowledgement status if parameter is missing then response contains all events data body count string optional name of property to use in aggregation all security events matching filter parameters are grouped and counted by selected property this parameter is required when client sends request with http header accept= application/vnd withsecure aggr+json data body anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page data body order string optional sorting order data body exclusivestart boolean optional if equals true, then persistencetimestampstart is used as exclusive lower bound otherwise, persistencetimestampstart is inclusive data body limit number optional the size of the single batch min 1 to max 200 value defines upper bound for number of items, that are sent in single response however it doesn't guarantee, that response will contain exact number of items if next page exist client that reads all items matching query parameters should depend only on nextanchor property, which contain link to next result client can stop iteration when nextanchor is missing in response input example {"headers" {"content type" "application/x www form urlencoded","accept" "application/json"},"data body" {"organizationid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad","persistencetimestampstart" "2022 08 01t00 00 01z","persistencetimestampend" "2022 08 01t00 00 01z","engine" \["engine1","engine2"],"enginegroup" \["ecp","edr"],"severity" \["critical","warning"],"targetid" "string","acknowledged"\ true,"count" "engine","anchor" "no value","order" "desc","exclusivestart"\ true,"limit" 50}} output parameter type description status code number http status code of the response reason string response reason phrase items array output field items items id string unique identifier items action string output field items action items engine string output field items engine items severity string output field items severity items servertimestamp string output field items servertimestamp items persistencetimestamp string output field items persistencetimestamp items eventtransactionid string unique identifier items clienttimestamp string output field items clienttimestamp items acknowledged boolean output field items acknowledged items organization object output field items organization items organization id string unique identifier items organization name string name of the resource items target object output field items target items target name string name of the resource items target id string unique identifier items device object output field items device items device id string unique identifier items device name string name of the resource items username string name of the resource items details object output field items details items details profilename string name of the resource items details path string output field items details path output example {"status code" 200,"response headers" {"date" "mon, 09 sep 2024 10 44 48 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 c460567a9f914407","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "ok","json body" {"items" \[{}],"nextanchor" "link to next page"}} read list of security events retrieve a list of security events within a specified time frame for a given organization, including hierarchical data if requested with a partner organizationid endpoint url /security events/v1/security events method get input argument name type required description parameters organizationid string optional uuid of an organization if organizationid is missing, default organization of authenticated client is used parameters engine array optional filter by engines that triggered event parameters persistencetimestampstart string optional lower bound for persistence timestamp in the returned security events minimum allowed value is 2022 08 01t00 00 01z parameters persistencetimestampend string optional upper, exclusive bound for persistence timestamp in the returned security events parameters servertimestampstart string optional lower bound for server timestamp in the returned security events parameters servertimestampend string optional upper, exclusive bound for server timestamp in the returned security events parameters severity string optional filter by event's severities parameters anchor string optional anchor pointing to the page that should be retrieved if the parameter is missing or equal to default value then endpoint returns first page parameters order string optional sorting order parameters exclusivestart boolean optional if equals "true", then persistencetimestampstart and servertimestampstart are used as exclusive lower bound otherwise, persistencetimestampstart and servertimestampstart are inclusive parameters limit number optional the size of the single batch min 1 to max 200 value defines upper bound for number of items, that are sent in single response however it doesn't guarantee, that response will contain exact number of items if next page exist client that reads all items matching query parameters should depend only on nextanchor property, which contain link to next result client can stop iteration when nextanchor is missing in response input example {"parameters" {"organizationid" "5a1b6078 3c68 4870 9d2b 4f1fff3485ad","engine" \["{engine1}","{engine2}"],"persistencetimestampstart" "","persistencetimestampend" "","servertimestampstart" "","servertimestampend" "","severity" "desc","anchor" "no value","order" "critical","exclusivestart"\ false,"limit" 200}} output parameter type description status code number http status code of the response items array output field items items id string unique identifier items servertimestamp string output field items servertimestamp items clienttimestamp string output field items clienttimestamp items persistencetimestamp string output field items persistencetimestamp items engine string output field items engine items severity string output field items severity items action string output field items action items organization object output field items organization items organization id string unique identifier items organization name string name of the resource items device object output field items device items device id string unique identifier items device name string name of the resource items device winsaddress string output field items device winsaddress items eventtransactionid string unique identifier items username string name of the resource nextanchor string output field nextanchor output example {"status code" 200,"response headers" {"date" "mon, 09 sep 2024 10 44 48 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 c460567a9f914407","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "","json body" {"items" \[{}],"nextanchor" "string"}} trigger new remote operation on devices initiates a specified operation on active devices within the client's organization using their uuids provided in the request body endpoint url /devices/v1/operations method post input argument name type required description operation string optional type of an operation to execute parameters message string optional for isolatefromnetwork and showmessage operations constraint > max 512 characters parameters consentmessage string optional for collectdiagnosticfile operation constraint > max 512 characters parameters profileid number optional for assignprofile operation parameters feature string optional for turnonfeature operation parameters turnontimeout number optional for turnonfeature operation must be between 5 and 1440 debug logging also turns off automatically with the device restart targets array optional list of targets (device identifiers) on which operation will be execute min items= 1 and max items =5 input example {"json body" {"operation" "isolatefromnetwork","parameters" {"message" "your device will be isolated","consentmessage" "","profileid" 123,"feature" "debuglogging","turnontimeout" 5},"metadataparameters" \[{"fileid" "string"}],"targets" \["ec8a0100 d313 4896 b3cb 02188e060bf3","01898f1e d32d 40fe b3c5 9f039c1eac04","1226e0a9 653a 4682 b4ad 6a2fd54218b9","181fd624 1db0 49b8 b1b9 b88d6336bd75","21ccd888 01cc 459d 9341 2001508a83fc"]}} output parameter type description status code number http status code of the response reason string response reason phrase multistatus array status value multistatus target string status value multistatus status number status value multistatus operationid number unique identifier transactionid string unique identifier output example {"status code" 207,"response headers" {"date" "mon, 09 sep 2024 07 12 50 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 cac6b1b18e344010","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "ok","json body" {"multistatus" \[{},{},{}],"transactionid" "0000 abcdef 1234"}} update devices modify the state or subscription of specified devices in withsecure elements endpoint security requires a 'targets' json body endpoint url /devices/v1/devices method patch input argument name type required description state string optional device state to be changed to targets array optional list of targets (device identifiers) on which state will be changed min items 1 max items 5 subscriptionkey string optional key of the subscription to which the devices will be moved input example {"json body" {"state" "blocked","targets" \["ec8a0100 d313 4896 b3cb 02188e060bf3"],"subscriptionkey" "e43v de4h u2x8 87l2 438v"}} output parameter type description status code number http status code of the response reason string response reason phrase multistatus array status value multistatus target string status value multistatus status number status value transactionid string unique identifier output example {"status code" 207,"response headers" {"date" "mon, 09 sep 2024 07 12 50 gmt","content type" "application/json","transfer encoding" "chunked","connection" "keep alive","server" "nginx","x transaction" "0000 cac6b1b18e344010","vary" "origin, access control request method, access control request headers","strict transport security" "max age=31536000 ; includesubdomains"},"reason" "ok","json body" {"multistatus" \[{"target" "ec8a0100 d313 4896 b3cb 02188e060bf3","status" 200},{"target" "01898f1e d32 update status of incidents updates the status of specified incidents in withsecure elements endpoint security using target identifiers and a new status value endpoint url /incidents/v1/incidents method post input argument name type required description targets array optional list of incident ids to update min items 1 max items 1 status string optional status of the incident resolution string optional resolution of incident that property is required when status of incident is 'closed' input example {"json body" {"targets" \["2c902c73 e2a6 40fd 9532 257ee102e1c1"],"status" "monitoring","resolution" "confirmed"}} output parameter type description status code number http status code of the response reason string response reason phrase multistatus array status value multistatus target string status value multistatus status number status value transactionid string unique identifier output example {"status code" 200,"reason" "ok","json body" {"multistatus" \[{}],"transactionid" "0000 d1467e4907a54c87"}} response headers header description example connection http response header connection keep alive content type the media type of the resource application/json date the date and time at which the message was originated mon, 09 sep 2024 10 35 40 gmt server information about the software used by the origin server nginx strict transport security http response header strict transport security max age=31536000 ; includesubdomains transfer encoding http response header transfer encoding chunked vary http response header vary origin, access control request method, access control request headers x transaction http response header x transaction 0000 ba65dbf08940468b