From 864de283749c86b9d17d0084ea46d46a7de7ce07 Mon Sep 17 00:00:00 2001 From: Jayson Grace Date: Mon, 25 Sep 2023 13:14:52 -0400 Subject: [PATCH] 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 --- ttps/examples/args/README.md | 26 +++++-- ttps/examples/fetchuri/README.md | 33 ++++++++ ttps/examples/fetchuri/fetchuri.yaml | 11 +++ ttps/examples/mitre/README.md | 31 ++++++++ ttps/examples/mitre/mitre.yaml | 19 +++++ ttps/examples/outputs/README.md | 39 ++++++++-- .../{step-outputs.yaml => outputs.yaml} | 1 + ttps/examples/steps/cleanup-step/README.md | 37 +++++++++ .../steps/cleanup-step/cleanup-step.yaml | 7 ++ ttps/examples/steps/edit-step/README.md | 75 +++++++++++++++++++ ttps/examples/steps/edit-step/edit-step.yaml | 33 ++++++++ ttps/examples/steps/edit-step/ttp.yaml | 16 ---- ttps/examples/sub-ttps/README.md | 56 ++++++++++++++ .../sub-ttps/{example.yaml => sub-ttps.yaml} | 0 14 files changed, 356 insertions(+), 28 deletions(-) create mode 100644 ttps/examples/fetchuri/README.md create mode 100644 ttps/examples/fetchuri/fetchuri.yaml create mode 100644 ttps/examples/mitre/README.md create mode 100644 ttps/examples/mitre/mitre.yaml rename ttps/examples/outputs/{step-outputs.yaml => outputs.yaml} (99%) create mode 100644 ttps/examples/steps/cleanup-step/README.md create mode 100644 ttps/examples/steps/cleanup-step/cleanup-step.yaml create mode 100644 ttps/examples/steps/edit-step/README.md create mode 100644 ttps/examples/steps/edit-step/edit-step.yaml delete mode 100644 ttps/examples/steps/edit-step/ttp.yaml create mode 100644 ttps/examples/sub-ttps/README.md rename ttps/examples/sub-ttps/{example.yaml => sub-ttps.yaml} (100%) diff --git a/ttps/examples/args/README.md b/ttps/examples/args/README.md index e56250e..8a1135c 100644 --- a/ttps/examples/args/README.md +++ b/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 ``` diff --git a/ttps/examples/fetchuri/README.md b/ttps/examples/fetchuri/README.md new file mode 100644 index 0000000..dd9618c --- /dev/null +++ b/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 +``` diff --git a/ttps/examples/fetchuri/fetchuri.yaml b/ttps/examples/fetchuri/fetchuri.yaml new file mode 100644 index 0000000..2383dcd --- /dev/null +++ b/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 diff --git a/ttps/examples/mitre/README.md b/ttps/examples/mitre/README.md new file mode 100644 index 0000000..4a241af --- /dev/null +++ b/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 +``` diff --git a/ttps/examples/mitre/mitre.yaml b/ttps/examples/mitre/mitre.yaml new file mode 100644 index 0000000..cfe1ec7 --- /dev/null +++ b/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" diff --git a/ttps/examples/outputs/README.md b/ttps/examples/outputs/README.md index 585d031..57af018 100644 --- a/ttps/examples/outputs/README.md +++ b/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 ``` diff --git a/ttps/examples/outputs/step-outputs.yaml b/ttps/examples/outputs/outputs.yaml similarity index 99% rename from ttps/examples/outputs/step-outputs.yaml rename to ttps/examples/outputs/outputs.yaml index dff08fa..2fa8c2b 100644 --- a/ttps/examples/outputs/step-outputs.yaml +++ b/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" diff --git a/ttps/examples/steps/cleanup-step/README.md b/ttps/examples/steps/cleanup-step/README.md new file mode 100644 index 0000000..9a04b28 --- /dev/null +++ b/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 +``` diff --git a/ttps/examples/steps/cleanup-step/cleanup-step.yaml b/ttps/examples/steps/cleanup-step/cleanup-step.yaml new file mode 100644 index 0000000..28907e8 --- /dev/null +++ b/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 diff --git a/ttps/examples/steps/edit-step/README.md b/ttps/examples/steps/edit-step/README.md new file mode 100644 index 0000000..6735c06 --- /dev/null +++ b/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 +``` diff --git a/ttps/examples/steps/edit-step/edit-step.yaml b/ttps/examples/steps/edit-step/edit-step.yaml new file mode 100644 index 0000000..8f83961 --- /dev/null +++ b/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(?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 diff --git a/ttps/examples/steps/edit-step/ttp.yaml b/ttps/examples/steps/edit-step/ttp.yaml deleted file mode 100644 index 5c6fe0f..0000000 --- a/ttps/examples/steps/edit-step/ttp.yaml +++ /dev/null @@ -1,16 +0,0 @@ ---- -name: edit_step_example -description: edits a file in various ways -steps: - - name: edit_target_file - edit_file: "file-to-edit.txt" - backup_file: "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(?ms:^another_multline_function_call\(.*?\)$)) - new: "/*${fn_call}*/" - regexp: true diff --git a/ttps/examples/sub-ttps/README.md b/ttps/examples/sub-ttps/README.md new file mode 100644 index 0000000..8859c60 --- /dev/null +++ b/ttps/examples/sub-ttps/README.md @@ -0,0 +1,56 @@ +# Chaining Tactics with SubTTPs + +Delve into the process of crafting a TTP with integrated SubTTPs. This technique +enables chaining multiple Tactics, Techniques, and Procedures for a streamlined +attack sequence. + +--- + +## Running `sub-ttps.yaml` Demonstration + +To visualize how SubTTPs function within a TTP, initiate the command below: + +```bash +ttpforge run forgearmory//examples/sub-ttps/sub-ttps.yaml +``` + +--- + +## Expected Output + +```text +INFO [*] Validating Steps +INFO [*] Validating Sub TTP: first_sub_ttp +INFO [*] Finished validating Sub TTP +INFO [*] Validating Sub TTP: second_sub_ttp +INFO [*] Finished validating Sub TTP +INFO [+] Finished validating steps +INFO [+] Running current TTP: sub_ttp_example +INFO [+] Running current step: first_sub_ttp +INFO [*] Executing Sub TTP: first_sub_ttp +INFO [+] Running current step: step_one +INFO ========= Executing ========== +hello +INFO ========= Done ========== +INFO [+] Finished running step: step_one +INFO Finished execution of sub ttp file +INFO [+] Finished running step: first_sub_ttp +INFO [+] Running current step: second_sub_ttp +INFO [*] Executing Sub TTP: second_sub_ttp +INFO [+] Running current step: step_one +INFO ========= Executing ========== +you said testing +INFO ========= Done ========== +INFO [+] Finished running step: step_one +INFO Finished execution of sub ttp file +INFO [+] Finished running step: second_sub_ttp +INFO [*] Completed TTP +INFO [*] Starting Cleanup +INFO ========= Executing ========== +cleanup my_sub_ttp_2 +INFO ========= Done ========== +INFO ========= Executing ========== +cleanup my_sub_ttp_1 +INFO ========= Done ========== +INFO [*] Cleanup Complete +``` diff --git a/ttps/examples/sub-ttps/example.yaml b/ttps/examples/sub-ttps/sub-ttps.yaml similarity index 100% rename from ttps/examples/sub-ttps/example.yaml rename to ttps/examples/sub-ttps/sub-ttps.yaml