Webroot BrightCloud®
Web Services

Webroot Brightcloud® Web Services


Home

Overview

Documentation

Code Samples

Log-in or Sign up

BrightCloud Web Services Overview


Purpose

BrightCloud Web Services is a RESTful API service for developers to access Webroot BrightCloud URL classification and reputation data. The two main pieces of information provided are:

  1. The category (or categories) for a URL which best represent(s) the content hosted on the URL at the time it was most recently reviewed by Webroot. We derive this data using advanced machine learning algorithms across 82 distinct website categories.
  2. The reputation index representing the URL's predictive risk. We calculate this score based on the URL's threat history, popularity, age, and thousands of other factors. The score ranges from 1 (High Risk) to 100 (Trustworthy).

BrightCloud Web Services Uses

BrightCloud Web Services is a RESTful API service for developers to access Webroot BrightCloud URL classification and reputation data. The two main pieces of information provided are:

  • Access a list of all available categories. In addition to providing a dynamic way to create a comprehensive category list (for reporting or data structure creation), this saves you space and bandwidth, improving speed and decreasing infrastructure costs.
  • Comprehensive classification and reputation information for URLs. The URL categories can serve several purposes, such as identifying security risks (malware, phishing, botnet, etc.), enforcing parental controls, and improving of network efficiency. In addition, you can use the URL reputation index to identify sites that contain potential security risks for networks and users. Possible applications include web filtering, proxy caching, safe browsing plugins, and security research.

Rest API

Introduction
We recommend using the REST interface to access BrightCloud Web Services. It is more aligned with the World Wide Web (www) architecture, which is true for any carefully designed REST interface. This interface uses URLs to address all the logical resources made available by the web service, and a fixed set of HTTP methods to query, add, and update these resources.

Security Considerations
Every REST request to BrightCloud Web Services needs to be signed using a special key or secret pair. BrightCloud Web Services use the 2-legged variation of the OAuth standard protocol for authenticating REST requests. The OAuth protocol not only uses the key/secret pair, but also a timestamp and a random "nonce" value for signing the requests to provide a high degree of security against a variety of attacks.

BrightCloud Web Services clients must generate a security string in accordance with the OAuth protocol (using their key/secret pair) for every REST request and send it in the HTTP Authorization header value in the request. A number of readymade OAuth consumer libraries are available on the internet for several popular languages (including PHP, Java, Ruby, and .NET) that admins can use for signing the requests with minimal effort.

The key/secret pair is unique for each end user. You can generate your own key/secret pair by registering at the BrightCloud Web Services website. Read more in our online article OAuth Integration for BrightCloud Web Services.

Rest URLs and Methods
The following table lists all combinations of resources, URLs, and allowed HTTP methods that BrightCloud Web Services supports for its REST interfaces.
 

Resource URL HTTP Methods
URL List http://thor.brightcloud.com/rest/uris GET, POST
URL Info http://thor.brightcloud.com/rest/uris/{ URL } GET, PUT
Category List http://thor.brightcloud.com/rest/uris/categories GET

 

Retrieve BrightCloud categories
Resource: Category List
URL: http://thor.brightcloud.com/rest/uris/categories
HTTP Method: GET
 

Sample Request Sample Response
GET /rest/uris/categories HTTP/1.1
HOST: thor.brightcloud.com
Authorization: OAuth
    realm="http://thor.brightcloud.com/rest",
    oauth_version="1.0",
    oauth_nonce="dbe9e4311c72dad530b7afe47ec50ceb",
    oauth_timestamp="1248962133",
    oauth_consumer_key="dpf43f3p2l4k3l03",
    oauth_token="",
    oauth_signature_method="HMAC-SHA1",
    oauth_signature="lWdn1ll3bAsKWMgpdheBvyt4bcQ%3D"

HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: text/xml

< bcap >
  < seqnum >1< /seqnum >
  < response >
    < status >200< /status >
    < statusmsg >OK< /statusmsg >
    < categories >
      < cat >
        < catid >68< /catid >
        < catname >Abortion< /catname >
        < catgroup >Legal Liability< /catgroup >
      < /cat >

 < cat >
        < catid >46< /catid >
        < catname >Abortion- Pro Choice< /catname >
        < catgroup >Legal Liability< /catgroup >
      < /cat >
      .
      .
      .
    < /categories >
  < /response >
< /bcap >

 

Retrieve categories for a URL
Resource: URI Information
URL: http://thor.brightcloud.com/rest/uris/{ URL }
HTTP Method: GET
 

Sample Request Sample Response
GET /rest/uris/www.google.com HTTP/1.1
HOST: thor.brightcloud.com
Authorization: OAuth
    realm="http://thor.brightcloud.com/rest",
    oauth_version="1.0",
    oauth_nonce="dbe9e4311c72dad530b7afe47ec50ceb",
    oauth_timestamp="1248962133",
    oauth_consumer_key="dpf43f3p2l4k3l03",
    oauth_token="",
    oauth_signature_method="HMAC-SHA1",
    oauth_signature="lWdn1ll3bAsKWMgpdheBvyt4bcQ%3D"
HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: text/xml

< bcap >
  < seqnum >1< /seqnum >
  < response >
    < status >200< /status >
    < statusmsg >OK< /statusmsg >
    < uri >www.google.com< /uri >
    < categories >
      < cat >
        < catid >50< /catid >
        < conf >85< /conf >
      < /cat >
    < /categories >
    < bcri >88< /bcri >
    < a1cat >1< /a1cat >
  < /response >
< /bcap >

 

Retrieve real-time updates
Resource: URI List
URL: http://thor.brightcloud.com/rest/uris
HTTP Method: GET
 

Sample Request Sample Response
GET /rest/uris HTTP/1.1
HOST: thor.brightcloud.com
Authorization: OAuth
    realm="http://thor.brightcloud.com/rest",
    oauth_version="1.0",
    oauth_nonce="dbe9e4311c72dad530b7afe47ec50ceb",
    oauth_timestamp="1248962133",
    oauth_consumer_key="dpf43f3p2l4k3l03",
    oauth_token="",
    oauth_signature_method="HMAC-SHA1",
    oauth_signature="lWdn1ll3bAsKWMgpdheBvyt4bcQ%3D"
HTTP/1.1 200 OK
Transfer-encoding: chunked
Content-type: text/xml

< bcap >
  < seqnum >1< /seqnum >
  < response >
    < status >200< /status >
    < statusmsg >OK< /statusmsg >
    < updatecdn >false< /updatecdn >
    < updatertu >false< /updatertu >
    < updatetime >2009/7/30 5:50:4< /updatetime >
    < cdnlist >< /cdnlist >
    < rtulist >< /rtulist >
  < /response >
< /bcap >