Example updates (#82)

* Add mitre and targets examples
* Refined TTP example READMEs for clarity and consistency

- Enhanced titles and descriptions for improved comprehension.
- Streamlined instructions for running demonstrations.
- Adjusted formatting for better visual distinction of sections.
- Renamed certain files for naming consistency.

Authored-by: Jayson Grace <jayson.e.grace@gmail.com>

ttps/examples/args/README.md

@@ -1,21 +1,35 @@
-# TTPs
+# Defining Arguments for TTPs
 
-These TTPs illustrate how to use the CLI argument features of TTPForge.
+Delve into the process of specifying arguments for a TTP. Proper argument
+definition ensures flexible and dynamic Tactics, Techniques, and Procedures.
 
-## define-args.yaml
+---
 
-Run this TTP as follows:
+## Running `define-args.yaml` Demonstration
+
+To witness the definition and usage of arguments within a TTP, execute:
 
 ```bash
-ttpforge run examples/args/define-args.yaml \
+ttpforge run forgearmory//examples/args/define-args.yaml \
   --arg a_message=foo \
   --arg a_number=1337
 ```
 
-Expected output:
+---
+
+## Expected Output
 
 ```text
+INFO    [*] Validating Steps
+INFO    [+] Finished validating steps
+INFO    [+] Running current TTP: define_args
+INFO    [+] Running current step: print_args
+INFO    ========= Executing ==========
 hi! You passed the message: foo
 You passed the number: 1337
 has_a_default has the value: 'this is the default value'
+INFO    ========= Done ==========
+INFO    [+] Finished running step: print_args
+INFO    [*] Completed TTP
+INFO    [*] No Cleanup Steps Found
 ```

ttps/examples/fetchuri/README.md

@@ -0,0 +1,33 @@
+# Using the FetchURI Step in TTPs
+
+Discover how to effectively employ the `FetchURI` step in TTPs to fetch content
+from a specific URI and store it in a file.
+
+---
+
+## Running `fetchuri-example.yaml` Demonstration
+
+To observe the functionality of the `FetchURI` step in action, execute:
+
+```bash
+ttpforge run forgearmory//examples/fetchuri/fetchuri.yaml
+```
+
+---
+
+## Expected Output
+
+```text
+INFO    [*] Validating Steps
+INFO    [+] Finished validating steps
+INFO    [+] Running current TTP: fetchuri_step_example
+INFO    [+] Running current step: fetch-google-and-store-in-file
+INFO    ========= Executing ==========
+INFO    ========= Result ==========
+INFO    [+] Finished running step: fetch-google-and-store-in-file
+INFO    [*] Completed TTP
+INFO    [*] Beginning Cleanup
+INFO    ========= Executing ==========
+INFO    ========= Result ==========
+INFO    [*] Finished Cleanup
+```

ttps/examples/fetchuri/fetchuri.yaml

@@ -0,0 +1,11 @@
+---
+name: fetchuri_step_example
+description: Illustrates how to employ the FetchURI step.
+
+steps:
+  - name: fetch-google-and-store-in-file
+    fetch_uri: https://google.com
+    location: ./google.txt
+    overwrite: true
+    cleanup:
+      inline: rm google.txt

ttps/examples/mitre/README.md

@@ -0,0 +1,31 @@
+# MITRE ATT&CK Mapping for TTPs
+
+Understand the process of mapping a TTP to the MITRE ATT&CK framework,
+a globally recognized cybersecurity matrix.
+
+---
+
+## Running `mitre.yaml` Demonstration
+
+To see the TTP mapping in action with the MITRE ATT&CK framework, execute:
+
+```bash
+ttpforge run forgearmory//examples/mitre/mitre.yaml
+```
+
+---
+
+## Expected Output
+
+```text
+INFO    [*] Validating Steps
+INFO    [+] Finished validating steps
+INFO    [+] Running current TTP: mitre-target
+INFO    [+] Running current step: friendly-message
+INFO    ========= Executing ==========
+You are running a TTP that is mapped to MITRE ATT&CK
+INFO    ========= Done ==========
+INFO    [+] Finished running step: friendly-message
+INFO    [*] Completed TTP
+INFO    [*] No Cleanup Steps Found
+```

ttps/examples/mitre/mitre.yaml

@@ -0,0 +1,19 @@
+---
+name: mitre-target
+description: |
+  Example to map a TTP to MITRE ATT&CK through tactics, techniques, and
+  subtechniques.
+mitre:
+  tactics:
+    - TA0003 Persistence
+  techniques:
+    - T1547 Boot or Logon Autostart Execution
+  subtechniques:
+    - "T1547.007 Boot or Logon Autostart Execution: Re-opened Applications"
+
+steps:
+  - name: friendly-message
+    inline: |
+      set -e
+
+      echo "You are running a TTP that is mapped to MITRE ATT&CK"

ttps/examples/outputs/README.md

@@ -1,20 +1,47 @@
-# TTPs
+# Passing Outputs Between TTP Steps
 
-These TTPs illustrate how to pass outputs between different steps.
+Discover the methodology to efficiently pass outputs from one TTP step
+to the subsequent steps, ensuring seamless data flow within a procedure.
 
-## step-outputs.yaml
+---
 
-Run this TTP as follows:
+## Running `outputs.yaml` Demonstration
+
+To observe the interplay of outputs between different TTP steps, execute:
 
 ```bash
-ttpforge run examples/outputs/step-outputs.yaml
+ttpforge run forgearmory//examples/outputs/outputs.yaml
 ```
 
-Expected output:
+---
+
+## Expected Output
 
 ```text
+INFO    [*] Validating Steps
+INFO    [+] Finished validating steps
+INFO    [+] Running current TTP: step_outputs_example
+INFO    [+] Running current step: raw_output
+INFO    ========= Executing ==========
 this will be accessible in stdout
+INFO    ========= Result ==========
+INFO    [+] Finished running step: raw_output
+INFO    [+] Running current step: access_raw_output
+INFO    ========= Executing ==========
 previous step output is this will be accessible in stdout
+
+INFO    ========= Result ==========
+INFO    [+] Finished running step: access_raw_output
+INFO    [+] Running current step: with_json_output
+INFO    ========= Executing ==========
 {"foo":"bar"}
+INFO    ========= Result ==========
+INFO    [+] Finished running step: with_json_output
+INFO    [+] Running current step: print_json
+INFO    ========= Executing ==========
 bar
+INFO    ========= Result ==========
+INFO    [+] Finished running step: print_json
+INFO    [*] Completed TTP
+INFO    [*] No Cleanup Steps Found
 ```

ttps/examples/outputs/step-outputs.yaml → ttps/examples/outputs/outputs.yaml

@@ -2,6 +2,7 @@
 name: step_outputs_example
 description: |
   Illustrates how to pass outputs between steps
+
 steps:
   - name: raw_output
     inline: echo "this will be accessible in stdout"

ttps/examples/steps/cleanup-step/README.md

@@ -0,0 +1,37 @@
+# File Creation and Cleanup using `test-cleanup` Step
+
+Discover how to create and subsequently clean up files leveraging the
+`test-cleanup` step. This example showcases the capability to create a
+directory and remove it in the cleanup step.
+
+---
+
+## Running `cleanup-step.yaml` Demonstration
+
+Execute the following command to illustrate the functionality of
+the `test-cleanup` step:
+
+```bash
+ttpforge run forgearmory//examples/steps/cleanup-step/cleanup-step.yaml
+```
+
+---
+
+## Expected Output
+
+```text
+INFO    [*] Validating Steps
+INFO    [+] Finished validating steps
+INFO    [+] Running current TTP: test-cleanup
+INFO    [+] Running current step: step_one
+INFO    ========= Executing ==========
+# Directory "testDir" is created here
+INFO    ========= Done ==========
+INFO    [+] Finished running step: step_one
+INFO    [*] Completed TTP
+INFO    [*] Starting Cleanup
+INFO    ========= Executing ==========
+# Directory "testDir" is removed here
+INFO    ========= Done ==========
+INFO    [*] Cleanup Complete
+```

ttps/examples/steps/cleanup-step/cleanup-step.yaml

@@ -0,0 +1,7 @@
+---
+name: test-cleanup
+steps:
+  - name: step_one
+    inline: mkdir testDir
+    cleanup:
+      inline: rm -rf testDir

ttps/examples/steps/edit-step/README.md

@@ -0,0 +1,75 @@
+# File Modification using `edit_file` Step
+
+Discover how to make amendments to files leveraging the `edit_file` step,
+a versatile tool for editing files through string matching or regular expressions.
+
+---
+
+## Running `edit-step.yaml` Demonstration
+
+Execute the following command to illustrate the power of the `edit_file` step:
+
+```bash
+ttpforge run forgearmory//examples/steps/edit-step/edit-step.yaml
+```
+
+---
+
+## Expected Output
+
+```text
+INFO    [*] Validating Steps
+INFO    [+] Finished validating steps
+INFO    [+] Running current TTP: edit_step_example
+INFO    [+] Running current step: target-file-pre-edit
+INFO    ========= Executing ==========
+This is an example file.
+
+The TTP will replace the string below:
+
+REPLACE_ME
+
+It will also delete the multi-line string below and replace
+it with a comment:
+
+result = await myclass.multi_line_function_call(
+    param1,
+    param2,
+)
+
+Lastly, it will comment out the subsequent lines using a C-Style /* ... */ comment.
+
+another_multline_function_call(
+    param1,
+    param2,
+)
+INFO    ========= Done ==========
+INFO    [+] Finished running step: target-file-pre-edit
+INFO    [+] Running current step: edit-target-file
+INFO    [+] Finished running step: edit-target-file
+INFO    [+] Running current step: target-file-post-edit
+INFO    ========= Executing ==========
+This is an example file.
+
+The TTP has replaced the string below with:
+
+REPLACED_BY_EDIT
+
+The multi-line string was deleted and replaced with a comment:
+
+# replaced with comment
+
+The following lines have been commented using a C-Style /* ... */ comment:
+
+/*another_multline_function_call(
+    param1,
+    param2,
+)*/
+INFO    ========= Done ==========
+INFO    [+] Finished running step: target-file-post-edit
+INFO    [*] Completed TTP
+INFO    [*] Starting Cleanup
+INFO    ========= Executing ==========
+INFO    ========= Done ==========
+INFO    [*] Cleanup Complete
+```

ttps/examples/steps/edit-step/edit-step.yaml

@@ -0,0 +1,33 @@
+---
+name: edit_step_example
+description: edits a file in various ways
+steps:
+  - name: target-file-pre-edit
+    inline: |
+      set -e
+
+      echo -e "Target file pre-edit:"
+      cat file-to-edit.txt
+  - name: edit-target-file
+    edit_file: "file-to-edit.txt"
+    backup_file: "/tmp/my-backup.txt"
+    edits:
+      - old: REPLACE_ME
+        new: REPLACED_BY_EDIT
+      - old: (?ms:^result = await myclass\.multi_line_function_call\(.*?\)$)
+        new: "# replaced with comment"
+        regexp: true
+      - old: (?P<fn_call>(?ms:^another_multline_function_call\(.*?\)$))
+        new: "/*${fn_call}*/"
+        regexp: true
+  - name: target-file-post-edit
+    inline: |
+      set -e
+
+      echo -e "Target file post-edit:"
+      cat $HOME/.ttpforge/repos/forgearmory/ttps/examples/steps/edit-step/file-to-edit.txt
+    cleanup:
+      inline: |
+        set -e
+
+        mv /tmp/my-backup.txt $HOME/.ttpforge/repos/forgearmory/ttps/examples/steps/edit-step/file-to-edit.txt