refac: added some type checking and fixed a duplicate bug (apparently)

Co-authored-by: Daan Selen <dselen@systemec.nl>

README.md

@@ -1,205 +1,282 @@
-> [!NOTE]
-> *If you experience issues or have suggestions, submit an issue! https://github.com/DaanSelen/meshbook/issues I'll respond ASAP!*
-
 # Meshbook
 
-A way to programmatically manage MeshCentral-managed machines, inspired by applications like [Ansible](https://github.com/ansible/ansible).<br>
-What problem does it solve? Well, what I wanted to be able to do is to automate system updates through [MeshCentral](https://github.com/ylianst/meshcentral). And some machines are behind unmanaged or 3rd party managed firewalls.<br>
-And many people will be comfortable with YAML configurations! It's almost like JSON, but different!<br>
+[![CodeQL Advanced](https://github.com/DaanSelen/meshbook/actions/workflows/codeql.yaml/badge.svg)](https://github.com/DaanSelen/meshbook/actions/workflows/codeql.yaml)
 
-# Quick-start:
+> \[!NOTE]
+> 💬 If you experience issues or have suggestions, [submit an issue](https://github.com/DaanSelen/meshbook/issues) — I'll respond ASAP!
 
-The quickest way to start is to grab a template from the templates folder in this repository.<br>
-Make sure to correctly pass the MeshCentral websocket API as `wss://<MeshCentral-Host>`.<br>
-And make sure to fill in the credentails of an account which has `Remote Commands`, `Details` and `Agent Console` permissions on the targeted devices or groups.<br>
+---
 
-> I did this through a "Service account" with rights on the device group.
+Meshbook is a tool to **programmatically manage MeshCentral-managed machines**, inspired by tools like [Ansible](https://github.com/ansible/ansible).
 
-Then make a yaml with a target and some commands! See below examples as a guideline. And do not forget to look at the bottom's notice.<br>
-To install, follow the following commands:<br>
+## What problem does it solve?
 
-### Linux setup:
+Meshbook is designed to:
+
+* Automate system updates or commands across multiple systems via [MeshCentral](https://github.com/Ylianst/MeshCentral), even behind third-party-managed firewalls.
+* Allow configuration using simple and readable **YAML files** (like Ansible playbooks).
+* Simplify the use of **group-based** or **tag-based** device targeting.
+
+---
+
+## 🏁 Quick Start
+
+### ✅ Prerequisites
+
+* Python 3.7+
+* Git
+* Access to a MeshCentral instance and credentials with:
+
+  * `Remote Commands`
+  * `Details`
+  * `Agent Console` permissions
+
+A service account with access to the relevant device groups is recommended.
+
+---
+
+### 🔧 Installation
+
+#### Linux
 
 ```bash
 git clone https://github.com/daanselen/meshbook
 cd ./meshbook
 python3 -m venv ./venv
 source ./venv/bin/activate
-pip3 install -r ./requirements.txt
+pip install -r requirements.txt
 cp ./templates/meshcentral.conf.template ./meshcentral.conf
 ```
 
-### Windows setup (PowerShell, not cmd):
+#### Windows (PowerShell)
 
-```shell
+```powershell
 git clone https://github.com/daanselen/meshbook
-cd ./meshbook
-python -m venv ./venv # or python3 when done through the Microsoft Store.
-.\venv\Scripts\activate # Make sure to check the terminal prefix.
-pip3 install -r ./requirements.txt
+cd .\meshbook
+python -m venv .\venv
+.\venv\Scripts\activate
+pip install -r .\requirements.txt
 cp .\templates\meshcentral.conf.template .\meshcentral.conf
 ```
 
-Now copy the configuration template from ./templates and fill it in with the correct details (remove .template from the file) this is shown in the last step of the setup(s).<br>
-The url should start with `wss://`.<br>
-You can check pre-made examples in the examples directory, make sure the values are set to your situation.<br>
-After this you can use meshbook, for example:
+> 📌 Rename `meshcentral.conf.template` to `meshcentral.conf` and fill in your actual connection details.
+> The URL must start with `wss://<MeshCentral-Host>`.
 
-### Linux run:
+---
+
+## 🚀 Running Meshbook
+
+Once installed and configured, run a playbook like this:
+
+### Linux:
 
 ```bash
-python3 .\meshbook.py -pb .\examples\echo.yaml
+python3 meshbook.py -pb ./examples/echo_example.yaml
 ```
 
-### Windows run:
+### Windows:
 
-```shell
+```powershell
 .\venv\Scripts\python.exe .\meshbook.py -pb .\examples\echo_example.yaml
 ```
 
-### How to check if everything is okay?
+Use `--help` to explore available command-line options:
 
-The python virtual environment can get messed up, therefore...<br>
-To check if everything is in working order, make sure that the lists from the following commands are aligned:
-
-```
-python3 -m pip list
-pip3 list
+```bash
+python3 meshbook.py --help
 ```
 
-If not, perhaps you are using the wrong executable, the wrong environment and so on...
+---
 
-# How to create a configuration?
+## 🛠️ Creating Configurations
 
-This paragraph explains how the program interprets certain information.
+Meshbook configurations are written in YAML. Below is an overview of supported fields.
 
-### Targeting:
-
-MeshCentral has `meshes` or `groups`, in this program they are called `group(s)`. Because of the way I designed this.<br>
-So to target for example a mesh/group in MeshCentral called: "Nerthus" do:
-
-> If your group has multiple words, then you need to use `"` to group the words.
+### ▶️ Group Targeting (Primary*)
 
 ```yaml
 ---
-name: example configuration
-group: "Nerthus"
-#target_os: "Linux" # <--- according to os_categories.json.
-powershell: True    # <--- this can be important for Windows clients.
+name: My Configuration
+group: "Dev Machines"
+powershell: true
 variables:
-  - name: var1
-    value: "This is the first variable"
+  - name: message
+    value: "Hello from Meshbook"
 tasks:
-  - name: echo the first variable!
-    command: 'echo "{{ var1 }}"'
+  - name: Echo a message
+    command: 'echo "{{ message }}"'
 ```
 
-It is also possible to target a single device, as seen in: [here](./examples/apt_update_example.yaml).<br>
+* `group`: MeshCentral group (aka "mesh"). Quotation marks required for multi-word names.
+* `powershell`: Set `true` for PowerShell commands on Windows clients.
 
-### Variables:
+### ▶️ Device Targeting (Secondary*)
 
-Variables are done by replacing the placeholders just before the runtime (the Python program does this, not you).<br>
-So if you have var1 declared, then the value of that declaration is placed wherever it finds {{ var1 }}.<br>
-This is done to imitate popular methods. See below [from the example](./examples/variable_usage_example.yaml).<br>
+You can also target a **specific device** rather than a group. See [`apt_update_example.yaml`](./examples/linux/apt_update_example.yaml) for reference.
 
-### Tasks:
+### ▶️ Variables
 
-The tasks you want to run should be contained under the `tasks:` with two fields, `name` and `command`.<br>
-The name field is for the user of meshbook, to clarify what the following command does in a summary.<br>
-The command field actually gets executed on the end-point.<br>
+Variables are replaced by Meshbook before execution. Syntax:
 
-### Windows Client Extra-information:
+```yaml
+variables:
+  - name: example_var
+    value: "Example value"
 
-If you want to launch commands at Windows machines, make sure you have your `os_categories.conf` up-to-date with the correct reported Windows versions.<br>
-And then make sure to create compatible commands, see: [windows examples](./examples/windows)<br>
-Related is the yaml option: `powershell: True`.
+tasks:
+  - name: Use the variable
+    command: 'echo "{{ example_var }}"'
+```
 
-### Granual Operating System filtering:
+* Primary and Secondary mark the order in which will take prescendence
 
-I have made the program so it can have a filter with the Operating systems. If you have a mixed group, please read:
-[This explanation](./docs/operating_system_filtering.md)
+### ▶️ Tasks
 
-### Tag filtering:
+Define multiple tasks:
 
-Filtering on MeshCentral tags is also possible with `target_tag` inside the meshbook. This string is case-sensitive, lower- and uppercase must match.<br>
-This is done because its human made and therefor needs to be keps well administrated.
+```yaml
+tasks:
+  - name: Show OS info
+    command: "cat /etc/os-release"
+```
 
-# Example:
+Each task must include:
 
-For the example, I used the following yaml file (you can find more in [this directory](./examples/)):
+* `name`: Description for human readability.
+* `command`: The actual shell or PowerShell command.
 
-The below group: `Dev` has three devices, of which one is offline, Meshbook checks if the device is reachable.<br>
-You can expand the command chain as follows:<br>
+---
+
+## 🪟 Windows Client Notes
+
+* Keep your `os_categories.json` up to date for proper OS filtering.
+* Ensure Windows commands are compatible (use `powershell: true` if needed).
+* Examples are available in [`examples/windows`](./examples/windows).
+
+---
+
+## 🔎 OS & Tag Filtering
+
+### Filter by OS
+
+You can limit commands to specific OS types:
+
+```yaml
+target_os: "Linux"  # As defined in os_categories.json
+```
+
+See [docs/operating\_system\_filtering.md](./docs/operating_system_filtering.md) for details.
+
+### Filter by Tag
+
+You can also filter using MeshCentral tags:
+
+```yaml
+target_tag: "Production"
+```
+
+> ⚠️ Tag values are **case-sensitive**.
+
+---
+
+## 📋 Example Playbook
 
 ```yaml
 ---
-name: Echo a string to the terminal through the meshbook example.
+name: Echo OS Info
 group: "Dev"
-#target_os: "Linux" # <--- according to os_categories.json
+target_os: "Linux"
 variables:
   - name: file
     value: "/etc/os-release"
 tasks:
-  - name: Echo!
+  - name: Show contents of os-release
     command: "echo $(cat {{ file }})"
 ```
 
-The following response it received when executing the first yaml of the above files (without the `-s` parameters, which just outputs the below JSON).
+Sample output:
 
-```shell
-$ python3 meshbook.py -mb books/aggregate_example.yaml -i --nograce -pr
-
-----------------------------------------
-meshbook: books/aggregate_example.yaml
-Operating System Categorisation file: ./os_categories.json
-Configuration file: ./config.conf
-Target Operating System category given: Linux
-Target group: Systemec Development
-Grace: False
-Silent: False
-----------------------------------------
-Trying to load the MeshCentral account credential file...
-Trying to load the meshbook yaml file and compile it into something workable...
-Trying to load the Operating System categorisation JSON file...
-Connecting to MeshCentral and establish a session using variables from previous credential file.
-Generating group list with nodes and reference the targets from that.
-----------------------------------------
-Executing playbook on the target(s): Development.
-----------------------------------------
-1. Running: Ping!
-----------------------------------------
+```json
 {
   "Task 1": {
-    "task_name": "Ping Quad9 DNS",
+    "task_name": "Show contents of os-release",
     "data": [
-        {
-            "complete": true,
-            "result": [
-                "PING 9.9.9.9 (9.9.9.9) 56(84) bytes of data.",
-                "64 bytes from 9.9.9.9: icmp_seq=1 ttl=61 time=26.8 ms",
-                "--- 9.9.9.9 ping statistics ---",
-                "1 packets transmitted, 1 received, 0% packet loss, time 0ms",
-                "rtt min/avg/max/mdev = 26.809/26.809/26.809/0.000 ms"
-            ],
-            "command": "ping 9.9.9.9 -c 1",
-            "device_id": "yourn nodeip",
-            "device_name": "yournodename"
-        }
+      {
+        "command": "echo $(cat /etc/os-release)",
+        "result": [
+          "NAME=\"Ubuntu\"",
+          "VERSION=\"22.04.4 LTS (Jammy Jellyfish)\""
+        ],
+        "complete": true,
+        "device_name": "dev-host1"
+      }
     ]
   }
 }
 ```
-The above without `-s` is quite verbose. use `--help` to read about parameters and getting a minimal response for example.
 
-# Important Notice:
+---
 
-If you want to use this, make sure to use `NON-BLOCKING` commands. MeshCentral does not work if you send it commands that wait.<br>
-A couple examples of `BLOCKING COMMANDS` which will never get back to the main MeshCentral server, and Meshbook will quit after the timeout but the agent will not come back:
+## ⚠️ Blocking Commands Warning
 
-```shell
-apt upgrade # without -y.
+Avoid using commands that **block indefinitely** — MeshCentral requires **non-blocking** execution.
 
+🚫 Examples of bad (blocking) commands:
+
+```bash
+apt upgrade       # Without -y
 sleep infinity
-
-ping 1.1.1.1 # without a -c flag (because it pings forever).
+ping 1.1.1.1      # Without -c
 ```
+
+✅ Use instead:
+
+```bash
+apt upgrade -y
+ping 1.1.1.1 -c 1
+```
+
+---
+
+## 🧪 Check Python Environment
+
+Sometimes the wrong Python interpreter or environment is used. To verify:
+
+```bash
+python3 -m pip list
+pip3 list
+```
+
+The lists should match. If not, make sure the correct environment is activated.
+
+---
+
+## 📂 Project Structure (excerpt)
+
+```bash
+meshbook/
+├── books/
+│   ├── apt-update.yaml
+│   └── rdp.yaml
+├── examples/
+│   ├── linux/
+│   │   ├── apt_update_example.yaml
+│   │   └── ...
+│   └── windows/
+│       ├── get_sys_info.yaml
+│       └── ...
+├── modules/
+│   ├── executor.py
+│   └── utilities.py
+├── meshbook.py
+├── os_categories.json
+├── requirements.txt
+├── templates/
+│   └── config.conf.template
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the terms of the GPL3 License. See [LICENSE](./LICENSE).

meshbook.py

@@ -4,6 +4,7 @@
 import argparse
 import asyncio
 from colorama import just_fix_windows_console
+import pyotp
 import json
 import meshctrl
 
@@ -12,7 +13,7 @@ from modules.console import *
 from modules.executor import *
 from modules.utilities import *
 
-meshbook_version = 1.3
+meshbook_version = "1.3.1"
 grace_period = 3 # Grace period will last for x (by default 3) second(s).
 
 async def init_connection(credentials: dict) -> meshctrl.Session:
@@ -20,128 +21,154 @@ async def init_connection(credentials: dict) -> meshctrl.Session:
     Use the libmeshctrl library to initiate a Secure Websocket (wss) connection to the MeshCentral instance.
     '''
 
-    session = meshctrl.Session(
-        credentials['hostname'],
-        user=credentials['username'],
-        password=credentials['password']
-    )
+    if "totp_secret" in credentials:
+        totp = pyotp.TOTP(credentials["totp_secret"])
+        otp = totp.now()
+
+        session = meshctrl.Session(
+            credentials['hostname'],
+            user=credentials['username'],
+            password=credentials['password'],
+            token=otp
+        )
+    else:
+        session = meshctrl.Session(
+            credentials['hostname'],
+            user=credentials['username'],
+            password=credentials['password']
+        )
     await session.initialized.wait()
     return session
 
 async def gather_targets(args: argparse.Namespace,
                          meshbook: dict,
                          group_list: dict[str, list[dict]],
-                         os_categories: dict) -> list[str]:
-    '''
-    Finds target devices based on meshbook criteria (device or group).
-    '''
+                         os_categories: dict) -> dict:
+    """
+    Finds target devices based on meshbook criteria (device, devices, group or groups).
+    """
 
+    group_list = {k.lower(): v for k, v in group_list.items()}  # Normalize keys
     target_list = []
     offline_list = []
+
     target_os = meshbook.get("target_os")
-    ignore_categorisation = meshbook.get("ignore_categorisation", False)
     target_tag = meshbook.get("target_tag")
+    ignore_categorisation = meshbook.get("ignore_categorisation", False)
 
+    assert target_os is not None, "target_os must be provided"
+    assert target_tag is not None, "target_tag must be provided"
+
+    async def add_processed_devices(processed):
+        """Helper to update target and offline lists."""
+        if processed:
+            target_list.extend(processed.get("valid_devices", []))
+            offline_list.extend(processed.get("offline_devices", []))
+
+    async def process_device_helper(device):
+        processed = await utilities.process_device(
+            device,
+            group_list,
+            os_categories,
+            target_os,
+            ignore_categorisation,
+            target_tag,
+            add_processed_devices
+        )
+        await add_processed_devices(processed)
+
+    async def process_group_helper(group):
+        processed = await utilities.filter_targets(
+            group, os_categories, target_os, ignore_categorisation, target_tag
+        )
+        await add_processed_devices(processed)
+
+    '''
+    Groups receive the first priority, then device targets.
+    '''
     match meshbook:
-        case {"device": pseudo_target}:  # Single device target
+        case {"group": pseudo_target}:
             if isinstance(pseudo_target, str):
-                processed_devices = await utilities.process_device_or_group(pseudo_target,
-                                                                            group_list,
-                                                                            os_categories,
-                                                                            target_os,
-                                                                            ignore_categorisation,
-                                                                            target_tag)
-                if len(processed_devices) > 0:
-                    matched_devices = processed_devices["valid_devices"]
-                    target_list.extend(matched_devices)
-                if len(processed_devices) > 0:
-                    offline_devices = processed_devices["offline_devices"]
-                    offline_list.extend(offline_devices)
+                pseudo_target = pseudo_target.lower()
 
+                if pseudo_target in group_list:
+                    await process_group_helper(group_list[pseudo_target])
+
+                elif pseudo_target not in group_list:
+                    console.nice_print(
+                        args,
+                        console.text_color.yellow + "Targeted group not found on the MeshCentral server.",
+                        True
+                    )
+            elif isinstance(pseudo_target, list):
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "Please use groups (Notice the plural with 'S') for multiple groups.",
+                    True
+                )
             else:
-                console.nice_print(args,
-                                   console.text_color.yellow + "Please use devices (Notice the 'S') for multiple devices.", True)
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "The 'group' key is being used, but an unknown data type was found, please check your values.",
+                    True
+                )
 
-        case {"devices": pseudo_target}:  # List of devices
+        case {"groups": pseudo_target}:
             if isinstance(pseudo_target, list):
-                for sub_pseudo_device in pseudo_target:
-                    processed_devices = await utilities.process_device_or_group(sub_pseudo_device,
-                                                                                group_list,
-                                                                                os_categories,
-                                                                                target_os,
-                                                                                ignore_categorisation,
-                                                                                target_tag,)
-                if len(processed_devices) > 0:
-                    matched_devices = processed_devices["valid_devices"]
-                    target_list.extend(matched_devices)
-                if len(processed_devices) > 0:
-                    offline_devices = processed_devices["offline_devices"]
-                    offline_list.extend(offline_devices)
-
+                for sub_group in pseudo_target:
+                    sub_group = sub_group.lower()
+                    if sub_group in group_list:
+                        await process_group_helper(group_list[sub_group])
+            elif isinstance(pseudo_target, str) and pseudo_target.lower() == "all":
+                for group in group_list.values():
+                    await process_group_helper(group)
+            elif isinstance(pseudo_target, str):
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "The 'groups' key is being used, but only one string is given. Did you mean 'group'?",
+                    True
+                )
             else:
-                console.nice_print(args, console.text_color.yellow + "The 'devices' method is being used, but only one string is given. Did you mean 'device'?", True)
-
-        case {"group": pseudo_target}:  # Single group target
-            if isinstance(pseudo_target, str) and pseudo_target in group_list:
-                processed_devices = await utilities.filter_targets(group_list[pseudo_target],
-                                                                    os_categories,
-                                                                    target_os,
-                                                                    ignore_categorisation,
-                                                                    target_tag)
-                if len(processed_devices) > 0:
-                    matched_devices = processed_devices["valid_devices"]
-                    target_list.extend(matched_devices)
-                if len(processed_devices) > 0:
-                    offline_devices = processed_devices["offline_devices"]
-                    offline_list.extend(offline_devices)
-
-            elif pseudo_target not in group_list:
-                console.nice_print(args,
-                                   console.text_color.yellow + "Targeted group not found on the MeshCentral server.", True)
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "The 'groups' key is being used, but an unknown data type was found, please check your values.",
+                    True
+                )
 
+        case {"device": pseudo_target}:
+            if isinstance(pseudo_target, str):
+                await process_device_helper(pseudo_target)
+            elif isinstance(pseudo_target, list):
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "Please use devices (Notice the plural with 'S') for multiple devices.",
+                    True
+                )
             else:
-                console.nice_print(args,
-                                   console.text_color.yellow + "Please use groups (Notice the 'S') for multiple groups.", True)
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "The 'device' key is being used, but an unknown data type was found, please check your values.",
+                    True
+                )
 
-
-        case {"groups": pseudo_target}:  # List of groups
+        case {"devices": pseudo_target}:
             if isinstance(pseudo_target, list):
-                for sub_pseudo_target in pseudo_target:
-                    if sub_pseudo_target in group_list:
-                        processed_devices = await utilities.filter_targets(group_list[sub_pseudo_target],
-                                                                            os_categories,
-                                                                            target_os,
-                                                                            ignore_categorisation,
-                                                                            target_tag)
-                    if len(processed_devices) > 0:
-                        matched_devices = processed_devices["valid_devices"]
-                        target_list.extend(matched_devices)
-                    if len(processed_devices) > 0:
-                        offline_devices = processed_devices["offline_devices"]
-                        offline_list.extend(offline_devices)
-
-            elif pseudo_target.lower() == "all":
-                for group in group_list:
-                    processed_devices = await utilities.filter_targets(group_list[group],
-                                                                        os_categories,
-                                                                        target_os,
-                                                                        ignore_categorisation,
-                                                                        target_tag)
-                    if len(processed_devices) > 0:
-                        matched_devices = processed_devices["valid_devices"]
-                        target_list.extend(matched_devices)
-                    if len(processed_devices) > 0:
-                        offline_devices = processed_devices["offline_devices"]
-                        offline_list.extend(offline_devices)
-
+                for sub_device in pseudo_target:
+                    await process_device_helper(sub_device)
+            elif isinstance(pseudo_target, str):
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "The 'devices' key is being used, but only one string is given. Did you mean 'device'?",
+                    True
+                )
             else:
-                console.nice_print(args,
-                                   console.text_color.yellow + "The 'groups' method is being used, but only one string is given. Did you mean 'group'?", True)
+                console.nice_print(
+                    args,
+                    console.text_color.yellow + "The 'devices' key is being used, but an unknown data type was found, please check your values.",
+                    True
+                )
 
-    return {
-        "target_list": target_list,
-        "offline_list": offline_list
-    }
+    return {"target_list": target_list, "offline_list": offline_list}
 
 async def main():
     just_fix_windows_console()
@@ -153,14 +180,16 @@ async def main():
     parser.add_argument("-mb", "--meshbook", type=str, help="Path to the meshbook yaml file.")
 
     parser.add_argument("-oc", "--oscategories", type=str, help="Path to the Operating System categories JSON file.", default="./os_categories.json")
-    parser.add_argument("--conf", type=str, help="Path for the API configuration file (default: ./config.conf).", default="./config.conf")
+    parser.add_argument("--conf", type=str, help="Path for the API configuration file (default: ./config.conf).", default="./api.conf")
     parser.add_argument("--nograce", action="store_true", help="Disable the grace 3 seconds before running the meshbook.")
-    parser.add_argument("-i", "--indent", action="store_true", help="Use an JSON indentation of 4 when this flag is passed.")
-    parser.add_argument("-r", "--raw-result", action="store_true", help="Print the raw result.")
-    parser.add_argument("-s", "--silent", action="store_true", help="Suppress terminal output.")
-    parser.add_argument("--shlex", action="store_true", help="Shlex the lines.")
+    parser.add_argument("-g", "--group", type=str, help="Specify a manual override for the group.", default="")
+    parser.add_argument("-d", "--device", type=str, help="Specify a manual override for a device", default="")
+    parser.add_argument("-i", "--indent", action="store_true", help="Use an JSON indentation of 4 when this flag is passed.", default=False)
+    parser.add_argument("-r", "--raw-result", action="store_true", help="Print the raw result.", default=False)
+    parser.add_argument("-s", "--silent", action="store_true", help="Suppress terminal output.", default=False)
+    parser.add_argument("--shlex", action="store_true", help="Shlex the lines.", default=False)
 
-    parser.add_argument("-v", "--version", action="store_true", help="Show the Meshbook version.")
+    parser.add_argument("--version", action="store_true", help="Show the Meshbook version.")
 
     args = parser.parse_args()
     local_categories_file = "./os_categories.json"
@@ -169,7 +198,7 @@ async def main():
         console.nice_print(args,
                            console.text_color.reset + "MeshBook Version: " + console.text_color.yellow + str(meshbook_version))
         return
-    
+
     if not args.meshbook:
         parser.print_help()
         return
@@ -183,6 +212,15 @@ async def main():
             (utilities.compile_book(args.meshbook))
         )
 
+        if args.group != "":
+            meshbook["group"] = args.group
+            if "device" in meshbook:
+              del meshbook["device"]
+        elif args.device != "":
+            meshbook["device"] = args.device
+            if "group" in meshbook:
+              del meshbook["group"]
+
         '''
         The following section mainly displays used variables and first steps of the program to the console.
         '''
@@ -191,24 +229,24 @@ async def main():
         console.nice_print(args,
                            console.text_color.reset + ("-" * 40))
         console.nice_print(args,
-                           "meshbook: " + console.text_color.yellow + args.meshbook)
+                           "meshbook: " + console.text_color.yellow + args.meshbook + console.text_color.reset + ".")
         console.nice_print(args,
-                           "Operating System Categorisation file: " + console.text_color.yellow + args.oscategories)
+                           "Operating System Categorisation file: " + console.text_color.yellow + args.oscategories + console.text_color.reset + ".")
         console.nice_print(args,
-                           "Configuration file: " + console.text_color.yellow + args.conf)
+                           "Configuration file: " + console.text_color.yellow + args.conf + console.text_color.reset + ".")
 
         # TARGET OS PRINTING
         if "target_os" in meshbook:
             console.nice_print(args,
-                               "Target Operating System category given: " + console.text_color.yellow + meshbook["target_os"])
+                               "Target Operating System category given: " + console.text_color.yellow + meshbook["target_os"] + console.text_color.reset + ".")
         else:
             console.nice_print(args,
-                               "Target Operating System category given: " + console.text_color.yellow + "All")
-            
+                               "Target Operating System category given: " + console.text_color.yellow + "All" + console.text_color.reset + ".")
+
         # Should Meshbook ignore categorisation?
         if "ignore_categorisation" in meshbook:
             console.nice_print(args,
-                                "Ignore the OS Categorisation file: " + console.text_color.yellow + str(meshbook["ignore_categorisation"]))
+                                "Ignore the OS Categorisation file: " + console.text_color.yellow + str(meshbook["ignore_categorisation"]) + console.text_color.reset + ".")
             if meshbook["ignore_categorisation"]:
                 console.nice_print(args,
                                 console.text_color.red + "!!!!\n" +
@@ -217,29 +255,29 @@ async def main():
                                 console.text_color.red + "\n!!!!")
         else:
             console.nice_print(args,
-                                "Ignore the OS Categorisation file: " + console.text_color.yellow + "False")
-        
+                                "Ignore the OS Categorisation file: " + console.text_color.yellow + "False" + console.text_color.reset + ".")
+
         # TARGET TAG PRINTING
         if "target_tag" in meshbook:
             console.nice_print(args,
-                               "Target Device tag given: " + console.text_color.yellow + meshbook["target_tag"])
+                               "Target Device tag given: " + console.text_color.yellow + meshbook["target_tag"] + console.text_color.reset + ".")
         else:
             console.nice_print(args,
-                               "Target Device tag given: " + console.text_color.yellow + "All")
+                               "Target Device tag given: " + console.text_color.yellow + "All" + console.text_color.reset + ".")
 
         # TARGET PRINTING
         if "device" in meshbook:
             console.nice_print(args,
-                               "Target device: " + console.text_color.yellow + str(meshbook["device"]))
+                               "Target device: " + console.text_color.yellow + str(meshbook["device"]) + console.text_color.reset + ".")
         elif "devices" in meshbook:
             console.nice_print(args,
-                               "Target devices: " + console.text_color.yellow + str(meshbook["devices"]))
+                               "Target devices: " + console.text_color.yellow + str(meshbook["devices"]) + console.text_color.reset + ".")
         elif "group" in meshbook:
             console.nice_print(args,
-                               "Target group: " + console.text_color.yellow + str(meshbook["group"]))
+                               "Target group: " + console.text_color.yellow + str(meshbook["group"]) + console.text_color.reset + ".")
         elif "groups" in meshbook:
             console.nice_print(args,
-                               "Target groups: " + console.text_color.yellow + str(meshbook["groups"]))
+                               "Target groups: " + console.text_color.yellow + str(meshbook["groups"]) + console.text_color.reset + ".")
 
         # RUNNING PARAMETERS PRINTING
         console.nice_print(args, "Grace: " + console.text_color.yellow + str((not args.nograce))) # Negation of bool for correct explanation
@@ -268,12 +306,16 @@ async def main():
         group_list = await transform.compile_group_list(session)
         compiled_device_list = await gather_targets(args, meshbook, group_list, os_categories)
 
-        if len(compiled_device_list["target_list"]) == 0:
-            console.nice_print(args, console.text_color.red + "No targets found or targets unreachable, quitting.", True)
-            console.nice_print(args, console.text_color.reset + ("-" * 40), True)
+        if "target_list" not in compiled_device_list or len(compiled_device_list["target_list"]) == 0:
+            console.nice_print(args,
+                               console.text_color.red + "No targets found or targets unreachable, quitting.", True)
+
+            console.nice_print(args,
+                               console.text_color.reset + ("-" * 40), True)
 
         else:
-            console.nice_print(args, console.text_color.reset + ("-" * 40))
+            console.nice_print(args,
+                               console.text_color.reset + ("-" * 40))
 
             match meshbook:
                 case {"group": candidate_target_name}:
@@ -288,13 +330,20 @@ async def main():
                 case {"devices": candidate_target_name}:
                     target_name = str(candidate_target_name)
 
-            console.nice_print(args, console.text_color.yellow + "Executing meshbook on the target(s): " + console.text_color.green + target_name + ".")
+                case _:
+                    target_name = ""
+
+
+            console.nice_print(args,
+                               console.text_color.yellow + "Executing meshbook on the target(s): " + console.text_color.green + target_name + console.text_color.yellow + ".")
 
             if not args.nograce:
-                console.nice_print(args, console.text_color.yellow + "Initiating grace-period...")
+                console.nice_print(args,
+                                   console.text_color.yellow + "Initiating grace-period...")
 
                 for x in range(grace_period):
-                    console.nice_print(args, console.text_color.yellow + "{}...".format(x+1)) # Countdown!
+                    console.nice_print(args,
+                                       console.text_color.yellow + "{}...".format(x+1)) # Countdown!
                     await asyncio.sleep(1)
 
             console.nice_print(args, console.text_color.reset + ("-" * 40))
@@ -307,7 +356,8 @@ async def main():
         await session.close()
 
     except OSError as message:
-        console.nice_print(args, console.text_color.red + message, True)
+        console.nice_print(args,
+                           console.text_color.red + f'{message}', True)
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    asyncio.run(main())

modules/console.py

@@ -14,6 +14,7 @@ class console:
             italic = "\x1B[3m"
             reset = "\x1B[0m"
 
+    @staticmethod
     def nice_print(args: argparse.Namespace, message: str, final: bool=False):
         '''
         Helper function for terminal output, with a couple variables for the silent flag. Also clears terminal color each time.

modules/executor.py

@@ -8,9 +8,10 @@ from time import sleep
 from modules.console import console
 from modules.utilities import transform
 
-intertask_delay = 0.5
+intertask_delay = 1
 
 class executor:
+    @staticmethod
     async def execute_meshbook(args: argparse.Namespace, session: meshctrl.Session, compiled_device_list: dict, meshbook: dict, group_list: dict) -> None:
         '''
         Actual function that handles meshbook execution, also responsible for formatting the resulting JSON.
@@ -28,7 +29,7 @@ class executor:
             if "powershell" in meshbook and meshbook["powershell"]:
                 response = await session.run_command(nodeids=targets, command=task["command"],powershell=True,ignore_output=False,timeout=900)
             else:
-                response = await session.run_command(nodeids=targets, command=task["command"],ignore_output=False,timeout=900)
+                response = await session.run_command(nodeids=targets, command=task["command"],powershell=False,ignore_output=False,timeout=900)
 
             task_batch = []
             for device in response:
@@ -38,7 +39,7 @@ class executor:
                 response[device]["device_name"] = await transform.translate_nodeid_to_name(device, group_list)
                 task_batch.append(response[device])
 
-            responses_list["Task " + str(round)] = {
+            responses_list["task_" + str(round)] = {
                 "task_name": task["name"],
                 "data": task_batch
             }
@@ -62,4 +63,4 @@ class executor:
 
         else:
             console.nice_print(args,
-                               json.dumps(responses_list), True)
+                               json.dumps(responses_list), True)

modules/utilities.py

@@ -10,6 +10,7 @@ Creation and compilation of the MeshCentral nodes list (list of all nodes availa
 '''
 
 class utilities:
+    @staticmethod
     async def load_config(args: argparse.Namespace,
                           segment: str = 'meshcentral-account') -> dict:
         '''
@@ -32,17 +33,20 @@ class utilities:
             print(f'Segment "{segment}" not found in config file {conf_file}.')
             os._exit(1)
 
-        return config[segment]
+        return dict(config[segment])
 
-    async def compile_book(meshbook_file: dict) -> dict:
+    @staticmethod
+    async def compile_book(meshbook_file: str) -> dict:
         '''
         Simple function that opens the file and replaces placeholders through the next function. After that just return it.
         '''
 
-        meshbook = open(meshbook_file, 'r')
+        with open(meshbook_file, 'r') as f:
+            meshbook = f.read()
         meshbook = await transform.replace_placeholders(yaml.safe_load(meshbook))
         return meshbook
     
+    @staticmethod
     def get_os_variants(target_category: str,
                         os_map: dict) -> set:
         '''
@@ -65,17 +69,19 @@ class utilities:
 
         return set()
 
+    @staticmethod
     async def filter_targets(devices: list[dict],
                              os_categories: dict,
-                             target_os: str = None,
+                             target_os: str = "",
                              ignore_categorisation: bool = False,
-                             target_tag: str = None) -> dict:
+                             target_tag: str = "") -> dict:
         '''
         Filters devices based on reachability and optional OS criteria, supporting nested OS categories.
         '''
 
         valid_devices = []
         offline_devices = []
+        allowed_os = set()
 
         # Identify correct OS filtering scope
         for key in os_categories:
@@ -109,28 +115,42 @@ class utilities:
             "offline_devices": offline_devices
         }
 
-    async def process_device_or_group(pseudo_target: str,
-                                      group_list: dict,
-                                      os_categories: dict,
-                                      target_os: str,
-                                      ignore_categorisation: bool,
-                                      target_tag: str) -> dict:
-        '''
-        Helper function to process devices or groups.
-        '''
-
+    @staticmethod
+    async def process_device(device: str,
+                            group_list: dict,
+                            os_categories: dict,
+                            target_os: str,
+                            ignore_categorisation: bool,
+                            target_tag: str,
+                            add_processed_devices=None) -> dict:
+        """
+        Processes a single device or pseudo-target against group_list,
+        filters matches by OS and tags, and adds processed devices.
+        """
         matched_devices = []
-        for group in group_list:
-            for device in group_list[group]:
-                if device["device_name"] == pseudo_target:
-                    matched_devices.append(device)
+        pseudo_target = device.lower()
 
+        # Find devices that match the pseudo_target
+        for group in group_list:
+            for dev in group_list[group]:
+                if dev["device_name"].lower() == pseudo_target:
+                    matched_devices.append(dev)
+
+        # If matches found, filter them and add processed devices
         if matched_devices:
-            return await utilities.filter_targets(matched_devices, os_categories, target_os, ignore_categorisation, target_tag)
-        return []
+            processed = await utilities.filter_targets(
+                matched_devices, os_categories, target_os, ignore_categorisation, target_tag
+            )
+            if add_processed_devices:
+                await add_processed_devices(processed)
+            return processed
+
+        # No matches found
+        return {"valid_devices": [], "offline_devices": []}
 
 import shlex
 class transform:
+    @staticmethod
     def process_shell_response(shlex_enable: bool, meshbook_result: dict) -> dict:
         for task_name, task_data in meshbook_result.items():
             if task_name == "Offline": # Failsafe
@@ -152,6 +172,7 @@ class transform:
                 node_responses["result"] = clean_output
         return meshbook_result
 
+    @staticmethod
     async def translate_nodeid_to_name(target_id: str, group_list: dict) -> str:
         '''
         Simple function that looks up nodeid to the human-readable name if existent - otherwise return None.
@@ -161,8 +182,9 @@ class transform:
             for device in group_list[group]:
                 if device["device_id"] == target_id:
                     return device["device_name"]
-        return None
+        return ""
     
+    @staticmethod
     async def replace_placeholders(meshbook: dict) -> dict:
         '''
         Replace the placeholders in both name and command fields of the tasks. According to the variables defined in the variables list.
@@ -196,6 +218,7 @@ class transform:
 
         return meshbook
     
+    @staticmethod
     async def compile_group_list(session: meshctrl.Session) -> dict:
         '''
         Function that retrieves the devices from MeshCentral and compiles it into a efficient list.

os_categories.json

@@ -2,6 +2,7 @@
 {
     "Linux": {
         "Debian": [
+            "Debian GNU/Linux 13 (trixie)",
             "Debian GNU/Linux 12 (bookworm)",
             "Debian GNU/Linux 11 (bullseye)"
         ],

requirements.txt

@@ -1,3 +1,4 @@
 colorama==0.4.6
 pyyaml==6.0.2
-libmeshctrl==1.2.0
+libmeshctrl==1.2.2
+pyotp==2.9.0

templates/api.conf.template

@@ -1,4 +1,5 @@
 [meshcentral-account]
 hostname =
 username = 
-password =
+password =
+totp_secret =