# Enrichment API Offer Usage Guide — Microsoft Sentinel

> Setup and configuration guide for ReversingLabs Enrichment API offer in Azure Marketplace for Microsoft Sentinel including subscription activation and Logic App connector configuration.

## Overview

This document is designed to help users install and set up an API subscription for ReversingLabs in
the Microsoft Azure Marketplace. The ReversingLabs API allows users to easily integrate threat
intelligence data into their existing security systems and workflows. This document will guide users
through the process of subscribing to the ReversingLabs API in the Azure Marketplace, including
information on prerequisites and any necessary configuration steps. By following the instructions in
this document, users will be able to quickly and easily access the powerful threat intelligence
capabilities provided by the ReversingLabs API.

## Getting Started

### Subscribing to the Marketplace Offer

Here are the general steps for subscribing to a SaaS offer in the Microsoft Azure Marketplace:

![Azure Marketplace SaaS offer subscription form](./images/api-offer-1.png)

1. Sign in to the Azure portal (https://portal.azure.com/) using your Microsoft account.
2. In the left-hand navigation menu, select "Marketplace."
3. Use the search bar at the top of the page to find the SaaS offer you want to subscribe to, such
as "ReversingLabs Enrichment APIs For Sentinel."
4. Select the offer to view its details and then select "Get it now."
5. On the "Subscribe to Plan" page, select a plan and click "Subscribe."
6. Choose the Azure subscription and resource group you want to use for the SaaS offer or
create new ones if necessary. (see image above)
7. Enter a unique resource name to identify the SaaS subscription (e.g. my-saas-subscription-1).
8. Follow the prompts to complete the subscription process and any necessary configuration
steps.
9. Click "Review and Subscribe" and/or "Subscribe" when ready.
10. Follow the Activating Subscription instructions below.

Once the process is complete, you can access the SaaS offer through the Azure portal.

### Activating a New Subscription

To activate your SaaS subscription after subscribing to an offer in the Microsoft Azure Marketplace:

![Azure Marketplace subscription Configure account now button](./images/api-offer-2.png)

1. Click "Configure account now" from the SaaS subscription's Azure Marketplace portal, which
will launch the ReversingLab’s API Provisioning Portal in a new tab or page. (see image
below).
2. Log in using the same Microsoft account used to purchase the SaaS subscription offer.
3. Activate the subscription by following the prompts on the provisioning portal by providing the
required information and pressing the Activate button. (see image below)
4. If you already have an Azure Microsoft Subscription linked to RL login credentials, you will see
a dropdown with options (as shown in the green box below) to add the newly subscribed
subscription services to an existing RL Login account or select "Create New Credential" to
start fresh with a new RL login unlinked to any previous subscriptions. These options are
available during the registration process. To remove services from a credential, simply
unsubscribe from the relevant Azure Marketplace subscriptions.

![ReversingLabs API Provisioning Portal credential selection dropdown](./images/api-offer-3.png)

5. Review the status page, which should include the subscription status, plan chosen, and
credential information needed to access the API services. A green “Subscribed” status
indicates the activation process is complete. A page refresh may be required to update the
status. (see image below).
6. You may choose to use the credential for all the products/services within the offer or you can
reset the password if needed by pressing the “Reset RL Password” button to the right.
7. Access your subscriptions and their details, including the offer subscribed to, from the Azure
Portal. From there, manage, cancel, and renew your subscription.

## Using the API Credentials

Use the username and password on the ReversingLabs subscription status page to access the API
services you have subscribed to. The page will also have information about each product and service,
including instructions if available.

![ReversingLabs API credentials status page with subscription information](./images/api-offer-4.png)

**Info: **RECOMMENDED****
It is strongly suggested to install the free "ReversingLabs Sentinel Content Hub" in
order to fully utilize the API services and gain valuable insights into your threat intelligence
implementation and the impact of ReversingLabs intelligence and automation on your operations
located here: https://reversinglabs-marketplace.azureedge.net/help/ReversingLabsSentinelContentHubInstall.pdf

To integrate the enrichment APIs into your own playbooks, you’ll need to configure a new API
Connection for the ReversingLabs TitaniumCloud Logic App connector. To do this, open the playbook
designer in a new or existing playbook, add a new step, and select the ReversingLabs TitaniumCloud
connector:

![Logic App designer with ReversingLabs connector selection step](./images/api-offer-5.png)

Next, select the “Get File Hash Reputation (preview)” action (this uses the TCA-0101 API).

After selecting the action, you’ll need to create the API connection. Provide a name for the connection,
enter the username and password provided after activating your subscription in the steps above, then
click the “create” button.

![Logic App connector authentication form with username and password fields](./images/api-offer-6.png)

### TCA-0101 / Get File Hash Reputation

The “Get File Hash Reputation” action takes the following input:

| Field | Description | Required |
| --- | --- | --- |
|Hash Type | a string that matches the algorithm for the submitted hash (md5/sha1/sha256) |Yes|
|Hash Value | a string matching the file hash to be submitted | Yes |
| Extended | select the default value “No” to only return the file reputation classification value. Select “Yes” to return additional information such as trust factor and threat level values; malware type, family name, and platform; first and last seen times, and more | Yes |
| Show Hashes | select the default value “No” to exclude hash values in the associated results. Select “Yes” to include the submitted hash values in the returned results. | No |
| Format |a string matching the format for the results to be returned in. Accepted values are “json” or “xml” |No |

![Get File Hash Reputation action configuration with parameter fields](./images/api-offer-7.png)

The expected output of a successful action returns a 200 status code:

![Successful API response with 200 status code and file reputation data](./images/api-offer-8.png)

### TCA-0104 / Get File Hash Analysis Detail

The “Get File Hash Analysis Detail” action takes the following input:

| Field | Description | Required |
| --- | --- | --- |
|Hash Type| a string that matches the algorithm for the submitted hash (md5/sha1/sha256) | Yes |
|Hash Value|  a string matching the file hash to be submitted | Yes |
|Format | a string matching the format for the results to be returned in. Accepted values are “json” or “xml” | No|

![Get File Hash Analysis Detail action configuration with hash input fields](./images/api-offer-9.png)

The expected output of a successful action returns a 200 status code:

![Successful API response with detailed file analysis data and classification](./images/api-offer-10.png)

## Common Errors

The following describes some of the common errors seen when using the playbooks actions listed
above:

| Error | Description | Resolution |
| --- | --- | --- |
| 400 | The 400 response typically means there was an issue with the request format. | Check the request for any typos, missing/incorrect fields |
| 404 | The 404 response means reputation information for the submitted file hash does not yet exist in TitaniumCloud. |N/A - we recommend submitting the file for static and dynamic analysis. |

## Frequently Asked Questions

When subscribing to a SaaS offer in the Microsoft Azure Marketplace, some common questions that
may be asked include:

**What should I do if I need to see my RL credentials / login username and password again?**

Go to the subscription’s details page and select the “Open SaaS Account on publisher’s site”
link to view the ReversingLab’s API Provisioning Portal. Your RL login credentials will be
visible by hovering your cursor on the yellow username and password fields in the
middle of the page.

**What should I do if I need to reset my RL login password?**

Go to the subscription’s details page and select the “Open SaaS Account on publisher’s site”
link to view the ReversingLab’s API Provisioning Portal. The Reset RL Password button is to
the right of the RL login credentials fields in the middle of the page.

**Which Azure subscription should I use to purchase this SaaS offer?**

You will have to select the subscription you wish to use. If you have multiple subscriptions, you'll have
to select the one you want to use.

**What are the costs associated with this SaaS offer?**

You will have to check the cost of the SaaS offer before subscribing. You can check the pricing details
in the offer's page.

**Are there any prerequisites or additional services required for this SaaS offer?**

Some SaaS offers may require additional Azure services or configurations to work properly. Make
sure to check the requirements for the specific SaaS offer before subscribing.

**Are there any limitations or usage restrictions for this SaaS offer?**

Some SaaS offers may have usage restrictions or quota limitations, such as limits on the number of
daily or monthly calls, files, records or storage. Make sure to check the terms of use for the specific
SaaS offer before subscribing.

**How can I manage and cancel my subscription?**

Once you have subscribed to a SaaS offer, you will be able to manage it through the Azure portal.
You'll be able to cancel the subscription by going to the subscription's details page and cancel it.
