[DO NOT REVIEW] Just trying some things out with the docs

README.md

@@ -5,7 +5,96 @@
 [![Pre-Commit](https://github.com/facebookincubator/ForgeArmory/actions/workflows/pre-commit.yaml/badge.svg)](https://github.com/facebookincubator/ForgeArmory/actions/workflows/pre-commit.yaml)
 [![Renovate](https://github.com/facebookincubator/ForgeArmory/actions/workflows/renovate.yaml/badge.svg)](https://github.com/facebookincubator/ForgeArmory/actions/workflows/renovate.yaml)
 
-This repo hosts the community-driven TTPs that Meta's TTPForge can consume.
+TTPForge is a cyber attack simulation platform. This project promotes a
+Purple Team approach to cybersecurity with the following goals:
+
+* To help blue teams accurately measure their detection and response capabilities
+  through high-fidelity simulations of real attacker activity.
+* To help red teams improve the ROI/actionability of their findings by packaging
+  their attacks as automated, repeatable simulations.
+
+TTPForge allows you to automate  attacker tactics, techniques, and procedures (TTPs)
+using a powerful but easy-to-use YAML format. This repo 
+contains our open-source catalog of TTPForge-powered TTPs - 
+check out the links below to learn more: 
+
+* [Install TTPForge](#installation)
+* [TTPForge Design Philosophy](docs/foundations/design-philosophy.md)
+* [Writing TTPs with TTPForge](docs/foundations/writing-ttps.md)
+* [Our TTP Library](https://github.com/facebookincubator/ForgeArmory/tree/main/ttps)
+
+## Installation
+
+1. Get latest TTPForge release:
+
+   ```bash
+   bashutils_url="https://raw.githubusercontent.com/l50/dotfiles/main/bashutils"
+
+   bashutils_path="/tmp/bashutils"
+
+   if [[ ! -f "${bashutils_path}" ]]; then
+      curl -s "${bashutils_url}" -o "${bashutils_path}"
+   fi
+
+   source "${bashutils_path}"
+
+   fetchFromGithub "facebookincubator" "TTPForge" "latest" ttpforge
+   ```
+
+   At this point, the latest `ttpforge` release should be in
+   `~/.local/bin/ttpforge` and subsequently, the `$USER`'s `$PATH`.
+
+   If running in a stripped down system, you can add TTPForge to your `$PATH`
+   with the following command:
+
+   ```bash
+   export PATH=$HOME/.local/bin:$PATH
+   ```
+
+1. Initialize TTPForge configuration
+
+   This command will place a configuration file at the default location
+   `~/.ttpforge/config.yaml` and download the
+   [ForgeArmory](https://github.com/facebookincubator/ForgeArmory)
+   TTPs repository:
+
+   ```bash
+   ttpforge init
+   ```
+
+TTPForge is now ready to use - check out our [tutorial](#tutorial) to
+start exploring its capabilities.
+
+## Tutorial
+
+1. List available TTP repositories (should show `forgearmory`)
+
+   ```bash
+   ttpforge list repos
+   ```
+
+1. List available TTPs that you can run:
+
+   ```bash
+   ttpforge list ttps
+   ```
+
+1. Examine an example TTP:
+
+   ```bash
+   ttpforge show ttp forgearmory//examples/args/define-args.yaml
+   ```
+
+1. Run the specified example:
+
+   ```bash
+   ttpforge run \
+     forgearmory//examples/args/define-args.yaml \
+     --arg a_message="hello" \
+     --arg a_number=1337
+   ```
+
+1. Next, check out the Armory's collection of [TTPs](https://github.com/facebookincubator/ForgeArmory/tree/main/ttps) and learn to [write your own TTPs](docs/foundations/writing-ttps.md) 
 
 ---
 

docs/foundations/args.md

@@ -0,0 +1,4 @@
+# Command-line Arguments: Making TTPs Configurable
+
+The TTPForge YAML format provides a rich syntax for specifying and validating
+command-line arguments and using them to control TTP execution.

docs/foundations/cleanup-actions.md

@@ -0,0 +1,73 @@
+# Reliable Post-Execution Cleanup
+
+## Goals 
+
+TTPs will often include destructive (or at the very least, messy) actions, such as:
+
+* Editing System Files (such as `/etc/sudoers` or `/root/.ssh/authorized_keys`)
+* Killing/Disabling Critical System Services (especially endpoint security solutions such as MDE)
+* Launching Cloud Resources (EC2 Instances/Docker Containers/Kubernetes Pods)
+
+Failure to clean up properly after such activity will at the very least inconvenience the user, 
+and at worst may actually create severe new security vulnerabilities in the target system. 
+
+Interpreter scripts usually lack standardized, platform-independent, and reliable methods for
+cleaning up attacker activity. In particular, it is especially difficult to ensure that these clean up
+processes are resilient to runtime errors. For example, when writing TTPs in bash, one would
+need to make very careful use of the [trap](https://tldp.org/LDP/Bash-Beginners-Guide/html/sect_12_02.html) feature.
+
+TTPForge's native support for cleanup actions provides users
+a reliable solution to these problems.
+
+## A Basic Cleanup Action
+
+Every [step](steps.md) in a TTPForge TTP can be associated with a specific cleanup action.
+For example, we could create a cleanup action that removes a file created during the 
+execution of the TTP, as shown below:
+
+https://github.com/facebookincubator/TTPForge/blob/main/cmd/test-resources/repos/example-ttps/cleanup/single.yaml
+
+This cleanup action will be executed once the TTP completes.
+Cleanup actions are most commonly `inline:` commands, as in the example above. 
+However, you can use any valid TTPForge step type as a cleanup action.
+
+## Multiple Cleanup Actions for Multiple Steps
+
+If we have multiple steps, we can create an appropriate cleanup action for each one.
+The example TTP below demonstrates how this works - for clarity, we've simplified the actual
+commands by replacing them with placeholders:
+
+https://github.com/facebookincubator/TTPForge/blob/main/cmd/test-resources/repos/example-ttps/cleanup/multiple.yaml
+
+This example highlights a crucial TTPForge feature: cleanup actions are run in last-in, 
+first-out (LIFO) order. Therefore, In this example, the malicious launch agent will be deleted prior to
+re-enabling EDR. This is critical; if cleanup actions were instead run in the same
+order as the steps themselves (first in, first out), then defenders would 
+receive unrealistic signal (EDR would detect the payload) and the fidelity of the simulation
+would be compromised. 
+
+## Fault Tolerance - Cleaning When Things Go Wrong
+
+If a particular step from the TTP fails to execute, prior steps that already executed
+still need to be cleaned up properly. Therefore, after each step, the corresponding 
+cleanup action is enqueued and, in the case of failure, all enqueued steps are executed
+in reverse (LIFO) order. The below TTP illustrates this behavior:
+
+https://github.com/facebookincubator/TTPForge/blob/main/cmd/test-resources/repos/example-ttps/cleanup/lifo.yaml
+
+As the third step is guaranteed to fail, 
+this TTP will always print the following cleanup activity
+
+```
+cleaning up second step
+cleaning up first step
+```
+
+## Delaying or Disabling Cleanup
+
+Sometimes, one may wish to execute a given TTP and then to leave the target system in 
+a "dirty" state for further analysis. For these purposes, TTPForge provides
+two useful command line flags for the `ttpforge run` command:
+
+* `--cleanup-delay-seconds` - delay cleanup execution for the specified integer number of seconds
+* `--no-cleanup` - do not run any cleanup actions; instead, simply exit when the last step completes.

docs/foundations/design-philosophy.md

@@ -0,0 +1,16 @@
+# Design Philosophy - TTPForge
+
+By far the fastest and easiest way to create an automated simulation of 
+attacker TTPs is to simply write a script that downloads
+any required attacker tooling and then runs the appropriate commands. 
+We'll refer to all such scripts (bash/powershell/python/etc.) as "interpreter scripts."
+Interpreter scripts are delightfully simple and quick to implement; 
+however, attempts to scale attack simulation efforts based on collections of interpreter
+scripts quickly run into a variety of problems listed below. TTPForge attempts to solve
+these problems while keeping TTP development just as fast and simple as interpreter scripts
+- click each link to see how the project aims to address that particular challenge:
+
+1. [High-Fidelity Telemetry Generation](steps.md)
+1. [Reliable Post-Execution Cleanup](cleanup-actions.md)
+1. [Convenient and Powerful Command Line Arguments](args.md)
+1. [Composability - Avoiding Reinventing the Wheel](steps.md#subttp-step)

docs/foundations/steps.md

@@ -0,0 +1,59 @@
+# Steps
+
+Relying on interpreter scripts for attack simulation will often provide defenders with logs/telemetry
+that differs from what they would observer in real cyber threat situations. For instance,
+an attacker who is maliciously editing a configuration file is unlikely to
+do so by running a shell command such as:
+
+```
+sed -ie 's/benign/malicious/' sabotaged.cfg
+```
+
+The code above will generate a varienty of indicators of compromise (IOCs) that would be visible
+to defenders: 
+
+1. Shell History Logs 
+1. Process Execution Logs
+
+In reality, an attacker would likely simply edit the file with an existing editor program (such as VS Code)
+or modify it directly from their C2 implant with no shell involved. Raw file modification telemetry
+would likely be necessary to detect this malicious action, and the attack simulation should reflect
+that reality. 
+
+TTPForge solves this problem by providing a wide range of native YAML-based steps from 
+which attack chains can be constructed. These steps (downloading files, editing files, etc.) are
+natively built into the TTPForge engine itself and do not produce unrealistic shell history telemetry.
+
+Note that the logs associated with execution of `ttpforge` itself from an interactive shell might be considered undesirable telemetry in certain situations - should this be the case, one can consider
+obfuscating `ttpforge` by renaming the binary or employing purpose-built obfuscation tools such as
+[garble](https://github.com/burrowers/garble).
+
+Each of TTPForge's step types is described below.
+
+# Create File Step
+
+This step will create a file the specified contents 
+on disk. Example use cases include:
+
+* Writing a malicious `crontab` file to establish persistence.
+* Dropping a malicious PHP webshell in `/var/www/html`.
+
+Usage of the `create_file:` step is demonstrated below:
+
+https://github.com/facebookincubator/TTPForge/blob/main/ttps/examples/steps/create-file/create-file-example.yaml
+
+Run this example as follows:
+
+```bash
+ttpforge run forgearmory//examples/steps/edit-file/edit-file-example.yaml
+```
+
+[create_file](../../ttps/examples/steps/create-file/README.md)
+[edit_file](../../ttps/examples/steps/edit-file/README.md)
+
+COMING SOON
+
+`file:`
+`inline:`
+`fetch_uri:`
+`ttp:`