How to integrate with OPSWAT GEARS cookie API

Transcription

1 How to integrate with OPSWAT GEARS cookie API About This Guide...2 Change Log... 3 Background... 4 Cookie Format...5 Cookie: Policy_State... 6 Cookie: License_Key... 6 Cookie: Device_ID... 6 Future enhancements... 6 Notes... 7 Supported browsers... 7 Supported GEARS clients... 7 Figure 1 Typical Sequence Diagram... 8 Figure 2 Schematic without SaaS to GEARS Cloud integration... 9 Figure 3 Schematic with SaaS to GEARS Cloud integration

2 About This Guide GEARS is a platform for network security management for IT and security professionals that provides visibility over all types of endpoint applications from antivirus to hard disk encryption and public file sharing, as well as the ability to enforce compliance and detect threats. More information on GEARS may be found at GEARS can be leveraged by SaaS products to control access to a service according to the compliance status of the endpoint attempting to connect. This guide specifically illustrates how to establish GEARS policy checks for any SaaS product OPSWAT, Inc. All rights reserved. OPSWAT, GEARS and the OPSWAT logo are trademarks of OPSWAT, Inc. All other trademarks, trade names, service marks, service names and images mentioned and/or used herein belong to their respective owners. 2

3 Change Log Date Revision Author Comment Dec 18 th Adam Winn First release 3

4 Background OPSWAT GEARS service runs on an endpoint and periodically checks the compliance status of the device against a security baseline (policy) configured and hosted in GEARS cloud. This compliance information for the endpoint is stored locally and also available from the GEARS cloud. Traditionally the information was available in the local system s registry, or via COM API, or in the cloud via RESTful API. This document describes a new method for retrieving device compliance information, via a cookie stored on the local endpoint. The cookie is generated by the GEARS service and injected into all supported local browsers. This injection happens every time the GEARS service performs a compliance check on the endpoint. The interval of this compliance check is an account-level configuration available in the GEARS cloud and ranges from 5 minutes to 60 minutes. When the cookie is injected, it is given an expiration date equal to the next scheduled compliance check. The cookie injection is automatic and will happen as long as the GEARS client is running. 4

5 Cookie Format Whenever a cookie injection is scheduled, actually three separate cookies are injected. This allows for either secure or insecure integration types. Format of the three cookies: Cookie Name: Device_ID License_Key Policy_State Content: {Unique device ID} {GEARS account license key} 0 or 1 Host: gears.opswat.com Path: / Send For: Any connection type Expires: {Next scheduled compliance check time} Type: Persistent 5

6 Cookie: Policy_State The Policy_State cookie provides the most basic compliance information possible. The content of this cookie is 1 when the device is compliant and 0 when the device is noncompliant. The drawbacks to checking this value without any further checks: 1) Any sufficiently knowledgeable user can manipulate this value 2) It is only known that the endpoint is compliant with some GEARS account s security policy, not any particular GEARS account Cookie: License_Key The License_Key cookie provides the account identifier (as a license key) to which the GEARS client is associated. Because each GEARS account can have a different security baseline (policy), it is important that the endpoint compliance state (Policy_State) is considered in conjunction with the expected license key. Using this cookie requires that the web service has preexisting knowledge of the expected license key. Cookie: Device_ID The Device_ID cookie is provided so the web service can access the richest and most secure information directly from the GEARS cloud. GEARS cloud has RESTful API methods, documented at Calling these REST API methods to get device information requires either a MAC address or a Device_ID. Since most web services (without the use of Java) cannot query the device s MAC address, the Device_ID is made available in this cookie. The REST APIs are secured with OAUTH 2.0. A client_key and client_secret for calling the REST APIs can be obtained by registering at This registration is tied to each GEARS account. While more complicated to implement, the Device_ID integration is much more secure than simply using the Policy_State and/or License_Key cookies because it is not as vulnerable to manipulation on the endpoint. Future enhancements An enhanced solution that would encrypt the contents of the cookie is being explored and may be released in the future. This would require pre-sharing a decryption key with the web service that needs to read the cookie. This would be advantageous for integrations that do not (or cannot) call the GEARS cloud REST APIs. 6

7 Notes 1) Because the cookies are injected on an interval, the presence (and expiration status) of a cookie can be used as a reliable indicator of the presence and running state of GEARS on the endpoint. 2) Cookie injection is automatic as long as GEARS is running on the endpoint. It is not configurable. 3) The cookie is injected into all detected and supported browsers on the endpoint. Even if one fails, the remaining browsers will still be tried. 4) This cookie injection has little to no impact on system resources (CPU, memory, disk IO, etc.) Supported browsers As of December 18 th, 2014, the cookie API is supported on: Windows 7, 8, 8.1: Internet Explorer, Firefox, Chrome* OSX: Safari, Firefox, Chrome * On Windows, the cookie injection will not succeed in Chrome while Chrome is running. The other Windows browsers do not have this limitation. A possible enhancement has been identified and is being researched. It would involve using HTML5 local storage instead of a traditional cookie. Supported GEARS clients As of December 18 th, 2014, the cookie API is supported and implemented in: GEARS for Windows: Persistent (managed) version GEARS for Windows: On demand (guest) version, no UAC* GEARS for Windows: On demand (guest) version, with UAC GEARS for Mac: Persistent (managed) version GEARS for Mac: On demand (guest) version * GEARS for Windows, On Demand version is available with and without UAC. When using the non-uac version as a user without local administrator rights, the cookie injection will not work with Internet Explorer 7

8 Figure 1 Typical Sequence Diagram 8

9 Figure 2 Schematic without SaaS to GEARS Cloud integration Figure 3 Schematic with SaaS to GEARS Cloud integration For more information, or if you have any questions about the steps above, please log into the OPSWAT Portal at and submit a ticket to request assistance from our support team. 9