GitLocker: The Coding Marketplace

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
)