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

     1  # TTPForge Actions: `edit_file`
     2  
     3  The `edit_file` action is useful for automating malicious modifications to files
     4  (for example, adding yourself to `/etc/sudoers` or commenting out important
     5  logging code). `edit_file` can append, delete, or replace lines in the target
     6  file - check out the examples below to learn more.
     7  
     8  ## Appending and Deleting Lines
     9  
    10  This example shows how to use the `append` and `delete` functionality of the
    11  `edit_file` action:
    12  
    13  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/actions/edit-file/append-delete.yaml#L1-L35
    14  
    15  You can experiment with the above TTP by installing the `examples` TTP
    16  repository (skip this if `ttpforge list repos` shows that the `examples` repo is
    17  already installed):
    18  
    19  ```bash
    20  ttpforge install repo https://github.com/facebookincubator/TTPForge --name examples
    21  ```
    22  
    23  and then running the below command:
    24  
    25  ```bash
    26  ttpforge run examples//actions/edit-file/append-delete.yaml
    27  ```
    28  
    29  ## Replacing Lines
    30  
    31  You can also use `edit_file` to replace lines in a file and optionally use
    32  powerful regular expressions to perform complex transformations. The next
    33  example shows this functionality in action:
    34  
    35  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/actions/edit-file/replace.yaml#L1-L47
    36  
    37  Try out the above TTP by running this command:
    38  
    39  ```bash
    40  ttpforge run examples//actions/edit-file/replace.yaml
    41  ```
    42  
    43  ## Fields
    44  
    45  You can specify the following YAML fields for the `edit_file` action:
    46  
    47  - `edit_file:` (type: `string`) the path to the file you want to edit (must
    48    exist).
    49  - `backup_file:` (type: `string`) the backup path to which the original file
    50    should be copied.
    51  - `edits:` (type: `list`) a list of edits to make. Each entry can contain the
    52    following fields:
    53    - `delete:` (type: `string`) string/pattern to delete - pair with
    54      `regexp: true` to treat as a Golang
    55      [regular expression](https://pkg.go.dev/regexp/syntax) and delete all
    56      matches thereof.
    57    - `append:` (type `string`) line(s) to append to the end of the file.
    58    - `old:` (type: `string`) string/pattern to replace - pair with `regexp: true`
    59      to treat as a Golang [regular expression](https://pkg.go.dev/regexp/syntax)
    60      and replace all matches thereof. Must always be paired with `new:`
    61    - `new:` (type: `string`) string with which to replace the string/pattern
    62      specified by `old:` - must always be paired with `old:`
    63  - `cleanup:` you can set this to `default` in order to automatically restore the
    64    original file once the TTP completes. **Note**: this only works when
    65    `backup_file` is set. You can also define a custom
    66    [cleanup action](https://github.com/facebookincubator/TTPForge/blob/main/docs/foundations/cleanup.md#cleanup-basics).
    67  
    68  ## Notes
    69  
    70  - `edit_file` will read the entire file into memory, perform all specified
    71    edits, and then write out the results. Be careful when using it against very
    72    large files.
    73  - `edit_file` does not support editing binary files.
    74  - The `edits` list is looped through from top to bottom and all edits are
    75    applied sequentially to the copy of the file contents residing in memory. This
    76    means, for example, that if you `append` and then later `delete` that same
    77    line, the resulting final file won't contain that line.