reversinglabs-sdk-py2 1.2.1

Description:

reversinglabssdkpy2 1.2.1

ReversingLabsSDK
A Python SDK for ReversingLabs REST services (TitaniumCloud and appliances) - Python 2 version.
The idea behind this SDK is to enable easier out-of-the-box development of software integrations and automation services that need to interact with ReversingLabs.
The SDK consists of several modules, where each module represents one ReversingLabs service or ReversingLabs TitaniumCloud.

ReversingLabsSDK

Module: a1000

Class A1000
Parameters
Methods


Module: ticloud

Common Parameters
Class FileReputation
Class AVScanners
Class FileAnalysis
Class RHA1FunctionalSimilarity
Class RHA1Analytics
Class URIStatistics
Class URIIndex
Class AdvancedSearch
Class ExpressionSearch
Class FileDownload
Class URLThreatIntelligence
Class AnalyzeURL
Class FileUpload
Class DynamicAnalysis
Class CertificateAnalytics
Class RansomwareIndicators


Module: tiscale

Class TitaniumScale
Parameters
Methods


Examples



Module: a1000
A Python module representing the ReversingLabs A1000 malware analysis platform.
Class:
class A1000(object)
def __init__(self, host, username=None, password=None, token=None, fields=__FIELDS, wait_time_seconds=2, retries=10, verify=True, proxies=None, user_agent=DEFAULT_USER_AGENT):

Parameters:
host - A1000 address
username - A1000 username
password - A1000 password
token - A1000 user token for the REST API
fields - optional fields that will be returned in the analysis report
wait_time_seconds - wait time between each report fetching retry
retries - number of report fetching retries
verify - verify SSL certificate
proxies - optional proxies in use
user_agent - optional user agent string

NOTE!
The default means of authorization on the ReversingLabs A1000 REST API is the token.
If username and password are used instead, a token fetching request will be done so the token can be used in further actions without the user explicitly providing the token.

Class methods:

configuration_dump

Returns the configuration of the instantiated A1000 object


test_connection

Creates a request towards the A1000 Check Status API to test the connection with A1000


upload_sample_from_path

Accepts a file path string and returns a response containing the analysis task ID


upload_sample_from_file

Accepts a file open in 'rb' mode and returns a response containing the analysis task ID


get_results

Accepts a list of hashes and returns a summary JSON report for each of them
This method utilizes the set number of retries and wait time in seconds to time
out if the analysis results are not ready


upload_sample_and_get_results

Accepts a file path string or an opened file in 'rb' mode for file upload and returns an analysis report response
This method combines uploading a sample and obtaining the analysis results
The result fetching action of this method utilizes the set number of retries and wait time in seconds to time
out if the analysis results are not ready


get_classification

Accepts one or more sample hashes and returns their classification


reanalyze_samples

Accepts a single hash or a list of hashes of the same type and reanalyzes the corresponding samples


get_extracted_files

Accepts a sample hash and returns a list of all files TitaniumCore engine extracted from the requested sample during static analysis


download_extracted_files

Accepts a single hash string and returns a downloadable archive file containing files extracted from the desired sample


delete_samples

Accepts a single hash string or a list of hashes and deletes the corresponding samples from A1000


download_sample

Accepts a single hash string and returns a downloadable sample


advanced_search

Accepts a search query string and performs advanced search for local samples on A1000
Returns only one defined page of results using one request


advanced_search_aggregated

Accepts a search query string and performs advanced search for local samples on A1000
Returns a list of results aggregated through multiple paginated requests




Module: ticloud
A Python module representing the ReversingLabs TitaniumCloud API-s.
Each class in this module represents one TitaniumCloud API and can be instantiated using the same set of parameters:
def __init__(self, host, username, password, verify=True, proxies=None, user_agent=DEFAULT_USER_AGENT, allow_none_return=False)

Parameters:
host - TitaniumCloud address
username - TitaniumCloud username
password - TitaniumCloud password
verify - verify SSL certificate
proxies - optional proxies in use
user_agent - optional user agent string
allow_none_return - if set to True, 404 response codes will return None instead of NotFoundError
Class:
class FileReputation(TiCloudAPI)

Methods:

get_file_reputation

Accepts a hash string or a list of hash strings and returns file reputation
Hash strings in a passed list must all be of the same hashing algorithm



Class:
class AVScanners(TiCloudAPI)

Methods:

get_scan_results

Accepts a hash string or a list of hash strings and returns AV scanner results
Hash strings in a passed list must all be of the same hashing algorithm



Class:
class FileAnalysis(TiCloudAPI)

Methods:

get_analysis_results

Accepts a hash string or a list of hash strings and returns extended file analysis


extract_uri_list_from_report

Accepts a list of entries from the FileAnalysis report and returns a list of URI-s from those entries.


get_file_type

Accepts a sample hash and returns the file type string



Class:
class RHA1FunctionalSimilarity(TiCloudAPI)

Methods:

get_similar_hashes

Accepts a hash string and returns a list of functionally similar hashes
Returns only one defined page of results using one request


get_similar_hashes_aggregated

Accepts a hash string and returns a list of functionally similar hashes
Returns a list of results aggregated through multiple paginated requests



Class:
class RHA1Analytics(TiCloudAPI)

Methods:

get_rha1_analytics

Accepts one or more hash strings and returns a count of functionally similar hashes grouped by classification



Class:
class URIStatistics(TiCloudAPI)

Methods:

get_uri_statistics

Accepts a URI string and returns a count of files associated with that URI grouped by classification



Class:
class URIIndex(TiCloudAPI)

Methods:

get_uri_index

Accepts a URI string and returns a list of files associated with this URI
Returns only one defined page of results using one request


get_uri_index_aggregated

Accepts a URI string and returns a list of files associated with this URI
Returns a list of results aggregated through multiple paginated requests



Class:
class AdvancedSearch(TiCloudAPI)

Methods:

search

Accepts a search query string and performs advanced search on the API
Returns only one defined page of results using one request


search_aggregated

Accepts a search query string and performs advanced search on the API
Returns a list of results aggregated through multiple paginated requests



Class:
class ExpressionSearch(TiCloudAPI)

Methods:

search

Accepts a list containing the search query and performs expression search on the API
Returns only one defined page of results using one request


search_aggregated

Accepts a list containing the search query and performs expression search on the API
Returns a list of results aggregated through multiple paginated requests



Class:
class FileDownload(TiCloudAPI)

Methods:

get_download_status

Accepts a hash string and returns the sample's availability for download


download_sample

Accepts a hash string and downloads the related sample from TitaniumCloud



Class:
class URLThreatIntelligence(TiCloudAPI)

Methods:

get_url_report

Accepts a URL string and returns detailed URL analysis info


get_downloaded_files

Accepts a URL string and returns a list of files downloaded from that URL


get_latest_url_analysis_feed

Returns the latest URL analysis reports
Returns only one defined page of results using one request


get_latest_url_analysis_feed_aggregated

Returns the latest URL analysis reports
Returns a list of results aggregated through multiple paginated requests


get_url_analysis_feed_from_date

Accepts time format and a start time and returns URL analysis reports from that defined time onward
Returns only one defined page of results using one request


get_url_analysis_feed_from_date_aggregated

Accepts time format and a start time and returns URL analysis reports from that defined time onward
Returns a list of results aggregated through multiple paginated requests



Class:
class AnalyzeURL(TiCloudAPI)

Methods:

submit_url

Sends a URL string for analysis and returns an analysis task ID



Class:
class FileUpload(TiCloudAPI)

Methods:

upload_sample_from_path

Accepts a file path string and uploads the desired file to the File Upload API


upload_sample_from_file

Accepts an open file handle and uploads the desired file to the File Upload API



Class:
class DynamicAnalysis(TiCloudAPI)

Methods:

detonate_sample

Submits a sample available in the cloud for dynamic analysis and returns processing info
The sample needs to be available in TitaniumCloud beforehand


get_dynamic_analysis_results

Returns dynamic analysis results for a desired sample
The analysis of the selected sample must be finished for the results to be available



Class:
class CertificateAnalytics(TiCloudAPI)

Methods:

get_certificate_analytics

Accepts a certificate hash thumbprint (hash string) and returns certificate analytics results



Class:
class RansomwareIndicators(TiCloudAPI)

Methods:

get_indicators

Accepts a list of indicator type strings and integers for historical hours, health check and returning only freemium indicators. Returns indicators of ransomware and related tools.




Module: tiscale
A Python module representing the ReversingLabs TitaniumScale malware analysis appliance.
Class:
class TitaniumScale(object)
def __init__(self, host, token, wait_time_seconds=2, retries=10, verify=True, proxies=None, user_agent=DEFAULT_USER_AGENT)

Parameters:
host - TitaniumScale address
token - A1000 user token for the REST API
wait_time_seconds - wait time between each report fetching retry
retries - number of report fetching retries
verify - verify SSL certificate
proxies - optional proxies in use
user_agent - optional user agent string
Methods:

upload_sample_from_path

Accepts a file path string for file upload and returns a response containing the analysis task URL


upload_sample_from_file

Accepts a file opened in 'rb' mode for file upload and returns a response containing the analysis task URL


get_results

Accepts an analysis task URL and returns a file analysis summary or a full analysis report
This method utilizes the set number of retries and wait time in seconds to time out if the analysis results are not ready


upload_sample_and_get_results

Accepts a file path string or an opened file in 'rb' mode for file upload and returns a file analysis summary or a full analysis report
This method combines uploading a sample and obtaining the analysis results
The result obtaining action of this method utilizes the set number of retries and wait time in seconds to time out if the analysis results are not ready




Examples
A1000
from ReversingLabs.SDK.a1000 import A1000

# Using username and password for authorization
a1000 = A1000(
host="https://a1000.address",
username="username",
password="password",
verify=True,
wait_time_seconds=3,
retries=10
)

response = a1000.upload_sample_and_get_results(
file_path="/path/to/file.exe",
retry=True,
custom_filename="CustomName",
tags="custom,tags,go,here",
)

json_report = response.json()

from ReversingLabs.SDK.a1000 import A1000

# Using token for authorization
a1000 = A1000(
host="http://a1000.address",
token="1js76asmklaslk288japj29s89z",
verify=False,
wait_time_seconds=2,
retries=15
)

response = a1000.get_extracted_files(
sample_hash="cf23df2207d99a74fbe169e3eba035e633b65d94",
page_size=30
)

json_report = response.json()

TitaniumCloud
from ReversingLabs.SDK.ticloud import FileReputation, URIStatistics, FileDownload, FileUpload


host = "https://data.reversinglabs.com"
username = "username"
password = "password"
user_agent = "MyCustom App v0.0.1"



file_reputation = FileReputation(
host=host,
username=username,
password=password,
user_agent=user_agent
)

reputation = file_reputation.get_file_reputation(
hash_input="cf23df2207d99a74fbe169e3eba035e633b65d94",
extended_results=True,
show_hashes_in_results=False
)



uri_statistics = URIStatistics(
host=host,
username=username,
password=password,
user_agent=user_agent
)

statistics = uri_statistics.get_uri_statistics(
uri_input="youtube.com"
)



file_download = FileDownload(
host=host,
username=username,
password=password,
user_agent=user_agent
)

download = file_download.download_sample(
hash_input="cf23df2207d99a74fbe169e3eba035e633b65d94"
)

with open("/path/to/file", "wb") as file_handle:
file_handle.write(download.content)



file_upload = FileUpload(
host=host,
username=username,
password=password,
user_agent=user_agent
)

upload = file_upload.upload_sample_from_path(
file_path="/path/to/file",
sample_name="Custom Sample Name",
sample_domain="webdomain.com"
)

TitaniumScale
from ReversingLabs.SDK.tiscale import TitaniumScale


titanium_scale = TitaniumScale(
host="https://tiscale.address",
token="examplesecrettoken", # replace with a proper token
verify=True,
wait_time_seconds=5,
retries=6
)

results = titanium_scale.upload_sample_and_get_results(
file_source=open("/path/to/file.exe", "rb"),
full_report=True
)