Endpoint Standard REST API Reference

WARNING: This is a legacy document, please view the latest version here.

Events

The Events API allows users to query the Endpoint Standard datastore for information on individual endpoint events that may have led to notifications/alerts. Individual endpoint events include network connections, process spawns, data access, and other indicators from the endpoint. These events are the raw data points fed into the streaming detection engine in Endpoint Standard. Only API keys of type “API” can call the events API.

Find Events

This API is being deactivated by September 2021.

You may continue to use the `integrationServices/v3/event` API until it is deactivated. Please use the Enriched Events Search API instead.

GET /integrationServices/v3/event

Retrieves all events matching the input search criteria. Response is a list of events in JSON format. Resulting events are sorted in descending order of time.

Query parameters can be used to filter the list of events:

  • hostName: filter on hostnames case insensitive. For example hostName=win-IA9NQ1GN8OI will match the hostname WIN-IA9NQ1GN8OI
  • hostNameExact: filter on the exact hostname. For example hostName=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI
  • ownerName: filter on owner name case insensitive.
  • ownerNameExact: same as ownerName but with case sensitivity
  • ipAddress: filter on events generated by a device with a given external or internal IP address
  • sha256Hash: filter on events generated by a process with the given SHA-256 hash. Note that this hash must be lowercase.
  • applicationName: filter on events generated by a process with the given application name (for example, googleupdate.exe. Note that this name must be lowercase)
  • eventType: filter on events with a given event type. Possible Event Types are:
    • “NETWORK”
    • “FILE_CREATE”
    • “REGISTRY_ACCESS”
    • “SYSTEM_API_CALL”
    • “CREATE_PROCESS”
    • “DATA_ACCESS”
    • “INJECT_CODE”
  • searchWindow: filter on events generated within a given relative time frame. Note that the default is one day if a searchWindow is not specified. Note that events may not be available past 30 days due to retention policies. Available options for using searchWindow:
    • 3h for the past three hours
    • 1d for the past one day - default
    • 1w for the past one week
    • 2w for the past two weeks
    • 1m for the past one month
    • all for all
    • Note: There is an additional restriction for this API endpoint specifically – /event only supports up to 2w for the maximum to limit the volume of data returned.
  • startTime / endTime: Using a combination of startTime and endTime filters events for the given absolute timeframe.
    • startTime and endTime must be used together
    • The timestamps are in RFC3339 format. Example: https://api-url.conferdeploy.net/integrationServices/v3/event?startTime=2017-11-15&endTime=2017-11-20
    • endTime - startTime must be <= 2w
    • Note: Events may not be available past 30 days due to retention policies.

Each event has a unique ID associated with it in the response payload. The event ID is stored as the value of the eventId key.

Example Request & Response:

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
      "https://api-url.conferdeploy.net/integrationServices/v3/event?searchWindow=1d&rows=1"
    
  • Response 200 (application/json)

    {
      "success": true,
      "latestTime": 0,
      "results": [
        {
          "eventId": "1defe38112e911e7b34047d6447797bd",
          "processDetails": {
            "userName": "SYSTEM",
            "processId": 2872,
            "milisSinceProcessStart": 32,
            "name": "taskeng.exe",
            "parentPid": 772,
            "interpreterHash": null,
            "interpreterName": null,
            "commandLine": "taskeng.exe {5267BC82-9B0D-4F0B-A566-E06CDE5602F1} S-1-5-18:NT AUTHORITY\\System:Service:",
            "parentName": "svchost.exe",
            "parentPrivatePid": "772-1489763380982-18",
            "targetPid": 2468,
            "targetPrivatePid": "2468-1490617768051-975",
            "parentCommandLine": "C:\\Windows\\system32\\svchost.exe -k netsvcs",
            "targetCommandLine": "C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe",
            "privatePid": "2872-1490617768004-974",
            "targetName": "GoogleUpdate.exe",
            "fullUserName": "NT AUTHORITY\\SYSTEM"
          },
          "eventTime": 1490617768036,
          "selectedApp": {
            "applicationName": "taskeng.exe",
            "virusName": null,
            "reputationProperty": "TRUSTED_WHITE_LIST",
            "effectiveReputation": null,
            "applicationPath": "C:\\Windows\\System32\\taskeng.exe",
            "md5Hash": "a21ac8d41e63cf1aa24ebc165ae82c9a",
            "effectiveReputationSource": null,
            "virusCategory": null,
            "sha256Hash": "74b9cf472d5008e00735482f084f886eaa201248d6e87ab6b1990e3670bd6693",
            "virusSubCategory": null
          },
          "attackStage": null,
          "targetApp": {
            "applicationName": "C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe",
            "virusName": null,
            "reputationProperty": "TRUSTED_WHITE_LIST",
            "effectiveReputation": null,
            "applicationPath": null,
            "md5Hash": null,
            "effectiveReputationSource": null,
            "virusCategory": null,
            "sha256Hash": "52fc3aa9f704300041e486e57fe863218e4cdf4c8eee05ca6b99a296efee5737",
            "virusSubCategory": null
          },
          "registryValue": null,
          "alertCategory": null,
          "longDescription": "The application \"<share><link hash=\"74b9cf472d5008e00735482f084f886eaa201248d6e87ab6b1990e3670bd6693\">C:\\Windows\\System32\\taskeng.exe</link></share>\" attempted to invoke the application \"C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe\", by calling the function \"CreateProcessW\". The operation was successful.",
          "threatIndicators": [
            "SUSPENDED_PROCESS"
          ],
          "securityEventCode": null,
          "deviceDetails": {
            "deviceName": "WIN-EK5MJ5DQC3Q",
            "agentLocation": "OFFSITE",
            "targetPriorityCode": 2,
            "deviceOwnerName": null,
            "deviceIpAddress": "1.2.3.4",
            "deviceHostName": "example.com",
            "email": "Administrator",
            "groupName": "Restrictive_Windows_Workstation",
            "deviceType": "WINDOWS",
            "deviceId": 218616,
            "targetPriorityType": "HIGH",
            "deviceIpV4Address": "1.2.3.4",
            "deviceLocation": {
              "city": "Ashburn",
              "countryCode": "US",
              "areaCode": 703,
              "metroCode": 123,
              "region": "VA",
              "dmaCode": 123,
              "countryName": "United States",
              "postalCode": "20148",
              "longitude": -77.487442,
              "latitude": 39.043757
            },
            "deviceVersion": "Server 2012 R2 x64 "
          },
          "eventType": "SYSTEM_API_CALL",
          "netFlow": {
            "service": null,
            "peerSiteReputation": null,
            "peerIpAddress": null,
            "destPort": null,
            "sourcePort": null,
            "peerFqdn": null,
            "destAddress": null,
            "peerIpV4Address": null,
            "sourceAddress": null,
            "peerLocation": null
          },
          "incidentId": null,
          "shortDescription": "The application \"<share><link hash=\"74b9cf472d5008e00735482f084f886eaa201248d6e87ab6b1990e3670bd6693\">taskeng.exe</link></share>\" successfully attempted to invoke the application \"C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe\".",
          "createTime": 1490617872232,
          "alertScore": 0,
          "parentApp": {
            "applicationName": "C:\\Windows\\System32\\svchost.exe",
            "virusName": null,
            "reputationProperty": null,
            "effectiveReputation": null,
            "applicationPath": null,
            "md5Hash": null,
            "effectiveReputationSource": null,
            "virusCategory": null,
            "sha256Hash": "c7db4ae8175c33a47baa3ddfa089fad17bc8e362f21e835d78ab22c9231fe370",
            "virusSubCategory": null
          }
        }
      ],
      "elapsed": 3,
      "message": "Success",
      "totalResults": 28
    }

Get details for a Specific Event

This API is being deactivated by September 2021.

You may continue to use the `integrationServices/v3/event` API until it is deactivated. Please use the Enriched Events Search API instead.

GET /integrationServices/v3/event/{id}

Retrieve details for an individual event given the event ID (eventId). Note that only events associated with incidents/notifications/alerts will be visible through this API. Other event IDs will return HTTP 404 (Object Not Found).

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
      https://api-url.conferdeploy.net/integrationServices/v3/event/1defe38112e911e7b34047d6447797bd
    
  • Response 200 (application/json)

    {
      "message": "Success",
      "eventInfo": {
        "eventId": "1defe38112e911e7b34047d6447797bd",
        "processDetails": {
          "userName": "SYSTEM",
          "processId": 2872,
          "milisSinceProcessStart": 32,
          "name": "taskeng.exe",
          "parentPid": 772,
          "interpreterHash": null,
          "interpreterName": null,
          "commandLine": "taskeng.exe {5267BC82-9B0D-4F0B-A566-E06CDE5602F1} S-1-5-18:NT AUTHORITY\\System:Service:",
          "parentName": "svchost.exe",
          "parentPrivatePid": "772-1489763380982-18",
          "targetPid": 2468,
          "targetPrivatePid": "2468-1490617768051-975",
          "parentCommandLine": "C:\\Windows\\system32\\svchost.exe -k netsvcs",
          "targetCommandLine": "C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe",
          "privatePid": "2872-1490617768004-974",
          "targetName": "GoogleUpdate.exe",
          "fullUserName": "NT AUTHORITY\\SYSTEM"
        },
        "eventTime": 1490617768036,
        "deviceSecurityEventCode": null,
        "killChainStatus": null,
        "processHash": {
          "applicationName": "taskeng.exe",
          "virusName": null,
          "reputationProperty": "TRUSTED_WHITE_LIST",
          "effectiveReputation": null,
          "applicationPath": "C:\\Windows\\System32\\taskeng.exe",
          "md5Hash": "a21ac8d41e63cf1aa24ebc165ae82c9a",
          "effectiveReputationSource": null,
          "virusCategory": null,
          "sha256Hash": "74b9cf472d5008e00735482f084f886eaa201248d6e87ab6b1990e3670bd6693",
          "virusSubCategory": null
        },
        "registryValue": null,
        "parentHash": {
          "applicationName": "C:\\Windows\\System32\\svchost.exe",
          "virusName": null,
          "reputationProperty": null,
          "effectiveReputation": null,
          "applicationPath": null,
          "md5Hash": null,
          "effectiveReputationSource": null,
          "virusCategory": null,
          "sha256Hash": "c7db4ae8175c33a47baa3ddfa089fad17bc8e362f21e835d78ab22c9231fe370",
          "virusSubCategory": null
        },
        "threatScore": 0,
        "createTime": 1490617872232,
        "longDescription": "The application \"<share><link hash=\"74b9cf472d5008e00735482f084f886eaa201248d6e87ab6b1990e3670bd6693\">C:\\Windows\\System32\\taskeng.exe</link></share>\" attempted to invoke the application \"C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe\", by calling the function \"CreateProcessW\". The operation was successful.",
        "threatIndicators": [
          "SUSPENDED_PROCESS"
        ],
        "securityEventCode": null,
        "deviceDetails": {
          "deviceName": "WIN-EK5MJ5DQC3Q",
          "agentLocation": "OFFSITE",
          "targetPriorityCode": 2,
          "deviceOwnerName": null,
          "deviceIpAddress": "1.2.3.4",
          "deviceHostName": "example.com",
          "email": "Administrator",
          "groupName": "Restrictive_Windows_Workstation",
          "deviceType": "WINDOWS",
          "deviceId": 218616,
          "targetPriorityType": "HIGH",
          "deviceIpV4Address": "1.2.3.4",
          "deviceLocation": {
            "city": "Ashburn",
            "countryCode": "US",
            "areaCode": 703,
            "metroCode": 123,
            "region": "VA",
            "dmaCode": 123,
            "countryName": "United States",
            "postalCode": "20148",
            "longitude": -77.487442,
            "latitude": 39.043757
          },
          "deviceVersion": "Server 2012 R2 x64 "
        },
        "orgDetails": {
          "organizationId": 423,
          "organizationName": "secureworks.com",
          "organizationType": "BUSINESS"
        },
        "eventType": "SYSTEM_API_CALL",
        "syslogLevel": null,
        "netFlow": {
          "service": null,
          "peerSiteReputation": null,
          "peerIpAddress": null,
          "destPort": null,
          "sourcePort": null,
          "peerFqdn": null,
          "destAddress": null,
          "peerIpV4Address": null,
          "sourceAddress": null,
          "peerLocation": null
        },
        "shortDescription": "The application \"<share><link hash=\"74b9cf472d5008e00735482f084f886eaa201248d6e87ab6b1990e3670bd6693\">taskeng.exe</link></share>\" successfully attempted to invoke the application \"C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe\".",
        "targetHash": {
          "applicationName": "C:\\Program Files (x86)\\Google\\Update\\GoogleUpdate.exe",
          "virusName": null,
          "reputationProperty": "TRUSTED_WHITE_LIST",
          "effectiveReputation": null,
          "applicationPath": null,
          "md5Hash": null,
          "effectiveReputationSource": null,
          "virusCategory": null,
          "sha256Hash": "52fc3aa9f704300041e486e57fe863218e4cdf4c8eee05ca6b99a296efee5737",
          "virusSubCategory": null
        }
      },
      "success": true
    }

Find Processes

This API is being deactivated by September 2021.

You may continue to use the `integrationServices/v3/process` API until it is deactivated. Please use the Processes Search API instead.

Find processes associated with a specific indicator or IP address filter. Only API keys of type “API” can call the processes API.

Find Processes

GET /integrationServices/v3/process

Queries all events using input search criteria and returns a list of processes. The response is a list of processes in JSON format.

Query parameters can be used to filter the list of processes:

  • hostName: filter on the hostname. For example, hostName=WIN-IA9NQ1GN8OI will return devices with case insensitive (partial match) hostname such as WIN-IA9NQ1GN8OI or win-IA9NQ1GN8OI
  • hostNameExact: filter on the exact hostname. For example, hostNameExact=WIN-IA9NQ1GN8OI will only return devices with the exact hostname WIN-IA9NQ1GN8OI but not a host named win-IA9NQ1GN8OI
  • ownerName: filter on owner name case insensitive (partial match).
  • ownerNameExact: same as ownerName but with case sensitivity
  • ipAddress: filter on events generated by a device with a given external or internal IP address
  • sha256Hash: filter on process’s sha256 hash
  • applicationName: filter on process’s application name
  • rows: limits the result to a specified number of rows (default=100 max=5000)
  • searchWindow: filter on events generated within a given relative time frame. The default is one day if a searchWindow is not specified. Events may not be available past 30 days due to retention policies. Maximum search window is one day. Possible values are:
    • 3h for the past three hours
    • 1d for the past one day
  • startTime / endTime: Using a combination of startTime and endTime filters events for the given absolute timeframe.
    • startTime and endTime must be used together
    • The timestamps are in RFC3339 format. For example, https://api-url.conferdeploy.net/integrationServices/v3/event?startTime=2017-11-15&endTime=2017-11-16
    • endTime - startTime must be <= 1d
    • Events may not be available past 30 days due to retention policies.

Note at least one or more of the following filters are required: ownerName, ownerNameExact, hostName, hostNameExact, ipAddress, sha256Hash, or applicationName

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
      "https://api-url.conferdeploy.net/integrationServices/v3/process?ipAddress=1.2.3.4&rows=1"
    
  • Response 200 (application/json)

    {
      "success": true,
      "latestTime": 0,
      "results": [
        {
          "applicationName": "chrome.exe",
          "processId": 3052,
          "numEvents": 252,
          "applicationPath": null,
          "privatePid": "3052-1489181082476-30",
          "sha256Hash": "c8b01dd0153bbe4527630fb002f9ef8b4e04127bdff212831ff67bd6ab0ea265"
        }
      ],
      "elapsed": 16,
      "message": "Success",
      "totalResults": 1
    }

Alerts

This API is being deactivated by September 2021.

You may continue to use the Alerts v3 API until it is deactivated. The replacement services is the Alerts v6 API available here.

Only API keys of type “API” can call the alerts API.

Get Details on Alert

GET /integrationServices/v3/alert/{id}

Get details on the events that led to an alert. This includes retrieving metadata around the alert as well as a list of all the events associated with the alert. Introduced in 0.21.

  • Request (application/json)

      $ curl -H X-Auth-Token:ABCD/1234 \
      https://api-url.conferdeploy.net/integrationServices/v3/alert/JSPJCU9K
    
  • Response 200 (application/json)

    {
      "success": true,
      "deviceInfo": {
        "assignedToName": null,
        "deviceName": "ProjectManagementMac",
        "avEngine": "",
        "linuxKernelVersion": null,
        "message": "success",
        "registeredTime": 1488234251183,
        "group": "default",
        "deregisteredTime": 0,
        "deviceType": "MAC",
        "scanLastActionTime": 0,
        "sensorVersion": "1.0.2.15",
        "assignedToId": 0,
        "scanStatus": null,
        "importance": "MEDIUM",
        "deviceId": 218609,
        "osVersion": "MAC OS X 10.9.0",
        "groupId": 2141,
        "userName": "Brad.Follmer@strugholdmining.com",
        "avStatus": null,
        "success": true,
        "status": "REGISTERED",
        "avLastScanTime": 0,
        "scanLastCompleteTime": 0
      },
      "orgId": 423,
      "message": "Success",
      "events": [
        {
          "eventId": "ac2b8641fd3b11e6808d7d14b0f2459a",
          "userName": null,
          "eventTime": 1488229840388,
          "parentPid": 146,
          "processId": 233,
          "applicationPath": "/Applications/Safari.app/Contents/MacOS/Safari",
          "eventType": "CREATE_PROCESS",
          "commandLine": null,
          "parentName": "/sbin/launchd",
          "longDescription": "The application \"<share><link hash=\"47b209606559bd304606b7197bea675175d9d339f9582fd44147fce5a78c6265\">/Applications/Safari.app/Contents/MacOS/Safari</link></share>\" invoked the application \"<share><link hash=\"41b6c19f1e6b30fd1bb0f89684ba1f8aaf2b7abf751a8fdd4def069ef21e699e\">/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/lib/jspawnhelper</link></share>\". ",
          "parentCommandLine": null,
          "processHash": "47b209606559bd304606b7197bea675175d9d339f9582fd44147fce5a78c6265",
          "threatIndicators": [
            "RUN_ANOTHER_APP"
          ],
          "parentPPid": "146",
          "killChainStatus": "INSTALL_RUN",
          "processMd5Hash": "c10a1acb932aa8a78a510c9e78bc2b37",
          "processPPid": "233",
          "parentHash": "6a18c33dbcd8e681878f19990276d1554d2d2a6c1fdb074627abaa79d32885d3",
          "policyState": "NOT_APPLIED"
        },
        ...
      ],
      "threatInfo": {
        "threatId": "ed0d0913598ed1798acf7848b6428070",
        "threatScore": 5,
        "summary": "The application Payload.class invoked another application (uname).",
        "time": 1488230650998,
        "indicators": [
          {
            "applicationName": "Payload.class",
            "indicatorName": "RUN_SYSTEM_APP",
            "sha256Hash": "6750c319c5d1ba2d2937ef602c2e5c03df6fb60449566e5efb0331310a655c4e"
          }
        ],
        "incidentId": "JSPJCU9K"
      }
    }

Last modified on May 9, 2021