docs: Documentation about gallia.toml and hooks

docs/config.md

@@ -0,0 +1,48 @@
+<!--
+SPDX-FileCopyrightText: AISEC Pentesting Team
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Configuration
+
+## gallia.toml
+
+All `gallia` settings stem from the commandline interface.
+The documentation for all available settings per subcommand is available via `-h/--help`.
+Frequently used settings can be put in a configfile which is called `gallia.toml`.
+Settings from the config file set the **default** of the respective commandline option.
+The config can always be overwritten by manually setting the relevant cli option.
+
+The configuration file `gallia.toml` is written in [TOML](https://toml.io/en/). 
+Inheritence is not supported; the first file is loaded.
+The `gallia.toml` file is loaded from these locations (in this particular order):
+
+* path specified in the env variable `GALLIA_CONFIG`; see {doc}`../env`.
+* current directory
+* current Git root (if the current directory is a Git repository)
+* `$XDG_CONFIG_HOME/gallia/gallia.toml`
+* `~/.config/gallia/gallia.toml`
+
+Only some cli options are exposed to the config file.
+The available config settings can be obtained from `gallia --template`.
+The output of `--template` is maintained to be up to date and is intended as a starting point.
+
+## Hooks
+
+`gallia` supports hooks for preparation or cleanup/postprocessing tasks.
+Alternatively, they can be useful for e.g. sending notifications about the exit_code via e.g. matrix or ntfy.sh.
+Hooks are shell scripts which are executed before (= pre-hook) or after (= post-hook) the `main()` method.
+These scripts can be specified via `--pre-hook` or `--post-hook` or via `gallia.toml` as well.
+
+The hook scripts have these environment variables set:
+
+GALLIA_HOOK
+: Either `pre` or `post`.
+
+GALLIA_ARTIFACTS_DIR
+: Path to the artifactsdir for the current testrun.
+
+GALLIA_EXIT_CODE
+: Only set for post-hooks; is set to the exit_code which `gallia` will use after the hook terminates.
+  For instance GALLIA_EXIT_CODE different from zero means that the current testrun failed.

docs/index.md

@@ -25,6 +25,7 @@ Acting as a generic interface, the [logging](https://fraunhofer-aisec.github.io/
 
 setup
 automation
+config
 transports
 env
 logging

src/gallia/command/base.py

@@ -140,7 +140,12 @@ def get_file_log_level(self, args: Namespace) -> Loglevel:
             return Loglevel.TRACE
         return Loglevel.TRACE if args.verbose >= 2 else Loglevel.DEBUG
 
-    def run_hook(self, variant: HookVariant, args: Namespace) -> None:
+    def run_hook(
+        self,
+        variant: HookVariant,
+        args: Namespace,
+        exit_code: int | None = None,
+    ) -> None:
         script = args.pre_hook if variant == HookVariant.PRE else args.post_hook
         if script is None:
             return
@@ -152,6 +157,9 @@ def run_hook(self, variant: HookVariant, args: Namespace) -> None:
             "GALLIA_HOOK": variant.value,
         } | os.environ
 
+        if exit_code is not None:
+            env |= {"GALLIA_EXIT_CODE": str(exit_code)}
+
         p = run(  # pylint: disable=subprocess-run-check
             script, env=env, text=True, capture_output=True, shell=True
         )
@@ -192,6 +200,11 @@ def configure_class_parser(self) -> None:
             default=self.config.get_value("gallia.post_hook", None),
             help="shell script to run after the main entry_point",
         )
+        group.add_argument(
+            "--skip-hooks",
+            action="store_true",
+            help="do not execute pre and post hooks",
+        )
         group.add_argument(
             "--lock-file",
             type=Path,
@@ -320,7 +333,8 @@ def entry_point(self, args: Namespace) -> int:
         else:
             setup_logging(self.get_log_level(args))
 
-        self.run_hook(HookVariant.PRE, args)
+        if not args.skip_hooks:
+            self.run_hook(HookVariant.PRE, args)
 
         exit_code = 0
         try:
@@ -350,7 +364,8 @@ def entry_point(self, args: Namespace) -> int:
                 )
                 self.logger.info(f"Stored artifacts at {self.artifacts_dir}")
 
-        self.run_hook(HookVariant.POST, args)
+        if not args.skip_hooks:
+            self.run_hook(HookVariant.POST, args, exit_code)
 
         if self._lock_file_fd is not None:
             self._release_flock()