-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #19 from MislavReversingLabs/main
1.2.0
- Loading branch information
Showing
2 changed files
with
324 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,323 @@ | ||
{ | ||
"cells": [ | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"# TitaniumCloud TAXII Ransomware and Related Tools Feed\n", | ||
"This notebook demonstrates how to use the TCTF-0001 TAXII Ransomware and Related Tools Feed which delivers fresh and up-to-date indicators of ransomware activity in the wild.\n", | ||
"**NOTE:** If pasted into a Python file in the displayed order, all code cells can also work as a Python script." | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "666cd5fd9718bf41" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"### Covered API classes\n", | ||
"This notebook covers examples for the following API class:\n", | ||
"- **TAXIIRansomwareFeed** (*TCTF-0001*)\n", | ||
"\n", | ||
"### Credentials\n", | ||
"Credentials are loaded from a local file instead of being written here in plain text.\n", | ||
"To learn how to creat the credentials file, see the **Storing and using the credentials** section in the [README file](./README.md)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "f1838f3e308cb935" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"### 1. Importing the required classes\n", | ||
"First, we will import the required API class from the ticloud module." | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "634bd47f0b5c6749" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"from ReversingLabs.SDK.ticloud import TAXIIRansomwareFeed" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "fa26769d0e56fd3" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"### 2. Loading the credentials\n", | ||
"Next, we will load our TitaniumCloud credentials from the local `ticloud_credentials.json` file.\n", | ||
"**NOTE: Instead of doing this step, you can paste your credentials while creating the Python object in the following step.**" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "e5af1a6d9ba3971a" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"import json\n", | ||
"\n", | ||
"\n", | ||
"CREDENTIALS = json.load(open(\"ticloud_credentials.json\"))\n", | ||
"USERNAME = CREDENTIALS.get(\"username\")\n", | ||
"PASSWORD = CREDENTIALS.get(\"password\")\n", | ||
"USER_AGENT = json.load(open('../user_agent.json'))[\"user_agent\"]" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "65b14a99e6dd84ff" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"### 3. Creating the TAXIIRansomwareFeed object\n", | ||
"Now we need to create the Python object for the TAXIIRansomwareFeed in order to use its quota displaying methods." | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "97b4ca8a2e895386" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"taxii_feed = TAXIIRansomwareFeed(\n", | ||
" host=\"https://data.reversinglabs.com\",\n", | ||
" username=USERNAME,\n", | ||
" password=PASSWORD,\n", | ||
" user_agent=USER_AGENT\n", | ||
")" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "4827090f00f908cd" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"### 4. Standard endpoints\n", | ||
"Every TAXII standard server has the following endpoints:\n", | ||
"- Discovery endpoint\n", | ||
"- API root endpoint\n", | ||
"- Collections endpoint" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "176ac60d172c18d9" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"#### Discovery endpoint\n", | ||
"The discovery endpoint is the starting point for learning about the available API roots on a TAXII server and to get the general info about the server. To fetch the discovery info from the TAXII Ransomware and Related Tools feed, do the run the following action:" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "fa14660cc41b86e" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"discovey_info = taxii_feed.discovery_info()\n", | ||
"print(discovey_info.text)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "f39d9135ab106e19" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"Now that we have discovery info, we can see the available API roots.\n", | ||
"\n", | ||
"#### API root endpoint\n", | ||
"To get the info about a specific API root, run the following action:" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "50e762735d47ece4" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"api_rooot_info = taxii_feed.api_root_info(api_root=\"ransomware-lite\")\n", | ||
"print(api_rooot_info.text)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "e0996573a5d8f8e9" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"#### Collections endpoint\n", | ||
"To get the info about a specific collection on an API root, run the following action:" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "8a686f76af83dd19" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"collection_info = taxii_feed.collections_info(api_root=\"ransomware-lite\")\n", | ||
"print(collection_info.text)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "d5a28e002780ed8a" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"### 5. Getting objects from the feed\n", | ||
"\n", | ||
"#### Single page of objects\n", | ||
"To fetch a single page of objects from a specified time onwards, do the following:" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "ec36bcf574f72792" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"from datetime import datetime, timedelta\n", | ||
"\n", | ||
"hours_back = 5.0 \n", | ||
"desired_time = datetime.today() - timedelta(hours=hours_back)\n", | ||
"time_string = desired_time.strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n", | ||
"\n", | ||
"one_page = taxii_feed.get_objects(\n", | ||
" api_root=\"ransomware-lite\",\n", | ||
" collection_id=\"024d3659-c21c-533f-88c9-3ad10607a040\",\n", | ||
" added_after=time_string\n", | ||
")\n", | ||
"\n", | ||
"print(one_page.text)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "46a5d6a510fac273" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"This example fetches data from the previous 5 hours relatively. To change the range, edit the `hours_back` variable.\n", | ||
"\n", | ||
"#### Objects from multiple pages\n", | ||
"Paging can be done manually or by using the `get_objects_aggregated` method which does the paging withing itself and returns a desired number of results. If the `max_results` parameter is set to `None`, ALL available results for the defined period will be returned." | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "80f507bfab879693" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"results_list = taxii_feed.get_objects_aggregated(\n", | ||
" api_root=\"ransomware-lite\",\n", | ||
" collection_id=\"024d3659-c21c-533f-88c9-3ad10607a040\",\n", | ||
" added_after=time_string,\n", | ||
" result_limit=50,\n", | ||
" max_results=500\n", | ||
")\n", | ||
"\n", | ||
"print(results_list)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "9389d1f1c959773c" | ||
}, | ||
{ | ||
"cell_type": "markdown", | ||
"source": [ | ||
"In our example, we defined that we need a maximum of 500 results. In case there is less than 500 results available for the defined period, the list will return the available maximum. The aggregating method does the paging for us and lets us worry only about the maximum desired number of results and the number of results returned per each page (`result_limit` - affects the number of requests being done in the background).\n", | ||
"\n", | ||
"#### Single specific object\n", | ||
"Apart from fetching latest indicators in general, the TAXII feed also allows fetching a single specific indicator using its ID:" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "c679c3b355da9be0" | ||
}, | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"outputs": [], | ||
"source": [ | ||
"specific_indicator = taxii_feed.get_objects(\n", | ||
" api_root=\"ransomware-lite\",\n", | ||
" collection_id=\"024d3659-c21c-533f-88c9-3ad10607a040\",\n", | ||
" match_id=\"indicator--1e14a458-f3f8-5d26-8049-097e00e55aa2\"\n", | ||
")\n", | ||
"\n", | ||
"print(specific_indicator.text)" | ||
], | ||
"metadata": { | ||
"collapsed": false | ||
}, | ||
"id": "622937eebbde79de" | ||
} | ||
], | ||
"metadata": { | ||
"kernelspec": { | ||
"display_name": "Python 3", | ||
"language": "python", | ||
"name": "python3" | ||
}, | ||
"language_info": { | ||
"codemirror_mode": { | ||
"name": "ipython", | ||
"version": 2 | ||
}, | ||
"file_extension": ".py", | ||
"mimetype": "text/x-python", | ||
"name": "python", | ||
"nbconvert_exporter": "python", | ||
"pygments_lexer": "ipython2", | ||
"version": "2.7.6" | ||
} | ||
}, | ||
"nbformat": 4, | ||
"nbformat_minor": 5 | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,3 @@ | ||
{ | ||
"user_agent": "ReversingLabs SDK Cookbook v1.1.0" | ||
"user_agent": "ReversingLabs SDK Cookbook v1.2.0" | ||
} |