Final review of project website.

.github/workflows/sphinx.yml

@@ -29,6 +29,14 @@ jobs:
       run: poetry run python src/util/cli_validator.py
     - name: Build HTML docs
       run: poetry run make docs-ci
+    - name: Copy Mappings Excel to Website
+      run: mkdir docs/extra/xlsx && cp "mappings/input/enterprise/xlsx/Sensor to Data Source.xlsx" docs/extra/xlsx
+    - name: Copy Mappings CSVs to Website
+      run: mkdir docs/extra/csv && cp mappings/input/enterprise/csv/*.csv docs/extra/csv
+    - name: Copy Navigator Layers to Website
+      run: mkdir docs/extra/navigator && cp mappings/layers/enterprise/*.json docs/extra/navigator
+    - name: Copy STIX Bundles to Website
+      run: mkdir docs/extra/stix && cp mappings/stix/enterprise/*.json docs/extra/stix
     - name: Upload HTML docs
       uses: actions/upload-artifact@v3
       with:

docs/definitions.rst

@@ -3,42 +3,46 @@ Definitions
 
 This page defines the key terms used throughout our research.
 
-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 represent "how" - the means by which adversaries achieve tactical objective.
-
-Sub-techniques
-~~~~~~~~~~~~~~
-Sub-techniques break down behaviors described by techniques into more specific means by which adversaries achieve tactical objectives.
-
-Data Source
-~~~~~~~~~~~
-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
-~~~~~~~~~~~~~~
-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 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
--------------
-Data elements are names, definitions, and attributes that are being used or captured in an event
-
-.. image:: _static/msdn_4688_ex.png
-   :width: 500
+   Data Elements are names, definitions, and attributes that are being used or captured
+   in an event.
 
-Sensors
--------
-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.
+   .. image:: _static/msdn_4688_ex.png
+      :width: 500
 
-Telemetry/Events
-----------------
-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.).
+Data Source
+   Data Sources represents information collected by a sensor or logging system that may
+   identify properties or values relevant to identifying the adversarial action being
+   ATT&CK Data Sources and Data Components can be found `here
+   <https://attack.mitre.org/datasources/>`__. performed, sequence of actions, or the
+   results of those actions.
 
-.. image:: _static/4688_ex.png
-   :width: 500
+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 networks.
+
+Sensor
+   A sensor is an agent or service capable of detecting or measuring information across
+   many different sources on a host or network in real-time. Sensors provide raw data
+   with high precision and accuracy.
+
+[Sub-]Technique
+   Techniques represent the "how" of cyber intrusions, i.e. the means by which
+   adversaries achieve tactical objective. Sub-techniques break down techniques into
+   more fine-grained descriptions of adversary behaviors.
+
+Telemetry
+   Telemetry consists of discrete events that are generated by sensors, e.g. log data.
+   Telemetry may be delivered in various formats (e.g., json, csv, etc.) and is often
+   streamed in near real-time.
+
+   .. image:: _static/4688_ex.png
+      :width: 500

docs/example_technique_mappings/cloudtrail.rst

@@ -1,125 +1,129 @@
 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. 
+Both CloudTrail examples involve User Account data components. The first reviews the use
+of User Account Modification to provide visibility into `Account Manipulation (T1098)
+<https://attack.mitre.org/techniques/T1098>`__, while the second considers User Account
+Metadata for detection of `Password Policy Discovery (T1201)
+<https://attack.mitre.org/techniques/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. 
+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”?
+**Looking at the event data, is this enough evidence to conclude that an account was
+manipulated per T1098?** Most CloudTrail events are straightforward, and the associated
+API call performs a User Account Modification that meets the criteria for concluding
+that an Account Manipulation has occurred.
 
-   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. 
+**TagUser:**
 
-   User must be valid on system or domain
+*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 explore relevant sub-techniques, in case those could provide
+additional insight in deciding if an event met the defined conditions:
 
-   - Any Action preserves an adversary access
-   - Modifying credentials
-   - Modifying permissions to groups
-   - Activity designed to subvert security policies
+  * `Additional Cloud Credentials (T1098.001)
+    <https://attack.mitre.org/techniques/T1098/001/>`__
+  * `Additional Cloud Roles (T1098.003)
+    <https://attack.mitre.org/techniques/T1098/003/>`__
 
- * TagUser
+*References:*
 
-   Event information: `AWS Documentation - AddTags <https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AddTags.html>`_
+  * `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. 
+**UpdateUser:**
 
-   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: 
+*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.
 
-   - `Additional Cloud Credentials (T1098.001) <https://attack.mitre.org/techniques/T1098/001/>`_
-   - `Additional Cloud Roles (T1098.003) <https://attack.mitre.org/techniques/T1098/003/>`_
+*References:*
 
- * UpdateUser
+* `AWS Documentation - UpdateUser
+  <https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateUser.html>`__
 
-   Event information: `AWS Documentation - UpdateUser <https://docs.aws.amazon.com/IAM/latest/APIReference/API_UpdateUser.html>`_
+**UploadSigningCertificate:**
 
-   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.
+*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.
 
- * UploadSigningCertificate
+*References:*
 
-   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>`_
+* `AWS Documentation- UploadSigningCertificate
+  <https://docs.aws.amazon.com/IAM/latest/APIReference/API_UploadSigningCertificate.html>`__
+* `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. 
+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.
+**Looking at the event data, is this enough evidence to conclude that attempts were
+being made to access detailed information about the password policy per technique
+T1201?** 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
+ **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.
 
-   No. This contains details about IAM policy versions, but does not provide information about 
-   attempts to access policy documents.
+*References:*
 
- * GetAccountPasswordPolicy
+* `AWS Documentation - CreatePolicyVersion
+  <https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreatePolicyVersion.html>`__
 
-   Event information: `AWS Documentation - GetAccountPasswordPolicy <https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetAccountPasswordPolicy.html>`_
+**GetAccountPasswordPolicy:**
 
-   Yes. The description of T1201 references that “password policies can be discovered in cloud 
-   environments using available APIs such as GetAccountPasswordPolicy in AWS.”
+*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:
+Select examples of User Account Metadata events:
 
    * AttachRolePolicy
    * AttachUserPolicy
    * CreatePolicy
    * CreatePolicyVersion
-
    * DeleteAccountPasswordPolicy
    * DeletePolicyVersoin
    * DeleteRolePolicy
    * DeleteUserPolicy
    * DetachUserPolicy
    * DetachRolePolicy
-
    * ChangePassword
    * GenerateCredentialReport
    * GetAccountPasswordPolicy
-
    * ListAttachedRolePolicies
    * ListEntitiesForPolicy
    * ListPoliciesGrantingServiceAccess
 
- * GetLoginProfile
+*References:*
+
+* `AWS Documentation - GetAccountPasswordPolicy
+  <https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetAccountPasswordPolicy.html>`__
+
+**GetLoginProfile:**
+
+*No.* This contains information about IAM usernames and password creation dates, not
+actual passwords or password policy constructs.
 
-   Event information: `AWS Documentation - GetLoginProfile <https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetLoginProfile.html>`_
+*References:*
 
-   No. This contains information about IAM usernames and password creation dates, not 
-   actual passwords or password policy constructs.
+* `AWS Documentation - GetLoginProfile
+  <https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetLoginProfile.html>`__

docs/example_technique_mappings/index.rst

@@ -1,23 +1,20 @@
-.. _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.
+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
+    network