illumio-pylo 0.3.11__py3-none-any.whl → 0.3.13__py3-none-any.whl

illumio_pylo/Helpers/exports.py

@@ -9,7 +9,7 @@ import illumio_pylo as pylo
 
 
 class ExcelHeader:
-    def __init__(self, name: str, nice_name: Optional[str] = None, max_width: Optional[int] = None, wrap_text: Optional[bool] = None, is_url: [bool] = False, url_text: str = 'Link'):
+    def __init__(self, name: str, nice_name: Optional[str] = None, max_width: Optional[int] = None, wrap_text: Optional[bool] = None, is_url: bool = False, url_text: str = 'Link'):
         self.name = name
         self.nice_name:str = nice_name if nice_name is not None else name
         self.max_width = max_width

illumio_pylo/LabelCommon.py

@@ -1,17 +1,27 @@
-from typing import Union
+from typing import TYPE_CHECKING
 from .Exception import PyloEx
 from .LabelStore import LabelStore
 
+if TYPE_CHECKING:
+    from .LabelDimension import LabelDimension
+
 
 class LabelCommon:
 
     __slots__ = ['owner', 'name', 'href', 'type']
 
-    def __init__(self, name: str, href: str, label_type: str, owner: LabelStore):
+    def __init__(self, name: str, href: str, label_type: str, owner: LabelStore) -> None:
         self.owner: LabelStore = owner
         self.name: str = name
         self.href: str = href
-        self.type = label_type
+        self.type: str = label_type
+
+    def get_dimension(self) -> 'LabelDimension':
+        """Get the LabelDimension object for this label's type from the owning LabelStore."""
+        dimension: 'LabelDimension | None' = self.owner.get_dimension(self.type)
+        if dimension is None:
+            raise PyloEx(f"Dimension '{self.type}' not found in LabelStore")
+        return dimension
 
     def is_label(self) -> bool:
         raise PyloEx("not implemented")

illumio_pylo/LabelDimension.py

@@ -0,0 +1,109 @@
+from typing import Dict, Optional, Set, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .API.JsonPayloadTypes import LabelDimensionObjectStructure
+
+# Module constants for dimension keys
+DIMENSION_KEY_ROLE: str = 'role'
+DIMENSION_KEY_APP: str = 'app'
+DIMENSION_KEY_ENV: str = 'env'
+DIMENSION_KEY_LOC: str = 'loc'
+
+# Set of built-in dimension keys
+BUILTIN_DIMENSION_KEYS: Set[str] = {DIMENSION_KEY_ROLE, DIMENSION_KEY_APP, DIMENSION_KEY_ENV, DIMENSION_KEY_LOC}
+
+
+class LabelDimension:
+    """
+    Represents a label dimension (type) in the Illumio PCE.
+    
+    Label dimensions define the categories of labels (e.g., role, app, env, loc).
+    Built-in dimensions are the standard four dimensions, while custom dimensions
+    can be created by the user.
+    """
+
+    __slots__ = ['key', 'display_name', 'href', 'created_at', 'created_by', 'updated_at', 'updated_by', 'raw_json']
+
+    def __init__(self, key: str, display_name: str, href: Optional[str] = None,
+                 created_at: Optional[str] = None, created_by: Optional[str] = None,
+                 updated_at: Optional[str] = None, updated_by: Optional[str] = None,
+                 raw_json: Optional['LabelDimensionObjectStructure'] = None) -> None:
+        self.key: str = key
+        self.display_name: str = display_name
+        self.href: Optional[str] = href
+        self.created_at: Optional[str] = created_at
+        self.created_by: Optional[str] = created_by
+        self.updated_at: Optional[str] = updated_at
+        self.updated_by: Optional[str] = updated_by
+        self.raw_json: Optional['LabelDimensionObjectStructure'] = raw_json
+
+    @staticmethod
+    def from_json(json_data: 'LabelDimensionObjectStructure') -> 'LabelDimension':
+        """
+        Factory method to create a LabelDimension from JSON data returned by the API.
+        
+        :param json_data: The JSON structure from the API
+        :return: A new LabelDimension instance
+        """
+        created_by: Optional[str] = None
+        if json_data.get('created_by') is not None:
+            created_by = json_data['created_by'].get('href')
+        
+        updated_by: Optional[str] = None
+        if json_data.get('updated_by') is not None:
+            updated_by = json_data['updated_by'].get('href')
+
+        return LabelDimension(
+            key=json_data['key'],
+            display_name=json_data['display_name'],
+            href=json_data.get('href'),
+            created_at=json_data.get('created_at'),
+            created_by=created_by,
+            updated_at=json_data.get('updated_at'),
+            updated_by=updated_by,
+            raw_json=json_data
+        )
+
+    @staticmethod
+    def create_builtin_dimensions() -> Dict[str, 'LabelDimension']:
+        """
+        Create the four built-in label dimensions with default display names.
+        
+        :return: A dictionary mapping dimension keys to LabelDimension objects
+        """
+        return {
+            DIMENSION_KEY_ROLE: LabelDimension(key=DIMENSION_KEY_ROLE, display_name='Role'),
+            DIMENSION_KEY_APP: LabelDimension(key=DIMENSION_KEY_APP, display_name='Application'),
+            DIMENSION_KEY_ENV: LabelDimension(key=DIMENSION_KEY_ENV, display_name='Environment'),
+            DIMENSION_KEY_LOC: LabelDimension(key=DIMENSION_KEY_LOC, display_name='Location'),
+        }
+
+    def is_role(self) -> bool:
+        """Check if this dimension is the Role dimension."""
+        return self.key == DIMENSION_KEY_ROLE
+
+    def is_application(self) -> bool:
+        """Check if this dimension is the Application dimension."""
+        return self.key == DIMENSION_KEY_APP
+
+    def is_environment(self) -> bool:
+        """Check if this dimension is the Environment dimension."""
+        return self.key == DIMENSION_KEY_ENV
+
+    def is_location(self) -> bool:
+        """Check if this dimension is the Location dimension."""
+        return self.key == DIMENSION_KEY_LOC
+
+    def is_builtin(self) -> bool:
+        """Check if this dimension is one of the four built-in dimensions."""
+        return self.key in BUILTIN_DIMENSION_KEYS
+
+    def is_custom(self) -> bool:
+        """Check if this dimension is a custom (non-built-in) dimension."""
+        return self.key not in BUILTIN_DIMENSION_KEYS
+
+    def __repr__(self) -> str:
+        return f"LabelDimension(key='{self.key}', display_name='{self.display_name}')"
+
+    def __str__(self) -> str:
+        return f"{self.display_name} ({self.key})"

illumio_pylo/LabelStore.py

@@ -1,15 +1,20 @@
 from hashlib import md5
 import random
-from typing import Set
+from typing import Set, Union
 # Pylo imports
 from illumio_pylo import log
 from .API.JsonPayloadTypes import LabelObjectJsonStructure, LabelGroupObjectJsonStructure, LabelDimensionObjectStructure
 from .Helpers import *
+from .LabelDimension import (
+    LabelDimension,
+    DIMENSION_KEY_ROLE, DIMENSION_KEY_APP, DIMENSION_KEY_ENV, DIMENSION_KEY_LOC
+)
 
-label_type_loc = 'loc'
-label_type_env = 'env'
-label_type_app = 'app'
-label_type_role = 'role'
+# Backward compatibility aliases
+label_type_loc: str = DIMENSION_KEY_LOC
+label_type_env: str = DIMENSION_KEY_ENV
+label_type_app: str = DIMENSION_KEY_APP
+label_type_role: str = DIMENSION_KEY_ROLE
 
 
 class LabelStore:
@@ -47,32 +52,78 @@ class LabelStore:
                         result.append(label)
             return result
 
-    __slots__ = ['owner', '_items_by_href', 'label_types', 'label_types_as_set', 'label_resolution_cache']
+    __slots__ = ['owner', '_items_by_href', '_dimensions', '_dimensions_dict', '_label_types_cache', '_label_types_as_set_cache', 'label_resolution_cache']
 
-    def __init__(self, owner: 'pylo.Organization'):
+    def __init__(self, owner: 'pylo.Organization') -> None:
         self.owner: "pylo.Organization" = owner
         self._items_by_href: Dict[str, Union[pylo.Label, pylo.LabelGroup]] = {}
-        self.label_types: List[str] = []
-        self.label_types_as_set: Set[str] = set()
+        self._dimensions: List[LabelDimension] = []
+        self._dimensions_dict: Dict[str, LabelDimension] = {}
+        self._label_types_cache: Optional[List[str]] = None
+        self._label_types_as_set_cache: Optional[Set[str]] = None
+
+        self.label_resolution_cache: Optional[Dict[str, List[pylo.Workload]]] = None
+
+    @property
+    def label_types(self) -> List[str]:
+        """Backward-compatible property returning list of label type keys (strings)."""
+        if self._label_types_cache is None:
+            self._label_types_cache = [dim.key for dim in self._dimensions]
+        return self._label_types_cache
+
+    @property
+    def label_types_as_set(self) -> Set[str]:
+        """Backward-compatible property returning set of label type keys (strings)."""
+        if self._label_types_as_set_cache is None:
+            self._label_types_as_set_cache = set(dim.key for dim in self._dimensions)
+        return self._label_types_as_set_cache
+
+    @property
+    def dimensions(self) -> List[LabelDimension]:
+        """Return the list of LabelDimension objects, preserving order."""
+        return self._dimensions
+
+    def get_dimension(self, key: str) -> Optional[LabelDimension]:
+        """Get a LabelDimension by its key."""
+        return self._dimensions_dict.get(key)
+
+    def _add_dimension(self, dimension: Union[str, LabelDimension]) -> None:
+        """Add a dimension to the store. Accepts either a string key or a LabelDimension object."""
+        if isinstance(dimension, str):
+            # Create a basic LabelDimension from string key for backward compatibility
+            if dimension in self._dimensions_dict:
+                return
+            # Create built-in dimensions with proper display names
+            builtin_dims: Dict[str, LabelDimension] = LabelDimension.create_builtin_dimensions()
+            if dimension in builtin_dims:
+                dim_obj: LabelDimension = builtin_dims[dimension]
+            else:
+                # Custom dimension from string - use key as display name
+                dim_obj = LabelDimension(key=dimension, display_name=dimension)
+        else:
+            dim_obj = dimension
+            if dim_obj.key in self._dimensions_dict:
+                return
 
-        self.label_resolution_cache: Optional[Dict[str, Union[pylo.Label, pylo.LabelGroup]]] = None
-        
-    def _add_dimension(self, dimension: str):
-        if dimension not in self.label_types_as_set:
-            self.label_types_as_set.add(dimension)
-            self.label_types.append(dimension)
+        self._dimensions.append(dim_obj)
+        self._dimensions_dict[dim_obj.key] = dim_obj
+        # Invalidate caches
+        self._label_types_cache = None
+        self._label_types_as_set_cache = None
 
-    def load_label_dimensions(self, json_list: Optional[List[LabelDimensionObjectStructure]]):
+    def load_label_dimensions(self, json_list: Optional[List[LabelDimensionObjectStructure]]) -> None:
         if json_list is None or len(json_list) == 0:
-            # add the default built-in label types
-            self._add_dimension(label_type_role)
-            self._add_dimension(label_type_app)
-            self._add_dimension(label_type_env)
-            self._add_dimension(label_type_loc)
+            # add the default built-in label types in the standard order
+            builtin_dims: Dict[str, LabelDimension] = LabelDimension.create_builtin_dimensions()
+            self._add_dimension(builtin_dims[DIMENSION_KEY_ROLE])
+            self._add_dimension(builtin_dims[DIMENSION_KEY_APP])
+            self._add_dimension(builtin_dims[DIMENSION_KEY_ENV])
+            self._add_dimension(builtin_dims[DIMENSION_KEY_LOC])
             return
 
-        for dimension in json_list:
-            self._add_dimension(dimension['key'])
+        for dimension_json in json_list:
+            dim_obj: LabelDimension = LabelDimension.from_json(dimension_json)
+            self._add_dimension(dim_obj)
 
     def load_labels_from_json(self, json_list: List[LabelObjectJsonStructure]):
         for json_label in json_list:
@@ -202,7 +253,7 @@ class LabelStore:
                             allow_label: bool = True,
                             raise_exception_if_not_found: bool = False) \
             -> Optional[Union['pylo.Label', 'pylo.LabelGroup', List[Union['pylo.Label', 'pylo.LabelGroup']]]]:
-        """Find a label by its name. If case_sensitive is False, the search is case-insensitive.
+        """Find a label by its name. If case_sensitive is False, the search is case-insensitive and will return a list of matches
         If case_sensitive is False it will return a list of labels with the same name rather than a single object.
         If missing_labels_names is not None, it will be filled with the names of the labels not found.
         If raise_exception_if_not_found is True, an exception will be raised if a label is not found.
@@ -210,22 +261,30 @@ class LabelStore:
         If a label is not found, None will be returned in the list.
         """
         if not isinstance(name, list):
-            if case_sensitive is False:
-                return self.find_object_by_name([name], label_type=label_type, case_sensitive=case_sensitive,
-                                                missing_labels_names=missing_labels_names,
-                                                allow_label_group=allow_label_group,
-                                                allow_label=allow_label,
-                                                raise_exception_if_not_found=raise_exception_if_not_found)
-            for label in self._items_by_href.values():
-                if label_type is not None and label.type != label_type:
-                    continue
-                if label.is_label() and allow_label:  # ignore groups
-                    if case_sensitive:
+            if case_sensitive:
+                for label in self._items_by_href.values():
+                    if label_type is not None and label.type != label_type:
+                        continue
+                    if label.is_label() and allow_label:
+                        if label.name == name:
+                            return label
+                    elif label.is_group() and allow_label_group:  # ignore labels
                         if label.name == name:
                             return label
-                elif allow_label_group:
-                    if label.name.lower() == name.lower():
-                        return label
+            else:
+                matches = []
+                for label in self._items_by_href.values():
+                    if label_type is not None and label.type != label_type:
+                        continue
+                    if label.is_label() and allow_label:
+                        if label.name.lower() == name.lower():
+                            matches.append(label)
+                    elif label.is_group() and allow_label_group:  # ignore labels
+                        if label.name.lower() == name.lower():
+                            matches.append(label)
+                if len(matches) > 0:
+                    return matches
+
             if raise_exception_if_not_found:
                 raise pylo.PyloEx("Label/group '%s' not found", name)
             if missing_labels_names is not None:

illumio_pylo/WorkloadStore.py

@@ -6,6 +6,7 @@ from .Organization import Organization
 from typing import Optional, List, Union, Set, Iterable
 
 from .WorkloadStoreSubClasses import UnmanagedWorkloadDraft, UnmanagedWorkloadDraftMultiCreatorManager
+from .FilterQuery import FilterQuery, get_workload_filter_registry
 
 
 class WorkloadStore:
@@ -297,5 +298,62 @@ class WorkloadStore:
     def new_unmanaged_workload_multi_creator_manager(self) -> UnmanagedWorkloadDraftMultiCreatorManager:
         return UnmanagedWorkloadDraftMultiCreatorManager(self)
 
+    def find_workloads_matching_query(self, query: str, include_deleted: bool = False) -> List['Workload']:
+        """
+        Find all workloads matching a filter query expression.
+
+        Query syntax supports:
+        - Comparison operators: ==, !=, <, >, <=, >=
+        - String operators: contains, matches (regex)
+        - Logical operators: and, or, not
+        - Parentheses for grouping
+
+        Available fields:
+        - name, hostname, forced_name, href, description
+        - online, managed, unmanaged, deleted
+        - os_id, os_detail
+        - ip_address, ip (checks all interfaces)
+        - last_heartbeat, last_heartbeat_received
+        - agent.status, agent.mode, mode, agent.version
+        - label.<type> for any label type configured in the PCE (e.g., label.role, label.app, label.env, label.loc)
+        - Shorthand aliases for labels (e.g., role, app, env, loc)
+        - created_at
+        - reference_count
+
+        Examples:
+            "(name == 'SRV158' or name == 'SRV48889') and ip_address == '192.168.2.54'"
+            "last_heartbeat_received <= '2022-09-12' and online == true"
+            "hostname contains 'prod' and label.env == 'Production'"
+            "name matches 'SRV[0-9]+' and not deleted == true"
+
+        :param query: filter query expression
+        :param include_deleted: whether to include deleted workloads in the search
+        :return: list of matching Workload objects
+        """
+        # Pass owner (Organization) to get registry with all configured label types
+        registry = get_workload_filter_registry(self.owner)
+        filter_query = FilterQuery(registry)
+
+        # Get workloads to filter
+        if include_deleted:
+            workloads = list(self.itemsByHRef.values())
+        else:
+            workloads = [w for w in self.itemsByHRef.values() if not w.deleted]
+
+        return filter_query.execute(query, workloads)
+
+    def find_workloads_matching_query_as_dict(self, query: str, include_deleted: bool = False) -> Dict[str, 'Workload']:
+        """
+        Find all workloads matching a filter query expression, returned as a dict with HREF as key.
+
+        See find_workloads_matching_query() for query syntax and available fields.
+
+        :param query: filter query expression
+        :param include_deleted: whether to include deleted workloads in the search
+        :return: dict of matching Workload objects with HREF as key
+        """
+        matching = self.find_workloads_matching_query(query, include_deleted)
+        return {w.href: w for w in matching}
+
 
 

illumio_pylo/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.3.11"
+__version__ = "0.3.13"
 
 from typing import Callable
 
@@ -12,9 +12,11 @@ from .ReferenceTracker import ReferenceTracker, Referencer, Pathable
 from .API.APIConnector import APIConnector, ObjectTypes
 from .API.RuleSearchQuery import RuleSearchQuery, RuleSearchQueryResolvedResultSet
 from .API.ClusterHealth import ClusterHealth
-from .API.Explorer import ExplorerResultSetV1, RuleCoverageQueryManager, ExplorerFilterSetV1, ExplorerQuery
+from .API.Explorer import (ExplorerResultSetV1, ExplorerResultSetV2, RuleCoverageQueryManager, ExplorerFilterSetV1,
+                           ExplorerFilterSetV2, ExplorerQuery, ExplorerQueryV2, ExplorerResultV2)
 from .API.AuditLog import AuditLogQuery, AuditLogQueryResultSet, AuditLogFilterSet
 from .API.CredentialsManager import get_credentials_from_file
+from .LabelDimension import LabelDimension, DIMENSION_KEY_ROLE, DIMENSION_KEY_APP, DIMENSION_KEY_ENV, DIMENSION_KEY_LOC
 from .LabelCommon import LabelCommon
 from .Label import Label
 from .LabelGroup import LabelGroup
@@ -31,7 +33,11 @@ from .Ruleset import Ruleset, RulesetScope, RulesetScopeEntry
 from .RulesetStore import RulesetStore
 from .SecurityPrincipal import SecurityPrincipal, SecurityPrincipalStore
 from .Organization import Organization
-from .Query import Query
+from .FilterQuery import (
+    FilterQuery, FilterRegistry, FilterField, ValueType,
+    WorkloadFilterRegistry, get_workload_filter_registry,
+    QueryLexer, QueryParser, QueryNode, AndNode, OrNode, NotNode, ConditionNode
+)
 
 
 def get_organization(fqdn: str, port: int, api_user: str, api_key: str,

illumio_pylo/cli/__init__.py

@@ -38,13 +38,15 @@ def run(forced_command_name: Optional[str] = None):
 
     parser = argparse.ArgumentParser(description='PYLO-CLI: Illumio API&More Command Line Interface')
     parser.add_argument('--pce', type=str, required=False,
-                        help='hostname of the PCE')
+                        help='name of the CredentialProfile to use (as defined in the credentials file)')
     parser.add_argument('--force-async-mode', action='store_true',
                         help='Forces the command to run async API queries when required (large PCEs which timeout on specific queries)')
     parser.add_argument('--debug', action='store_true',
                         help='Enables extra debugging output in Pylo framework')
     parser.add_argument('--use-cache', action='store_true',
                         help='For developers only')
+    parser.add_argument('--include-deleted-workloads', action='store_true',
+                        help='Include deleted workloads when loading data from the PCE')
     parser.add_argument('--version', action='store_true', help='Prints the version of the Pylo CLI')
 
     selected_command = None
@@ -80,6 +82,7 @@ def run(forced_command_name: Optional[str] = None):
 
     credential_profile_name = args['pce']
     settings_use_cache = args['use_cache']
+    include_deleted_workloads = args['include_deleted_workloads']
     org: Optional[pylo.Organization] = None
 
     # We are getting the command object associated to the command name if it was not already set (via forced_command_name)
@@ -111,7 +114,7 @@ def run(forced_command_name: Optional[str] = None):
             print("OK!")
 
             print(" * Downloading PCE objects from API... ".format(credential_profile_name), end="", flush=True)
-            config_data = connector.get_pce_objects(list_of_objects_to_load=selected_command.load_specific_objects_only, force_async_mode=args['force_async_mode'])
+            config_data = connector.get_pce_objects(list_of_objects_to_load=selected_command.load_specific_objects_only, force_async_mode=args['force_async_mode'], include_deleted_workloads=include_deleted_workloads)
             timer_download_finished = time.perf_counter()
             print("OK! (execution time: {:.2f} seconds)".format(timer_download_finished - timer_start))
 

illumio_pylo/cli/commands/__init__.py

@@ -33,3 +33,4 @@ from .credential_manager import command_object
 from .iplist_analyzer import command_object
 from .ven_compatibility_report_export import command_object
 from .label_delete_unused import command_object
+from .traffic_export import command_object