Docker-in-Docker (DinD) capabilities of public runners deactivated. More info

README.md 22 KB
Newer Older
Gabriel.Moreau's avatar
Gabriel.Moreau committed
1
# SWMB - Secure Windows Mode Batch
MOREAU Gabriel's avatar
MOREAU Gabriel committed
2

Gabriel Moreau's avatar
Gabriel Moreau committed
3
## Main links
Gabriel Moreau's avatar
Gabriel Moreau committed
4

Gabriel Moreau's avatar
Gabriel Moreau committed
5 6 7
 * The latest version of the SWMB **documentation** can be found [online](https://resinfo-gt.pages.in2p3.fr/swmb/resinfo-swmb/docs/).
 * The latest version of the SWMB **setup installer** is available on the [download page](https://resinfo-gt.pages.in2p3.fr/swmb/resinfo-swmb/).

8
**Main sub-menu**:
9

Gabriel Moreau's avatar
Gabriel Moreau committed
10 11 12 13
 * [CONTRIBUTING](./CONTRIBUTING.md)
 * [FAQ](./FAQ.md)
 * [LICENSE](./LICENSE.md)
 * [NEWS](./NEWS.md)
Gabriel Moreau's avatar
Gabriel Moreau committed
14
 * [REFERENCES](./REFERENCES.md)
Gabriel Moreau's avatar
Gabriel Moreau committed
15 16
 * [USE CASE (distribution)](./dists/README.md)

Gabriel Moreau's avatar
Gabriel Moreau committed
17 18
## Preamble

19 20 21 22
This is a PowerShell script for automation of routine tasks done after fresh installations of Windows 10 and Windows Server 2016 / 2019.
This is by no means any complete set of all existing Windows tweaks and neither is it another "antispying" type of script.
It's simply a setting which I like to use and which in my opinion make the system less obtrusive.

Gabriel Moreau's avatar
Gabriel Moreau committed
23 24 25
SWMB is a project from the SWMB working group of the RESINFO business network of CNRS and the French higher education.
It is about managing security, confidentiality and privacy under the Windows 10 operating system with the help of scripts,
thus without using a graphical interface.
26
The objective is to be able to easily deploy security tweaks (strategy) on a computer park,
Gabriel Moreau's avatar
Gabriel Moreau committed
27 28 29 30 31 32 33 34 35 36 37
whether or not the computers are in an Active Directory domain.
In a concern of tracing (quality) and knowledge sharing, all possible actions are readable in a text format.
The chosen programming language is Microsoft Powershell.
All the code and documentation is available on a Git forge.

The choice to implement a scripting system is therefore a complementary choice to a solution with GPO associated with Active Directory servers.
The question of how SWMB is deployed on the workstations is not directly linked to the SWMB project itself.
It is software like any other and can therefore be integrated into any configuration management system.

The project is intended to be modular.
It must be easy to maintain, easy to understand, easy to extend and easy to use.
Gabriel Moreau's avatar
Gabriel Moreau committed
38
The website [comparison-of-windows-10-privacy-tools](https://www.ghacks.net/2015/08/14/comparison-of-windows-10-privacy-tools/) references many possible solutions.
Gabriel Moreau's avatar
Gabriel Moreau committed
39 40 41 42
SWMB chose to take as a starting point the code of Disassembler0 which is now archived: `Win10-Initial-Setup-Script`,
because it met all our criteria above.

Regarding the applicable security strategies,
43 44
SWMB is mainly based on the tweaks enacted by the French National Agency for Information Systems Security ([ANSSI](https://www.ssi.gouv.fr/)).
There are thus three levels of possible tweaks in SWMB:
45

46
 * `Modules\SWMB\Win10` - tweaks extracted from the ANSSI documentation, or from certain instructions of the RSSI of the CNRS,
Gabriel Moreau's avatar
Gabriel Moreau committed
47
    applicable in the whole ESR (Higher Education and Research in France);
48 49
 * `Modules\SWMB\Custom` - interesting tweaks that you can extend for your site.
 * `Modules\SWMB\Experimental` - future tweaks under active development and not fully tested.
Gabriel Moreau's avatar
Gabriel Moreau committed
50
    Feedback from users may be interesting.
51 52

Each tweak can be enabled (`enable`) or disabled (`disable`) very easily in a configuration file (`preset`).
Gabriel Moreau's avatar
Gabriel Moreau committed
53
Sample files are available.
54
Each tweak is associated with a comment in French or English referring to its origin.
Gabriel Moreau's avatar
Gabriel Moreau committed
55 56 57
The French language has sometimes been chosen in order to follow the ANSSI's terminology
and because of the French version of Windows 10 which is used in most of our computers in the ESR.

58
For `Custom` tweaks, it is possible to set them with a variable file in order to adapt them to your park.
Gabriel Moreau's avatar
Gabriel Moreau committed
59
A set of default parameters is proposed.
60 61
The other tweaks are not configurable, because they are, at first, to take or to leave!
The upstream project on which we based ourselves had not planned to be able to parameterize tweaks.
Gabriel Moreau's avatar
Gabriel Moreau committed
62 63 64
It is an extension that we added.

**Some references**:
65

Gabriel Moreau's avatar
Gabriel Moreau committed
66
 * Upstream project [Win10-Initial-Setup-Script](https://github.com/Disassembler0/Win10-Initial-Setup-Script) by Disassembler0 user
Gabriel Moreau's avatar
Gabriel Moreau committed
67
 * Document from the [ANSSI](https://fr.wikipedia.org/wiki/Agence_nationale_de_la_s%C3%A9curit%C3%A9_des_syst%C3%A8mes_d%27information)
Gabriel Moreau's avatar
Gabriel Moreau committed
68
   (Agence Nationale de la Sécurité des Systèmes d'Information - France) :
Gabriel Moreau's avatar
Gabriel Moreau committed
69
   [restreindre-la-collecte-de-donnees-sous-windows-10](https://www.ssi.gouv.fr/administration/guide/restreindre-la-collecte-de-donnees-sous-windows-10/)
Gabriel Moreau's avatar
Gabriel Moreau committed
70 71
 * Document of the [BSI](https://fr.wikipedia.org/wiki/Office_f%C3%A9d%C3%A9ral_de_la_s%C3%A9curit%C3%A9_des_technologies_de_l%27information)
   (Federal Office for Information Technology Security - Germany) :
Gabriel Moreau's avatar
Gabriel Moreau committed
72
   [Hardening_Guideline.pdf](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Cyber-Security/SiSyPHuS/AP11/Hardening_Guideline.pdf)
73
 * [Sécuriser son parc Windows avec le projet modulaire et communautaire SWMB](https://hal.archives-ouvertes.fr/hal-03608835) (french 2022)
Olivier De Marchi's avatar
Olivier De Marchi committed
74

Gabriel Moreau's avatar
Gabriel Moreau committed
75
More references on the page [REFERENCES](./REFERENCES.md).
76 77


Gabriel Moreau's avatar
Gabriel Moreau committed
78 79
## Installation

Gabriel Moreau's avatar
Gabriel Moreau committed
80 81
You can find on the [download page](https://resinfo-gt.pages.in2p3.fr/swmb/resinfo-swmb/) the latest versions of the SWMB setup installer,
and also a [WAPT](https://www.wapt.fr) package, a ZIP archive usable with [OCS inventory](https://ocsinventory-ng.org/)...
Gabriel Moreau's avatar
Gabriel Moreau committed
82 83
These setup packages are made with the [NSIS](https://sf.net/projects/nsis/) software (Nullsoft Scriptable Install System).
It is possible not to install and activate scheduled tasks at computer startup and user logon.
Gabriel Moreau's avatar
Gabriel Moreau committed
84

Gabriel Moreau's avatar
Gabriel Moreau committed
85 86 87
![SWMB Graphical Installer 1](Images/swmb-setup-1.png)
![SWMB Graphical Installer 2](Images/swmb-setup-2.png)

Gabriel Moreau's avatar
Gabriel Moreau committed
88
It is possible to do a silent installation with the `/S` flag.
Gabriel Moreau's avatar
Gabriel Moreau committed
89 90 91 92 93 94 95
The `/ACTIVATED_PRESET` flag can be set to 0 if you do not want the default presets
to be installed for predefined scheduled tasks (see [Tasks](#task)).

```
SWMB-Setup-XXX.XXX.XXX.exe /S /ACTIVATED_PRESET=0
```

96 97
You will also find, in the [dists](dists) directory, examples of deployment or use
of the SWMB software environment
Gabriel Moreau's avatar
Gabriel Moreau committed
98
(manual, at machine startup, with [OCS inventory](https://ocsinventory-ng.org/),
99 100
[WAPT](https://www.wapt.fr) package, volume encryption,
uninstall [Kasperky Endpoint](dists/uninstall-kaspersky/README.md)...).
Gabriel Moreau's avatar
Gabriel Moreau committed
101

Gabriel Moreau's avatar
Gabriel Moreau committed
102 103 104 105 106 107 108
 * Please note that the uninstallation of
[Kaspersky Endpoint](dists/uninstall-kaspersky/README.md)
and its network agent on the client computer is a stand-alone distribution
in the form of an archive that is self-sufficient
and does not need to be installed on the computer.

 * The [README](dists/manual-use/README.md) file in the "manual-use" directory
Gabriel Moreau's avatar
Gabriel Moreau committed
109
reminds some principles about Powershell execution policies.
Gabriel Moreau's avatar
Gabriel Moreau committed
110 111


Olivier De Marchi's avatar
Olivier De Marchi committed
112 113
## Usage

114 115 116 117 118 119 120 121 122
If you just want to run the script with the default preset,
download and unpack the [latest release](https://github.com/Disassembler0/Win10-Initial-Setup-Script/releases)
and then simply double-click on the *Default.cmd* file and confirm *User Account Control* prompt.
Make sure your account is a member of *Administrators* group as the script attempts to run with elevated privileges.

The script supports command line options and parameters which can help you customize the tweak selection or even add your own custom tweaks,
however these features require some basic knowledge of command line usage and PowerShell scripting.
Refer to [Advanced usage](#advanced-usage) section for more details.

Gabriel Moreau's avatar
Gabriel Moreau committed
123
### Direct use from PowerShell
Olivier De Marchi's avatar
Olivier De Marchi committed
124

Gabriel Moreau's avatar
Gabriel Moreau committed
125
```ps1
Gabriel Moreau's avatar
Gabriel Moreau committed
126 127
# Execution of a single function / tweak
.\swmb.ps1 NameOfTheTweak
Gabriel.Moreau's avatar
Gabriel.Moreau committed
128

Gabriel Moreau's avatar
Gabriel Moreau committed
129 130
# Execution of a preset of tweaks
.\swmb.ps1 -preset "Presets\LocalMachine-Default.preset"
Gabriel.Moreau's avatar
Gabriel.Moreau committed
131
```
Olivier De Marchi's avatar
Olivier De Marchi committed
132

Gabriel Moreau's avatar
Gabriel Moreau committed
133
### Integrated use in a PowerShell script
Gabriel Moreau's avatar
Gabriel Moreau committed
134 135

```ps1
Gabriel Moreau's avatar
Gabriel Moreau committed
136 137
# Loading the SWMB base engine with all the main modules (neested)
# Put only SWMB.psm1 if you want only the core
Gabriel Moreau's avatar
Gabriel Moreau committed
138 139 140 141 142
Import-Module Modules\SWMB.psd1

# Initialize
SWMB_Init

Gabriel Moreau's avatar
Gabriel Moreau committed
143 144
# Load a preset file (can be called several times)
# Each preset file is a suite of tweaks
Gabriel Moreau's avatar
Gabriel Moreau committed
145
SWMB_LoadTweakFile "Presets\LocalMachine-Default.preset"
Gabriel Moreau's avatar
Gabriel Moreau committed
146

Gabriel Moreau's avatar
Gabriel Moreau committed
147
# Load one tweak (can be called multiple times)
148
# Unloads the tweak if it starts with the exclamation mark (!)
Gabriel Moreau's avatar
Gabriel Moreau committed
149 150
SWMB_AddOrRemoveTweak "NomFonction"

Gabriel Moreau's avatar
Gabriel Moreau committed
151
# If you want to check the consistency of tweaks
Gabriel Moreau's avatar
Gabriel Moreau committed
152 153
SWMB_CheckTweaks

Gabriel Moreau's avatar
Gabriel Moreau committed
154
# Execute all loaded tweaks (presets)
Gabriel Moreau's avatar
Gabriel Moreau committed
155 156 157
SWMB_RunTweaks
```

158 159 160 161 162 163 164 165 166 167
### Advanced usage

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File swmb.ps1 [-import filename] [-preset filename] [-log logname] [[!]tweakname]

    -import filename        load module with user-defined tweaks
    -preset filename        load preset with tweak names to apply
    -log logname            save script output to a file
    tweakname               apply tweak with this particular name
    !tweakname              remove tweak with this particular name from selection

Gabriel Moreau's avatar
Gabriel Moreau committed
168
### All command line option
Gabriel Moreau's avatar
Gabriel Moreau committed
169 170

`swmb.ps1` currently supports the following parameters:
Gabriel Moreau's avatar
Gabriel Moreau committed
171

Gabriel Moreau's avatar
Gabriel Moreau committed
172 173 174
 * `-core` : if used, it must be the first option.
   Import only the core (minimal) module `SWMB.psm1`,
   not all the neested module declared in `SWMB.psd1`.
Gabriel Moreau's avatar
Gabriel Moreau committed
175
 * `-import module_file.psm1` : imports the module into SWMB.
Gabriel Moreau's avatar
Gabriel Moreau committed
176 177
   You can extend SWMB, as is, with your own tweaks.
   This option can be declare as many times as necessary.
Gabriel Moreau's avatar
Gabriel Moreau committed
178
 * `-preset preset_file.preset` : loads all the tweak groups defined in a preset file.
Gabriel Moreau's avatar
Gabriel Moreau committed
179 180 181 182 183
   This option can be declared as many times as necessary.
 * `-log log_file` : messages will be written to the log file file
   and not in the terminal.
 * `-check` : does not execute the tweaks but only checks if they exist
   (in accordance with the preset file).
Gabriel Moreau's avatar
Gabriel Moreau committed
184
 * `-print` : does not execute the tweaks but only print them.
185
 * `-version` : print the SWMB version.
Gabriel Moreau's avatar
Gabriel Moreau committed
186 187
 * `-exp` : this is just a shortcut to import the `Experimental.psm1` module.
   This option is mainly used by developers to help test new tweaks.
Gabriel Moreau's avatar
Gabriel Moreau committed
188
 * `-hash hash_file.hash` makes a hash of the tweak list (preset)
Gabriel Moreau's avatar
Gabriel Moreau committed
189 190 191 192
   and compares it with the old hash stored in filename.
   If the hashes differ, a system checkpoint is performed.
   It is a good idea to put the hash file in the `C:\ProgramData\SWMB\Caches` folder
   with the name of the most important preset followed by the `.hash` extension.
Gabriel Moreau's avatar
Gabriel Moreau committed
193

Gabriel Moreau's avatar
Gabriel Moreau committed
194 195 196 197 198 199 200 201 202
### Graphical User Interface

There is a minimal graphical user interface.
A link to it appears in the start menu under the name SWMB Secure Windows.
This interface allows to force the execution of some tasks: boot, disk encryption...
There is also a version number check.

![SWMB Graphical User Interface](Images/capture-wisemoui.png)

Gabriel Moreau's avatar
Gabriel Moreau committed
203 204 205 206 207 208 209
### Tasks

The goal is not to change anything in the SWMB installation folder.
Two scheduled tasks are configured.
One takes place at machine startup (Boot) and the other at user login (Logon).

These two tasks will look for their parameters in the `C:\ProgramData\SWMB\Presets` folder.
210

Gabriel Moreau's avatar
Gabriel Moreau committed
211 212 213
 * CurrentUser-Logon.ps1 - Load preset at user logon `C:\ProgramData\SWMB\Presets\CurrentUser-Logon.preset`
 * LocalMachine-Boot.ps - Load preset  at boot `C:\ProgramData\SWMB\Presets\LocalMachine-Boot.preset`

Gabriel Moreau's avatar
Gabriel Moreau committed
214
By default, the presets [CurrentUser-Logon-Recommanded.preset](Presets/CurrentUser-Logon-Recommanded.preset)
Gabriel Moreau's avatar
Gabriel Moreau committed
215 216 217 218 219 220 221 222
and [LocalMachine-Boot-Recommanded.preset](Presets/LocalMachine-Boot-Recommanded.preset) are copied
to the `C:\ProgramData\SWMB\Presets` folder.
They are automatically updated with each new version of SWMB because they contain the magic string "`file automatically updated`".
If you have your own preset files, they will not be updated.
Moreover, during the installation,
it is possible not to set these preset files by default by unchecking a box in the installer
(flag `/ACTIVATED_PRESET=0` in command line).

Gabriel Moreau's avatar
Gabriel Moreau committed
223 224 225 226 227 228 229 230 231 232 233 234 235
If a module with the same name (with extension `.psm1`) exist in the folder `C:\ProgramData\SWMB\Modules`,
it's will be import.

An event is created in Application journal at begin and end of the task.
Output of the task are redirected in a log file inside the folder `C:\ProgramData\SWMB\Logs`.

Two preset `CurrentUser-Logon-Test.preset` and `LocalMachine-Boot-Test.preset`
are copied on folder `C:\ProgramData\SWMB\Presets`.
They could serve for test or as simple example.
Do not modify these examples directly, they will be updated in the next software update.
Rename them and modify them.


236 237 238 239 240 241 242 243 244 245 246
## Presets

The tweak library consists of separate idempotent functions, containing one tweak each. The functions can be grouped to *presets*.
Preset is simply a list of function names which should be called.
Any function which is not present or is commented in a preset will not be called, thus the corresponding tweak will not be applied.
In order for the script to do something, you need to supply at least one tweak library via `-import` and at least one tweak name,
either via `-preset` or directly as command line argument.

The tweak names can be prefixed with exclamation mark (`!`) which will instead cause the tweak to be removed from selection.
This is useful in cases when you want to apply the whole preset, but omit a few specific tweaks in the current run.
Alternatively, you can have a preset which "patches" another preset by adding and removing a small amount of tweaks.
GRAS David's avatar
GRAS David committed
247

Gabriel Moreau's avatar
Gabriel Moreau committed
248 249 250 251
The preset file is in practice a list of tweaks to apply.
There is one tweak per line.
It is possible to have empty lines, comments.
These are identified with the # character, as in many scripting languages.
Gabriel Moreau's avatar
Gabriel Moreau committed
252

Gabriel Moreau's avatar
Gabriel Moreau committed
253 254
The presets are classified in the folder `Presets`.
Currently, there is one preset per paragraph of the ANSSI concerning the settings for the computer configuration.
255

Gabriel Moreau's avatar
Gabriel Moreau committed
256 257 258 259 260
 * Telemetry preset
 * Cortana and search preset
 * User experience preset
 * Universal Applications preset
 * Cloud preset
Gabriel Moreau's avatar
Gabriel Moreau committed
261

Gabriel Moreau's avatar
Gabriel Moreau committed
262
**Prefix** - Moreover, some presets concern the computer while others concern the current user.
Gabriel Moreau's avatar
Gabriel Moreau committed
263 264 265 266
In one case, the tweaks affect the overall operation of the operating system and must be run as an administrator (or under the SYSTEM user),
in the other case, the actions are to be launched, for example at login, with the identity of the person.
Preset files are therefore prefixed with the extensions `LocalMachine-` and `CurrentUser-`.

Gabriel Moreau's avatar
Gabriel Moreau committed
267
It is possible to include a set of presets in another file with the keyword `$PRESET`.
Gabriel Moreau's avatar
Gabriel Moreau committed
268
The preset `LocalMachine-Default.preset` gathers all the recommended presets mentioned above for the machine.
Gabriel Moreau's avatar
Gabriel Moreau committed
269

Gabriel Moreau's avatar
Gabriel Moreau committed
270
**Path** -  It is possible to put a wildcard, for example `*`, in the name of a preset.
Gabriel Moreau's avatar
Gabriel Moreau committed
271
All presets that match the rule are then loaded.
Gabriel Moreau's avatar
Gabriel Moreau committed
272 273
It is also possible to have a space in the path name by protecting the entire string with double quotation marks `"`
(and only double quote), otherwise these quotation marks are optional.
Gabriel Moreau's avatar
Gabriel Moreau committed
274 275 276 277 278
The path can be both relative and absolute (local path to the machine like `C:\` or UNC network path starting with `\\`).
If you have a space and a double quote in your path,
it is always possible to put a wildcard like a `*` or a `?` to get around either one.
Normally, no standard path uses both symbols.

Gabriel Moreau's avatar
Gabriel Moreau committed
279
```ps1
Gabriel Moreau's avatar
Gabriel Moreau committed
280 281
$PRESET LocalMachine-Cloud.preset
$PRESET LocalMachine-CortanaSearch.preset
Gabriel Moreau's avatar
Gabriel Moreau committed
282 283 284 285 286
...
```
In order to facilitate the deployment,
the modularity and the management of programmed tasks,
it is also possible to import a module within a preset file, with the keyword `$IMPORT`.
Gabriel Moreau's avatar
Gabriel Moreau committed
287
This is the same way ans same rules for the path as the `$PRESET` keyword.
Gabriel Moreau's avatar
Gabriel Moreau committed
288
Note the support of wildcards in the name of the module to import, allowing to import several of them.
Gabriel Moreau's avatar
Gabriel Moreau committed
289
The module path must be relative to the preset file or absolute.
Gabriel Moreau's avatar
Gabriel Moreau committed
290 291
```ps1
$IMPORT ..\Modules\MyModule.psm1
Gabriel Moreau's avatar
Gabriel Moreau committed
292
$IMPORT "C:\Program Files\MyLocalProgram\Modules\MyModule.psm1"
Gabriel Moreau's avatar
Gabriel Moreau committed
293 294
```
You can import as many modules as you want.
Gabriel Moreau's avatar
Gabriel Moreau committed
295

GRAS David's avatar
GRAS David committed
296

297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
To supply a customized preset, you can either pass the function names directly as arguments.

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File swmb.ps1 -import Win10.psm1 EnableFirewall EnableDefender

Or you can create a file where you write the function names (one function name per line, no commas or quotes, whitespaces allowed, comments starting with `#`) and then pass the filename using `-preset` parameter.  
Example of a preset file `mypreset.txt`:

    # Security tweaks
    EnableFirewall
    EnableDefender

    # UI tweaks
    ShowKnownExtensions
    ShowHiddenFiles   # Only hidden, not system

Command using the preset file above:

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File swmb.ps1 -import Win10.psm1 -preset mypreset.txt

316 317
### Summary of the total number of tweaks

Gabriel Moreau's avatar
Gabriel Moreau committed
318 319 320 321 322 323 324 325 326 327 328 329 330 331
 | Status | Number of tweaks                       |      |      |      |
 | :---   | :---                                   | ---: | ---: | ---: |
 | Info   | Number of RESINFO tweaks               |      |      |   84 |
 | Info   | Number of Enable and Disable tweaks    |  179 |  179 |  358 |
 | Info   | Number of Install and Uninstall tweaks |   20 |   20 |   40 |
 | Warn   | Number of Show and Hide tweaks         |   56 |   53 |  109 |
 | Info   | Number of Add and Remove tweaks        |    3 |    3 |    6 |
 | Warn   | Number of Set and Unset tweaks         |   35 |    4 |   39 |
 | Warn   | Number of Pin and Unpin tweaks         |    0 |    2 |    2 |
 | Info   | Number of total tweaks GPO             |      |      |  554 |
 | Info   | Number of Sys tweaks (system)          |      |      |    9 |
 | Info   | Number of View tweaks (debug)          |      |      |    7 |
 | Info   | Number of Obsolete tweaks              |      |      |    3 |
 | Info   | Number of total tweaks functions       |      |      |  573 |
332 333

### Import your lib
334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368

The script also supports inclusion of custom tweaks from user-supplied modules passed via `-import` parameter. The content of the user-supplied module is completely up to the user, however it is strongly recommended to have the tweaks separated in respective functions as the main tweak library has. The user-supplied scripts are loaded into the main script via `Import-Module`, so the library should ideally be a `.psm1` PowerShell module. 
Example of a user-supplied tweak library `mytweaks.psm1`:

```powershell
Function MyTweak1 {
    Write-Output "Running MyTweak1..."
    # Do something
}

Function MyTweak2 {
    Write-Output "Running MyTweak2..."
    # Do something else
}
```

Command using the script above:

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File swmb.ps1 -import mytweaks.psm1 MyTweak1 MyTweak2

### Combination

All features described above can be combined. You can have a preset which includes both tweaks from the original script and your personal ones. Both `-import` and `-preset` options can be used more than once, so you can split your tweaks into groups and then combine them based on your current needs. The `-import` modules are always imported before the first tweak is applied, so the order of the command line parameters doesn't matter and neither does the order of the tweaks (except for `RequireAdmin`, which should always be called first and `Restart`, which should be always called last). It can happen that some tweaks are applied more than once during a singe run because you have them in multiple presets. That shouldn't cause any problems as the tweaks are idempotent.  
Example of a preset file `otherpreset.txt`:

    MyTweak1
    MyTweak2
    !ShowHiddenFiles   # Will remove the tweak from selection
    WaitForKey

Command using all three examples combined:

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File swmb.ps1 -import Win10.psm1 -import mytweaks.psm1 -preset mypreset.txt -preset otherpreset.txt Restart


369
### Definition of your own variable values
Gabriel.Moreau's avatar
Gabriel.Moreau committed
370

371
If you want to define your own variable values used in the `Custom.psm1` module, do the following:
372

373 374 375
 * Create a file named `Custom-VarOverload.psm1` in the same directory as the `Custom-VarDefault.psm1` module,
   or in any parent `..` or sub-folder `Modules` of a parent folder!
   This leaves a lot of choices...
376
   It's also possible to create it inside the program data folder dedicated to SWMB
Gabriel Moreau's avatar
Gabriel Moreau committed
377
   (`C:\ProgramData\SWMB\Modules`).
378 379 380
 * Set the hash values of your global variables
   (Don't change the whole hash table like in the `Custom-VarDefault.psm1` file)
 * Example:
381
   ```ps
382
   $Global:SWMB_Custom.NTP_ManualPeerList = "0.fr.pool.ntp.org, 1.fr.pool.ntp.org"
383
   ```
Gabriel Moreau's avatar
Gabriel Moreau committed
384

Gabriel Moreau's avatar
Gabriel Moreau committed
385
Order in which the `Custom-VarOverload.psm1` module will be loaded into memory:
Gabriel Moreau's avatar
Gabriel Moreau committed
386 387 388 389 390 391 392 393
first to the current folder (`(Get-Location).Path`),
second to the program data folder
and last to the module installation folder.
For each of these folders, it will recursively search folder after folder
until it reaches the root folder.

 1. `.\Custom-VarOverload.psm1`
 1. `.\Modules\Custom-VarOverload.psm1`
Gabriel Moreau's avatar
Gabriel Moreau committed
394 395 396 397 398
 1. `..\Custom-VarOverload.psm1`
 1. `..\Modules\Custom-VarOverload.psm1`
 1. `..\..\Custom-VarOverload.psm1`
 1. `..\..\Modules\Custom-VarOverload.psm1`
 1. and so on...
Gabriel Moreau's avatar
Gabriel Moreau committed
399 400 401 402 403
 1. `$Env:ProgramData\SWMB\Custom-VarOverload.psm1`
 1. `$Env:ProgramData\SWMB\Modules\Custom-VarOverload.psm1`
 1. and so on...
 1. `$Env:ProgramFiles\SWMB\Modules\SWMB\Custom-VarOverload.psm1`
 1. `$Env:ProgramFiles\SWMB\Modules\SWMB\Modules\Custom-VarOverload.psm1`
Gabriel Moreau's avatar
Gabriel Moreau committed
404

405 406
For sensitive keys, it is possible to define a `Custom-VarAutodel.psm1` module.
This one works exactly the same way as the `Custom-VarOverload.psm1` module
Gabriel Moreau's avatar
Gabriel Moreau committed
407
except that SWMB **deletes this module file** for security reasons right **after loading** it into memory.
408
So it is only valid once unless you recreate it between two SWMB launches.
GRAS David's avatar
GRAS David committed
409

Gabriel Moreau's avatar
Gabriel Moreau committed
410
The module `Custom-VarAutodel.psm1` is searched in the same folder as the module `Custom-VarOverload.psm1`.
Gabriel Moreau's avatar
Gabriel Moreau committed
411
The `VarOverload` module **is loaded first** if it exists, however **both modules are loaded if they are in the same folder**.
Gabriel Moreau's avatar
Gabriel Moreau committed
412 413
The recursive search in subfolders stops as soon as one or both modules are found in a folder.

414 415 416 417 418 419 420 421 422 423 424 425 426
### Logging

If you'd like to store output from the script execution,
you can do so using `-log` parameter followed by a filename of the log file you want to create.
For example:

    powershell.exe -NoProfile -ExecutionPolicy Bypass -File swmb.ps1 -import Win10.psm1 -preset mypreset.txt -log myoutput.log

The logging is done using PowerShell `Start-Transcript` cmdlet,
which writes extra information about current environment (date, machine and user name, command used for execution etc.)
to the beginning of the file and logs both standard output and standard error streams.


Gabriel Moreau's avatar
Gabriel Moreau committed
427 428 429 430 431 432 433 434 435 436 437 438 439 440
### Integration into another Git project

One way to use SWMB is to integrate it in one of your projects as a Git subtree.
```bash
git remote add -f SWMB https://gitlab.in2p3.fr/resinfo-gt/swmb/resinfo-swmb.git
git subtree add --prefix SWMB/ SWMB master --squash
```

To update (synchronize) your repository with the SWMB project repository:
```bash
git subtree pull --prefix SWMB/ https://gitlab.in2p3.fr/resinfo-gt/swmb/resinfo-swmb.git master --squash
```

See [CONTRIBUTING](./CONTRIBUTING.md).