Skip to content

intel471/titan-client-python

BranchesTags

Repository files navigation

Titan Python Client

Official low-level client for Intel 471's Titan API. It aims at providing common ground for all the endpoints in Python.

This Python package is automatically generated by the OpenAPI Generator project:

  • API version: 1.20.0
  • Package version: 1.20.0.3
  • Build package: org.openapitools.codegen.languages.PythonLegacyClientCodegen

Requirements.

Python >= 3.8

Installation & Usage

pip install

pip install titan-client

You can install the python package directly from GitHub:

pip install git+ssh://git@github.com/intel471/titan-client-python.git

(you may need to run pip with root permission)

Then import the package:

import titan_client

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import titan_client

Getting Started

Please follow the installation procedure and then run the following:

from __future__ import print_function

import time
import titan_client
from titan_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.intel471.com/v1
# See configuration.py for a list of all supported configuration parameters.
configuration = titan_client.Configuration(
    host = "https://api.intel471.com/v1"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure HTTP basic authorization: BasicAuth
configuration = titan_client.Configuration(
    username = 'YOUR_USERNAME',
    password = 'YOUR_PASSWORD'
)


# Enter a context with an instance of the API client
with titan_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = titan_client.ActorsApi(api_client)
    actor = 'synthx' # str | Search for handles only. At least one of `actor`, `forum` parameter is required. (optional)
    forum = '0day' # str | Search for actors active on given forum. (optional)
    _from = '2day' # str | Long unix time or string time range. Search data starting from given creation time (including). (optional)
    until = '1day' # str | Long unix time or string time range. Search data ending before given creation time (excluding). (optional)
    last_updated_from = '2day' # str | Long unix time or string time range. Search data starting from given last updated time (including). Empty indicates unbounded. (optional)
    last_updated_until = '1day' # str | Long unix time or string time range. Search data ending before given last updated time (excluding). Empty indicates unbounded. (optional)
    sort = 'relevance' # str | Sort results by relevance or by the object's native time in descending (latest) or ascending (earliest) order. (optional) (default to 'relevance')
    offset = 0 # int | Skip leading number of records. (optional) (default to 0)
    count = 10 # int | Returns given number of records starting from `offset` position. (optional) (default to 10)

    try:
        # Search Actors
        api_response = api_instance.actors_get(actor=actor, forum=forum, _from=_from, until=until, last_updated_from=last_updated_from, last_updated_until=last_updated_until, sort=sort, offset=offset, count=count)
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling ActorsApi->actors_get: %s\n" % e)

Serialization

Each call to the API instance returns a structure of python objects. The response can be then serialized to one of the common formats if needed.

Python dict

In order to convert the response into the python dict structure, call to_dict() method on the response object. It accepts an optional boolean argument serialize, which defaults to False. When set to True, the names of the keys will not be normalised to snake_case, but will be kept intact, as received from the API endpoint.

serialized = api_response.to_dict(serialize=True)

STIX format

In order to convert the response into the STIX format (v2.1), call to_stix() method on the response object. It will convert the API response into respective STIX objects and return them inside a Bundle object (from stix2 package). Bundle object can be serialized into JSON string using serialize() method.

bundle = api_response.to_stix()
json_repr = bundle.serialize()

Some responses can be enriched with extra details coming from additional API calls. For example reports associated with IoCs can get the full description fetched and ingested into the description field. In order to enable the enrichment, pass an instance of titan_client.titan_stix.STIXMapperSettings class into the to_stix() method. It should be initialised with at least titan_client package and initialised api_client. By default it will enable enrichment for full GiRs names and for reports descriptions. For the full list of settings please refer to the implementation of STIXMapperSettings class.

import titan_client
from titan_client.titan_stix import STIXMapperSettings
configuration = titan_client.Configuration(...)
with titan_client.ApiClient(configuration) as api_client:
    api_instance = titan_client.IOCsApi(api_client)
    api_response = api_instance.iocs_get(ioc="*", ioc_type="maliciousDomain")
    bundle = api_response.to_stix(STIXMapperSettings(titan_client, api_client))

The most common enrichment is expanding Intel Requirements' IDs into full names using /girs endpoint. As the GiRs do not change too often, the response is cached by default to limit unnecessary API calls. Default TTL is set to 10 hours and it can be controlled with I471_TITAN_CLIENT_CACHE_TTL env variable, which accepts number of seconds.

If the objects returned by the endpoint for some reason can't be mapped into STIX format, EmptyBundle exception will be raised.

At the moment following API methods provide the response in STIX format:

API endpoints Client's classes/methods Produced outcome Available enrichment Additional info
/indicators, /indicators/stream, IndicatorsApi#indicators_get, IndicatorsApi#indicators_stream_get Indicator and Malware SDOs related using Relationship object; URL, IPv4Address or File Observable related with the Indicator SDO using Relationship object Full names of Intel Requirements -
/iocs IOCsApi#iocs_get Indicator and Report SDOs and either URL, DomainName, IPv4Address or File Observable. Both Indicator and Observable objects are related with the Report using Report's internal property object_refs. Observable and Indicator objects also are related using Relationship object Full descriptions of associated reports; attachments in format compatible with OpenCTI Only indicators of type MaliciousDomain, MaliciousURL, IPAddress, MD5, SHA1 and SHA256
/yara YARAApi#yara_get Indicator and Malware SDOs related using Relationship object Full names of Intel Requirements -
/cve/reports, /cve/reports/{uid} VulnerabilitiesApi#cve_reports_get, VulnerabilitiesApi#cve_reports_uid_get Vulnerability SDOs Full names of Intel Requirements -

Please note that STIX mapping is an experimental feature. Not all the endpoints are mapped yet and those that are mapped might have issues and might be a subject of further re-modelling. If to_stix() method is called on a response from the endpoint that is not mapped yet, StixMapperNotFound exception will be raised.

Documentation for API Endpoints

All URIs are relative to https://api.intel471.com/v1

Class Method HTTP request Description
ActorsApi actors_get GET /actors Search Actors
ActorsApi actors_uid_get GET /actors/{uid} Get Actor
AlertsApi alerts_get GET /alerts Get Alerts
CredentialsApi credential_sets_accessed_urls_get GET /credentialSets/accessedUrls Search credential set accessed urls
CredentialsApi credential_sets_accessed_urls_stream_get GET /credentialSets/accessedUrls/stream Credential set accessed url stream
CredentialsApi credential_sets_get GET /credentialSets Search credential sets
CredentialsApi credential_sets_stream_get GET /credentialSets/stream Credential set stream
CredentialsApi credentials_accessed_urls_get GET /credentials/accessedUrls Search credential accessed urls
CredentialsApi credentials_accessed_urls_stream_get GET /credentials/accessedUrls/stream Credential accessed url stream
CredentialsApi credentials_get GET /credentials Search credentials
CredentialsApi credentials_occurrences_get GET /credentials/occurrences Search credential occurrences
CredentialsApi credentials_occurrences_stream_get GET /credentials/occurrences/stream Credential occurrence stream
CredentialsApi credentials_stream_get GET /credentials/stream Credential stream
DataLeakBlogsApi dataleak_posts_get GET /dataleak/posts Search Data Leak Posts
EntitiesApi entities_get GET /entities Search Entities.
EventsApi events_get GET /events Search Malware Intelligence Events
EventsApi events_stream_get GET /events/stream Stream Malware Intelligence Events
ForumsApi posts_get GET /posts Search Forum Posts
ForumsApi private_messages_get GET /privateMessages Search Private Messages
GIRsApi girs_get GET /girs Search GIRs
GlobalSearchApi search_get GET /search Search - Global Search
IOCsApi iocs_get GET /iocs Search Indicator of Compromise (IoC)
IndicatorsApi indicators_get GET /indicators Search Malware Intelligence Indicators
IndicatorsApi indicators_stream_get GET /indicators/stream Stream Malware Intelligence Indicators
MalwareFamiliesApi malware_families_get GET /malwareFamilies Search Malware Families
MarketplacesApi marketplaces_get GET /marketplaces Search Marketplaces
MarketplacesApi marketplaces_products_get GET /marketplaces/products Search Products
MarketplacesApi marketplaces_products_stream_get GET /marketplaces/products/stream Products stream
MarketplacesApi marketplaces_resources_get GET /marketplaces/resources Search Resources
MarketplacesApi marketplaces_resources_stream_get GET /marketplaces/resources/stream Resources stream
MarketplacesApi marketplaces_vendors_get GET /marketplaces/vendors Search Vendors
MarketplacesApi marketplaces_vendors_stream_get GET /marketplaces/vendors/stream Vendors stream
MessagingServicesApi messaging_services_instant_messages_get GET /messagingServices/instantMessages Search Instant Messages
NewsApi news_get GET /news Search News
NewsApi news_uid_get GET /news/{uid} Get News
ReportsApi breach_alerts_get GET /breachAlerts Search Breach Alerts
ReportsApi breach_alerts_uid_get GET /breachAlerts/{uid} Get Breach Alert
ReportsApi malware_reports_get GET /malwareReports Search Malware Intelligence Reports
ReportsApi malware_reports_uid_get GET /malwareReports/{uid} Get Malware Intelligence Report
ReportsApi reports_get GET /reports Search Reports
ReportsApi reports_uid_get GET /reports/{uid} Get Report
ReportsApi situation_reports_get GET /situationReports Search Situation Reports
ReportsApi situation_reports_report_uid_get GET /situationReports/{reportUid} Get Situation Report
ReportsApi spot_reports_get GET /spotReports Search Spot Reports
ReportsApi spot_reports_uid_get GET /spotReports/{uid} Get Spot Report
TagsApi tags_get GET /tags Get Tag List
VulnerabilitiesApi cve_reports_get GET /cve/reports Search Vulnerability Reports (CVE)
VulnerabilitiesApi cve_reports_uid_get GET /cve/reports/{uid} Get Vulnerability Report (CVE)
WatchersApi watcher_groups_get GET /watcherGroups Get Watcher Group List
WatchersApi watcher_groups_group_uid_delete DELETE /watcherGroups/{group-uid} Delete Watcher Group
WatchersApi watcher_groups_group_uid_get GET /watcherGroups/{group-uid} Get Watcher Group
WatchersApi watcher_groups_group_uid_put PUT /watcherGroups/{group-uid} Put Watcher Group
WatchersApi watcher_groups_group_uid_watchers_get GET /watcherGroups/{group-uid}/watchers Get Watchers list
WatchersApi watcher_groups_group_uid_watchers_post POST /watcherGroups/{group-uid}/watchers Create Watcher
WatchersApi watcher_groups_group_uid_watchers_watcher_uid_delete DELETE /watcherGroups/{group-uid}/watchers/{watcher-uid} Delete Watcher
WatchersApi watcher_groups_group_uid_watchers_watcher_uid_get GET /watcherGroups/{group-uid}/watchers/{watcher-uid} Get Watcher
WatchersApi watcher_groups_group_uid_watchers_watcher_uid_put PUT /watcherGroups/{group-uid}/watchers/{watcher-uid} Put Watcher
WatchersApi watcher_groups_post POST /watcherGroups Create Watcher Group
YARAApi yara_get GET /yara Search Malware Intelligence YARA

Documentation For Models

Documentation For Authorization

BasicAuth

  • Type: HTTP basic authentication

Author

About

Official low-level Python client for Titan API.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

4 stars

Watchers

4 watching

Forks

1 fork
Report repository

Releases 23

Release 1.20.0.3 Latest
Sep 23, 2024
+ 22 releases

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages