Updated docs (#11)

* Updated docs * Update use_cases.rst * Use cases and methodology updates * Documentation updates * Fix document references * Fixed bullet points * Fixed step2 bulleted list * Update use cases * Documentation updates Sensor Mapping and Example Scenarios * Updated example scenario link names * Change caps to lowercase * Updated overview bullet list * Addressed build errors * Update lowercase filenames --------- Co-authored-by: Mark E. Haase <[email protected]>
center-for-threat-informed-defense · Nov 22, 2023 · 4ed2eb9 · 4ed2eb9
1 parent 6815214
commit 4ed2eb9
Show file tree

Hide file tree

Showing 48 changed files with 685 additions and 189 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # Sensor Mappings to ATT&CK
 
-Sensor Mappings to ATT&CK (SMTA) is a Center for Threat-Informed Defense (Center) project that
+Sensor Mappings to ATT&CK (SMAP) is a Center for Threat-Informed Defense (Center) project that
 assists security operations teams and security leaders understand which tools, capabilities, and
-events can help detect real-world adversary TTPs in their environments. SMTA builds on [MITRE ATT&CK®](https://attack.mitre.org/)
+events can help detect real-world adversary TTPs in their environments. SMAP builds on [MITRE ATT&CK®](https://attack.mitre.org/)
 Data Sources by connecting the conceptual data source representions of information that can be collected 
 to concrete logs, sensors, and other security capabilities that provide that type of data. This work complements
 the Center's [Security Stack Mappings](https://github.com/center-for-threat-informed-defense/security-stack-mappings) project by allowing defenders to use both resources to understand their overall defensive coverage and make threat-informed decisions.  
@@ -21,29 +21,32 @@ the Center's [Security Stack Mappings](https://github.com/center-for-threat-info
 <!-- TODO Write one paragraph about how users should get started,
      and update the table of resources below. -->
 
-This scope of this project includes mappings to ATT&CK Data Sources from:
+The scope of this project includes mappings to ATT&CK Data Sources from Host Sensors, which 
+gather data from endpoints in the environment (e.g., Windows, Linux), and Network Sensors, 
+which gather data gather from network communications, typically outbound connections. 
+The specific sensors mapped are:
 - Sysmon (all events) 
 - Windows Event Log (security-relevant events) 
 - Auditd 
 - CloudTrail 
 - OSQuery
 - ZEEK
 
-The mapping structure, methodology, and scenarios are fully described in [the project website](https://center-for-threat-informed-defense.github.io/sensor-mappings-to-attack/).
+The mapping structure, methodology, and usage are fully described in [the project website](https://center-for-threat-informed-defense.github.io/sensor-mappings-to-attack/).
 
-| Resource                     | Description                                    |
-| ---------------------------- | ---------------------------------------------- |
-| [Project Website](#)         | Documentation, methodology, and use cases.     |
-| [Mappings](#)                | In-scope sensors mapped to ATT&CK.             |
-| [ATT&CK Navigator Layers](#) | ATT&CK Navigator layers for the SMTA mappings. |
+| Resource                     | Description                                          |
+| ---------------------------- | ---------------------------------------------------- |
+| [Project Website](#)         | Documentation, methodology, use cases, examples.     |
+| [Mappings](#)                | In-scope sensors mapped to ATT&CK.                   |
+| [ATT&CK Navigator View](#)   | ATT&CK Navigator view of the SMAP mappings.          |
 
 ## Getting Involved
 
 There are several ways that you can get involved with this project and help advance
 threat-informed defense.
 
 Please review the mappings, use them, and tell us what you think. We welcome your review
-and feedback on the SMTA mappings, our methodology, and other resources.
+and feedback on the SMAP mappings, our methodology, and other resources.
 
 We are interested developing additional tools and resources to help the community
 understand and make threat-informed decisions in their risk management programs. Share
@@ -54,7 +57,7 @@ your ideas and we will consider them as we explore additional research projects.
 Please submit [issues](https://github.com/center-for-threat-informed-defense/sensor-mappings-to-attack/issues) for any technical questions/concerns
 or contact [[email protected]](mailto:[email protected]?subject=subject=Question%20about%20sensor-mappings-to-attack) directly for more general inquiries.
 
-We welcome your feedback and contributions to help advance SMTA. Please see the guidance for 
+We welcome your feedback and contributions to help advance SMAP. Please see the guidance for 
 contributors if are you interested in [contributing or simply reporting issues.](/CONTRIBUTING.md)
 
 ## Notice

diff --git a/docs/_static/4688_Ex.png → docs/_static/4688_ex.png b/docs/_static/4688_Ex.png → docs/_static/4688_ex.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/Relationship_Ex.png b/docs/_static/Relationship_Ex.png
diff --git a/docs/_static/WinEx2.png b/docs/_static/WinEx2.png
diff --git a/docs/_static/ATTACK_Ex_PC.png → docs/_static/attack_ex_pc.png b/docs/_static/ATTACK_Ex_PC.png → docs/_static/attack_ex_pc.png
diff --git a/docs/_static/build_sensor_mappings.png b/docs/_static/build_sensor_mappings.png
diff --git a/docs/_static/cldtrlex1.png b/docs/_static/cldtrlex1.png
diff --git a/docs/_static/cldtrlex2.png b/docs/_static/cldtrlex2.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/gaps.png b/docs/_static/gaps.png
diff --git a/docs/_static/linuxex1.png b/docs/_static/linuxex1.png
diff --git a/docs/_static/methodology.png b/docs/_static/methodology.png
diff --git a/docs/_static/MSDN_4688_Ex.png → docs/_static/msdn_4688_ex.png b/docs/_static/MSDN_4688_Ex.png → docs/_static/msdn_4688_ex.png
diff --git a/docs/_static/MSDN_4688_Ex_Attributes.png → docs/_static/msdn_4688_ex_attributes.png b/docs/_static/MSDN_4688_Ex_Attributes.png → docs/_static/msdn_4688_ex_attributes.png
diff --git a/docs/_static/networkex1.png b/docs/_static/networkex1.png
diff --git a/docs/_static/relationship_ex.png b/docs/_static/relationship_ex.png
diff --git a/docs/_static/sensors.png b/docs/_static/sensors.png
diff --git a/docs/_static/threats.png b/docs/_static/threats.png
diff --git a/docs/_static/visibility.png b/docs/_static/visibility.png
diff --git a/docs/_static/winex1.png b/docs/_static/winex1.png
diff --git a/docs/_static/winex2.png b/docs/_static/winex2.png
diff --git a/docs/acknowledgements.rst b/docs/acknowledgements.rst
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -7,4 +7,4 @@ 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.
+    mappings, and worked examples.
diff --git a/docs/definitions.rst b/docs/definitions.rst
@@ -1,46 +1,44 @@
 Definitions
 ===========
 
-This page defines the key terms used throughout our research. 
+This page defines the key terms used throughout our research.
 
-MITRE ATT&CK 
+MITRE ATT&CK
 ------------
 MITRE ATT&CK® is a globally-accessible knowledge base of adversary tactics and techniques based on real-world observations. ATT&CK focuses on how external adversaries compromise and operate within computer information networks.
 
-Techniques 
+Techniques
 ~~~~~~~~~~
-"how" - the means by which adversaries achieve tactical goals
-
+Techniques represent "how" - the means by which adversaries achieve tactical objective.
 
 Sub-techniques
 ~~~~~~~~~~~~~~
-Describes more specific means by which adversaries achieve tactical goals at a lower level than techniques
+Sub-techniques break down behaviors described by techniques into more specific means by which adversaries achieve tactical objectives.
 
-Data Source 
+Data Source
 ~~~~~~~~~~~
-Source of information collected by a sensor or logging system that may be used to collect information relevant to identifying the action being performed, sequence of actions, or the results of those actions by an adversary
-
+Data Sources represent information collected by a sensor or logging system that may identify properties or values relevant to identifying the adversarial action being performed, sequence of actions, or the results of those actions.
 
 Data Component
 ~~~~~~~~~~~~~~
-Any constituent pieces of the data source, which are best described separately. Components may have their own set of metadata (describing the associated fields/values associated with the source) and activities (describing actions of the source).
+Data Components are  constituent pieces of the data source, which are best described separately. Components may have their own set of metadata (describing the associated fields/values associated with the source) and activities (describing actions of the source).
 
 ATT&CK Data Sources and Data Components can be found `here <https://attack.mitre.org/datasources/>`_.
 
 Data Elements
 -------------
-Names, definitions, and attributes that are being used or captured in an event
+Data elements are names, definitions, and attributes that are being used or captured in an event
 
-.. image:: _static/MSDN_4688_Ex.png
+.. image:: _static/msdn_4688_ex.png
    :width: 500
 
 Sensors
 -------
-An agent or service capable of detecting or measuring information across many different sources on a host in real-time and providing raw data with high precision and accuracy 
+A sensor is an agent or service capable of detecting or measuring information across many different sources on a host in real-time. Sensors provide raw data with high precision and accuracy.
 
 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
+Telemetry/events are generated by sensors in the form of log data, automatically generated and transmitted or streamed in near real-time, regardless of the format (e.g., json, csv, etc.).
 
-.. image:: _static/4688_Ex.png
+.. image:: _static/4688_ex.png
    :width: 500
diff --git a/docs/example_technique_mappings.rst b/docs/example_technique_mappings.rst
diff --git a/docs/example_technique_mappings/cloudtrail.rst b/docs/example_technique_mappings/cloudtrail.rst
@@ -0,0 +1,125 @@
+CloudTrail Example Scenarios
+============================
+
+Both CloudTrail examples involve User Account data components. The first review the use of
+User Account Modification to provide visibility into Account Manipulation (T1098), while the 
+second considers User Account Metadata for detection of Password Policy Discovery (T1201)
+behavior. 
+
+Account Manipulation (T1098)
+----------------------------
+
+The following are the criteria considered for Account Manipulation (T1098). These were 
+directly taken by reviewing the definition of the technique. 
+
+.. image:: ../_static/cldtrlex1.png
+   :width: 700
+
+1. Looking at the event logs themselves, is this enough proof or evidence to determine 
+   “changes to account objects were made under this technique”?
+
+   Most CloudTrail events are straightforward, and the associated API call performs a 
+   User Account Modification that meets the criteria for proving an Account Manipulation 
+   may have occurred. 
+
+   User must be valid on system or domain
+
+   - Any Action preserves an adversary access
+   - Modifying credentials
+   - Modifying permissions to groups
+   - Activity designed to subvert security policies
+
+ * TagUser
+
+   Event information: `AWS Documentation - AddTags <https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AddTags.html>`_
+
+   Yes. Careful attention was given to CloudTrail Roles, and related information. For 
+   example, the “TagUser/UntagUser” API entry was examined to determine that the act of 
+   Tagging/Untagging met the conditions to change (give or takeaway) access. 
+
+   One concept that came up was to also explore relevant sub-techniques, in case those could 
+   provide additional insight in deciding if an event met the defined conditions: 
+
+   - `Additional Cloud Credentials (T1098.001) <https://attack.mitre.org/techniques/T1098/001/>`_
+   - `Additional Cloud Roles (T1098.003) <https://attack.mitre.org/techniques/T1098/003/>`_
+
+ * UpdateUser
+
+   Event information: `AWS Documentation - UpdateUser <https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateUser.html>`_
+
+   Yes. Another interesting event is UpdateUser. As an API call, it does not perform a 
+   technical action that results in literal modification of concern (i.e., no access or 
+   permissions for an IAM user is changed). It does not preserve adversary action in a 
+   purely technical sense. HOWEVER: It does qualify because it could be used to “hide in 
+   plain sight” The event is worth noting as potential evidence of (an unexpected) name 
+   change.
+
+ * UploadSigningCertificate
+
+   Event information: `AWS Documentation- UploadSigningCertificate <https://docs.aws.amazon.com/IAM/latest/APIReference/API_UploadSigningCertificate.html>`_
+
+   Yes. This provides the name of the IAM user the signing certificate is for and the 
+   contents of the signing certificate. The elements provide information that can be used 
+   to look for changes to account objects.
+
+ Additional information: `AWS Documentation - SetSecurityTokenServicePreferences <https://docs.aws.amazon.com/IAM/latest/APIReference/API_SetSecurityTokenServicePreferences.html>`_
+
+Password Policy Discovery (T1201)
+----------------------------------
+
+The following are the criteria considered for Password Policy Discovery (T1201). These 
+were directly taken by reviewing the definition of the technique. 
+
+.. image:: ../_static/cldtrlex2.png
+   :width: 700
+
+1. Looking at the event logs themselves, is this enough proof or evidence to determine 
+   “are attempts being made to access detailed information about the password policy 
+   under this technique”?
+
+   This technique may be used by adversaries attempting to access/obtain detailed password 
+   policy information. This policy information may aid the creation of password lists for 
+   dictionary or brute force attacks.
+
+ * CreatePolicyVersion
+
+   Event information: `AWS Documentation - CreatePolicyVersion <https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreatePolicyVersion.html>`_
+
+   No. This contains details about IAM policy versions, but does not provide information about 
+   attempts to access policy documents.
+
+ * GetAccountPasswordPolicy
+
+   Event information: `AWS Documentation - GetAccountPasswordPolicy <https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetAccountPasswordPolicy.html>`_
+
+   Yes. The description of T1201 references that “password policies can be discovered in cloud 
+   environments using available APIs such as GetAccountPasswordPolicy in AWS.”
+
+   Select Examples of User Account Metadata events:
+
+   * AttachRolePolicy
+   * AttachUserPolicy
+   * CreatePolicy
+   * CreatePolicyVersion
+
+   * DeleteAccountPasswordPolicy
+   * DeletePolicyVersoin
+   * DeleteRolePolicy
+   * DeleteUserPolicy
+   * DetachUserPolicy
+   * DetachRolePolicy
+
+   * ChangePassword
+   * GenerateCredentialReport
+   * GetAccountPasswordPolicy
+
+   * ListAttachedRolePolicies
+   * ListEntitiesForPolicy
+   * ListPoliciesGrantingServiceAccess
+
+ * GetLoginProfile
+
+   Event information: `AWS Documentation - GetLoginProfile <https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetLoginProfile.html>`_
+
+   No. This contains information about IAM usernames and password creation dates, not 
+   actual passwords or password policy constructs.
diff --git a/docs/example_technique_mappings/index.rst b/docs/example_technique_mappings/index.rst
@@ -0,0 +1,23 @@
+.. _Example Pages:
+
+======================================
+Example Scenarios
+======================================
+
+Overview
+--------
+
+Examples are provided to depict how these mappings can be used to get from Sensor Events to ATT&CK Data Sources to 
+ATT&CK Techniques. It should be stated up front that there is no easy, one-to-one mapping from data source to technique. 
+In addition, not all events are created equal in regard to visibility of specific techniques, and two events with the 
+same field names can in fact represent different data. Some amount of analyst judgement is required and, whenever 
+judgement is involved, there can be differences in opinion. The mapping methodology and these examples are provided to 
+demonstrate the judgement and rationale to apply when identifying specific event visibility into techniques. Of course, 
+additonal customized considerations must also be given when looking to provide insight into a specific environment.
+
+.. toctree::
+
+    windows
+    linux
+    cloudtrail
+    network