Enrichment API Offer Usage Guide
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:
- Sign in to the Azure portal (https://portal.azure.com/) using your Microsoft account.
- In the left-hand navigation menu, click on "Marketplace."
- 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."
- Click on the offer to view its details and then click "Get it now."
- On the "Subscribe to Plan" page, select a plan and click "Subscribe."
- Choose the Azure subscription and resource group you want to use for the SaaS offer or create new ones if necessary. (see image above)
- Enter a unique resource name to identify the SaaS subscription (e.g. my-saas-subscription-1).
- Follow the prompts to complete the subscription process and any necessary configuration steps.
- Click "Review and Subscribe" and/or "Subscribe" when ready.
- 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:
- 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).
- Log in using the same Microsoft account used to purchase the SaaS subscription offer.
- Activate the subscription by following the prompts on the provisioning portal by providing the required information and pressing the Activate button. (see image below)
- 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.
- 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).
- 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.
- 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.
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:
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.
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 |
The expected output of a successful action returns a 200 status code:
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 |
The expected output of a successful action returns a 200 status code:
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 click on 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 clicking or hoving 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 click on 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.