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:

• 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

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

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.