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
- Cloud Threat Lookup APIs
- File Analysis APIs
- URL Analysis APIs
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:
- 400 (Bad Request): The request was malformed or contained unsupported values.
- 401 (Unauthorized): No authorization information has been provided or the authorization information has expired.
- 404 (Not Found): The requested URL endpoint does not exist.
- 405 (Method Not Allowed): The requested URL endpoint does not support the used HTTP method.
- 429 (Too Many Requests): The user has sent too many requests in a given amount of time, rate limit for the current request type is reached.
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:
- Germany (https://de.api.labs.sophos.com)
- US (https://us.api.labs.sophos.com)
- Australia (https://au.api.labs.sophos.com)
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
- Rate Limit Value: The number of requests allowed for the defined period of time.
- Rate Limit Period: Integer value of rolling window time period in seconds.
- Rate Limit Requests Left: The number of requests currently remaining in the rolling window time period.
- Rate Limit End: Fractional number; seconds left until the next allowed request if rate limit is applied, otherwise 0.
Current values
Endpoint | Name | Rate Limit Value | Rate Limit Period |
---|---|---|---|
File Hash Lookup | 5000 | 60 | |
URL Category Lookup | 5000 | 60 | |
IP Category Lookup | 5000 | 60 | |
Android APK Lookup | 5000 | 60 | |
Static File Analysis - File submit | 30 | 60 | |
Static File Analysis - File hash query | 300 | 60 | |
Static File Analysis - Job UUID query | 3000 | 60 | |
Dynamic File Analysis - File submit | 30 | 60 | |
Static and Dynamic File Analysis - File submit | 30 | 60 | |
Dynamic File Analysis - File hash query | 300 | 60 | |
Dynamic File Analysis - Job UUID query | 3000 | 60 |
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. | Resp status |
Response headers | Description | |
---|---|---|---|---|---|
X-Rate-Limit- Requests-Left | X-Rate-Limit- End |
||||
10:00:00 | 1 | 200 | 99 | 0.0 | Remaining requests within a rate limit sliding window is decreased for each request. |
10:00:02 | 2 | 200 | 98 | 0.0 | |
10:00:03 | 3 | 200 | 97 | 0.0 | |
... | 4 .. 98 | 200 | 96 .. 2 | 0.0 | |
10:14:22 | 99 | 200 | 1 | 0.0 | |
10:14:31 | 100 | 200 | 0 | 28 |
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 | 101 | 429 | 0 | 28 |
Request refused, the next request allowed in 28.198755 seconds. |
10:15:00 | 102 | 200 | 0 | 1.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 | 103 | 429 | 0 | 0.05 | Request refused, the next request allowed in 0.050000 seconds. |
10:15:04 | 104 | 200 | 1 | 0.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.