Overview

SophosLabs Intelix is a cloud-based threat intelligence and threat analysis platform, enabling programmers to directly tap into the technology behind SophosLabs through a suite of RESTful APIs.

SophosLabs has, for over 30 years, specialized in threat analysis to power Sophos products with real-time identification of known and unknown malware as well as processing over 600 million threat queries per day within its global reputation service. With SophosLabs Intelix, you can now harness SophosLabs’ vast troves of threat intelligence data and an array of static and dynamic threat analysis techniques through our easy-to-use, RESTful APIs. All hosted on the Amazon Web Services Marketplace with pay-as-you-go pricing including a free tier.

List of services

  1. Cloud Threat Lookup APIs
    1. File Hash Lookup API
    2. URL Category Lookup API
    3. IP Category Lookup API
    4. Android APK Lookup API
  2. File Analysis APIs
    1. Static File Analysis API
    2. Dynamic File Analysis API
    3. Single Submission File Analysis API
  3. URL Analysis APIs
    1. Static URL Analysis API

How to register

To register for the SophosLabs Intelix APIs first you must have an active Amazon Web Services (AWS) account. Once you have an account, click here or search the AWS Marketplace for SophosLabs Intelix. Click the “Subscribe” button and follow the instructions. You will be guided to the SophosLabs customer verification and onboarding landing page from which you can complete your registration.

API flow

You can authenticate against the SophosLabs Intelix APIs once you have obtained credentials. These credentials, a client ID and a client secret, are provided during the onboarding process after you have subscribed to SophosLabs Intelix on the AWS Marketplace.

Before you can start doing things like submitting files for analysis or query IP addresses, you need to use your credentials to authenticate and obtain your access token.

First, make a POST request to the token endpoint using your client credentials. An access token is sent in response to a successful authentication. All subsequent API calls to the SophosLabs Intelix APIs will require this access token be sent in the header. This access token is valid for one hour before you need to reauthenticate and get a new token.

Authentication

See: API Authentication

Error handling

Client-side warnings

In case there's a warning in the response it means the report contained some warnings. This still returns with a 2xx status code and means there were some bad parameters passed to the endpoint.

Client-side errors

Generally, the caller should not retry calls if the returned HTTP status code is 4xx. These status codes mean an error on the caller's side.

Examples:

Server-side errors

The caller should retry the calls if the returned HTTP status code is 5xx. These status codes mean an error on the server side.

Retry strategy

We recommend to use the retry strategy provided by AWS.

Region handling

SophosLabs Intelix API calls are handled in the following regions:

The user has to call a region directly.

Note: the authentication endpoint is region independent.

Rate limit

Our API endpoint rate limit values are dynamically aligned to the system's capacity to ensure stability for all users.

Each endpoint may have different rate limit values. The client is informed about them through HTTP response headers.

In case of a rate limit violation the client receives an HTTP 429 (Too Many Requests) response.

Definitions

Current values

EndpointNameRate Limit ValueRate Limit Period
/lookup/files/v1/*File Hash Lookup500060
/lookup/urls/v1/* URL Category Lookup500060
/lookup/ips/v1/* IP Category Lookup500060
/lookup/apk/v1/*Android APK Lookup500060
/analysis/file/static/v1Static File Analysis - File submit3060
/analysis/file/static/v1/reportsStatic File Analysis - File hash query30060
/analysis/file/static/v1/reports/{job_id}Static File Analysis - Job UUID query300060
/analysis/file/dynamic/v1Dynamic File Analysis - File submit3060
/analysis/file/dynamic/v1Static and Dynamic File Analysis - File submit3060
/analysis/file/dynamic/v1/reportsDynamic File Analysis - File hash query30060
/analysis/file/dynamic/v1/reports/{job_id}Dynamic File Analysis - Job UUID query300060

Example response headers

X-Rate-Limit-Value: 100
X-Rate-Limit-Period: 900
X-Rate-Limit-Requests-Left: 52
X-Rate-Limit-End: 0
    

Rolling Window

We implement rate limiting using a rolling/sliding window time period. The below table illustrates what the response headers would look like as this rate limit is exceeded.

Rate Limit = 100 requests
Period = 900 seconds

Time
of day
Request
no.
Response
status
Response headersDescription
X-Rate-Limit-
Requests-Left
X-Rate-Limit-
End
10:00:00.2000001200990.0 Remaining requests within a rate limit sliding window is decreased for each request.
10:00:02.5000002200980.0
10:00:03.3000003200970.0
...4 .. 9820096 .. 20.0
10:14:22.4000009920010.0
10:14:31.500002100200028.699998 Request accepted, but no more requests left within the current sliding window. The next request will be allowed in 28.699998 seconds.
10:14:32.001245101429028.198755 Request refused, the next request allowed in 28.198755 seconds.
10:15:00.20000010220001.3 Request accepted, but no more requests left within the current sliding window. The next request will be allowed in 1.300000 seconds.
10:15:01.45000010342900.05 Request refused, the next request allowed in 0.050000 seconds.
10:15:04.00000010420010.0 The sliding windows start point went over the 3rd query, so the user has 2 request allowed at this point. Therefore the current request is accepted and one more left within the current sliding window.

Development support

You can get development support on Stack Overflow using the sophoslabs-intelix tag.

Copyright

Sophos, SophosLabs, and SophosLabs Intelix are registered trademarks of Sophos Limited and Sophos Group. All other product and company names mentioned are trademarks or registered trademarks of their respective owners.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise unless you are either a valid licensee where the documentation can be reproduced in accordance with the license terms or you otherwise have the prior permission in writing of the copyright owner.