Clean Up

Finished methodology verbiage, changed images to match template colors, deleted unnecessary images
center-for-threat-informed-defense · Oct 17, 2023 · 9fc224f · 9fc224f
1 parent 117ac96
commit 9fc224f
Show file tree

Hide file tree

Showing 38 changed files with 182 additions and 44 deletions.
diff --git a/docs/SENSORMAPPING.xlsx → SENSORMAPPING.xlsx b/docs/SENSORMAPPING.xlsx → SENSORMAPPING.xlsx
diff --git a/docs/Acknowledgements.rst b/docs/Acknowledgements.rst
@@ -0,0 +1,13 @@
+Acknowledgements
+================
+
+The Sensor Mappings project team includes:
+
+* Tiffany Bergeron
+* Misha Belisle
+* Eric Lorenz
+* Mark Perry
+* Cristina Padro
+* Robert Schull
+* Lex Crumpton
+* Tiffany Lee
diff --git a/docs/Changelog b/docs/Changelog
@@ -0,0 +1,10 @@
+Changelog
+=========
+
+Sensor Mappings to ATT&CK 1.0
+-------------------------
+
+1.0.0 -- December 14, 2023
+
+    The initial release of Sensor Mappings to ATT&CK includes the model, methodology,
+    definitions, and worked examples.
diff --git a/docs/Changelog.rst b/docs/Changelog.rst
@@ -0,0 +1,10 @@
+Changelog
+=========
+
+Sensor Mappings to ATT&CK 1.0
+-----------------------------
+
+1.0.0 -- December 14, 2023
+
+    The initial release of Sensor Mappings to ATT&CK includes the model, methodology,
+    definitions, and worked examples.
diff --git a/docs/Example-Technique-Mappings.rst b/docs/Example-Technique-Mappings.rst
@@ -0,0 +1,41 @@
+Example Scenarios
+==========================
+
+As we worked through some of the event IDs to ATT&CK data source mappings, we found that not all events are created equal in regards to detecting ATT&CK techniques. Two events with the same field names can represent different data.  
+
+For example, both T1134: Access Token Manipulation and T1543: Create or Modify System Process include Process Creation. However, through our list of mappings, process creation includes Sysmon 1, WinEvtx 4688, and WinEvtx 4696. As we moved through research, our first assumption was that Sysmon 1 and WinEvtx 4688 will potentially detect T1543 but WinEvtx 4696 can be an additional detection for T1134. 
+
+So below we go through some examples of why certain Events work to detect certain ATT&CK techniques.
+
+
+Windows
+-------
+
+T1543 Create or Modify System Process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Our first scenario is to look into why WinEvtx 4696 is not a feasible detection for T1543: Create or Modify System Process. 
+
+.. image:: _static/WinEx2.png
+   :width: 700
+
+We start by asking ourselves, "**is there enough proof or evidence to say this system process was created or modified?**"
+
+
+`Sysmon EID 1 <https://www.ultimatewindowssecurity.com/securitylog/encyclopedia/event.aspx?eventid=90001>`_ was a resounding "**Yes**". Sysmon EID 1 simply triggers when a new process is created, which (in this context) may be created during installation of new software or as part of automated, repeated execution of software such as services. This event's attributes provides very detailed information about the process and the process execution, which is enough to indicate that this technique could have occurred.
+
+`WinEvtx EID 4688 <https://learn.microsoft.com/en-us/windows/security/threat-protection/auditing/event-4688>`_
+was a resounding "**Yes**". When a system process or a user opens an executable, Windows creates a process in which that executable runs. Hence, this event is generated every time a program is started or executed. All necessary details about the executed program, who the program ran as, and the process that started the process is provided by the event, which is enough evidence to indicate that this technique could have occurred.
+
+`WinEvtx EID 4696 <https://learn.microsoft.com/en-us/windows/security/threat-protection/auditing/event-4696>`_
+was a "**Yes with a Caveat**". A primary token is an access token that is typically created only by the Windows kernel and is assigned to a process to represent the default security information for that process. This primary token is assigned to a process when the process is created, which is why this event falls under process creation. This event, however, will only be generated when a process (usually a service or a scheduled task) starts under the authority of a different user than the user who created the process. In other words, this event triggers every time a process runs using the non-current access token by changing the "Token Elevation Type", enforced by Window's User Account Control (UAC). 
+
+**Caveat**: This event doesn’t generate when the process starts with the authority of the same user that created the process. For example, if a user with a "limited" (token with decreased privilege) Token Elevation Type (i.e., 3) creates a new process also with a "limited" Token Elevation Type, this event will not be generated. 
+
+Type 3 is the normal value when UAC is enabled and a user simply starts a program from the Start Menu. It's a limited token with administrative privileges removed and administrative groups disabled. The limited token is used when User Account Control is enabled, the application does not require administrative privilege, and the user does not choose to start the program using Run as administrator.
+
+So, not only is all the information needed for the creation of the system process in WinEvtx 4688, including the primary token. But also WinEvtx is deprecated starting from Windows 7 and Windows 2008 R2.
+
+
+
+
diff --git a/docs/Future-Work.rst b/docs/Future-Work.rst
@@ -7,12 +7,4 @@ Sensor Mappings to ATT&CK project is planning to look at other areas of research
 - Event ID mappings to Vendor Sensors
 - Additional Sensors within the Windows, Linux, MacOS, Network, and Cloud platform
 
-Note: Pay attention to the differences between similar data sources and events. Two events with the same field names can represent different data. For example, process data collected from Sysmon 1, Windows Event 4688, and/or Windows Event 4696 could provide visibility into behaviors associated with T1134: Access Token Manipulation. But when looking for T1543: Create or Modify System Process, data should not be collected from Windows Event 4696 to prove adversary activity as this technique does not involve the use of system tokens. The following visuals are provided to help illustrate this example:
-
-.. image:: _static/T1543EX.png
-   :width: 600
-
-.. image:: _static/T1134EX.png
-   :width: 600
-
 If you have any thoughts to future areas of research, please submit a `GitHub Issue <https://github.com/center-for-threat-informed-defense/sensor-mappings-to-attack/issues>`_
diff --git a/docs/_static/WELEX.png → docs/_static/4688_Ex.png b/docs/_static/WELEX.png → docs/_static/4688_Ex.png
diff --git a/docs/_static/PCEX.png → docs/_static/ATTACK_Ex_PC.png b/docs/_static/PCEX.png → docs/_static/ATTACK_Ex_PC.png
diff --git a/docs/_static/DE1.png b/docs/_static/DE1.png
diff --git a/docs/_static/DE2.png b/docs/_static/DE2.png
diff --git a/docs/_static/DE3.png b/docs/_static/DE3.png
diff --git a/docs/_static/DE4.png b/docs/_static/DE4.png
diff --git a/docs/_static/DE5.png b/docs/_static/DE5.png
diff --git a/docs/_static/DEF1.png b/docs/_static/DEF1.png
diff --git a/docs/_static/DEF2.png b/docs/_static/DEF2.png
diff --git a/docs/_static/DEF3.png b/docs/_static/DEF3.png
diff --git a/docs/_static/DataElement_Ex.png b/docs/_static/DataElement_Ex.png
diff --git a/docs/_static/DefinitionCorrelation_Ex.png b/docs/_static/DefinitionCorrelation_Ex.png
diff --git a/docs/_static/WELEX2.png → docs/_static/MSDN_4688_Ex.png b/docs/_static/WELEX2.png → docs/_static/MSDN_4688_Ex.png
diff --git a/docs/_static/WELEX4.png → docs/_static/MSDN_4688_Ex_Attributes.png b/docs/_static/WELEX4.png → docs/_static/MSDN_4688_Ex_Attributes.png
diff --git a/docs/_static/PDS.png b/docs/_static/PDS.png
diff --git a/docs/_static/RDE1.png b/docs/_static/RDE1.png
diff --git a/docs/_static/RDE3.png b/docs/_static/RDE3.png
diff --git a/docs/_static/RDE4.png b/docs/_static/RDE4.png
diff --git a/docs/_static/RDE5.png b/docs/_static/RDE5.png
diff --git a/docs/_static/Relationship_Ex.png b/docs/_static/Relationship_Ex.png
diff --git a/docs/_static/T1134EX.png b/docs/_static/T1134EX.png
diff --git a/docs/_static/T1543EX.png b/docs/_static/T1543EX.png
diff --git a/docs/_static/WELEX3.png b/docs/_static/WELEX3.png
diff --git a/docs/_static/WSE.png b/docs/_static/WSE.png
diff --git a/docs/_static/WinEx2.png b/docs/_static/WinEx2.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -34,6 +34,8 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinxcontrib.excel_table",
+    # "sphinxawesome_theme",
+    # "sphinx-design",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/definitions.rst b/docs/definitions.rst
@@ -31,7 +31,7 @@ Data Elements
 -------------
 Names, definitions, and attributes that are being used or captured in an event
 
-.. image:: _static/WELEX3.png
+.. image:: _static/MSDN_4688_Ex.png
    :width: 500
 
 Sensors
@@ -42,5 +42,5 @@ Telemetry/Events
 ----------------
 Generated by sensors in the form of log data, regardless of the format (e.g., json, csv, etc.), as long as the data is automatically generated and transmitted or streamed in near real-time
 
-.. image:: _static/WELEX.png
+.. image:: _static/4688_Ex.png
    :width: 500
diff --git a/docs/index.rst b/docs/index.rst
@@ -23,8 +23,11 @@ threat-informed decisions.
     definitions
     methodology/index
     levels/index
+    Example-Technique-Mappings
     use_cases
     Future-Work
+    Changelog
+    Acknowledgements
 
 Notice
 ------

diff --git a/docs/methodology/step2.rst b/docs/methodology/step2.rst
@@ -17,7 +17,7 @@ Think about the questions below for additional context on potential source of th
 
 Let's take a look at Windows `Event ID 4688 <https://learn.microsoft.com/en-us/windows/security/threat-protection/auditing/event-4688>`_. Because this is a Microsoft tool, we can go straight to their website to get addition context on what this event does. By the event description, 4688 is generated every time a new process starts. We can also see within the information provided by this event the user account that requested the creation of the process, and information of a process that executed a new process. This event also provides metadata that can help us to describe the data elements needed in Step 3 later on in the methodology process.
 
-.. image:: ../_static/WELEX2.png
+.. image:: ../_static/MSDN_4688_Ex.png
    :width: 600
 
 - The action that triggered the generation of this event was the creation of a new process (Activity). 
@@ -27,12 +27,12 @@ Correlate to ATT&CK Data Component Defintion
 --------------------------------------------
 In correlation to ATT&CK, when you go to the `Data Source <https://attack.mitre.org/datasources/>`_ pages you can see definitions for a given one. 
 
-.. image:: ../_static/PCEX.png
+.. image:: ../_static/ATTACK_Ex_PC.png
    :width: 600
 
 ATT&CK's definition of process creation is : **..the initial construction of an executable..** through keyword analysis, this turns out to be the same as **..a process is created..** Therefore we can comfortably link event ID 4688 with ATT&CK Data Component. 
 
 Lets look at Sysmon EID 1, Sysmon EID 8, WinEvtx 4688, and WinEvtx 4696. The image below shows that the definition all have some correlation with either starting or executing a process. 
 
-.. image:: ../_static/DEF3.png
+.. image:: ../_static/DefinitionCorrelation_Ex.png
    :width: 700
diff --git a/docs/methodology/step3.rst b/docs/methodology/step3.rst
@@ -8,47 +8,32 @@ Next in reviewing the event ID, **identify the data element**. Once we identify
 
 As we mentioned in Step 2, `Event ID 4688 <https://learn.microsoft.com/en-us/windows/security/threat-protection/auditing/event-4688>`_ also provides attributes that can help us to describe the data elements needed. For instance, regarding the user account data element, we have information of its logon id and the domain it belongs to. 
 
-.. image:: ../_static/WELEX4.png
+.. image:: ../_static/MSDN_4688_Ex_Attributes.png
    :width: 600
 
-The use of Data Elements help to understand key attributes that are related to the adversary behavior. For example, if an adversary modifies a Windows Registry value, collection of Windows Registry telemetry is needed. **How the adversary modified the registry, such as the process or user that performed the action**, is how we pinpoint the data elements. Below continuing on with our process example. As we think about how an adversary can create a process we are left with process, user, command, and thread. 
+The use of Data Elements help to understand key attributes that are related to the adversary behavior. For example, if an adversary modifies a Windows Registry value, collection of Windows Registry telemetry is needed. 
 
-.. image:: ../_static/DE3.png
-   :width: 700
-
-Additional questions to ask yourself is: 
+Think about the questions below for additional context on how to establish data elements.
 
-- What are the main data objects to collect data from?
-- What are all the data objects that define the context of the data source?
-- What are some attributes from the event log that contributes to the activity of the adversary behavior?
+- *How is the adversary conducting a behavior?*
+- *What are all the data objects that define the context of the data source?*
+- *What are some attributes from the event log that contributes to the activity of the adversary behavior?*
 
-This method can also be used to provide a general idea of what is needed to be collected. For example, data elements that provide metadata about network traffic can be grouped together and be associated with Netflow.
-
-.. image:: ../_static/DE2.png
-   :width: 600
-
-The image below displays how we can extend the concept of an event log and capture the data elements featured within it. 
-
-.. image:: ../_static/DE5.png
-   :width: 600
+.. image:: ../_static/DataElement_Ex.png
+   :width: 700
 
+This method can also be used to provide a general idea of what is needed to be collected. 
 
-There is a fundamental rule that should be considered when defining: **there is no one correct way to define data elements**. Please look to your organizational needs to help define what data elements means to you.
+Note: There is a fundamental rule that should be considered when defining: **there is no one correct way to define data elements**. Please look to your organizational needs to help define what data elements means to you.
 
 Identify Relationships among Data Elements
 ------------------------------------------
 
-By documenting the event collection, source (creation of a new process), and data elements (user account and process), we can start describing **interactions among elements through relationships**. Relationships in ATT&CK have been categorized between *activity* and *information*. Activity relationships are the ones that make references to the action that triggered the generation of the event. Informational relationships are the ones defined based on the metadata provided by the event. 
-
-.. image:: ../_static/RDE1.png
-   :width: 600
-
-As the groupings grow, the similarities appear where different platforms or sensors tend to link to the same ATT&CK Data Source. 
+By documenting the event collection, source (creation of a new process), and data elements (user account and process), we can start describing **interactions among elements through relationships**. 
 
-.. image:: ../_static/RDE4.png
-   :width: 600
+Note: Relationships in ATT&CK have been categorized between *activity* and *information*. Activity relationships are the ones that make references to the action that triggered the generation of the event. Informational relationships are the ones defined based on the metadata provided by the event. Therefore, please be aware of alternative data elements (i.e. a thread can create a process).
 
-As discussed by `OSSEM <https://github.com/OTRF/OSSEM>`_ at their ATT&CKcon 2018 and 2019 presentation. The activity of the relationship leads to Data Components. Data Components will help us to categorize relationships among data elements based on the security context they describe (i.e. Creation, Execution, Deletion). 
+.. image:: ../_static/Relationship_Ex.png
+   :width: 700
 
-.. image:: ../_static/RDE5.png
-   :width: 700   
+As discussed by `OSSEM <https://github.com/OTRF/OSSEM>`_ at their ATT&CKcon 2018 and 2019 presentation. The activity of the relationship leads to Data Components. Data Components will help us to categorize relationships among data elements based on the security context they describe (i.e. Creation, Execution, Deletion).   
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -11,6 +11,8 @@ packages = []
 python = "^3.8"
 pytz = "^2023.3"
 sphinxcontrib-excel-table = "^1.0.8"
+sphinx-panels = "^0.6.0"
+sphinxawesome-theme = "^4.1.0"
 
 
 [tool.poetry.group.dev.dependencies]