cti-python-stix2/docs/guide/FileSystem.ipynb

520 lines
22 KiB
Plaintext

{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## FileSystem \n",
"\n",
"The FileSystem suite contains **FileSystemStore **, **FileSystemSource** and **FileSystemSink**. Under the hood, all FileSystem objects point to a file directory (on disk) that contains STIX2 content. \n",
"\n",
"The directory and file structure of the intended STIX2 content should be:\n",
"\n",
"```\n",
"stix2_content/\n",
" /STIX2 Domain Object type\n",
" STIX2 Domain Object\n",
" STIX2 Domain Object\n",
" .\n",
" .\n",
" .\n",
" /STIX2 Domain Object type\n",
" STIX2 Domain Object\n",
" STIX2 Domain Object\n",
" .\n",
" .\n",
" .\n",
" .\n",
" .\n",
" .\n",
" /STIX2 Domain Object type\n",
"```\n",
"\n",
"Essentially a master STIX2 content directory where each subdirectory aligns to a STIX2 domain object type (i.e. \"attack-pattern\", \"campaign\", \"malware\" etc..). Within each STIX2 domain object subdirectory are json files that are STIX2 domain objects of the specified type. The name of the json files correspond to the ID of the STIX2 domain object found within that file. A real example of the FileSystem directory structure:\n",
"\n",
"```\n",
"stix2_content/\n",
" /attack-pattern\n",
" attack-pattern--00d0b012-8a03-410e-95de-5826bf542de6.json\n",
" attack-pattern--0a3ead4e-6d47-4ccb-854c-a6a4f9d96b22.json\n",
" attack-pattern--1b7ba276-eedc-4951-a762-0ceea2c030ec.json\n",
" /campaign\n",
" /course-of-action\n",
" course-of-action--2a8de25c-f743-4348-b101-3ee33ab5871b.json\n",
" course-of-action--2c3ce852-06a2-40ee-8fe6-086f6402a739.json\n",
" /identity\n",
" identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5.json\n",
" /indicator\n",
" /intrusion-set\n",
" /malware\n",
" malware--1d808f62-cf63-4063-9727-ff6132514c22.json\n",
" malware--2eb9b131-d333-4a48-9eb4-d8dec46c19ee.json\n",
" /observed-data\n",
" /report\n",
" /threat-actor\n",
" /vulnerability\n",
"```\n",
"\n",
"**FileSystemStore** is intended for use cases where STIX2 content is retrieved and pushed to the same file directory. As **FileSystemStore** is just a wrapper around a paired **FileSystemSource** and **FileSystemSink** that point the same file directory.\n",
"\n",
"Use cases where STIX2 content will only be retrieved or pushed, then a **FileSystemSource** and **FileSystemSink** can be used individually. Or for the use case where STIX2 content will be retrieved from one distinct file directory and pushed to another.\n",
"\n",
"### FileSystem API\n",
"\n",
"\n",
"### FileSystemSource (snapshot)\n",
"* **get()** - search/retrieve most current STIX SDO/SRO via its ID\n",
"* **all_versions()** - search/retrieve all versions of STIX SDO/SRO via its id\n",
"* **query()** - search/retrieve STIX SDO/SRO(s) via search filters\n",
" \n",
"### FileSystemSink (snapshot)\n",
"* **add()** - add STIX SDO/SRO to a target file system endpoint.\n",
" \n",
"### FileSystemStore (snapshot)\n",
"\n",
"(super set of the FileSystemSource and FileSystemSink)\n",
"* **get()**\n",
"* **all_versions()**\n",
"* **query()**\n",
"* **add()**\n",
"\n",
"A note on **get()**, **all_versions()**, and **query()**. The format of the STIX2 content targeted by the FileSystem suite is json files. When STIX2 content (in json) is retrieved by the **FileSystemStore** from disk, the content will attempt to be parsed into full-featured python STIX2 objects and returned as such. \n",
"\n",
"A note on **add()**. When STIX content is added (pushed) to the file system, the STIX content can be supplied in the following forms: python STIX objects, python dicts (of valid STIX objects or Bundles), json-encoded strings (of valid STIX objects or Bundles), or a (python)list of any of the previously listed types. Any of the previous STIX content forms will be converted to a STIX json object (in a STIX Bundle) and written to disk. \n",
"\n",
"### FileSystem Examples\n",
"\n",
"#### FileSystemStore\n",
" "
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--00c3bfcb-99bd-4767-8c03-b08f585f5c8a\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:33:19.746Z\",\n",
" \"modified\": \"2017-05-31T21:33:19.746Z\",\n",
" \"name\": \"PowerDuke\",\n",
" \"description\": \"PowerDuke is a backdoor that was used by APT29 in 2016. It has primarily been delivered through Microsoft Word or Excel attachments containing malicious macros.[[Citation: Volexity PowerDuke November 2016]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0139\",\n",
" \"external_id\": \"S0139\"\n",
" },\n",
" {\n",
" \"source_name\": \"Volexity PowerDuke November 2016\",\n",
" \"description\": \"Adair, S.. (2016, November 9). PowerDuke: Widespread Post-Election Spear Phishing Campaigns Targeting Think Tanks and NGOs. Retrieved January 11, 2017.\",\n",
" \"url\": \"https://www.volexity.com/blog/2016/11/09/powerduke-post-election-spear-phishing-campaigns-targeting-think-tanks-and-ngos/\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n"
]
}
],
"source": [
"from stix2 import FileSystemStore\n",
"\n",
"\"\"\"\n",
"Working with the FileSystemStore, where STIX content can be retrieved and pushed to a file system.\n",
"\"\"\"\n",
"\n",
"# create FileSystemStore\n",
"fs = FileSystemStore(\"/home/michael/Desktop/sample_stix2_data\")\n",
"\n",
"# retrieve STIX2 content from FileSystemStore\n",
"ap = fs.get(\"attack-pattern--00d0b012-8a03-410e-95de-5826bf542de6\")\n",
"mal = fs.get(\"malware--00c3bfcb-99bd-4767-8c03-b08f585f5c8a\")\n",
"\n",
"# for visual purposes\n",
"print(mal)"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"from stix2 import ThreatActor, Indicator\n",
"\n",
"# create new STIX threat-actor\n",
"ta = ThreatActor(name=\"Adjective Bear\",\n",
" labels=[\"nation-state\"],\n",
" sophistication=\"innovator\",\n",
" resource_level=\"government\",\n",
" goals=[\n",
" \"compromising media outlets\",\n",
" \"water-hole attacks geared towards political, military targets\",\n",
" \"intelligence collection\"\n",
" ])\n",
"\n",
"# create new indicators\n",
"ind = Indicator(description=\"Crusades C2 implant\",\n",
" labels=[\"malicious-activity\"],\n",
" pattern=\"[file:hashes.'SHA-256' = '54b7e05e39a59428743635242e4a867c932140a999f52a1e54fa7ee6a440c73b']\")\n",
"\n",
"ind1 = Indicator(description=\"Crusades C2 implant 2\",\n",
" labels=[\"malicious-activity\"],\n",
" pattern=\"[file:hashes.'SHA-256' = '64c7e05e40a59511743635242e4a867c932140a999f52a1e54fa7ee6a440c73b']\")\n",
"\n",
"# add STIX object (threat-actor) to FileSystemStore\n",
"fs.add(ta)\n",
"\n",
"# can also add multiple STIX objects to FileSystemStore in one call\n",
"fs.add([ind, ind1])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### FileSystemSource - (if STIX content is only to be retrieved from FileSystem)"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{\n",
" \"type\": \"attack-pattern\",\n",
" \"id\": \"attack-pattern--00d0b012-8a03-410e-95de-5826bf542de6\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:30:54.176Z\",\n",
" \"modified\": \"2017-05-31T21:30:54.176Z\",\n",
" \"name\": \"Indicator Removal from Tools\",\n",
" \"description\": \"If a malicious...command-line parameters, Process monitoring\",\n",
" \"kill_chain_phases\": [\n",
" {\n",
" \"kill_chain_name\": \"mitre-attack\",\n",
" \"phase_name\": \"defense-evasion\"\n",
" }\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Technique/T1066\",\n",
" \"external_id\": \"T1066\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n"
]
}
],
"source": [
"from stix2 import FileSystemSource\n",
"\"\"\"\n",
"Working with FileSystemSource for retrieveing STIX content.\n",
"\"\"\"\n",
"\n",
"# create FileSystemSource\n",
"fs_source = FileSystemSource(\"/home/michael/Desktop/sample_stix2_data\")\n",
"\n",
"# retrieve STIX 2 objects\n",
"ap = fs_source.get(\"attack-pattern--00d0b012-8a03-410e-95de-5826bf542de6\")\n",
"\n",
"# for visual purposes\n",
"print(ap)"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--0f862b01-99da-47cc-9bdb-db4a86a95bb1\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:32:54.772Z\",\n",
" \"modified\": \"2017-05-31T21:32:54.772Z\",\n",
" \"name\": \"Emissary\",\n",
" \"description\": \"Emissary is a Trojan that has been used by Lotus Blossom. It shares code with Elise, with both Trojans being part of a malware group referred to as LStudio.[[Citation: Lotus Blossom Dec 2015]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0082\",\n",
" \"external_id\": \"S0082\"\n",
" },\n",
" {\n",
" \"source_name\": \"Lotus Blossom Dec 2015\",\n",
" \"description\": \"Falcone, R. and Miller-Osborn, J.. (2015, December 18). Attack on French Diplomat Linked to Operation Lotus Blossom. Retrieved February 15, 2016.\",\n",
" \"url\": \"http://researchcenter.paloaltonetworks.com/2015/12/attack-on-french-diplomat-linked-to-operation-lotus-blossom/\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n",
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--2a6f4c7b-e690-4cc7-ab6b-1f821fb6b80b\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:32:33.348Z\",\n",
" \"modified\": \"2017-05-31T21:32:33.348Z\",\n",
" \"name\": \"LOWBALL\",\n",
" \"description\": \"LOWBALL is malware used by admin@338. It was used in August 2015 in email messages targeting Hong Kong-based media organizations.[[Citation: FireEye admin@338]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0042\",\n",
" \"external_id\": \"S0042\"\n",
" },\n",
" {\n",
" \"source_name\": \"FireEye admin@338\",\n",
" \"description\": \"FireEye Threat Intelligence. (2015, December 1). China-based Cyber Threat Group Uses Dropbox for Malware Communications and Targets Hong Kong Media Outlets. Retrieved December 4, 2015.\",\n",
" \"url\": \"https://www.fireeye.com/blog/threat-research/2015/11/china-based-threat.html\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n",
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--00c3bfcb-99bd-4767-8c03-b08f585f5c8a\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:33:19.746Z\",\n",
" \"modified\": \"2017-05-31T21:33:19.746Z\",\n",
" \"name\": \"PowerDuke\",\n",
" \"description\": \"PowerDuke is a backdoor that was used by APT29 in 2016. It has primarily been delivered through Microsoft Word or Excel attachments containing malicious macros.[[Citation: Volexity PowerDuke November 2016]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0139\",\n",
" \"external_id\": \"S0139\"\n",
" },\n",
" {\n",
" \"source_name\": \"Volexity PowerDuke November 2016\",\n",
" \"description\": \"Adair, S.. (2016, November 9). PowerDuke: Widespread Post-Election Spear Phishing Campaigns Targeting Think Tanks and NGOs. Retrieved January 11, 2017.\",\n",
" \"url\": \"https://www.volexity.com/blog/2016/11/09/powerduke-post-election-spear-phishing-campaigns-targeting-think-tanks-and-ngos/\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n",
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--0db09158-6e48-4e7c-8ce7-2b10b9c0c039\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:32:55.126Z\",\n",
" \"modified\": \"2017-05-31T21:32:55.126Z\",\n",
" \"name\": \"Misdat\",\n",
" \"description\": \"Misdat is a backdoor that was used by Dust Storm from 2010 to 2011.[[Citation: Cylance Dust Storm]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0083\",\n",
" \"external_id\": \"S0083\"\n",
" },\n",
" {\n",
" \"source_name\": \"Cylance Dust Storm\",\n",
" \"description\": \"Gross, J. (2016, February 23). Operation Dust Storm. Retrieved February 25, 2016.\",\n",
" \"url\": \"https://www.cylance.com/hubfs/2015%20cylance%20website/assets/operation-dust-storm/Op%20Dust%20Storm%20Report.pdf?t=1456259131512\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n",
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--1d808f62-cf63-4063-9727-ff6132514c22\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:33:06.433Z\",\n",
" \"modified\": \"2017-05-31T21:33:06.433Z\",\n",
" \"name\": \"WEBC2\",\n",
" \"description\": \"WEBC2 is a backdoor used by APT1 to retrieve a Web page from a predetermined C2 server.[[Citation: Mandiant APT1 Appendix]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0109\",\n",
" \"external_id\": \"S0109\"\n",
" },\n",
" {\n",
" \"source_name\": \"Mandiant APT1 Appendix\",\n",
" \"description\": \"Mandiant. (n.d.). Appendix C (Digital) - The Malware Arsenal. Retrieved July 18, 2016.\",\n",
" \"url\": \"https://www.fireeye.com/content/dam/fireeye-www/services/pdfs/mandiant-apt1-report-appendix.zip\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n"
]
}
],
"source": [
"from stix2 import Filter\n",
"\n",
"# create filter for type=malware\n",
"query = [Filter(\"type\", \"=\", \"malware\")]\n",
"\n",
"# query on the filter\n",
"mals = fs_source.query(query)\n",
"\n",
"for mal in mals:\n",
" print(mal)"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{\n",
" \"type\": \"malware\",\n",
" \"id\": \"malware--00c3bfcb-99bd-4767-8c03-b08f585f5c8a\",\n",
" \"created_by_ref\": \"identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5\",\n",
" \"created\": \"2017-05-31T21:33:19.746Z\",\n",
" \"modified\": \"2017-05-31T21:33:19.746Z\",\n",
" \"name\": \"PowerDuke\",\n",
" \"description\": \"PowerDuke is a backdoor that was used by APT29 in 2016. It has primarily been delivered through Microsoft Word or Excel attachments containing malicious macros.[[Citation: Volexity PowerDuke November 2016]]\",\n",
" \"labels\": [\n",
" \"malware\"\n",
" ],\n",
" \"external_references\": [\n",
" {\n",
" \"source_name\": \"mitre-attack\",\n",
" \"url\": \"https://attack.mitre.org/wiki/Software/S0139\",\n",
" \"external_id\": \"S0139\"\n",
" },\n",
" {\n",
" \"source_name\": \"Volexity PowerDuke November 2016\",\n",
" \"description\": \"Adair, S.. (2016, November 9). PowerDuke: Widespread Post-Election Spear Phishing Campaigns Targeting Think Tanks and NGOs. Retrieved January 11, 2017.\",\n",
" \"url\": \"https://www.volexity.com/blog/2016/11/09/powerduke-post-election-spear-phishing-campaigns-targeting-think-tanks-and-ngos/\"\n",
" }\n",
" ],\n",
" \"object_marking_refs\": [\n",
" \"marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168\"\n",
" ]\n",
"}\n"
]
}
],
"source": [
"# add more filters to the query\n",
"query.append(Filter(\"modified\", \">\" , \"2017-05-31T21:33:10.772474Z\"))\n",
"\n",
"mals = fs_source.query(query)\n",
"\n",
"# for visual purposes\n",
"for mal in mals:\n",
" print(mal)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"#### FileSystemSink - (if STIX content is only to be pushed to FileSystem)"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"from stix2 import FileSystemSink, Campaign\n",
"\"\"\"\n",
"Working with FileSystemSink for pushing STIX content.\n",
"\"\"\"\n",
"# create FileSystemSink\n",
"fs_sink = FileSystemSink(\"/home/michael/Desktop/sample_stix2_data\")\n",
"\n",
"# create STIX objects and add to sink\n",
"camp = Campaign(name=\"The Crusades\",\n",
" objective=\"Infiltrating Israeli, Iranian and Palestinian digital infrastructure and government systems.\",\n",
" aliases=[\"Desert Moon\"])\n",
"\n",
"ind = Indicator(description=\"Crusades C2 implant\",\n",
" labels=[\"malicious-activity\"],\n",
" pattern=\"[file:hashes.'SHA-256' = '54b7e05e39a59428743635242e4a867c932140a999f52a1e54fa7ee6a440c73b']\")\n",
"\n",
"ind1 = Indicator(description=\"Crusades C2 implant\",\n",
" labels=[\"malicious-activity\"],\n",
" pattern=\"[file:hashes.'SHA-256' = '54b7e05e39a59428743635242e4a867c932140a999f52a1e54fa7ee6a440c73b']\")\n",
"\n",
"# add Campaign object to FileSystemSink\n",
"fs_sink.add(camp)\n",
"\n",
"# can also add STIX objects to FileSystemSink in on call\n",
"fs_sink.add([ind, ind1])"
]
}
],
"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.12"
}
},
"nbformat": 4,
"nbformat_minor": 2
}