github.com/facebookincubator/ttpforge@v1.0.13-0.20240405153150-5ae801628835/docs/foundations/cleanup.md (about)

     1  # Reliable Post-Execution Cleanup of TTP Actions
     2  
     3  **Note**: to run the examples in this section, make sure you have the `examples`
     4  repository installed with `ttpforge list repos` and if not run:
     5  
     6  ```bash
     7  ttpforge install repo https://github.com/facebookincubator/TTPForge --name examples
     8  ```
     9  
    10  ## Goals
    11  
    12  TTPs will often include destructive (or at the very least, messy) actions, such
    13  as:
    14  
    15  - Editing System Files (such as `/etc/sudoers` or `/root/.ssh/authorized_keys`)
    16  - Killing/Disabling Critical System Services (especially endpoint security
    17    solutions such as MDE)
    18  - Launching Cloud Resources (EC2 Instances/Docker Containers/Kubernetes Pods)
    19  
    20  Failure to clean up properly after such activity will at the very least
    21  inconvenience the user, and at worst may actually create severe new security
    22  vulnerabilities in the target system.
    23  
    24  Interpreter scripts usually lack standardized, platform-independent, and
    25  reliable methods for cleaning up attacker activity. In particular, it is
    26  especially difficult to ensure that these clean up processes are resilient to
    27  runtime errors. For example, when writing TTPs in bash, one would need to make
    28  very careful use of the
    29  [trap](https://tldp.org/LDP/Bash-Beginners-Guide/html/sect_12_02.html) feature.
    30  
    31  TTPForge's native support for cleanup actions provides users with a reliable
    32  solution to these problems.
    33  
    34  ## Cleanup Basics
    35  
    36  Every step in a TTPForge TTP can be associated with a cleanup action. That
    37  cleanup action can be any valid TTPForge [action type](actions.md). Here's an
    38  example TTP with several steps that have associated cleanup actions:
    39  
    40  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/cleanup/basic.yaml#L1-L25
    41  
    42  You can run this example with the command:
    43  `ttpforge run examples//cleanup/basic.yaml` - based on the output, notice the
    44  following key aspects about how cleanup actions work:
    45  
    46  1. Every time a step completes successfully, its cleanup action is added to the
    47     cleanup queue.
    48  1. Not every step defines a cleanup action, and that's just fine. No cleanup
    49     action will be added to the queue upon completion of those steps.
    50  1. Once the TTP completes (or a step fails), the actions in the cleanup queue
    51     are executed in reverse (last-in, first-out) order.
    52  
    53  Pay particular attention to point (3) - TTPForge executes cleanup actions in
    54  reverse order because it is quite common for later steps to depend on earlier
    55  ones. For instance, one would definitely want the steps of the following
    56  scenario cleaned up in reverse order:
    57  
    58  1. Attacker adds self to `/etc/sudoers`
    59  1. Attacker loads a malicious kernel module for persistence.
    60  
    61  If we cleaned up step (1) first, we would then lose the privileges required to
    62  cleanup (2).
    63  
    64  ## Delaying or Disabling Cleanup
    65  
    66  Sometimes, one may wish to execute a given TTP and then to leave the target
    67  system in a "dirty" state for further analysis. For these purposes, TTPForge
    68  provides two useful command line flags for the `ttpforge run` command:
    69  
    70  - `--cleanup-delay-seconds` - delay cleanup execution for the specified integer
    71    number of seconds
    72  - `--no-cleanup` - do not run any cleanup actions; instead, simply exit when the
    73    last step completes.
    74  
    75  ## Default Cleanup Actions
    76  
    77  Certain action types (such as [create_file](actions/create_file.md) and
    78  [edit_file](actions/edit_file.md)) have a default cleanup action that can be
    79  invoked by specifying `cleanup: default` in their YAML configuration. In the
    80  case of `create_file`, the default cleanup action removes the created file.
    81  Check out the example below, which you can run with
    82  `ttpforge run examples//cleanup/default.yaml`:
    83  
    84  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/cleanup/default.yaml#L1-L12
    85  
    86  ## Handling Failures Gracefully
    87  
    88  Whenever a step fails, the cleanup process will begin from the last successful
    89  step (the step immediately preceding the failure). The example below (which you
    90  can run with `ttpforge run examples//cleanup/failure.yaml`) shows how cleanup
    91  actions gracefully handle the failure of a step:
    92  
    93  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/cleanup/failure.yaml#L1-L27
    94  
    95  Note that **we don't clean up the failed step itself**, because that is usually
    96  not desired behavior. Consider the following example situations:
    97  
    98  - The step failed to create file due to a permissions issue. The cleanup action
    99    to delete the file would also fail because the file was never created in the
   100    first place.
   101  - The step failed to setup a cloud resource due to a capacity constraint. The
   102    cleanup action to remove the resource would also fail because no resource was
   103    ever provisioned in the first place.
   104  
   105  If a cleanup action fails, all remaining cleanup actions in the queue are
   106  abandoned and not run. In this situation, it's likely that something is
   107  fundamentally wrong with the TTP/test system and we want to prompt the user to
   108  investigate rather than pushing forward and perhaps deleting something that we
   109  shouldn't.