Merge pull request #175 from lindsey-w/master

Update psuedocode

.github/workflows/lint-yaml.yml

@@ -0,0 +1,110 @@
+name: Lint the yaml
+
+on:
+  pull_request_target:
+  push:
+    branches: [master]
+
+jobs:
+  yamllint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install script dependencies
+        run: pip install -r ./scripts/requirements.txt
+      - name: Run yamllint
+        run: yamllint analytics/ data_model/ sensors/
+  analysis-schema:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install script dependencies
+        run: pip install -r ./scripts/requirements.txt
+      - name: Validate against analysis schema
+        run: yamale -s scripts/analytic_schema.yaml --no-strict analytics/
+  datamodel-schema:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install script dependencies
+        run: pip install -r ./scripts/requirements.txt
+      - name: Validate against data model schema
+        run: yamale -s scripts/datamodel_schema.yaml --no-strict data_model/
+  sensor-schema:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install script dependencies
+        run: pip install -r ./scripts/requirements.txt
+      - name: Validate against sensor schema
+        run: yamale -s scripts/sensor_schema.yaml --no-strict sensors/
+  filetype-is-yaml:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+      - name: Files should be .yaml not .yml and should also be actual files (ex. not directories)
+        shell: bash
+        run: find analytics data_model sensors -mindepth 1 -maxdepth 1 \( ! -name "*.yaml" \) -o \( ! -type f \)
+  id-filename-equivalence:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+      - name: Analytics files need to have their filename be '{id}.yaml'
+        run: >
+          ret=0;
+          for file in analytics/*.yaml; do
+            echo "Checking $file";
+            if ! [ "$(basename $file | sed -e "s/\.yaml$//")" = "$(yq '.id' < $file)" ]; then
+              echo "Failed";
+              ret=1;
+            fi;
+          done;
+          exit "$ret"
+      - name: Data model files need to have their filename be '{name but fully lowercase and with underscores replacing spaces}.yaml'
+        run: >
+          ret=0;
+          for file in data_model/*.yaml; do
+            echo "Checking $file";
+            if ! [ "$(basename $file | sed -e "s/\.yaml$//")" = "$(yq '.name | downcase | sub(" ", "_")' < $file)" ]; then
+              echo "Failed";
+              ret=1;
+            fi;
+          done;
+          exit "$ret"
+      - name: Sensor files need to have their filename be '{sensor_name but fully lowercase}_{sensor_version}.yaml'
+        run: >
+          ret=0;
+          for file in sensors/*.yaml; do
+            echo "Checking $file";
+            if ! [ "$(basename $file | sed -e "s/\.yaml$//")" = "$(yq '(.sensor_name | downcase) + "_" + .sensor_version' < $file)" ]; then
+              echo "Failed";
+              ret=1;
+            fi;
+          done;
+          exit "$ret"

.github/workflows/regenerate-docs.yml

@@ -0,0 +1,53 @@
+name: Regenerate /docs using the generate_*.py scripts
+
+on:
+  pull_request_target:
+  push:
+    branches: [master]
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Pull down repo
+        uses: actions/checkout@v3
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.head_ref }}
+      - name: Clean /docs/data_model
+        shell: bash
+        run: rm -rfv ./docs/data_model
+      - name: Clean /docs/analytics
+        shell: bash
+        run: rm -rfv ./docs/analytics
+      - name: Clean /docs/sensors
+        shell: bash
+        run: rm -rfv ./docs/sensors
+      - name: Set up python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install script dependencies
+        run: pip install -r ./scripts/requirements.txt
+      - name: Regenerate datamodels
+        working-directory: ./scripts
+        run: python generate_datamodels.py
+      - name: Regenerate analytics
+        working-directory: ./scripts
+        run: python generate_analytics.py
+      - name: Regenerate sensors
+        working-directory: ./scripts
+        run: python generate_sensors.py
+      - name: Regenerate attack nav layer
+        working-directory: ./scripts
+        run: python generate_attack_nav_layer.py
+      - name: Commit new static site
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: 'Automated commit to rebuild the static site'
+          commit_options: '--signoff'
+          commit_user_name: 'Build and Push Automation Script'
+          commit_user_email: '<>'

.yamllint

@@ -0,0 +1,5 @@
+---
+extends: default
+
+rules:
+  line-length: disable

analytics/CAR-2013-01-002.yaml

@@ -1,3 +1,4 @@
+---
 title: Autorun Differences
 submission_date: 2013/01/25
 information_domain: 'Analytic, Host'
@@ -11,7 +12,7 @@ analytic_types:
 contributors:
   - MITRE
 id: CAR-2013-01-002
-description: |-
+description: |
   The Sysinternals tool [Autoruns](../sensors/autoruns) checks the registry and file system for known identify persistence mechanisms. It will output any tools identified, including built-in or added-on Microsoft functionality and third party software. Many of these locations are known by adversaries and used to obtain [Persistence](https://attack.mitre.org/tactics/TA0003). Running Autoruns periodically in an environment makes it possible to collect and monitor its output for differences, which may include the removal or addition of persistent tools. Depending on the persistence mechanism and location, legitimate software may be more likely to make changes than an adversary tool. Thus, this analytic may result in significant noise in a highly dynamic environment. While Autoruns is a convenient method to scan for programs using persistence mechanisms its scanning nature does not conform well to streaming based analytics. This analytic could be replaced with one that draws from sensors that collect registry and file information if streaming analytics are desired.
 
   Utilizes the Sysinternals autoruns tool (ignoring validated Microsoft entries). Primarily not a detection analytic by itself but through analysis of results by an analyst can be used for such. Building another analytic on top of this one identifying unusual entries would likely be a beneficial alternative.

analytics/CAR-2013-01-003.yaml

@@ -1,3 +1,4 @@
+---
 title: SMB Events Monitoring
 submission_date: 2013/01/25
 information_domain: Network
@@ -10,8 +11,8 @@ analytic_types:
 contributors:
   - MITRE
 id: CAR-2013-01-003
-description: |-
-  [Server Message Block](https://en.wikipedia.org/wiki/Server_Message Block) (SMB) is used by Windows to allow for file, pipe, and printer sharing over port 445/tcp. It allows for enumerating, and reading from and writing to file shares for a remote computer. Although it is heavily used by Windows servers for legitimate purposes and by users for file and printer sharing, many adversaries also use SMB to achieve [Lateral Movement](https://attack.mitre.org/tactics/TA0008). Looking at this activity more closely to obtain an adequate sense of situational awareness may make it possible to detect adversaries moving between hosts in a way that deviates from normal activity. Because SMB traffic is heavy in many environments, this analytic may be difficult to turn into something that can be used to quickly detect an APT. In some cases, it may make more sense to run this analytic in a forensic fashion. Looking through and filtering its output after an intrusion has been discovered may be helpful in identifying the scope of compromise. 
+description: |
+  [Server Message Block](https://en.wikipedia.org/wiki/Server_Message Block) (SMB) is used by Windows to allow for file, pipe, and printer sharing over port 445/tcp. It allows for enumerating, and reading from and writing to file shares for a remote computer. Although it is heavily used by Windows servers for legitimate purposes and by users for file and printer sharing, many adversaries also use SMB to achieve [Lateral Movement](https://attack.mitre.org/tactics/TA0008). Looking at this activity more closely to obtain an adequate sense of situational awareness may make it possible to detect adversaries moving between hosts in a way that deviates from normal activity. Because SMB traffic is heavy in many environments, this analytic may be difficult to turn into something that can be used to quickly detect an APT. In some cases, it may make more sense to run this analytic in a forensic fashion. Looking through and filtering its output after an intrusion has been discovered may be helpful in identifying the scope of compromise.
 
   ### Output Description
 
@@ -28,8 +29,8 @@ coverage:
       - T1021.002
     coverage: Moderate
 implementations:
-  - description: 'Although there may be more native ways to detect detailed SMB events on the host, they can be extracted out of network traffic. With the right protocol decoders, port 445 traffic can be filtered and even the file path (relative to the share) can be retrieved. '
-    code: |-
+  - description: 'Although there may be more native ways to detect detailed SMB events on the host, they can be extracted out of network traffic. With the right protocol decoders, port 445 traffic can be filtered and even the file path (relative to the share) can be retrieved.'
+    code: |
       flow = search Flow:Message
       smb_events = filter flow where (dest_port == "445" and protocol == "smb")
       smb_events.file_name = smb_events.proto_info.file_name

analytics/CAR-2013-02-003.yaml

@@ -1,3 +1,4 @@
+---
 title: Processes Spawning cmd.exe
 submission_date: 2013/02/05
 information_domain: Host

analytics/CAR-2013-02-008.yaml

@@ -1,3 +1,4 @@
+---
 title: Simultaneous Logins on a Host
 submission_date: 2013/02/18
 information_domain: Host
@@ -12,7 +13,7 @@ analytic_types:
 contributors:
   - MITRE
 id: CAR-2013-02-008
-description: |-
+description: |
   Multiple users logged into a single machine at the same time, or even within the same hour, do not typically occur in networks we have observed.
 
   Logon events are Windows Event Code 4624 for Windows Vista and above, 518 for pre-Vista. Logoff events are 4634 for Windows Vista and above, 538 for pre-Vista.
@@ -26,10 +27,10 @@ coverage:
       - T1078.003
     coverage: Low
 implementations:
-  - code: |-
+  - code: |
       users_list = search UserSession:Login
       users_grouped = group users_list by hostname
-      users_grouped = from users_grouped select min(time) as earliest_time, max(time) as latest_time count(user) as user_count 
+      users_grouped = from users_grouped select min(time) as earliest_time, max(time) as latest_time count(user) as user_count
       multiple_logins = filter users_grouped where (latest_time - earliest_time <= 1 hour and user_count > 1)
       output multiple_logins
     type: pseudocode

analytics/CAR-2013-02-012.yaml

@@ -1,3 +1,4 @@
+---
 title: User Logged in to Multiple Hosts
 submission_date: 2013/02/27
 information_domain: Host
@@ -12,7 +13,7 @@ analytic_types:
 contributors:
   - MITRE
 id: CAR-2013-02-012
-description: |-
+description: |
   Most users use only one or two machines during the normal course of business. User accounts that log in to multiple machines, especially over a short period of time, may be compromised. Remote logins among multiple machines may be an indicator of [Lateral Movement](https://attack.mitre.org/tactics/TA0008).
 
   Certain users will likely appear as being logged into several machines and may need to be "whitelisted." Such users would include network admins or user names that are common to many hosts.
@@ -25,8 +26,8 @@ coverage:
     tactics:
       - TA0008
     subtechniques:
-       - T1078.002
-       - T1078.003
+      - T1078.002
+      - T1078.003
     coverage: Moderate
 d3fend_mappings:
   - iri: d3f:AuthenticationEventThresholding

analytics/CAR-2013-03-001.yaml

@@ -1,3 +1,4 @@
+---
 title: Reg.exe called from Command Shell
 submission_date: 2013/03/28
 information_domain: Host
@@ -10,7 +11,7 @@ analytic_types:
 contributors:
   - MITRE
 id: CAR-2013-03-001
-description: |-
+description: |
   Registry modifications are often essential in establishing persistence via known Windows mechanisms. Many legitimate modifications are done graphically via `regedit.exe` or by using the corresponding channels, or even calling the Registry APIs directly. The built-in utility `reg.exe` provides a [command-line interface](https://en.wikipedia.org/wiki/Command-line_interface) to the registry, so that queries and modifications can be performed from a shell, such as `cmd.exe`. When a user is responsible for these actions, the parent of `cmd.exe` will likely be `explorer.exe`. Occasionally, power users and administrators write scripts that do this behavior as well, but likely from a different process tree. These background scripts must be learned so they can be tuned out accordingly.
 
   ### Output Description
@@ -45,15 +46,15 @@ coverage:
     coverage: Moderate
 implementations:
   - description: 'To gain better context, it may be useful to also get information about the cmd process to know its parent. This may be helpful when tuning the analytic to an environment, if this behavior happens frequently. This may also help to rule out instances of users running '
-    code: |-
+    code: |
       processes = search Process:Create
       reg = filter processes where (exe == "reg.exe" and parent_exe == "cmd.exe")
       cmd = filter processes where (exe == "cmd.exe" and parent_exe != "explorer.exe"")
       reg_and_cmd = join (reg, cmd) where (reg.ppid == cmd.pid and reg.hostname == cmd.hostname)
       output reg_and_cmd
     type: pseudocode
   - description: DNIF version of the above pseudocode.
-    code: |-
+    code: |
       _fetch * from event where $LogName=WINDOWS-SYSMON AND $EventID=1 AND $Process=regex(.*reg\.exe.*)i AND $ParentProcess=regex(.*cmd\.exe.*)i as #A limit 100
       >>_fetch * from event where $LogName=WINDOWS-SYSMON AND $EventID=1 AND $Process=regex(.*cmd\.exe.*)i NOT $ParentProcess=regex(.*explorer\.exe.*)i as #B limit 100
       >>_checkif sjoin #B.$PPID = #A.$CPID str_compare #B.$SystemName eq #A.$SystemName include

analytics/CAR-2013-04-002.yaml

@@ -1,3 +1,4 @@
+---
 title: Quick execution of a series of suspicious commands
 submission_date: 2013/04/11
 information_domain: 'Analytic, Host'

analytics/CAR-2013-05-002.yaml

@@ -1,3 +1,4 @@
+---
 title: Suspicious Run Locations
 submission_date: 2013/05/07
 information_domain: Host

analytics/CAR-2013-05-003.yaml

@@ -1,3 +1,4 @@
+---
 title: SMB Write Request
 submission_date: 2013/05/13
 information_domain: 'Host, Network'
@@ -35,7 +36,7 @@ coverage:
       - T1078.003
     coverage: Moderate
 implementations:
-  - code: |-
+  - code: |
       flow = search Flow:Message
       smb_write = filter flow where (dest_port == "445" and protocol == "smb.write")
       smb_write.file_name = smb_write.proto_info.file_name

analytics/CAR-2013-05-004.yaml

@@ -1,3 +1,4 @@
+---
 title: Execution with AT
 submission_date: 2013/05/13
 information_domain: Host

analytics/CAR-2013-05-005.yaml

@@ -1,3 +1,4 @@
+---
 title: SMB Copy and Execution
 submission_date: 2013/05/13
 information_domain: 'Host, Network'

analytics/CAR-2013-05-009.yaml

@@ -1,3 +1,4 @@
+---
 title: Running executables with same hash and different names
 submission_date: 2013/05/23
 information_domain: Host

analytics/CAR-2013-07-001.yaml

@@ -1,3 +1,4 @@
+---
 title: Suspicious Arguments
 submission_date: 2013/07/05
 information_domain: Host

analytics/CAR-2013-07-002.yaml

@@ -1,3 +1,4 @@
+---
 title: RDP Connection Detection
 submission_date: 2013/07/24
 information_domain: 'Analytic, Network'

analytics/CAR-2013-07-005.yaml

@@ -1,3 +1,4 @@
+---
 title: Command Line Usage of Archiving Software
 submission_date: 2013/07/31
 information_domain: Host
@@ -12,7 +13,7 @@ analytic_types:
 contributors:
   - MITRE
 id: CAR-2013-07-005
-description: |-
+description: |
   Before [exfiltrating data](https://attack.mitre.org/tactics/TA0010) that an adversary has [collected](https://attack.mitre.org/tactics/TA0009), it is very likely that a [compressed archive](https://attack.mitre.org/techniques/T1560) will be created, so that transfer times are minimized and fewer files are transmitted. There is variety between the tools used to compress data, but the command line usage and context of archiving tools, such as ZIP, RAR, and 7ZIP, should be monitored.
 
   In addition to looking for RAR or 7z program names, command line usage of 7Zip or RAR can be detected with the flag usage of "`\* a \*`". This is helpful, as adversaries may change program names.
@@ -25,18 +26,18 @@ coverage:
     coverage: Moderate
 implementations:
   - description: 'This analytic looks for the command line argument `a`, which is used by RAR. However, there may be other programs that have this as a legitimate argument and may need to be filtered out.'
-    code: |-
+    code: |
       processes = search Process:Create
       rar_argument = filter processes where (command_line == "* a *")
       output rar_argument
     type: pseudocode
   - description: DNIF version of the above pseudocode.
-    code: |-
+    code: |
       _fetch * from event where $LogName=WINDOWS-SYSMON AND $EventID=1 AND $Process=regex(.* a .*)i limit 100
     type: DNIF
     data_model: Sysmon native
   - description: LogPoint version of the above pseudocode.
-    code: |-
+    code: |
       norm_id=WindowsSysmon event_id=1 command="* a *"
     type: LogPoint
     data_model: LogPoint native