Endpoint Standard REST API Tutorial Using Postman

Posted on May 8, 2018

The Endpoint Standard REST API provides a RESTful API for CbDefense, which means that it can be consumed by practically any language. Postman is a REST API Development Environment that allows users to interact with a REST API in a quick & easy way.

This is a quick tutorial on how to use Postman to interact with the CbDefense REST API.

Requirements

  • Access to your Endpoint Standard instance.
  • A connector configured on CbDefense or the ability to create a connector.
  • Postman installed on your computer.

API Basics

The Endpoint Standard API is accessible through a special hostname assigned to your organization. Contact support for the hostname associated with your API backend. Once you receive the API hostname, the following API routes are accessible through the integrationServices path on your API host.

Authentication is handled by an API key and Connector ID, which is generated from the Connectors page of the Endpoint Standard console. The API key and Connector ID are concatenated together to form the X-Auth-Token HTTP header, which is used to control access to the Endpoint Standard API. For more information on generating the API token and the HTTP header, see the Endpoint Standard API authentication reference.

Getting Started

  1. Download and install Postman.
  2. Configure a “API” connector on your CbDefense instance - for information on how to generate API keys, see the Developer Network.
  3. Ensure that your new Connector key is of type “API”.
  4. Make a note of the ConnectorID and API key.

Next, we will configure Postman and send our first API request to CbDefense!

Postman Configuration

Here’s a screenshot of my postman instance:

Postman Config

Steps to configure Postman:

  1. Launch Postman.
  2. Create a new collection (folder) for your API requests.
  3. Create a new request and add it to the collection created in step 2.
  4. Select the request type as GET
  5. Enter the request URL - https://<cbc-hostname>/integrationServices/v3/device?rows=2
    • Example - https://defense.conferdeploy.net/integrationServices/v3/device?rows=2
  6. Under the API request, go to headers and add a new header:
    • Header key: X-Auth-Token
    • Header value: <api_key/connector_id>
  7. Click send!
  8. If all goes well, view the response. (this example is limited to one row)
{
    "latestTime": 0,
    "success": true,
    "message": "Success",
    "totalResults": 29,
    "elapsed": 2,
    "results": [
        {
            "adGroupId": 0,
            "policyOverride": false,
            "currentSensorPolicyName": null,
            "deviceMetaDataItemList": null,
            "lastDevicePolicyRequestedTime": null,
            "lastDevicePolicyChangedTime": null,
            "lastPolicyUpdatedTime": null,
            "lastVirusActivityTime": 0,
            "firstVirusActivityTime": 0,
            "createTime": null,
            "lastReportedTime": 1522686351476,
            "testId": -1,
            "avMaster": false,
            "avProductVersion": "",
            "avAveVersion": "",
            "avPackVersion": "",
            "avVdfVersion": "",
            "sensorOutOfDate": false,
            "email": "",
            "deviceId": 6638,
            "deviceType": "WINDOWS",
            "targetPriorityType": "MEDIUM",
            "uninstallCode": null,
            "organizationId": 432,
            "deviceOwnerId": 71283,
            "deviceGuid": null,
            "deviceSessionId": null,
            "assignedToId": null,
            "assignedToName": null,
            "middleName": null,
            "lastName": "",
            "firstName": "",
            "activationCode": "",
            "organizationName": "",
            "osVersion": "Windows 10 x64",
            "activationCodeExpiryTime": 1521480682823,
            "sensorVersion": "3.2.0.103",
            "registeredTime": 1520878064278,
            "lastContact": 1522692813125,
            "windowsPlatform": null,
            "vdiBaseDevice": null,
            "avStatus": [
                "AV_DEREGISTERED"
            ],
            "deregisteredTime": 1522692843985,
            "sensorStates": [
                "ACTIVE",
                "LIVE_RESPONSE_NOT_RUNNING",
                "LIVE_RESPONSE_NOT_KILLED",
                "LIVE_RESPONSE_DISABLED",
                "SECURITY_CENTER_OPTLN_DISABLED"
            ],
            "messages": null,
            "rootedBySensor": false,
            "rootedBySensorTime": null,
            "quarantined": false,
            "lastInternalIpAddress": "",
            "macAddress": null,
            "lastExternalIpAddress": "",
            "lastLocation": "OFFSITE",
            "avUpdateServers": null,
            "passiveMode": false,
            "lastResetTime": 0,
            "lastShutdownTime": 0,
            "scanStatus": null,
            "scanLastActionTime": 0,
            "scanLastCompleteTime": 0,
            "linuxKernelVersion": null,
            "avEngine": "",
            "avLastScanTime": 0,
            "virtualMachine": false,
            "virtualizationProvider": null,
            "rootedByAnalytics": false,
            "rootedByAnalyticsTime": null,
            "uninstalledTime": null,
            "encodedActivationCode": null,
            "originEventHash": null,
            "status": "",
            "name": "",
            "policyId": 2230,
            "policyName": "default"
        }
    ]
}

Conclusion & Resources