Trustworthiness and SDFL

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,5 +17,5 @@ Please fill out the following template to help us review your pull request.
 <!-- List any related issues, e.g. "Closes #123" -->
 
 ## Signed-off-by
-Signed-off-by: *Your Name (email)*  
-Date: *YYYY-MM-DD*
+Signed-off-by: *Your Name (email)*
+Date: *YYYY-MM-DD*

CLA.md

@@ -18,5 +18,5 @@ By submitting a pull request, patch or code snippet, you agree that:
    your contribution and that Authors may use, sell or license the
    software containing your contribution at its sole discretion.
 
-Signed-off-by: *Enrique Tomás Martínez Beltrán (enriquetomas@um.es)*  
-Date: *2025-06-25*
+Signed-off-by: *Enrique Tomás Martínez Beltrán (enriquetomas@um.es)*
+Date: *2025-06-25*

COMMERCIAL_INFO.md

@@ -1,6 +1,6 @@
 # NEBULA Enterprise License
 
-This repository is published under **GNU AGPL v3.0**.  
+This repository is published under **GNU AGPL v3.0**.
 If you wish to embed NEBULA in closed-source products, offer it as a hosted service, or obtain an SLA, please e-mail **enriquetomas@um.es** and **alberto.huertas@um.es**.
 
-A bespoke commercial agreement (OEM / subscription / SaaS) will be provided on request.
+A bespoke commercial agreement (OEM / subscription / SaaS) will be provided on request.

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Follow conventional-commit style.
 ## 2 • Sign the CLA
 When you open your first Pull Request, **CLA-assistant** will block the
 merge until you tick the box confirming you accept the
-[ICLA](CLA.md).  
+[ICLA](CLA.md).
 Add a Developer-Certificate-of-Origin line in every commit:
 
 ```
@@ -23,4 +23,4 @@ The pull request will be reviewed by the maintainers.
 The maintainers will provide feedback on the pull request.
 
 ## 6 • Merge the Pull Request
-The pull request will be merged by the maintainers.
+The pull request will be merged by the maintainers.

README.md

@@ -159,4 +159,33 @@ We would like to thank the following projects for their contributions which have
 - [FastAPI](https://github.com/tiangolo/fastapi) for the RESTful API
 - [Fedstellar](https://github.com/CyberDataLab/fedstellar) platform and [p2pfl](https://github.com/pguijas/p2pfl/) library
 - [Adversarial Robustness Toolbox (ART)](https://github.com/Trusted-AI/adversarial-robustness-toolbox) for the implementation of adversarial attacks
+- [Opacus](https://github.com/meta-pytorch/opacus) for differential privacy training support
+- [AI Fairness 360 (AIF360)](https://github.com/Trusted-AI/AIF360) for fairness metric definitions
+- [HolisticAI](https://github.com/holistic-ai/holisticai) for trustworthiness and fairness metric definitions
 - [D3.js](https://github.com/d3/d3-force) for the network visualizations
+
+## Third-party Differential Privacy
+
+NEBULA uses Opacus for differential privacy training:
+
+- Yousefpour, A., Shilov, I., Sablayrolles, A., Testuggine, D., Prasad, K., Malek, M., Nguyen, J., Ghosh, S., Bharadwaj, A., Zhao, J., Cormode, G., & Mironov, I. (2021). Opacus: User-Friendly Differential Privacy Library in PyTorch. arXiv:2109.12298. Licensed under Apache License 2.0: https://github.com/meta-pytorch/opacus/blob/main/LICENSE
+
+## Third-party Trustworthiness Metrics
+
+NEBULA implements some trustworthiness and fairness metrics following definitions documented in external toolkits:
+
+- AI Fairness 360 (AIF360). AI Fairness 360 [Software]. https://github.com/Trusted-AI/AIF360. Licensed under Apache License 2.0: https://github.com/Trusted-AI/AIF360/blob/main/LICENSE
+
+- Holistic AI. HolisticAI [Software]. https://github.com/holistic-ai/holisticai. Licensed under Apache License 2.0: https://github.com/holistic-ai/holisticai/blob/main/LICENSE
+
+## Third-party Tabular Datasets
+
+NEBULA preprocesses these datasets for experiments, including splitting, scaling, encoding, label mapping, filtering, and/or sample limiting depending on the dataset.
+
+- Becker, B. & Kohavi, R. (1996). Adult [Dataset]. UCI Machine Learning Repository. https://doi.org/10.24432/C5XW20. Licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/
+
+- Blackard, J. (1998). Covertype [Dataset]. UCI Machine Learning Repository. https://doi.org/10.24432/C50K5N. Licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/
+
+- Wolberg, W., Mangasarian, O., Street, N., & Street, W. (1993). Breast Cancer Wisconsin (Diagnostic) [Dataset]. UCI Machine Learning Repository. https://doi.org/10.24432/C5DW2B. Licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/
+
+- Stolfo, S., Fan, W., Lee, W., Prodromidis, A., & Chan, P. (1999). KDD Cup 1999 Data [Dataset]. UCI Machine Learning Repository. https://doi.org/10.24432/C51C7N. Licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/

app/deployer.py

@@ -289,17 +289,17 @@ def run_script(self, script):
     def kill_script_processes(self, pids_file):
         """
         Forcefully terminates processes listed in a given PID file, including their child processes.
-    
+
         Args:
             pids_file (str): Path to the file containing PIDs, one per line.
-    
+
         Behavior:
             - Reads the PIDs from the file.
             - For each PID, checks if the process exists.
             - If it exists, kills all child processes recursively before killing the main process.
             - Handles and logs exceptions such as missing processes or invalid PID entries.
             - Logs warnings and errors appropriately.
-    
+
         Typical use case:
             Used to clean up running processes related to a scenario or script that has been deleted or stopped.
         """
@@ -344,7 +344,7 @@ def run_observer():
     """
     Starts a watchdog observer to monitor the configuration directory for changes.
 
-    This function is typically used to execute additional scripts or trigger events 
+    This function is typically used to execute additional scripts or trigger events
     during the execution of a federated learning session by monitoring file system changes.
 
     Main functionalities:
@@ -357,7 +357,7 @@ def run_observer():
         - Trigger specific actions during a federation lifecycle.
 
     Note:
-        The observer runs in a blocking mode and will keep the process alive 
+        The observer runs in a blocking mode and will keep the process alive
         until manually stopped or interrupted.
     """
     # Watchdog for running additional scripts in the host machine (i.e. during the execution of a federation)
@@ -373,7 +373,7 @@ class Deployer:
     """
     Handles the configuration and initialization of deployment parameters for the NEBULA system.
 
-    This class reads and stores various deployment-related settings such as port assignments, 
+    This class reads and stores various deployment-related settings such as port assignments,
     environment paths, logging configuration, and system mode (production, development, or simulation).
 
     Main functionalities:
@@ -438,7 +438,7 @@ def configure_logger(self):
         """
         Configures the logging system for the deployment controller.
 
-        This method sets up both console and file logging with a consistent format and appropriate log levels. 
+        This method sets up both console and file logging with a consistent format and appropriate log levels.
         It also ensures that Uvicorn loggers are properly configured to avoid duplicate log outputs.
 
         Main functionalities:
@@ -452,7 +452,7 @@ def configure_logger(self):
             - Ensures clean and consistent logging output during deployment.
 
         Note:
-            This method does not set up file logging directly, but prepares the base configuration 
+            This method does not set up file logging directly, but prepares the base configuration
             and Uvicorn logger behavior for further logging use.
         """
         log_console_format = "[%(asctime)s] [%(name)s] [%(levelname)s] %(message)s"
@@ -475,7 +475,7 @@ def ensure_directory_access(self, directory_path: str) -> str:
         """
         Ensures that the specified directory exists and is writable.
 
-        This method attempts to create the directory if it does not exist and verifies 
+        This method attempts to create the directory if it does not exist and verifies
         write access by writing and deleting a temporary metadata file.
 
         Args:
@@ -521,8 +521,8 @@ def start(self):
         """
         Starts the NEBULA deployment process and all associated services.
 
-        This method initializes the NEBULA platform by setting up the environment, 
-        checking port availability, starting key services (controller, frontend, WAF), 
+        This method initializes the NEBULA platform by setting up the environment,
+        checking port availability, starting key services (controller, frontend, WAF),
         and launching a filesystem observer to react to configuration changes.
 
         Main functionalities:
@@ -539,7 +539,7 @@ def start(self):
             - Central entry point for managing NEBULA components during deployment.
 
         Note:
-            The method blocks indefinitely until manually interrupted, 
+            The method blocks indefinitely until manually interrupted,
             and ensures graceful shutdown upon receiving SIGINT or SIGTERM.
         """
         banner = """
@@ -616,8 +616,8 @@ def signal_handler(self, sig, frame):
         """
         Handles system termination signals to ensure a clean shutdown.
 
-        This method is triggered when the application receives SIGTERM or SIGINT signals 
-        (e.g., via Ctrl+C or `kill`). It logs the event, performs cleanup actions, and 
+        This method is triggered when the application receives SIGTERM or SIGINT signals
+        (e.g., via Ctrl+C or `kill`). It logs the event, performs cleanup actions, and
         terminates the process gracefully.
 
         Args:
@@ -749,7 +749,7 @@ def run_controller(self):
                 )
 
         network_name = f"{os.environ['USER']}_nebula-net-base"
-        
+
         try:
             subprocess.check_call(["nvidia-smi"])
             self.gpu_available = True

app/windows/install.ps1

@@ -1,2 +1,2 @@
 # Run make install
-make install
+make install

docs/_prebuilt/commercial-faq.md

@@ -1,13 +1,13 @@
 # Commercial FAQ — NEBULA Enterprise
 
-**Q 1. What does the commercial license cover?**  
+**Q 1. What does the commercial license cover?**
 To be determined.
 
-**Q 2. Does the commercial edition include extra features?**  
+**Q 2. Does the commercial edition include extra features?**
 To be determined.
 
-**Q 3. Pricing model?**  
+**Q 3. Pricing model?**
 To be determined.
 
-**Q 4. Can we contribute back fixes?**  
-Absolutely; your patches remain under AGPL in the community edition, and you can keep proprietary extensions private under the commercial agreement.
+**Q 4. Can we contribute back fixes?**
+Absolutely; your patches remain under AGPL in the community edition, and you can keep proprietary extensions private under the commercial agreement.

nebula/addons/attacks/communications/floodingattack.py

@@ -69,9 +69,9 @@ async def wrapper(*args, **kwargs):
                                 )
                             _, *new_args = args  # Exclude self argument
                             await func(*new_args, **kwargs)
-                _, *new_args = args 
+                _, *new_args = args
                 return await func(*new_args)
-            
+
             return wrapper
 
         return decorator

nebula/addons/attacks/dataset/datapoison.py

@@ -71,6 +71,59 @@ def _convert_to_tensor(self, data: torch.Tensor | Image.Image | tuple) -> torch.
         else:
             return torch.tensor(data)
 
+    def _restore_data_format(self, data, original):
+        if isinstance(data, torch.Tensor):
+            array_data = data.detach().cpu().numpy()
+        else:
+            array_data = np.asarray(data)
+
+        original_shape = None
+        if isinstance(original, torch.Tensor):
+            original_shape = tuple(original.shape)
+        elif isinstance(original, Image.Image):
+            original_shape = np.array(original).shape
+        elif hasattr(original, "shape"):
+            original_shape = tuple(original.shape)
+
+        if original_shape is not None and array_data.shape != original_shape and array_data.size == np.prod(original_shape):
+            array_data = array_data.reshape(original_shape)
+
+        if isinstance(original, torch.Tensor):
+            restored = torch.as_tensor(array_data, device=original.device)
+            if original.dtype.is_floating_point:
+                original_max = original.detach().max() if original.numel() > 0 else torch.tensor(1.0, device=original.device)
+                if restored.numel() > 0 and original_max > 1 and restored.min() >= 0 and restored.max() <= 1:
+                    restored = restored * original_max
+                return restored.to(dtype=original.dtype)
+
+            if restored.numel() > 0 and restored.min() >= 0 and restored.max() <= 1:
+                restored = restored * torch.iinfo(original.dtype).max
+            return restored.clamp(torch.iinfo(original.dtype).min, torch.iinfo(original.dtype).max).to(dtype=original.dtype)
+
+        if isinstance(original, Image.Image):
+            original_array = np.array(original)
+            restored = self._restore_array_dtype(array_data, original_array.dtype, original_array)
+            return Image.fromarray(restored, mode=original.mode)
+
+        if isinstance(original, np.ndarray):
+            return self._restore_array_dtype(array_data, original.dtype, original)
+
+        return data
+
+    def _restore_array_dtype(self, data: np.ndarray, dtype: np.dtype, original: np.ndarray | None = None) -> np.ndarray:
+        dtype = np.dtype(dtype)
+        if np.issubdtype(dtype, np.integer):
+            if data.size > 0 and data.min() >= 0 and data.max() <= 1:
+                data = data * np.iinfo(dtype).max
+            return np.rint(np.clip(data, np.iinfo(dtype).min, np.iinfo(dtype).max)).astype(dtype)
+
+        if original is not None and data.size > 0 and original.size > 0:
+            original_max = np.max(original)
+            if original_max > 1 and data.min() >= 0 and data.max() <= 1:
+                data = data * original_max
+
+        return data.astype(dtype)
+
     def _handle_single_point(self, tensor: torch.Tensor) -> tuple[torch.Tensor, bool]:
         """
         Handle single point tensors by reshaping them.
@@ -100,7 +153,7 @@ def __init__(self, noise_type: str):
         """
         self.noise_type = noise_type.lower()
 
-    def apply_noise(self, t: torch.Tensor | Image.Image, poisoned_noise_percent: float) -> torch.Tensor:
+    def apply_noise(self, t: torch.Tensor | Image.Image, poisoned_noise_percent: float):
         """
         Applies noise to a tensor based on the specified noise type and poisoning percentage.
 
@@ -109,9 +162,10 @@ def apply_noise(self, t: torch.Tensor | Image.Image, poisoned_noise_percent: flo
             poisoned_noise_percent: The percentage of noise to be applied (0-100)
 
         Returns:
-            The tensor with noise applied
+            The poisoned data in the same format as the input
         """
-        t = self._convert_to_tensor(t)
+        original = t[0] if isinstance(t, tuple) else t
+        t = self._convert_to_tensor(original)
         t, is_single_point = self._handle_single_point(t)
 
         arr = t.detach().cpu().numpy()
@@ -122,21 +176,21 @@ def apply_noise(self, t: torch.Tensor | Image.Image, poisoned_noise_percent: flo
         )
 
         if self.noise_type == "salt":
-            poisoned = torch.tensor(random_noise(arr, mode=self.noise_type, amount=poisoned_ratio))
+            poisoned = random_noise(arr, mode=self.noise_type, amount=poisoned_ratio)
         elif self.noise_type == "gaussian":
-            poisoned = torch.tensor(random_noise(arr, mode=self.noise_type, mean=0, var=poisoned_ratio, clip=True))
+            poisoned = random_noise(arr, mode=self.noise_type, mean=0, var=poisoned_ratio, clip=True)
         elif self.noise_type == "s&p":
-            poisoned = torch.tensor(random_noise(arr, mode=self.noise_type, amount=poisoned_ratio))
+            poisoned = random_noise(arr, mode=self.noise_type, amount=poisoned_ratio)
         elif self.noise_type == "nlp_rawdata":
             poisoned = self.poison_to_nlp_rawdata(arr, poisoned_ratio)
         else:
             logging.info(f"ERROR: noise_type '{self.noise_type}' not supported in data poison attack.")
-            return t
+            return original
 
         if is_single_point:
             poisoned = poisoned[0]
 
-        return poisoned
+        return self._restore_data_format(poisoned, original)
 
     def poison_to_nlp_rawdata(self, text_data: list, poisoned_ratio: float) -> list:
         """
@@ -221,18 +275,19 @@ def __init__(self, target_label: int):
         """
         self.target_label = target_label
 
-    def add_x_to_image(self, img: torch.Tensor | Image.Image) -> torch.Tensor:
+    def add_x_to_image(self, img: torch.Tensor | Image.Image):
         """
         Adds a 10x10 pixel 'X' mark to the top-left corner of an image.
 
         Args:
             img: Input image tensor or PIL Image
 
         Returns:
-            Modified image with X pattern
+            Modified image in the same format as the input
         """
         logging.info(f"[{self.__class__.__name__}] Adding X pattern to image")
-        img = self._convert_to_tensor(img)
+        original = img[0] if isinstance(img, tuple) else img
+        img = self._convert_to_tensor(original)
         img, is_single_point = self._handle_single_point(img)
 
         # Handle batch dimension if present
@@ -267,7 +322,7 @@ def add_x_to_image(self, img: torch.Tensor | Image.Image) -> torch.Tensor:
         if is_single_point:
             img = img[0]
 
-        return img
+        return self._restore_data_format(img, original)
 
     def poison_data(
         self,

nebula/addons/attacks/model/gllneuroninversion.py

@@ -66,4 +66,4 @@ def model_attack(self, received_weights):
         # Inject random noise of the same shape and type
         received_weights[target_key] = torch.empty_like(target_weights).uniform_(0, noise_scale)
 
-        return received_weights
+        return received_weights

nebula/addons/attacks/model/swappingweights.py

@@ -109,4 +109,4 @@ def model_attack(self, received_weights):
         if self.layer_idx + 2 < len(layer_keys):
             received_weights[layer_keys[self.layer_idx + 2]] = received_weights[layer_keys[self.layer_idx + 2]][:, perm]
 
-        return received_weights
+        return received_weights

nebula/addons/defenses/__init__.py

@@ -0,0 +1 @@
+"""Defense add-ons for Nebula."""