```{eval-rst}
.. image:: ../images/cropped-plus3it-logo-cmyk.png
:width: 140px
:alt: Powered by Plus3 IT Systems
:align: right
:target: https://www.plus3it.com
```
# Salt Contents Archive File
The SallStack contents archive contains three main file-hierarchies
- `pillar`
- `states`
- `winrepo`
## The `pillar` Directory-Tree
This directry-hierarchy contains the pillar-data that is used to govern the behavior of executed SaltStack states. If modifying SaltStack states' behavior from their defaults (or supplying mandatory parameters), place the modifications under this directory-hierarchy.
Any automation-formulae that make reference to Pillar data – typically such formulae will include a `pillar.example` or `pillar.example.yml` in their content-root directory – may have their behavior modified through content under this directory-tree. Typically, this directory-tree will contain a `common` directory-tree and a directory-tree for each supported deployment environment. Thus, if one is creating behavioral-controls for `dev`, `test` and `prod` [environments](#the-pillar-directory-tree), the `pillar` directory tree will contain:
- [`common` directory](#the-common-directory-tree)
- `dev` directory
- `prod` directory
- `test` directory
Each formula that should be executed for a given site and environment should reference each formula's previously-mentioned `pillar.example` or `pillar.example.yml` files. Relevant content should be placed into either the `common` directory's `init.sls` files or in the environment-specific `init.sls` files. See below discussions for which directories should be used for a given method of setting parameter values.
In addition, the top-level directory will contain a `top.sls` and (optionally) a `map.jinja` file. These files help Watchmaker's SaltStack components know what further content to execute.
### The `top.sls` file
The `top.sls` file-content will typically look like (taken from the [watchmaker-salt-content](https://github.com/plus3it/watchmaker-salt-content) project's [`pillar/top.sls`](https://raw.githubusercontent.com/plus3it/watchmaker-salt-content/master/pillar/top.sls) file):
```yaml
base:
'G@os_family:RedHat':
- common.ash-linux
- common.scap.elx
'G@os_family:Windows':
- common.ash-windows
- common.netbanner
- common.scap.windows
- common.winrepo
```
What this content does is selects a base set of Saltstack pillar-data to read in. This makes execution-customizations of selected saltstack formulae available for those formulae to consume. In the base-scenario (shown above), SaltStack will use the executing system's `os_family` to select which pillar-content to read in. Reading in only platform-relevant content helps reduce the amount of content that Saltstack has to read in.
```{eval-rst}
.. note::
This value can be queried-for/verified on a host with watchmaker installed by executing:
``salt-call -c /opt/watchmaker/salt/ --output text grains.get os_family``
On an Enterprise Linux system, this will produce:
``local: RedHat``
```
If further execution-customization content is desired to be made available to executing formulae, it may be set up here.
## The `map.jinja` file
The presence/use of a `map.jinja` file is optional in the `pillar` root-directory. Any `map.jinja` file within the `pillar` _hierarchy_ is designed to facilitate the loading of pillar data. The primary reason for having a `map.jinja` within the `pillar` root-directory is if there's common pillar data that needs to be shared across environments. If there's a need for such shared content, the pillar subdirectories would reference the shared file at `/map.jinja` (typically, if they reference a `map.jinja` file, at all, they will reference their "local" version by pointing at `map.jinja`).
### The `common` Directory-Tree
As the name suggest, this directory-tree contains parameter-values that should be the same across all configured environments. This directory _typically_ contains one or more subdirectories. Subdirectories will one-for-one match with the `common.` strings found in the top-level `pillar` directory's `top.sls` file. Each sub-directory will contain one or more `.sls` files that will contain the relevant, common-across-all-environments pillar (per-formula parameter value) data. Thus, if one has a `.../pillar/top.sls` that looks like (as shown in the `top.sls` file subsection):
```yaml
base:
'G@os_family:RedHat':
- common.ash-linux
- common.scap.elx
'G@os_family:Windows':
- common.ash-windows
- common.netbanner
- common.scap.windows
- common.winrepo
```
The `.../pillar/common` subdirectory will need to have the subdirectories:
- `ash-linux`
- `ash-windows`
- `netbanner`
- `scap`[^1]
- `winrepo`
Each of the above-listed subdirectories – with the exception of the `scap` subdirectory will have an `init.sls` file[^2]. Each of these files will contain parameter-dictionaries that align with invoked formulae's `pillar.example` or `pillar.example.yml` files.
To illustrate behavior tailoring, use the `.../pillar/common/ash-linux/init.sls` file with contents similar to:
```
{%- set os = salt.grains.filter_by({
'AlmaLinux': 'centos',
'CentOS': 'centos',
'CentOS Stream': 'centos',
'OEL': 'ol',
'RedHat': 'rhel',
'Rocky': 'centos',
}, grain='os') %}
ash-linux:
lookup:
scap-profile: stig
scap-cpe: /root/scap/content/openscap/ssg-rhel{{ grains['osmajorrelease'] }}-cpe-dictionary.xml
scap-xccdf: /root/scap/content/openscap/ssg-{{ os }}{{ grains['osmajorrelease'] }}-xccdf.xml
scap-ds: /root/scap/content/openscap/ssg-{{ os }}{{ grains['osmajorrelease'] }}-ds.xml
```
Then compare it to the ash-linux project's [pillar.example](https://raw.githubusercontent.com/plus3it/ash-linux-formula/master/pillar.example) file. The project's example file attempts to show available parameters whose values can be set/overridden and how they fit into the parameter-map's structure. In the above, the `ash-linux:lookup:scap-profile` parameter's value is set to `stig`. However, if one consult's the formula-project's `pillar.example` file, it's found that any of the values `stig-rhel7-server-gui-upstream`, `standard`, `pci-dss`, `C2S` or `common` are valid[^3].
As such, if one wanted to make the ash-linux-formula automation use a hardening-profile other than `stig`, one could specify any of the values found in that `pillar.example` file (e.g., change `stig` to `pci-dss` to use the `pci-dss` hardening-profile, instead).
Similarly, if one wanted to change where relevant SCAP-content should be loaded from the `scap-cpe`, `scap-xccdf` and/or `scap-ds` values could all be modified.
### The `` Directory-Tree(s)
The `` directory-trees work similarly to the `common` directory tree. The primary difference is focus. Where the `common` directory-tree sets broad-scope behaviors via pillar-variables' parameter/values, the `` directory-trees set more-limited scopes' behaviors. These directory-trees are intended to align with an infrastructure-as-code environment where an organization has multiple, similar environments that each have specific needs (e.g., to point to per-environment CSP endpoints, security-services servers, etc., install different sets of software or apply different security-benchmarks).
The structure for the `` directory-trees is much simpler than that for the `common` directory tree. There are no subdirectories under each `` directory, just a single `init.sls` file. These typically take the form of:
```
{%- load_yaml as os_families %}
RedHat:
:
lookup:
:
:
...
:
...
:
lookup:
:
:
...
:
Windows:
:
lookup:
:
:
...
:
...
:
lookup:
:
:
...
:
```
Each of the ``s listed above may be string, list, dictionary or map data-types. The data-type will be dictated by the needs of the formula and illustrated in the relevant formulae's `pillar.example` or `pillar.example.yml` files. For example, to configure the [mcafee-agent-formula](https://github.com/plus3it/mcafee-agent-formula/) to properly configure Trellix to run on Windows and Linux hosts in the `prod` environment, one would have a `.../pillar/prod/init.sls` file that looked something like:
```
{%- load_yaml as os_families %}
RedHat:
:
lookup:
:
:
...
:
trellix-agent:
lookup:
source: s3://enterprise-software/mcafee/mcafee-agent/5.7.9/install.sh
source_hash: s3://enterprise-software/mcafee/mcafee-agent/5.7.9/install.sh.SHA512
client_in_ports:
- 5575
client_out_ports:
- 80
- 443
...
:
lookup:
:
:
...
:
Windows:
:
lookup:
:
:
...
:
trellix-agent:
lookup:
version: '5.7.9.139'
winrepo:
versions:
'5.7.9.139':
installer: s3://enterprise-software/mcafee/mcafee-agent/5.7.9/FramePkg.exe
...
:
lookup:
:
:
...
:
```
The above would instruct the mcafee-agent-formula (see the automation's [pillar.example](https://raw.githubusercontent.com/plus3it/mcafee-agent-formula/master/pillar.example) file for insight) automation to:
- Linux: Download and execute the the Trellix 5.7.9 installer from the `s3://enterprise-software/mcafee/mcafee-agent/5.7.9/` bucket-path – and validate the file's integrity using the checksum file `install.sh.SHA512` from the same S3 bucket-path – and set up firewalld inbound exceptions for port tcp/5575 and outbound exceptions for ports 80/tcp and 443/tcp.
- Windows: Download and execute the Trellix "Frame" 5.7.9.139 package's executable-installer from the `s3://enterprise-software/mcafee/mcafee-agent/5.7.9/` bucket-path.
Similar `init.sls` content would be needed for any other Watchmaker formula used to install, configure or manage the execution of software.
## The `states` Directory-Tree
This directory-hierarchy governs _which_ Saltstack states will be executed from the available SaltStack formulae. Typically, only modification to this directory's `top.sls` is needed:
- States that are not desired for execution can be commented out or wholly removed.
- States that require conditional-execution can be placed inside of appropriate (Jinja) condition-blocks
- States that are beyond what's defined in the default `top.sls` can be added here to ensure their execution during a full run of watchmaker
- If a change in execution-order is desired, alter the list-order: listed states are executed serially in first-to-last order
## The `winrepo` Directory-Tree
This directory-hierarchy contains windows-specific automation-content. Unlike the `pillar` and `states` directory-trees, content in this directory-tree is not expected to be multi-platform.
[^1]: In the case of the `scap` directory (and content that functions similarly), instead of an `init.sls` file, it will instead have `.sls` files named to match what's in the `top.sls` file. In the illustrated case, that means a `elx.sls` and a `windows.sls` file.
[^2]: Formulae whose pillar-data is platform-separated such as the `scap` directory's typically will not need an `init.sls` file as the per-platform `.sls` files will directly-referenced and subsume the `init.sls` file's functionality.
[^3]: While efforts are made to keep the examples up to date and correct, it's possible that "valid" parameter-values listed in a given watchmaker-formula project's `pillar.example` file will become invalid over time. If one encounters incorrect or missing exmaple parameter content in a given formula project's `pillar.example` file, please open an issue against that project.