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

     1  # Finding and Running TTPs
     2  
     3  ## TTP Repositories
     4  
     5  TTPs built with TTPForge are organized into collections called repositories.
     6  Each repository contains multiple TTPs that are grouped into categories. You can
     7  configure TTPForge with the default set of TTP repositories by running:
     8  
     9  ```bash
    10  ttpforge init
    11  ```
    12  
    13  You can then view the enabled TTP repositories by running:
    14  
    15  ```bash
    16  ttpforge list repos
    17  ```
    18  
    19  ## Listing and Examining TTPs in Repositories
    20  
    21  You can list the TTPs contained within all your TTP repositories as follows:
    22  
    23  ```bash
    24  ttpforge list ttps
    25  ```
    26  
    27  This will print a list of **TTP References**, which have the format
    28  `[repository name]//path/to/ttp`
    29  
    30  You can look at the configuration of any given TTP by running
    31  `ttpforge show ttp [ttp-reference]` - for example:
    32  
    33  ```bash
    34  ttpforge show ttp examples//cleanup/basic.yaml
    35  ```
    36  
    37  To learn more about the TTPForge YAML configuration format, check out the
    38  relevant [docs](actions.md).
    39  
    40  ## Running TTPs from Repositories
    41  
    42  You can execute any TTP from a TTP repository by passing the appropriate TTP
    43  reference to the `ttpforge run` command - for example:
    44  
    45  ```bash
    46  ttpforge run examples//cleanup/basic.yaml
    47  ```
    48  
    49  Note that you can also run TTPs by directly passing an (absolute or relative)
    50  path to the appropriate YAML file - this can be convenient when you are
    51  developing new TTPs and working with a local TTP repository checkout at a
    52  non-standard path.
    53  
    54  ## Removing and Installing TTP Repositories
    55  
    56  You can remove a TTP repository using the `ttpforge remove repo` command - we
    57  will demonstrate this on the `forgearmory` repo:
    58  
    59  ```bash
    60  ttpforge remove repo forgearmory
    61  ```
    62  
    63  Notice how the `forgearmory` entry has now disappeared from the output of
    64  `ttpforge list repos`. We can then reinstall that repository using the
    65  `ttpforge install repo` command:
    66  
    67  ```bash
    68  ttpforge install repo --name forgearmory https://github.com/facebookincubator/forgearmory
    69  ```
    70  
    71  The `ttpforge install` runs `git clone` under the hood, so it will work with any
    72  valid URL that you could pass to `git clone`.
    73  
    74  ## Creating Your Own TTP Repository
    75  
    76  In order to create your own TTP repository, whether for use at your own company
    77  or for open-source publication, you just need to:
    78  
    79  1. Create a Git Repository
    80  2. Add the appropriate
    81     [TTPForge Repository Configuration](#repository-configuration-files) file.
    82  
    83  You can then install your repository with `ttpforge install repo` as
    84  demonstrated above.
    85  
    86  ## How TTPForge Manages TTP Repos
    87  
    88  ### The Global TTPForge Configuration File
    89  
    90  TTPForge keeps track of the TTP repositories installed on your system by using
    91  the **TTPForge Global Configuration File**, which is stored at
    92  `~/.ttpforge/config.yaml` by default. Take a look inside that file (if it isn't
    93  there, you should run `ttpforge init`) - you should see contents similar to the
    94  following:
    95  
    96  ```yml
    97  ---
    98  repos:
    99    - name: examples
   100      path: repos/examples
   101      git:
   102        url: https://github.com/facebookincubator/TTPForge
   103    - name: forgearmory
   104      path: repos/forgearmory
   105      git:
   106        url: https://github.com/facebookincubator/forgearmory
   107  ```
   108  
   109  Each of the `path:` entries above is a _relative path_ that is interpreted based
   110  on the directory of the TTPForge configuration file. Therefore, in the above
   111  example, these repository paths map to `~/.ttpforge/repos/examples` and
   112  `~/.ttpforge/repos/forgearmory`. Feel free to `ls` those files and look around
   113  the TTP repositories.
   114  
   115  **Note**: One can also use absolute repository paths in this configuration file.
   116  This may be useful if your company maintains your own internal TTPForge
   117  repositories and assigns those internal repositories to standardized
   118  installation paths.
   119  
   120  ### Repository Configuration Files
   121  
   122  Each TTP repository contains a `ttpforge-repo-config.yaml` file in the
   123  repository root directory. This file specifies which folders within the
   124  repository contain TTPs that TTPForge should index. For example, you can examine
   125  the repository configuration file for the `examples` repo:
   126  
   127  ```bash
   128  cat ~/.ttpforge/repos/examples/ttpforge-repo-config.yaml
   129  ```
   130  
   131  You should see something like this, which tells TTPForge that the TTPs from this
   132  repository live in `example-ttps`:
   133  
   134  ```yml
   135  ---
   136  ttp_search_paths:
   137    - example-ttps
   138  ```
   139  
   140  Note that repository owners may add as many `ttp_search_path` entries as they
   141  wish.
   142  
   143  ### Using a Custom Configuration File
   144  
   145  You can override the global configuration file by passing the
   146  `-c [config-file-path]` option to any TTPForge command. You probably won't ever
   147  need to do this, although we do use this feature extensively in the unit tests
   148  for the TTPForge codebase itself.