Skip to content

Commit 1353b85

Browse files
MislavReversingLabsMislavReversingLabs
authored
Merge pull request #19 from MislavReversingLabs/main
1.2.0
2 parents cb195e7 + aaa42a3 commit 1353b85

File tree

2 files changed

+324
-1
lines changed

2 files changed

+324
-1
lines changed

‎TitaniumCloud/taxii_ransomware_feed.ipynb

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"source": [
6+
"# TitaniumCloud TAXII Ransomware and Related Tools Feed\n",
7+
"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",
8+
"**NOTE:** If pasted into a Python file in the displayed order, all code cells can also work as a Python script."
9+
],
10+
"metadata": {
11+
"collapsed": false
12+
},
13+
"id": "666cd5fd9718bf41"
14+
},
15+
{
16+
"cell_type": "markdown",
17+
"source": [
18+
"### Covered API classes\n",
19+
"This notebook covers examples for the following API class:\n",
20+
"- **TAXIIRansomwareFeed** (*TCTF-0001*)\n",
21+
"\n",
22+
"### Credentials\n",
23+
"Credentials are loaded from a local file instead of being written here in plain text.\n",
24+
"To learn how to creat the credentials file, see the **Storing and using the credentials** section in the [README file](./README.md)"
25+
],
26+
"metadata": {
27+
"collapsed": false
28+
},
29+
"id": "f1838f3e308cb935"
30+
},
31+
{
32+
"cell_type": "markdown",
33+
"source": [
34+
"### 1. Importing the required classes\n",
35+
"First, we will import the required API class from the ticloud module."
36+
],
37+
"metadata": {
38+
"collapsed": false
39+
},
40+
"id": "634bd47f0b5c6749"
41+
},
42+
{
43+
"cell_type": "code",
44+
"execution_count": null,
45+
"outputs": [],
46+
"source": [
47+
"from ReversingLabs.SDK.ticloud import TAXIIRansomwareFeed"
48+
],
49+
"metadata": {
50+
"collapsed": false
51+
},
52+
"id": "fa26769d0e56fd3"
53+
},
54+
{
55+
"cell_type": "markdown",
56+
"source": [
57+
"### 2. Loading the credentials\n",
58+
"Next, we will load our TitaniumCloud credentials from the local `ticloud_credentials.json` file.\n",
59+
"**NOTE: Instead of doing this step, you can paste your credentials while creating the Python object in the following step.**"
60+
],
61+
"metadata": {
62+
"collapsed": false
63+
},
64+
"id": "e5af1a6d9ba3971a"
65+
},
66+
{
67+
"cell_type": "code",
68+
"execution_count": null,
69+
"outputs": [],
70+
"source": [
71+
"import json\n",
72+
"\n",
73+
"\n",
74+
"CREDENTIALS = json.load(open(\"ticloud_credentials.json\"))\n",
75+
"USERNAME = CREDENTIALS.get(\"username\")\n",
76+
"PASSWORD = CREDENTIALS.get(\"password\")\n",
77+
"USER_AGENT = json.load(open('../user_agent.json'))[\"user_agent\"]"
78+
],
79+
"metadata": {
80+
"collapsed": false
81+
},
82+
"id": "65b14a99e6dd84ff"
83+
},
84+
{
85+
"cell_type": "markdown",
86+
"source": [
87+
"### 3. Creating the TAXIIRansomwareFeed object\n",
88+
"Now we need to create the Python object for the TAXIIRansomwareFeed in order to use its quota displaying methods."
89+
],
90+
"metadata": {
91+
"collapsed": false
92+
},
93+
"id": "97b4ca8a2e895386"
94+
},
95+
{
96+
"cell_type": "code",
97+
"execution_count": null,
98+
"outputs": [],
99+
"source": [
100+
"taxii_feed = TAXIIRansomwareFeed(\n",
101+
" host=\"https://data.reversinglabs.com\",\n",
102+
" username=USERNAME,\n",
103+
" password=PASSWORD,\n",
104+
" user_agent=USER_AGENT\n",
105+
")"
106+
],
107+
"metadata": {
108+
"collapsed": false
109+
},
110+
"id": "4827090f00f908cd"
111+
},
112+
{
113+
"cell_type": "markdown",
114+
"source": [
115+
"### 4. Standard endpoints\n",
116+
"Every TAXII standard server has the following endpoints:\n",
117+
"- Discovery endpoint\n",
118+
"- API root endpoint\n",
119+
"- Collections endpoint"
120+
],
121+
"metadata": {
122+
"collapsed": false
123+
},
124+
"id": "176ac60d172c18d9"
125+
},
126+
{
127+
"cell_type": "markdown",
128+
"source": [
129+
"#### Discovery endpoint\n",
130+
"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:"
131+
],
132+
"metadata": {
133+
"collapsed": false
134+
},
135+
"id": "fa14660cc41b86e"
136+
},
137+
{
138+
"cell_type": "code",
139+
"execution_count": null,
140+
"outputs": [],
141+
"source": [
142+
"discovey_info = taxii_feed.discovery_info()\n",
143+
"print(discovey_info.text)"
144+
],
145+
"metadata": {
146+
"collapsed": false
147+
},
148+
"id": "f39d9135ab106e19"
149+
},
150+
{
151+
"cell_type": "markdown",
152+
"source": [
153+
"Now that we have discovery info, we can see the available API roots.\n",
154+
"\n",
155+
"#### API root endpoint\n",
156+
"To get the info about a specific API root, run the following action:"
157+
],
158+
"metadata": {
159+
"collapsed": false
160+
},
161+
"id": "50e762735d47ece4"
162+
},
163+
{
164+
"cell_type": "code",
165+
"execution_count": null,
166+
"outputs": [],
167+
"source": [
168+
"api_rooot_info = taxii_feed.api_root_info(api_root=\"ransomware-lite\")\n",
169+
"print(api_rooot_info.text)"
170+
],
171+
"metadata": {
172+
"collapsed": false
173+
},
174+
"id": "e0996573a5d8f8e9"
175+
},
176+
{
177+
"cell_type": "markdown",
178+
"source": [
179+
"#### Collections endpoint\n",
180+
"To get the info about a specific collection on an API root, run the following action:"
181+
],
182+
"metadata": {
183+
"collapsed": false
184+
},
185+
"id": "8a686f76af83dd19"
186+
},
187+
{
188+
"cell_type": "code",
189+
"execution_count": null,
190+
"outputs": [],
191+
"source": [
192+
"collection_info = taxii_feed.collections_info(api_root=\"ransomware-lite\")\n",
193+
"print(collection_info.text)"
194+
],
195+
"metadata": {
196+
"collapsed": false
197+
},
198+
"id": "d5a28e002780ed8a"
199+
},
200+
{
201+
"cell_type": "markdown",
202+
"source": [
203+
"### 5. Getting objects from the feed\n",
204+
"\n",
205+
"#### Single page of objects\n",
206+
"To fetch a single page of objects from a specified time onwards, do the following:"
207+
],
208+
"metadata": {
209+
"collapsed": false
210+
},
211+
"id": "ec36bcf574f72792"
212+
},
213+
{
214+
"cell_type": "code",
215+
"execution_count": null,
216+
"outputs": [],
217+
"source": [
218+
"from datetime import datetime, timedelta\n",
219+
"\n",
220+
"hours_back = 5.0 \n",
221+
"desired_time = datetime.today() - timedelta(hours=hours_back)\n",
222+
"time_string = desired_time.strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n",
223+
"\n",
224+
"one_page = taxii_feed.get_objects(\n",
225+
" api_root=\"ransomware-lite\",\n",
226+
" collection_id=\"024d3659-c21c-533f-88c9-3ad10607a040\",\n",
227+
" added_after=time_string\n",
228+
")\n",
229+
"\n",
230+
"print(one_page.text)"
231+
],
232+
"metadata": {
233+
"collapsed": false
234+
},
235+
"id": "46a5d6a510fac273"
236+
},
237+
{
238+
"cell_type": "markdown",
239+
"source": [
240+
"This example fetches data from the previous 5 hours relatively. To change the range, edit the `hours_back` variable.\n",
241+
"\n",
242+
"#### Objects from multiple pages\n",
243+
"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."
244+
],
245+
"metadata": {
246+
"collapsed": false
247+
},
248+
"id": "80f507bfab879693"
249+
},
250+
{
251+
"cell_type": "code",
252+
"execution_count": null,
253+
"outputs": [],
254+
"source": [
255+
"results_list = taxii_feed.get_objects_aggregated(\n",
256+
" api_root=\"ransomware-lite\",\n",
257+
" collection_id=\"024d3659-c21c-533f-88c9-3ad10607a040\",\n",
258+
" added_after=time_string,\n",
259+
" result_limit=50,\n",
260+
" max_results=500\n",
261+
")\n",
262+
"\n",
263+
"print(results_list)"
264+
],
265+
"metadata": {
266+
"collapsed": false
267+
},
268+
"id": "9389d1f1c959773c"
269+
},
270+
{
271+
"cell_type": "markdown",
272+
"source": [
273+
"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",
274+
"\n",
275+
"#### Single specific object\n",
276+
"Apart from fetching latest indicators in general, the TAXII feed also allows fetching a single specific indicator using its ID:"
277+
],
278+
"metadata": {
279+
"collapsed": false
280+
},
281+
"id": "c679c3b355da9be0"
282+
},
283+
{
284+
"cell_type": "code",
285+
"execution_count": null,
286+
"outputs": [],
287+
"source": [
288+
"specific_indicator = taxii_feed.get_objects(\n",
289+
" api_root=\"ransomware-lite\",\n",
290+
" collection_id=\"024d3659-c21c-533f-88c9-3ad10607a040\",\n",
291+
" match_id=\"indicator--1e14a458-f3f8-5d26-8049-097e00e55aa2\"\n",
292+
")\n",
293+
"\n",
294+
"print(specific_indicator.text)"
295+
],
296+
"metadata": {
297+
"collapsed": false
298+
},
299+
"id": "622937eebbde79de"
300+
}
301+
],
302+
"metadata": {
303+
"kernelspec": {
304+
"display_name": "Python 3",
305+
"language": "python",
306+
"name": "python3"
307+
},
308+
"language_info": {
309+
"codemirror_mode": {
310+
"name": "ipython",
311+
"version": 2
312+
},
313+
"file_extension": ".py",
314+
"mimetype": "text/x-python",
315+
"name": "python",
316+
"nbconvert_exporter": "python",
317+
"pygments_lexer": "ipython2",
318+
"version": "2.7.6"
319+
}
320+
},
321+
"nbformat": 4,
322+
"nbformat_minor": 5
323+
}

‎user_agent.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
{
2-
"user_agent": "ReversingLabs SDK Cookbook v1.1.0"
2+
"user_agent": "ReversingLabs SDK Cookbook v1.2.0"
33
}

0 commit comments

Comments
 (0)