Skip to content

Commit 283ef03

Browse files
Cyb3rWard0gCyb3rWard0g
committed
Improved attack_client INIT to load local STIX data
1 parent d6ad52d commit 283ef03

3 files changed

Lines changed: 205 additions & 33 deletions

File tree

‎attackcti/attack_api.py‎

Lines changed: 73 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
# https://github.com/oasis-open/cti-python-stix2/issues/183
1010
# https://stackoverflow.com/a/4406521
1111

12-
from stix2 import TAXIICollectionSource, Filter, CompositeDataSource, FileSystemSource
12+
from stix2 import TAXIICollectionSource, Filter, CompositeDataSource
1313
from stix2.datastore.filters import apply_common_filters
1414
from stix2.utils import get_type_from_id
1515
from stix2.v20.sdo import (
@@ -25,9 +25,10 @@
2525
import json
2626
import os
2727

28-
from .models import *
29-
from pydantic import TypeAdapter
28+
from pydantic import TypeAdapter, ValidationError
3029
from typing import List, Type, Dict, Any, Union
30+
from attackcti.models import *
31+
from attackcti.utils.storage import STIXStore
3132

3233
# os.environ['http_proxy'] = "http://xxxxxxx"
3334
# os.environ['https_proxy'] = "https://xxxxxxx"
@@ -37,18 +38,9 @@
3738
MOBILE_ATTACK = "2f669986-b40b-4423-b720-4396ca6a462b"
3839
ICS_ATTACK = "02c3ef24-9cd4-48f3-a99f-b74ce24f1d34"
3940

40-
ENTERPRISE_ATTACK_LOCAL_DIR = "enterprise-attack"
41-
MOBILE_ATTACK_LOCAL_DIR = "mobile-attack"
42-
ICS_ATTACK_LOCAL_DIR = "ics-attack"
43-
44-
class attack_client(object):
45-
"""A Python Module for ATT&CK"""
46-
TC_ENTERPRISE_SOURCE = None
47-
TC_PRE_SOURCE = None
48-
TC_MOBILE_SOURCE = None
49-
TC_ICS_SOURCE = None
50-
COMPOSITE_DS = None
51-
41+
class attack_client:
42+
"""A Python Module for accessing ATT&CK data locally or remotely."""
43+
5244
pydantic_model_mapping = {
5345
"techniques": Technique,
5446
"data-component": DataComponent,
@@ -72,30 +64,79 @@ class attack_client(object):
7264
"x-mitre-data-component": DataComponent
7365
}
7466

75-
def __init__(self, local_path=None, proxies=None, verify=True):
67+
def __init__(self, local_paths=None, proxies=None, verify=True):
7668
"""
69+
Initializes the ATT&CK client, setting up local or remote data sources.
70+
7771
Args:
78-
proxies - See https://requests.readthedocs.io/en/latest/user/advanced/#proxies
79-
verify - See https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification
72+
local_paths (dict, optional): Dictionary with paths to local directories or JSON files for each domain.
73+
Keys should be 'enterprise', 'mobile', and 'ics'.
74+
proxies (dict, optional): Dictionary mapping protocol or protocol and hostname to the URL of the proxy.
75+
verify (bool, optional): Whether to verify SSL certificates. Defaults to True.
8076
"""
77+
self.COMPOSITE_DS = CompositeDataSource()
8178

82-
if local_path is not None and os.path.isdir(os.path.join(local_path, ENTERPRISE_ATTACK_LOCAL_DIR)) \
83-
and os.path.isdir(os.path.join(local_path, MOBILE_ATTACK_LOCAL_DIR)) \
84-
and os.path.isdir(os.path.join(local_path, ICS_ATTACK_LOCAL_DIR)):
85-
self.TC_ENTERPRISE_SOURCE = FileSystemSource(os.path.join(local_path, ENTERPRISE_ATTACK_LOCAL_DIR))
86-
self.TC_MOBILE_SOURCE = FileSystemSource(os.path.join(local_path, MOBILE_ATTACK_LOCAL_DIR))
87-
self.TC_ICS_SOURCE = FileSystemSource(os.path.join(local_path, ICS_ATTACK_LOCAL_DIR))
88-
else:
89-
ENTERPRISE_COLLECTION = Collection(ATTACK_STIX_COLLECTIONS + ENTERPRISE_ATTACK + "/", verify=verify, proxies=proxies)
90-
MOBILE_COLLECTION = Collection(ATTACK_STIX_COLLECTIONS + MOBILE_ATTACK + "/", verify=verify, proxies=proxies)
91-
ICS_COLLECTION = Collection(ATTACK_STIX_COLLECTIONS + ICS_ATTACK + "/", verify=verify, proxies=proxies)
79+
# Validate local_paths with Pydantic
80+
if local_paths:
81+
try:
82+
self.local_paths = STIXLocalPaths(**local_paths)
83+
except ValidationError as e:
84+
raise ValueError(f"Invalid local_paths: {e}")
9285

93-
self.TC_ENTERPRISE_SOURCE = TAXIICollectionSource(ENTERPRISE_COLLECTION)
94-
self.TC_MOBILE_SOURCE = TAXIICollectionSource(MOBILE_COLLECTION)
95-
self.TC_ICS_SOURCE = TAXIICollectionSource(ICS_COLLECTION)
86+
# Initialize data sources
87+
self.init_data_sources(self.local_paths if local_paths else None, proxies, verify)
88+
89+
def init_data_sources(self, local_paths, proxies, verify):
90+
"""
91+
Initializes data sources, either local or remote.
92+
93+
Args:
94+
local_paths (LocalPathsModel, optional): Validated dictionary with paths to local directories or JSON files for each domain.
95+
proxies (dict, optional): Dictionary mapping protocol or protocol and hostname to the URL of the proxy.
96+
verify (bool, optional): Whether to verify SSL certificates. Defaults to True.
97+
"""
98+
if local_paths:
99+
self.TC_ENTERPRISE_SOURCE = self.load_stix_store(local_paths.enterprise)
100+
self.TC_MOBILE_SOURCE = self.load_stix_store(local_paths.mobile)
101+
self.TC_ICS_SOURCE = self.load_stix_store(local_paths.ics)
102+
103+
if not (self.TC_ENTERPRISE_SOURCE and self.TC_MOBILE_SOURCE and self.TC_ICS_SOURCE):
104+
self.initialize_taxii_sources(proxies, verify)
105+
else:
106+
self.initialize_taxii_sources(proxies, verify)
96107

97-
self.COMPOSITE_DS = CompositeDataSource()
98108
self.COMPOSITE_DS.add_data_sources([self.TC_ENTERPRISE_SOURCE, self.TC_MOBILE_SOURCE, self.TC_ICS_SOURCE])
109+
110+
def load_stix_store(self, path):
111+
"""
112+
Loads a STIXStore from the given path.
113+
114+
Args:
115+
path (str): Path to the source directory or JSON file.
116+
117+
Returns:
118+
The loaded STIXStore or None if the path is invalid.
119+
"""
120+
if path and os.path.exists(path):
121+
store = STIXStore(path)
122+
return store.get_store()
123+
return None
124+
125+
def initialize_taxii_sources(self, proxies, verify):
126+
"""
127+
Initializes data sources from the ATT&CK TAXII server.
128+
129+
Args:
130+
proxies (dict, optional): Dictionary mapping protocol or protocol and hostname to the URL of the proxy.
131+
verify (bool, optional): Whether to verify SSL certificates. Defaults to True.
132+
"""
133+
ENTERPRISE_COLLECTION = Collection(ATTACK_STIX_COLLECTIONS + ENTERPRISE_ATTACK + "/", verify=verify, proxies=proxies)
134+
MOBILE_COLLECTION = Collection(ATTACK_STIX_COLLECTIONS + MOBILE_ATTACK + "/", verify=verify, proxies=proxies)
135+
ICS_COLLECTION = Collection(ATTACK_STIX_COLLECTIONS + ICS_ATTACK + "/", verify=verify, proxies=proxies)
136+
137+
self.TC_ENTERPRISE_SOURCE = TAXIICollectionSource(ENTERPRISE_COLLECTION)
138+
self.TC_MOBILE_SOURCE = TAXIICollectionSource(MOBILE_COLLECTION)
139+
self.TC_ICS_SOURCE = TAXIICollectionSource(ICS_COLLECTION)
99140

100141
def get_stix_objects(
101142
self,

‎attackcti/models.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,4 +191,9 @@ def extract_phase_name(cls, values: Dict[str, Any]):
191191
kill_chain_phases = values['tactic']
192192
phase_names = [phase['phase_name'] for phase in kill_chain_phases if 'phase_name' in phase]
193193
values['tactic'] = phase_names
194-
return values
194+
return values
195+
196+
class STIXLocalPaths(BaseModel):
197+
enterprise: Optional[str] = Field(None, description="Path to the local enterprise-attack directory or JSON file.")
198+
mobile: Optional[str] = Field(None, description="Path to the local mobile-attack directory or JSON file.")
199+
ics: Optional[str] = Field(None, description="Path to the local ics-attack directory or JSON file.")

‎docs/playground/11-Initialize_Client_Local_STIX_data.ipynb‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Initialize ATTACK Client with Local STIX Data"
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"## Local JSON Files"
15+
]
16+
},
17+
{
18+
"cell_type": "code",
19+
"execution_count": 2,
20+
"metadata": {},
21+
"outputs": [],
22+
"source": [
23+
"local_paths = {\n",
24+
" 'enterprise': 'downloads/v15.1/enterprise-attack.json',\n",
25+
" 'mobile': 'downloads/v15.1/mobile-attack.json',\n",
26+
" 'ics': 'downloads/v15.1/ics-attack.json'\n",
27+
"}"
28+
]
29+
},
30+
{
31+
"cell_type": "markdown",
32+
"metadata": {},
33+
"source": [
34+
"## Initialize ATTACK Client"
35+
]
36+
},
37+
{
38+
"cell_type": "code",
39+
"execution_count": 3,
40+
"metadata": {},
41+
"outputs": [],
42+
"source": [
43+
"from attackcti import attack_client"
44+
]
45+
},
46+
{
47+
"cell_type": "code",
48+
"execution_count": 4,
49+
"metadata": {},
50+
"outputs": [],
51+
"source": [
52+
"lift = attack_client(local_paths=local_paths)"
53+
]
54+
},
55+
{
56+
"cell_type": "code",
57+
"execution_count": 5,
58+
"metadata": {},
59+
"outputs": [],
60+
"source": [
61+
"enterprise_techniques = lift.get_enterprise_techniques()"
62+
]
63+
},
64+
{
65+
"cell_type": "code",
66+
"execution_count": 6,
67+
"metadata": {},
68+
"outputs": [
69+
{
70+
"data": {
71+
"text/plain": [
72+
"637"
73+
]
74+
},
75+
"execution_count": 6,
76+
"metadata": {},
77+
"output_type": "execute_result"
78+
}
79+
],
80+
"source": [
81+
"len(enterprise_techniques)"
82+
]
83+
},
84+
{
85+
"cell_type": "code",
86+
"execution_count": 7,
87+
"metadata": {},
88+
"outputs": [
89+
{
90+
"data": {
91+
"text/plain": [
92+
"AttackPattern(type='attack-pattern', id='attack-pattern--005a06c6-14bf-4118-afa0-ebcd8aebb0c9', created_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', created='2019-11-27T14:58:00.429Z', modified='2023-11-15T14:33:53.354Z', name='Scheduled Task', description='Adversaries may abuse the Windows Task Scheduler to perform task scheduling for initial or recurring execution of malicious code. There are multiple ways to access the Task Scheduler in Windows. The [schtasks](https://attack.mitre.org/software/S0111) utility can be run directly on the command line, or the Task Scheduler can be opened through the GUI within the Administrator Tools section of the Control Panel. In some cases, adversaries have used a .NET wrapper for the Windows Task Scheduler, and alternatively, adversaries have used the Windows netapi32 library to create a scheduled task.\\n\\nThe deprecated [at](https://attack.mitre.org/software/S0110) utility could also be abused by adversaries (ex: [At](https://attack.mitre.org/techniques/T1053/002)), though <code>at.exe</code> can not access tasks created with <code>schtasks</code> or the Control Panel.\\n\\nAn adversary may use Windows Task Scheduler to execute programs at system startup or on a scheduled basis for persistence. The Windows Task Scheduler can also be abused to conduct remote Execution as part of Lateral Movement and/or to run a process under the context of a specified account (such as SYSTEM). Similar to [System Binary Proxy Execution](https://attack.mitre.org/techniques/T1218), adversaries have also abused the Windows Task Scheduler to potentially mask one-time execution under signed/trusted system processes.(Citation: ProofPoint Serpent)\\n\\nAdversaries may also create \"hidden\" scheduled tasks (i.e. [Hide Artifacts](https://attack.mitre.org/techniques/T1564)) that may not be visible to defender tools and manual queries used to enumerate tasks. Specifically, an adversary may hide a task from `schtasks /query` and the Task Scheduler by deleting the associated Security Descriptor (SD) registry value (where deletion of this value must be completed using SYSTEM permissions).(Citation: SigmaHQ)(Citation: Tarrask scheduled task) Adversaries may also employ alternate methods to hide tasks, such as altering the metadata (e.g., `Index` value) within associated registry keys.(Citation: Defending Against Scheduled Task Attacks in Windows Environments) ', kill_chain_phases=[KillChainPhase(kill_chain_name='mitre-attack', phase_name='execution'), KillChainPhase(kill_chain_name='mitre-attack', phase_name='persistence'), KillChainPhase(kill_chain_name='mitre-attack', phase_name='privilege-escalation')], revoked=False, external_references=[ExternalReference(source_name='mitre-attack', url='https://attack.mitre.org/techniques/T1053/005', external_id='T1053.005'), ExternalReference(source_name='ProofPoint Serpent', description='Campbell, B. et al. (2022, March 21). Serpent, No Swiping! New Backdoor Targets French Entities with Unique Attack Chain. Retrieved April 11, 2022.', url='https://www.proofpoint.com/us/blog/threat-insight/serpent-no-swiping-new-backdoor-targets-french-entities-unique-attack-chain'), ExternalReference(source_name='Defending Against Scheduled Task Attacks in Windows Environments', description='Harshal Tupsamudre. (2022, June 20). Defending Against Scheduled Tasks. Retrieved July 5, 2022.', url='https://blog.qualys.com/vulnerabilities-threat-research/2022/06/20/defending-against-scheduled-task-attacks-in-windows-environments'), ExternalReference(source_name='Twitter Leoloobeek Scheduled Task', description='Loobeek, L. (2017, December 8). leoloobeek Status. Retrieved December 12, 2017.', url='https://twitter.com/leoloobeek/status/939248813465853953'), ExternalReference(source_name='Tarrask scheduled task', description='Microsoft Threat Intelligence Team & Detection and Response Team . (2022, April 12). Tarrask malware uses scheduled tasks for defense evasion. Retrieved June 1, 2022.', url='https://www.microsoft.com/security/blog/2022/04/12/tarrask-malware-uses-scheduled-tasks-for-defense-evasion/'), ExternalReference(source_name='Microsoft Scheduled Task Events Win10', description='Microsoft. (2017, May 28). Audit Other Object Access Events. Retrieved June 27, 2019.', url='https://docs.microsoft.com/en-us/windows/security/threat-protection/auditing/audit-other-object-access-events'), ExternalReference(source_name='TechNet Scheduled Task Events', description='Microsoft. (n.d.). General Task Registration. Retrieved December 12, 2017.', url='https://technet.microsoft.com/library/dd315590.aspx'), ExternalReference(source_name='TechNet Autoruns', description='Russinovich, M. (2016, January 4). Autoruns for Windows v13.51. Retrieved June 6, 2016.', url='https://technet.microsoft.com/en-us/sysinternals/bb963902'), ExternalReference(source_name='TechNet Forum Scheduled Task Operational Setting', description='Satyajit321. (2015, November 3). Scheduled Tasks History Retention settings. Retrieved December 12, 2017.', url='https://social.technet.microsoft.com/Forums/en-US/e5bca729-52e7-4fcb-ba12-3225c564674c/scheduled-tasks-history-retention-settings?forum=winserver8gen'), ExternalReference(source_name='SigmaHQ', description='Sittikorn S. (2022, April 15). Removal Of SD Value to Hide Schedule Task - Registry. Retrieved June 1, 2022.', url='https://github.com/SigmaHQ/sigma/blob/master/rules/windows/registry/registry_delete/registry_delete_schtasks_hide_task_via_sd_value_removal.yml')], object_marking_refs=['marking-definition--fa42a846-8d90-4e51-bc29-71d5b4802168'], x_mitre_attack_spec_version='3.2.0', x_mitre_contributors=['Andrew Northern, @ex_raritas', 'Bryan Campbell, @bry_campbell', 'Zachary Abzug, @ZackDoesML', 'Selena Larson, @selenalarson', 'Sittikorn Sangrattanapitak'], x_mitre_data_sources=['Windows Registry: Windows Registry Key Creation', 'File: File Modification', 'File: File Creation', 'Process: Process Creation', 'Command: Command Execution', 'Network Traffic: Network Traffic Flow', 'Scheduled Job: Scheduled Job Creation'], x_mitre_deprecated=False, x_mitre_detection='Monitor process execution from the <code>svchost.exe</code> in Windows 10 and the Windows Task Scheduler <code>taskeng.exe</code> for older versions of Windows. (Citation: Twitter Leoloobeek Scheduled Task) If scheduled tasks are not used for persistence, then the adversary is likely to remove the task when the action is complete. Monitor Windows Task Scheduler stores in %systemroot%\\\\System32\\\\Tasks for change entries related to scheduled tasks that do not correlate with known software, patch cycles, etc.\\n\\nConfigure event logging for scheduled task creation and changes by enabling the \"Microsoft-Windows-TaskScheduler/Operational\" setting within the event logging service. (Citation: TechNet Forum Scheduled Task Operational Setting) Several events will then be logged on scheduled task activity, including: (Citation: TechNet Scheduled Task Events)(Citation: Microsoft Scheduled Task Events Win10)\\n\\n* Event ID 106 on Windows 7, Server 2008 R2 - Scheduled task registered\\n* Event ID 140 on Windows 7, Server 2008 R2 / 4702 on Windows 10, Server 2016 - Scheduled task updated\\n* Event ID 141 on Windows 7, Server 2008 R2 / 4699 on Windows 10, Server 2016 - Scheduled task deleted\\n* Event ID 4698 on Windows 10, Server 2016 - Scheduled task created\\n* Event ID 4700 on Windows 10, Server 2016 - Scheduled task enabled\\n* Event ID 4701 on Windows 10, Server 2016 - Scheduled task disabled\\n\\nTools such as Sysinternals Autoruns may also be used to detect system changes that could be attempts at persistence, including listing current scheduled tasks. (Citation: TechNet Autoruns)\\n\\nRemote access tools with built-in features may interact directly with the Windows API to perform these functions outside of typical system utilities. Tasks may also be created through Windows system management tools such as Windows Management Instrumentation and PowerShell, so additional logging may need to be configured to gather the appropriate data.', x_mitre_domains=['enterprise-attack'], x_mitre_is_subtechnique=True, x_mitre_modified_by_ref='identity--c78cb6e5-0c4b-4611-8297-d1b8b55e40b5', x_mitre_permissions_required=['Administrator'], x_mitre_platforms=['Windows'], x_mitre_remote_support=True, x_mitre_version='1.5')"
93+
]
94+
},
95+
"execution_count": 7,
96+
"metadata": {},
97+
"output_type": "execute_result"
98+
}
99+
],
100+
"source": [
101+
"enterprise_techniques[1]"
102+
]
103+
}
104+
],
105+
"metadata": {
106+
"kernelspec": {
107+
"display_name": "Python 3",
108+
"language": "python",
109+
"name": "python3"
110+
},
111+
"language_info": {
112+
"codemirror_mode": {
113+
"name": "ipython",
114+
"version": 3
115+
},
116+
"file_extension": ".py",
117+
"mimetype": "text/x-python",
118+
"name": "python",
119+
"nbconvert_exporter": "python",
120+
"pygments_lexer": "ipython3",
121+
"version": "3.12.1"
122+
}
123+
},
124+
"nbformat": 4,
125+
"nbformat_minor": 2
126+
}

0 commit comments

Comments
 (0)