catocli 3.0.26__py3-none-any.whl → 3.0.29__py3-none-any.whl

catocli/Utils/clidriver.py

@@ -47,16 +47,16 @@ from ..parsers.query_enterpriseDirectory import query_enterpriseDirectory_parse
 from ..parsers.query_devices import query_devices_parse
 from ..parsers.query_accountSnapshot import query_accountSnapshot_parse
 from ..parsers.query_catalogs import query_catalogs_parse
-from ..parsers.query_site import query_site_parse
 from ..parsers.query_xdr import query_xdr_parse
-from ..parsers.query_policy import query_policy_parse
-from ..parsers.query_container import query_container_parse
+from ..parsers.query_site import query_site_parse
 from ..parsers.query_groups import query_groups_parse
+from ..parsers.query_container import query_container_parse
+from ..parsers.query_policy import query_policy_parse
 from ..parsers.mutation_xdr import mutation_xdr_parse
-from ..parsers.mutation_sites import mutation_sites_parse
-from ..parsers.mutation_container import mutation_container_parse
 from ..parsers.mutation_site import mutation_site_parse
+from ..parsers.mutation_sites import mutation_sites_parse
 from ..parsers.mutation_policy import mutation_policy_parse
+from ..parsers.mutation_container import mutation_container_parse
 from ..parsers.mutation_admin import mutation_admin_parse
 from ..parsers.mutation_accountManagement import mutation_accountManagement_parse
 from ..parsers.mutation_sandbox import mutation_sandbox_parse
@@ -182,16 +182,16 @@ query_enterpriseDirectory_parser = query_enterpriseDirectory_parse(query_subpars
 query_devices_parser = query_devices_parse(query_subparsers)
 query_accountSnapshot_parser = query_accountSnapshot_parse(query_subparsers)
 query_catalogs_parser = query_catalogs_parse(query_subparsers)
-query_site_parser = query_site_parse(query_subparsers)
 query_xdr_parser = query_xdr_parse(query_subparsers)
-query_policy_parser = query_policy_parse(query_subparsers)
-query_container_parser = query_container_parse(query_subparsers)
+query_site_parser = query_site_parse(query_subparsers)
 query_groups_parser = query_groups_parse(query_subparsers)
+query_container_parser = query_container_parse(query_subparsers)
+query_policy_parser = query_policy_parse(query_subparsers)
 mutation_xdr_parser = mutation_xdr_parse(mutation_subparsers)
-mutation_sites_parser = mutation_sites_parse(mutation_subparsers)
-mutation_container_parser = mutation_container_parse(mutation_subparsers)
 mutation_site_parser = mutation_site_parse(mutation_subparsers)
+mutation_sites_parser = mutation_sites_parse(mutation_subparsers)
 mutation_policy_parser = mutation_policy_parse(mutation_subparsers)
+mutation_container_parser = mutation_container_parse(mutation_subparsers)
 mutation_admin_parser = mutation_admin_parse(mutation_subparsers)
 mutation_accountManagement_parser = mutation_accountManagement_parse(mutation_subparsers)
 mutation_sandbox_parser = mutation_sandbox_parse(mutation_subparsers)

catocli/Utils/formatter_utils.py

@@ -165,17 +165,6 @@ def build_wide_timeseries_header(dimension_names: List[str], measures: List[str]
     return header
 
 
-
-
-
-
-
-
-
-
-
-
-
 def format_to_csv(response_data: Dict[str, Any], operation_name: str) -> str:
     """
     Main function to format response data to CSV based on operation type

catocli/Utils/help_formatter.py

@@ -82,19 +82,33 @@ class JSONExample:
         """Format the JSON example for the specific platform - show only the best format"""
         if platform_info.platform == 'windows':
             if platform_info.shell == 'powershell':
-                # For PowerShell, show multiple options to work around quote stripping issues
+                # For PowerShell, show here-string format
                 return self._format_powershell_comprehensive(command_name)
             else:
                 # For cmd, use single-line with escaped quotes
                 single_line = json.dumps(self.parsed_json) if self.parsed_json else self.json_data.replace('\n', ' ')
                 escaped_json = single_line.replace('"', '\\"')
-                return [f'catocli {command_name} "{escaped_json}" -p']
+                # Extract flags from command template
+                flags = self._extract_flags_from_template()
+                return [f'catocli {command_name} "{escaped_json}" {flags}'.strip()]
         else:
-            # For Unix-like systems, use multi-line
+            # For Unix-like systems, use multi-line with proper formatting
             return [self.command_template.format(command=command_name, json=self.json_data)]
     
+    def _extract_flags_from_template(self) -> str:
+        """Extract flags from the command template (everything after {json})""" 
+        # Extract everything after '{json}' in the template
+        if "'{json}'" in self.command_template:
+            parts = self.command_template.split("'{json}'")
+            if len(parts) > 1:
+                return parts[1].strip()
+        return ""
+    
     def _format_powershell_comprehensive(self, command_name: str) -> List[str]:
         """Format PowerShell here-string example with proper quote escaping"""
+        # Extract flags from command template
+        flags = self._extract_flags_from_template()
+        
         # Escape double quotes in JSON for PowerShell compatibility
         escaped_json = self.json_data.replace('"', '\\"')
         
@@ -103,7 +117,7 @@ class JSONExample:
             "# PowerShell (using here-string):",
             f"catocli {command_name} @'",
             escaped_json,
-            "'@ -p"
+            f"'@ {flags}".strip() if flags else "'@"
         ]
         
         return examples
@@ -227,52 +241,94 @@ class UniversalHelpFormatter:
             readme_examples = self._extract_from_readme(command_path)
             if readme_examples:
                 for example in readme_examples:
-                    # Check if this example starts with a comment (lines starting with #)
-                    if example.startswith('#') and '\n' in example:
-                        # This is a comment followed by a command - need to format the command part
+                    # Check if this is a header or description line (not a command)
+                    if example.startswith('###') or (example.startswith('-') and 'catocli' not in example):
+                        # This is a header or description - preserve as-is
+                        help_lines.append(example)
+                        continue
+                    
+                    # Check if this example starts with a comment followed by a command
+                    if example.startswith('#') and '\n' in example and 'catocli' in example:
+                        # This is a comment followed by a command - extract both parts
                         lines = example.split('\n', 1)
                         if len(lines) == 2:
                             comment_line = lines[0]
-                            command_line = lines[1]
+                            command_part = lines[1]
                             
-                            # Check if command has JSON and format appropriately
-                            if '{' in command_line and '}' in command_line:
-                                json_match = self._extract_json_from_example(command_line)
+                            # Check if command has multi-line JSON and format appropriately
+                            if "'{" in command_part and "}'" in command_part:
+                                json_match = self._extract_json_from_example(command_part)
                                 if json_match:
+                                    # Extract command flags (everything after }')
+                                    flags = ""
+                                    if "}'" in command_part:
+                                        flags_match = re.search(r"}'\s*(.*)$", command_part, re.MULTILINE)
+                                        if flags_match:
+                                            flags = flags_match.group(1).strip()
+                                    
+                                    # Create command template with flags
+                                    if flags:
+                                        command_template = f"catocli {{command}} '{{json}}' {flags}"
+                                    else:
+                                        command_template = "catocli {command} '{json}'"
+                                    
                                     # Create JSONExample and apply platform-specific formatting
-                                    json_example = JSONExample(json_match)
+                                    json_example = JSONExample(json_match, command_template)
                                     formatted_commands = json_example.format_for_platform(self.platform_info, command_name)
                                     # Add comment first, then formatted commands
                                     help_lines.append(comment_line)
                                     help_lines.extend(formatted_commands)
                                 else:
                                     # JSON extraction failed, format as simple command
-                                    formatted_command = self._format_simple_command_for_platform(command_line)
+                                    formatted_command = self._format_simple_command_for_platform(command_part)
                                     help_lines.append(comment_line)
                                     help_lines.append(formatted_command)
                             else:
                                 # Simple command - apply platform formatting
-                                formatted_command = self._format_simple_command_for_platform(command_line)
+                                formatted_command = self._format_simple_command_for_platform(command_part)
                                 help_lines.append(comment_line)
                                 help_lines.append(formatted_command)
                         else:
                             # Fallback - preserve as-is
                             help_lines.append(example)
-                    elif '{' in example and '}' in example:
-                        # Check if this is a multi-line JSON example that can be platform-formatted
-                        json_match = self._extract_json_from_example(example)
-                        if json_match and not example.startswith('#'):
-                            # Create JSONExample and apply platform-specific formatting
-                            json_example = JSONExample(json_match)
-                            formatted_examples = json_example.format_for_platform(self.platform_info, command_name)
-                            help_lines.extend(formatted_examples)
+                    elif 'catocli' in example and '{' in example and '}' in example:
+                        # This is a catocli command with JSON - check if multi-line
+                        if '\n' in example and "'{" in example:
+                            # Multi-line JSON command
+                            json_match = self._extract_json_from_example(example)
+                            if json_match:
+                                # Extract command flags (everything after }')
+                                flags = ""
+                                if "}'" in example:
+                                    flags_match = re.search(r"}'\s*(.*)$", example, re.MULTILINE)
+                                    if flags_match:
+                                        flags = flags_match.group(1).strip()
+                                
+                                # Create command template with flags
+                                if flags:
+                                    command_template = f"catocli {{command}} '{{json}}' {flags}"
+                                else:
+                                    command_template = "catocli {command} '{json}'"
+                                
+                                # Create JSONExample and apply platform-specific formatting
+                                json_example = JSONExample(json_match, command_template)
+                                formatted_examples = json_example.format_for_platform(self.platform_info, command_name)
+                                help_lines.extend(formatted_examples)
+                            else:
+                                # Preserve as-is if JSON extraction fails
+                                help_lines.append(example)
                         else:
-                            # Preserve as-is if it has comments or JSON extraction fails
-                            help_lines.append(example)
+                            # Single-line command with JSON - format as simple command
+                            formatted_example = self._format_simple_command_for_platform(example)
+                            help_lines.append(formatted_example)
                     else:
-                        # Simple command examples without JSON - apply platform formatting
-                        formatted_example = self._format_simple_command_for_platform(example)
-                        help_lines.append(formatted_example)
+                        # Simple command examples without JSON or description text - apply platform formatting
+                        if 'catocli' in example:
+                            formatted_example = self._format_simple_command_for_platform(example)
+                            help_lines.append(formatted_example)
+                        else:
+                            # Not a command - preserve as-is (likely description text)
+                            help_lines.append(example)
                     help_lines.append("")  # Add spacing between examples
         
         description_examples = []
@@ -307,7 +363,7 @@ class UniversalHelpFormatter:
         return "\n".join(help_lines)
 
     def _extract_from_readme(self, command_path: str) -> List[str]:
-        """Extract all catocli examples from README.md files with comments"""
+        """Extract catocli examples from README.md files, prioritizing Additional Examples section"""
         examples = []
         
         # Find README.md file
@@ -328,21 +384,48 @@ class UniversalHelpFormatter:
             
             command_name = command_path.replace('_', ' ')
             
-            # Check if "### Examples Summary" or "### Additional Examples" sections exist
-            has_examples_summary = "### Examples Summary" in content or "### Additional Examples" in content
-            if has_examples_summary:
-                # Extract and display the examples summary section
-                summary_pattern = r'### (?:Examples Summary|Additional Examples)\n(.*?)(?=\n###|\n## |\Z)'
-                summary_match = re.search(summary_pattern, content, re.DOTALL)
-                if summary_match:
-                    summary_content = summary_match.group(1).strip()
-                    examples.append(f"\n### Examples Summary")
-                    examples.append(summary_content)
+            # Check if "## Advanced Usage" or "### Additional Examples" section exists
+            has_advanced_usage = "## Advanced Usage" in content
+            has_additional_examples = "### Additional Examples" in content
+            
+            # Define content to parse
+            content_to_parse = content
+            if has_advanced_usage:
+                # Extract the Advanced Usage section (up to #### which is next level heading)
+                advanced_pattern = r'## Advanced Usage\n(.*?)(?=\n####|\Z)'
+                advanced_match = re.search(advanced_pattern, content, re.DOTALL)
+                if advanced_match:
+                    content_to_parse = advanced_match.group(1)
+                    # Add a header for the examples
+                    examples.append("### Examples")
+                    # Extract list items from Additional Examples intro (before first # heading)
+                    intro_pattern = r'### Additional Examples\n(.*?)(?=\n#[^#])'
+                    intro_match = re.search(intro_pattern, content_to_parse, re.DOTALL)
+                    if intro_match and intro_match.group(1).strip():
+                        intro_text = intro_match.group(1).strip()
+                        # Only add if it contains bullet points or descriptions
+                        if '-' in intro_text:
+                            examples.append(intro_text)
+                    examples.append("")  # Add spacing
+            elif has_additional_examples:
+                # Fallback: Extract only the Additional Examples section
+                additional_pattern = r'### Additional Examples\n(.*?)(?=\n####|\n## |\Z)'
+                additional_match = re.search(additional_pattern, content, re.DOTALL)
+                if additional_match:
+                    content_to_parse = additional_match.group(1)
+                    examples.append("### Examples")
+                    # Extract list items from the section intro
+                    intro_pattern = r'^(.*?)(?=\n#[^#])'
+                    intro_match = re.search(intro_pattern, content_to_parse, re.DOTALL)
+                    if intro_match and intro_match.group(1).strip():
+                        intro_text = intro_match.group(1).strip()
+                        if '-' in intro_text:
+                            examples.append(intro_text)
                     examples.append("")  # Add spacing
             
-            # Extract ALL catocli commands from markdown code blocks
+            # Extract catocli commands from markdown code blocks
             code_block_pattern = r'```(?:bash|shell|json)?\n(.*?)```'
-            matches = re.findall(code_block_pattern, content, re.DOTALL)
+            matches = re.findall(code_block_pattern, content_to_parse, re.DOTALL)
             
             for match in matches:
                 # Split the match into individual lines and extract catocli commands with comments
@@ -375,10 +458,14 @@ class UniversalHelpFormatter:
                             # Keep the full command line including the opening bracket
                     elif in_multiline_json and current_command:
                         # We're in a multi-line JSON block - preserve exact formatting
-                        if stripped_line == "}'":
-                            # End of multi-line JSON
+                        if "}'" in stripped_line:
+                            # End of multi-line JSON - include any flags after }'
                             current_command += '\n' + line
                             in_multiline_json = False
+                            # Append the completed command
+                            examples.append(current_command)
+                            current_command = None
+                            current_comment = None
                         else:
                             # Continue multi-line JSON with exact indentation
                             current_command += '\n' + line
@@ -402,13 +489,14 @@ class UniversalHelpFormatter:
                 if current_command and not in_multiline_json:
                     examples.append(current_command)
             
-            # Also look for inline catocli commands (in backticks)
-            inline_pattern = r'`(catocli[^`]+)`'
-            inline_matches = re.findall(inline_pattern, content)
-            
-            for cmd in inline_matches:
-                if command_name in cmd and cmd not in examples:
-                    examples.append(cmd)
+            # If no Additional Examples section was found, also look for inline catocli commands (in backticks)
+            if not has_additional_examples:
+                inline_pattern = r'`(catocli[^`]+)`'
+                inline_matches = re.findall(inline_pattern, content)
+                
+                for cmd in inline_matches:
+                    if command_name in cmd and cmd not in examples:
+                        examples.append(cmd)
                     
         except Exception as e:
             print(f"Warning: Could not parse README for {command_path}: {e}")
@@ -465,20 +553,21 @@ class UniversalHelpFormatter:
     def _extract_json_from_example(self, example: str) -> str:
         """Extract JSON data from a catocli command example"""
         try:
-            # Look for JSON in single quotes first (most common)
-            single_quote_pattern = r"catocli[^']*'([^']+)'"
-            match = re.search(single_quote_pattern, example)
+            # Look for multi-line JSON first (between '{ and }' with potential flags after)
+            # This pattern captures everything between '{ and }' (non-greedy)
+            multiline_pattern = r"'(\{[\s\S]*?\})'(?:\s+[-\w])*"
+            match = re.search(multiline_pattern, example)
             if match:
                 json_str = match.group(1)
                 # Validate it's JSON by trying to parse it
                 json.loads(json_str)
                 return json_str
             
-            # Look for multi-line JSON (between '{ and }')
-            multiline_pattern = r"'\{([\s\S]*?)\}'"
-            match = re.search(multiline_pattern, example)
+            # Fallback to simple single-line JSON in single quotes
+            single_quote_pattern = r"catocli[^']*'([^']+)'"
+            match = re.search(single_quote_pattern, example)
             if match:
-                json_str = "{" + match.group(1) + "}"
+                json_str = match.group(1)
                 # Validate it's JSON by trying to parse it
                 json.loads(json_str)
                 return json_str

catocli/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "3.0.26"
+__version__ = "3.0.29"
 __cato_host__ = "https://api.catonetworks.com/api/v1/graphql2"

catocli/parsers/query_accountMetrics/README.md

@@ -42,7 +42,10 @@ catocli query accountMetrics '{
 ### Additional Examples
 - Example all values and lables
 - Example all values and lables for a single account
-- Example all values and lables for a single user
+- Monitor all key performance indicators for a specific site:
+- Analyze network performance for specific users:
+- Get a simple health snapshot without filters:
+- Focus on bandwidth utilization with packet loss metrics
 - Last hour no filters
 
 # Example all values and lables
@@ -88,34 +91,78 @@ catocli query accountMetrics '{
 }' 
 ```
 
-# Example all values and lables for a single user
+# Monitor all key performance indicators for a specific site:
 
 ```bash
-# Example all values and lables for a single user
+# Monitor all key performance indicators for a specific site:
 catocli query accountMetrics '{
     "buckets": 24,
+    "groupDevices": true,
+    "groupInterfaces": true,
     "labels": [
+        "bytesDownstream",
+        "bytesUpstream",
         "health",
-        "jitterDownstream",
+        "lastMileLatency",
+        "lastMilePacketLoss",
+        "rtt"
+    ],
+    "siteIDs": ["132814"],
+    "timeFrame": "last.P1D",
+    "perSecond": true,
+    "toRate": true
+}' -f csv --csv-filename=accountmetrics_site.csv
+```
+
+# Analyze network performance for specific users:
+
+```bash
+# Analyze network performance for specific users:
+catocli query accountMetrics '{
+    "buckets": 24,
+    "labels": [
+        "health",
+        "jitterDownstream", 
         "jitterUpstream",
         "lastMileLatency",
         "lastMilePacketLoss",
-        "lostDownstream",
-        "lostDownstreamPcnt",
-        "lostUpstream",
-        "lostUpstreamPcnt",
-        "packetsDiscardedDownstream",
-        "packetsDiscardedDownstreamPcnt",
-        "packetsDiscardedUpstream",
-        "packetsDiscardedUpstreamPcnt",
         "packetsDownstream",
         "packetsUpstream"
     ],
-    "timeFrame": "last.PT1H",
-    "userIDs": [
-        "0"
-    ]
-}'
+    "timeFrame": "last.P1D",
+    "userIDs": ["1000000"]
+}' -f csv --csv-filename=accountmetrics_user.csv
+```
+
+# Get a simple health snapshot without filters:
+
+```bash
+# Get a simple health snapshot without filters:
+catocli query accountMetrics '{
+    "timeFrame": "last.PT1H"
+}' -f csv --csv-filename=accountmetrics_health.csv
+```
+
+# Focus on bandwidth utilization with packet loss metrics
+
+```bash
+# Focus on bandwidth utilization with packet loss metrics
+catocli query accountMetrics '{
+    "buckets": 48,
+    "labels": [
+        "bytesDownstream",
+        "bytesUpstream", 
+        "bytesTotal",
+        "bytesDownstreamMax",
+        "bytesUpstreamMax",
+        "lostDownstreamPcnt",
+        "lostUpstreamPcnt"
+    ],
+    "siteIDs": ["132814"],
+    "timeFrame": "last.P2D",
+    "perSecond": true,
+    "withMissingData": true
+}' -f csv --csv-filename=accountmetrics_packet_loss.csv
 ```
 
 # Last hour no filters

catocli/parsers/query_appStats/README.md

@@ -44,6 +44,12 @@ catocli query appStats '{
 ### Additional Examples
 - Query to export user activity as in flows_created, for distinct users (user_name) for the last day
 - Query to export application_name, user_name and risk_score with traffic sum(upstream, downstream, trafffic) for last day
+- Track daily user engagement and flow creation
+- Analyze applications by usage and security risk
+- Analyze applications by usage and security risk:
+- Top applications weekly by bandwidth
+- Daily per-user bandwidth consumption
+- Monthly traffic patterns by country
 
 # Query to export user activity as in flows_created, for distinct users (user_name) for the last day
 
@@ -107,6 +113,127 @@ catocli query appStats '{
 }' -f csv --csv-filename app_user_account_metrics_report.csv
 ```
 
+# Track daily user engagement and flow creation
+
+```bash
+# Track daily user engagement and flow creation
+catocli query appStats '{
+    "dimension": [
+      {"fieldName": "user_name"},
+      {"fieldName": "domain"}
+    ],
+    "measure": [
+        {"aggType": "sum", "fieldName": "flows_created"},
+        {"aggType": "count_distinct", "fieldName": "user_name"},
+        {"aggType": "sum", "fieldName": "traffic"}
+    ],
+    "timeFrame": "last.P1D"
+}' -f csv --csv-filename=appstats_user_activity.csv
+```
+
+# Analyze applications by usage and security risk
+
+```bash
+# Analyze applications by usage and security risk:
+catocli query appStats '{
+    "dimension": [
+        {"fieldName": "application_name"},
+        {"fieldName": "user_name"},
+        {"fieldName": "risk_score"}
+    ],
+    "measure": [
+        {"aggType": "sum", "fieldName": "downstream"},
+        {"aggType": "sum", "fieldName": "upstream"},
+        {"aggType": "sum", "fieldName": "traffic"}
+    ],
+    "timeFrame": "last.P1D"
+}' -f csv --csv-filename=appstats_user_risk_report.csv
+```
+
+# Top applications weekly by bandwidth
+
+```bash
+# Top applications weekly by bandwidth
+catocli query appStats '{
+    "dimension": [{"fieldName": "application_name"}],
+    "measure": [
+        {"aggType": "sum", "fieldName": "traffic"},
+        {"aggType": "sum", "fieldName": "flows_created"}
+    ],
+    "appStatsSort": [
+        {"fieldName": "traffic", "order": "desc"}
+    ],
+    "timeFrame": "last.P7D"
+}' -f csv --csv-filename=appstats_app_utilization.csv
+```
+
+# Daily per-user bandwidth consumption
+
+```bash
+# Daily per-user bandwidth consumption
+catocli query appStats '{
+    "dimension": [
+        {"fieldName": "user_name"}
+    ],
+    "measure": [
+        {"aggType": "sum", "fieldName": "downstream"},
+        {"aggType": "sum", "fieldName": "upstream"},
+        {"aggType": "sum", "fieldName": "traffic"},
+        {"aggType": "sum", "fieldName": "flows_created"}
+    ],
+    "timeFrame": "last.P1D"
+}' -f csv --csv-filename=appstats_user_bw.csv
+```
+
+### 5. High-Risk Application Analysis
+
+Focus on applications with elevated risk scores:
+
+```bash
+catocli query appStats '{
+    "appStatsFilter": [
+        {
+            "fieldName": "risk_score",
+            "operator": "gte", 
+            "values": ["5"]
+        }
+    ],
+    "appStatsSort": [
+        {
+            "fieldName": "risk_score",
+            "order": "desc"
+        }
+    ],
+    "dimension": [
+        {"fieldName": "application_name"},
+        {"fieldName": "risk_score"},
+        {"fieldName": "user_name"}
+    ],
+    "measure": [
+        {"aggType": "sum", "fieldName": "traffic"},
+        {"aggType": "sum", "fieldName": "flows_created"}
+    ],
+    "timeFrame": "last.P7D"
+}' -f csv --csv-filename=appstats_app_by_risk.csv
+```
+
+# Monthly traffic patterns by country
+
+```bash
+# Monthly traffic patterns by country
+catocli query appStats '{
+    "dimension": [
+        {"fieldName": "site_country"},
+        {"fieldName": "src_site_country_code"}
+    ],
+    "measure": [
+        {"aggType": "sum", "fieldName": "traffic"},
+        {"aggType": "count_distinct", "fieldName": "user_name"}
+    ],
+    "timeFrame": "last.P1M"
+}' -f csv --csv-filename=appstats_by_country.csv
+```
+