catocli 3.0.22__tar.gz → 3.0.25__tar.gz

catocli-3.0.25/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: catocli
+Version: 3.0.25
+Summary: Cato Networks cli wrapper for the GraphQL API.
+Home-page: https://github.com/Cato-Networks/cato-cli
+Author: Cato Networks
+Author-email: [email protected]
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urllib3
+Requires-Dist: certifi
+Requires-Dist: six
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Cato Networks GraphQL API CLI
+
+The package provides a simple to use CLI that reflects industry standards (such as the AWS cli), and enables customers to manage Cato Networks configurations and processes via the [Cato Networks GraphQL API](https://api.catonetworks.com/api/v1/graphql2) easily integrating into configurations management, orchestration or automation frameworks to support the DevOps model.
+
+## Overview
+
+CatoCLI is a command-line interface that provides access to the Cato Networks GraphQL API, enabling you to:
+- Generate detailed network and security reports
+- Analyze user and application activity
+- Monitor network performance and events
+- Export data in multiple formats (JSON, CSV)
+- Automate reporting and monitoring tasks
+
+## Prerequisites
+
+- Python 3.6 or higher
+- CatoCLI installed (`pip3 install catocli`)
+- Valid Cato Networks API token and Account ID
+- Proper authentication configuration (see [Authentication Setup](#authentication-setup))
+
+## Installation  
+
+`pip3 install catocli`
+
+## Authentication Setup
+
+Configure your CatoCLI profile before using any query operations:
+
+```bash
+# Interactive configuration
+catocli configure set
+
+# Non-interactive configuration
+catocli configure set --cato-token "your-api-token" --account-id "12345"
+
+# List configured profiles
+catocli configure list
+
+# Show current profile
+catocli configure show
+```
+
+### Documentation
+
+For detailed information about profile management, see [PROFILES.md](PROFILES.md).
+
+[CLICK HERE](https://support.catonetworks.com/hc/en-us/articles/4413280536081-Generating-API-Keys-for-the-Cato-API) to see how create an API key to authenticate.
+
+## Running the CLI
+	catocli -h
+	catocli query -h
+	catocli query entityLookup -h
+	catocli query entityLookup '{"type":"country"}`
+    
+    // Override the accountID value as a cli argument
+	catocli query entityLookup -accountID=12345 '{"type":"country"}`
+
+## Check out run locally not as pip package
+	git clone git@github.com:Cato-Networks/cato-cli.git
+	cd cato-cli
+	python3 -m catocli -h
+
+## Query Operations
+
+### Core Analytics Queries
+
+| Operation | Description | Guide |
+|-----------|-------------|--------|
+| [Account Metrics](./catocli_user_guide/account-metrics.md) | Network performance metrics by site, user, or interface | 📊 |
+| [Application Statistics](./catocli_user_guide/app-stats.md) | User activity and application usage analysis | 📱 |
+| [Application Statistics Time Series](./catocli_user_guide/app-stats-timeseries.md) | Traffic analysis over time with hourly/daily breakdowns | 📈 |
+| [Events Time Series](./catocli_user_guide/events-timeseries.md) | Security events, connectivity, and threat analysis | 🔒 |
+| [Socket Port Metrics](./catocli_user_guide/socket-port-metrics.md) | Socket interface performance and traffic analysis | 🔌 |
+| [Socket Port Time Series](./catocli_user_guide/socket-port-timeseries.md) | Socket performance metrics over time | ⏱️ |
+
+### Advanced Topics
+
+- [Common Patterns & Best Practices](./catocli_user_guide/common-patterns.md) - Output formats, time frames, filtering patterns
+- [Python Integration - Windows](./catocli_user_guide/python-integration-windows.md) - Windows-specific Python automation examples
+- [Python Integration - Unix/Linux/macOS](./catocli_user_guide/python-integration-unix.md) - Unix-based Python integration guide
+- [SIEM Integration Guide](./catocli_user_guide/siem-integration.md) - Real-time security event streaming to SIEM platforms
+
+## Quick Start Examples
+
+### Basic Network Health Check
+```bash
+# Get last hour account metrics
+catocli query accountMetrics '{"timeFrame":"last.PT1H"}'
+```
+
+### User Activity Report (csv format)
+```bash
+# Export user activity for the last month to CSV
+catocli query appStats '{
+    "dimension": [{"fieldName": "user_name"}],
+    "measure": [{"aggType": "sum", "fieldName": "flows_created"}],
+    "timeFrame": "last.P1M"
+}' -f csv --csv-filename user_activity_report.csv
+```
+
+### Security Events Analysis
+```bash
+# Weekly security events breakdown
+catocli query eventsTimeSeries '{
+    "buckets": 7,
+    "eventsFilter": [{"fieldName": "event_type", "operator": "is", "values": ["Security"]}],
+    "eventsMeasure": [{"aggType": "sum", "fieldName": "event_count"}],
+    "timeFrame": "last.P7D"
+}'
+```
+
+## Output Formats
+
+CatoCLI supports multiple output formats:
+
+- **Enhanced JSON** (default): Formatted with granularity adjustments
+- **Raw JSON**: Original API response with `-raw` flag
+- **CSV**: Structured data export with `-f csv`
+- **Custom CSV**: Named files with `--csv-filename` and `--append-timestamp`
+
+## Time Frame Options
+
+Common time frame patterns:
+- `last.PT1H` - Last hour
+- `last.P1D` - Last day  
+- `last.P7D` - Last week
+- `last.P1M` - Last month
+- `utc.2023-02-{28/00:00:00--28/23:59:59}` - Custom UTC range
+
+## Getting Help
+
+- Use `-h` or `--help` with any command for detailed usage
+- Check the [Cato API Documentation](https://api.catonetworks.com/documentation/)
+- Review individual operation guides linked above
+
+
+This CLI is a Python 3 application and has been tested with Python 3.6 -> 3.8
+
+## Requirements:
+    python 3.6 or higher
+    
+## Confirm your version of python if installed:
+    Open a terminal
+    Enter: python -V or python3 -V
+
+## Installing the correct version for environment:
+https://www.python.org/downloads/

catocli-3.0.25/README.md

@@ -0,0 +1,147 @@
+# Cato Networks GraphQL API CLI
+
+The package provides a simple to use CLI that reflects industry standards (such as the AWS cli), and enables customers to manage Cato Networks configurations and processes via the [Cato Networks GraphQL API](https://api.catonetworks.com/api/v1/graphql2) easily integrating into configurations management, orchestration or automation frameworks to support the DevOps model.
+
+## Overview
+
+CatoCLI is a command-line interface that provides access to the Cato Networks GraphQL API, enabling you to:
+- Generate detailed network and security reports
+- Analyze user and application activity
+- Monitor network performance and events
+- Export data in multiple formats (JSON, CSV)
+- Automate reporting and monitoring tasks
+
+## Prerequisites
+
+- Python 3.6 or higher
+- CatoCLI installed (`pip3 install catocli`)
+- Valid Cato Networks API token and Account ID
+- Proper authentication configuration (see [Authentication Setup](#authentication-setup))
+
+## Installation  
+
+`pip3 install catocli`
+
+## Authentication Setup
+
+Configure your CatoCLI profile before using any query operations:
+
+```bash
+# Interactive configuration
+catocli configure set
+
+# Non-interactive configuration
+catocli configure set --cato-token "your-api-token" --account-id "12345"
+
+# List configured profiles
+catocli configure list
+
+# Show current profile
+catocli configure show
+```
+
+### Documentation
+
+For detailed information about profile management, see [PROFILES.md](PROFILES.md).
+
+[CLICK HERE](https://support.catonetworks.com/hc/en-us/articles/4413280536081-Generating-API-Keys-for-the-Cato-API) to see how create an API key to authenticate.
+
+## Running the CLI
+	catocli -h
+	catocli query -h
+	catocli query entityLookup -h
+	catocli query entityLookup '{"type":"country"}`
+    
+    // Override the accountID value as a cli argument
+	catocli query entityLookup -accountID=12345 '{"type":"country"}`
+
+## Check out run locally not as pip package
+	git clone git@github.com:Cato-Networks/cato-cli.git
+	cd cato-cli
+	python3 -m catocli -h
+
+## Query Operations
+
+### Core Analytics Queries
+
+| Operation | Description | Guide |
+|-----------|-------------|--------|
+| [Account Metrics](./catocli_user_guide/account-metrics.md) | Network performance metrics by site, user, or interface | 📊 |
+| [Application Statistics](./catocli_user_guide/app-stats.md) | User activity and application usage analysis | 📱 |
+| [Application Statistics Time Series](./catocli_user_guide/app-stats-timeseries.md) | Traffic analysis over time with hourly/daily breakdowns | 📈 |
+| [Events Time Series](./catocli_user_guide/events-timeseries.md) | Security events, connectivity, and threat analysis | 🔒 |
+| [Socket Port Metrics](./catocli_user_guide/socket-port-metrics.md) | Socket interface performance and traffic analysis | 🔌 |
+| [Socket Port Time Series](./catocli_user_guide/socket-port-timeseries.md) | Socket performance metrics over time | ⏱️ |
+
+### Advanced Topics
+
+- [Common Patterns & Best Practices](./catocli_user_guide/common-patterns.md) - Output formats, time frames, filtering patterns
+- [Python Integration - Windows](./catocli_user_guide/python-integration-windows.md) - Windows-specific Python automation examples
+- [Python Integration - Unix/Linux/macOS](./catocli_user_guide/python-integration-unix.md) - Unix-based Python integration guide
+- [SIEM Integration Guide](./catocli_user_guide/siem-integration.md) - Real-time security event streaming to SIEM platforms
+
+## Quick Start Examples
+
+### Basic Network Health Check
+```bash
+# Get last hour account metrics
+catocli query accountMetrics '{"timeFrame":"last.PT1H"}'
+```
+
+### User Activity Report (csv format)
+```bash
+# Export user activity for the last month to CSV
+catocli query appStats '{
+    "dimension": [{"fieldName": "user_name"}],
+    "measure": [{"aggType": "sum", "fieldName": "flows_created"}],
+    "timeFrame": "last.P1M"
+}' -f csv --csv-filename user_activity_report.csv
+```
+
+### Security Events Analysis
+```bash
+# Weekly security events breakdown
+catocli query eventsTimeSeries '{
+    "buckets": 7,
+    "eventsFilter": [{"fieldName": "event_type", "operator": "is", "values": ["Security"]}],
+    "eventsMeasure": [{"aggType": "sum", "fieldName": "event_count"}],
+    "timeFrame": "last.P7D"
+}'
+```
+
+## Output Formats
+
+CatoCLI supports multiple output formats:
+
+- **Enhanced JSON** (default): Formatted with granularity adjustments
+- **Raw JSON**: Original API response with `-raw` flag
+- **CSV**: Structured data export with `-f csv`
+- **Custom CSV**: Named files with `--csv-filename` and `--append-timestamp`
+
+## Time Frame Options
+
+Common time frame patterns:
+- `last.PT1H` - Last hour
+- `last.P1D` - Last day  
+- `last.P7D` - Last week
+- `last.P1M` - Last month
+- `utc.2023-02-{28/00:00:00--28/23:59:59}` - Custom UTC range
+
+## Getting Help
+
+- Use `-h` or `--help` with any command for detailed usage
+- Check the [Cato API Documentation](https://api.catonetworks.com/documentation/)
+- Review individual operation guides linked above
+
+
+This CLI is a Python 3 application and has been tested with Python 3.6 -> 3.8
+
+## Requirements:
+    python 3.6 or higher
+    
+## Confirm your version of python if installed:
+    Open a terminal
+    Enter: python -V or python3 -V
+
+## Installing the correct version for environment:
+https://www.python.org/downloads/

{catocli-3.0.22 → catocli-3.0.25}/catocli/Utils/formatter_app_stats.py

@@ -14,12 +14,12 @@ from typing import Dict, List, Any
 
 # Import shared utility functions
 try:
-    from .formatter_utils import convert_bytes_to_mb
+    from .formatter_utils import convert_bytes_to_mb, is_bytes_measure
 except ImportError:
     try:
-        from catocli.Utils.formatter_utils import convert_bytes_to_mb
+        from catocli.Utils.formatter_utils import convert_bytes_to_mb, is_bytes_measure
     except ImportError:
-        from formatter_utils import convert_bytes_to_mb
+        from formatter_utils import convert_bytes_to_mb, is_bytes_measure
 
 
 def format_app_stats(response_data: Dict[str, Any], output_format: str = 'json') -> str:
@@ -89,24 +89,27 @@ def _format_app_stats_to_json(response_data: Dict[str, Any]) -> str:
         record_data = {}
         
         for i, (field, value) in enumerate(fields_map.items()):
-            # Add unit type information for bytes fields
-            if (i < len(record_unit_types) and record_unit_types[i] == 'bytes'):
-                formatted_mb = convert_bytes_to_mb(value)
-                if formatted_mb and formatted_mb != str(value):
+            # Check if this is a bytes field using both unit type and field name
+            unit_type = record_unit_types[i] if i < len(record_unit_types) else "unknown"
+            is_bytes_field = (unit_type == 'bytes') or is_bytes_measure(field, unit_type)
+            
+            if is_bytes_field:
+                try:
+                    formatted_mb = convert_bytes_to_mb(value)
                     record_data[field] = {
                         "value": value,
                         "formatted_mb": formatted_mb,
                         "unit_type": "bytes"
                     }
-                else:
+                except (ValueError, ZeroDivisionError):
                     record_data[field] = {
                         "value": value,
-                        "unit_type": "bytes"
+                        "unit_type": "bytes_err"
                     }
             else:
                 record_data[field] = {
                     "value": value,
-                    "unit_type": record_unit_types[i] if i < len(record_unit_types) else "unknown"
+                    "unit_type": unit_type
                 }
         
         organized_data["appStats"]["records"].append(record_data)
@@ -155,7 +158,10 @@ def _format_app_stats_to_csv(response_data: Dict[str, Any]) -> str:
     # Create headers with _mb suffix for bytes fields
     headers = []
     for i, field_name in enumerate(field_names):
-        if i < len(field_unit_types) and field_unit_types[i] == 'bytes':
+        unit_type = field_unit_types[i] if i < len(field_unit_types) else "unknown"
+        is_bytes_field = (unit_type == 'bytes') or is_bytes_measure(field_name, unit_type)
+        
+        if is_bytes_field:
             headers.append(f'{field_name}_mb')
         else:
             headers.append(field_name)
@@ -172,12 +178,19 @@ def _format_app_stats_to_csv(response_data: Dict[str, Any]) -> str:
         for i, field in enumerate(field_names):
             value = fields_map.get(field, '')
             
-            # Convert bytes to MB if the field type is bytes
-            if (i < len(record_unit_types) and record_unit_types[i] == 'bytes'):
-                formatted_value = convert_bytes_to_mb(value)
-                row.append(formatted_value if formatted_value else value)
+            # Check if this is a bytes field using both unit type and field name
+            unit_type = record_unit_types[i] if i < len(record_unit_types) else "unknown"
+            is_bytes_field = (unit_type == 'bytes') or is_bytes_measure(field, unit_type)
+            
+            # Convert bytes to MB if the field is a bytes field
+            if is_bytes_field:
+                try:
+                    formatted_value = convert_bytes_to_mb(value) if value != '' else ''
+                    row.append(formatted_value)
+                except (ValueError, ZeroDivisionError):
+                    row.append(str(value) if value != '' else '')
             else:
-                row.append(value)
+                row.append(str(value) if value != '' else '')
         
         writer.writerow(row)
     

{catocli-3.0.22 → catocli-3.0.25}/catocli/Utils/formatter_app_stats_timeseries.py

@@ -16,12 +16,12 @@ from typing import Dict, List, Any, Tuple
 
 # Import shared utility functions
 try:
-    from .formatter_utils import format_timestamp, parse_label_for_dimensions_and_measure
+    from .formatter_utils import format_timestamp, parse_label_for_dimensions_and_measure, is_bytes_measure, convert_bytes_to_mb
 except ImportError:
     try:
-        from catocli.Utils.formatter_utils import format_timestamp, parse_label_for_dimensions_and_measure
+        from catocli.Utils.formatter_utils import format_timestamp, parse_label_for_dimensions_and_measure, is_bytes_measure, convert_bytes_to_mb
     except ImportError:
-        from formatter_utils import format_timestamp, parse_label_for_dimensions_and_measure
+        from formatter_utils import format_timestamp, parse_label_for_dimensions_and_measure, is_bytes_measure, convert_bytes_to_mb
 
 
 def format_app_stats_timeseries(response_data: Dict[str, Any], output_format: str = 'json') -> str:
@@ -170,20 +170,18 @@ def _format_app_stats_timeseries_to_json(response_data: Dict[str, Any]) -> str:
             for timestamp, value in measure_data['data'].items():
                 timestamp_str = format_timestamp(timestamp)
                 
-                if measure in ['downstream', 'upstream', 'traffic'] and value:
+                if is_bytes_measure(measure):
                     try:
-                        mb_value = value
-                        # mb_value = float(value) / 1048576
-                        formatted_value = f"{mb_value:.3f}".rstrip('0').rstrip('.')
+                        converted_value = convert_bytes_to_mb(value)
                         formatted_data[timestamp_str] = {
                             'value': value,
-                            'formatted_mb': formatted_value,
-                            'unit_type': 'mb'
+                            'formatted_mb': converted_value,
+                            'unit_type': 'bytes'
                         }
                     except (ValueError, ZeroDivisionError):
                         formatted_data[timestamp_str] = {
                             'value': value,
-                            'unit_type': 'mb'
+                            'unit_type': 'bytes_err'
                         }
                 else:
                     formatted_data[timestamp_str] = {
@@ -322,20 +320,14 @@ def _format_app_stats_timeseries_to_csv(response_data: Dict[str, Any]) -> str:
                 value = data.get(timestamp, '')
                 
                 # Convert bytes measures to MB and add appropriate suffix
-                if measure in ['downstream', 'upstream', 'traffic']:
-                    if value:
-                        try:
-                            # Current bug in appStatsTimeSeries returning mb indicating unit as bytes
-                            # mb_value = float(value) / 1048576
-                            mb_value = value
-                            formatted_value = f"{mb_value:.3f}".rstrip('0').rstrip('.')
-                            row_data[f'{measure}_mb'] = formatted_value
-                        except (ValueError, ZeroDivisionError):
-                            row_data[f'{measure}_mb'] = value
-                    else:
-                        row_data[f'{measure}_mb'] = value
+                if is_bytes_measure(measure):
+                    try:
+                        converted_value = convert_bytes_to_mb(value) if value != '' else ''
+                        row_data[f'{measure}_mb'] = converted_value
+                    except (ValueError, ZeroDivisionError):
+                        row_data[f'{measure}_mb'] = str(value) if value != '' else ''
                 else:
-                    row_data[measure] = value
+                    row_data[measure] = str(value) if value != '' else ''
             
             rows.append(row_data)
     

{catocli-3.0.22 → catocli-3.0.25}/catocli/Utils/formatter_utils.py

@@ -118,6 +118,7 @@ def is_bytes_measure(measure: str, units: str = "") -> bool:
     """
     bytes_measures = {
         'downstream', 'upstream', 'traffic', 'bytes', 'bytesDownstream', 
+        'bytes_upstream', 'bytes_downstream', 'bytes_total',
         'bytesUpstream', 'bytesTotal', 'throughput_downstream', 'throughput_upstream'
     }
     

catocli-3.0.25/catocli/__init__.py

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

{catocli-3.0.22 → catocli-3.0.25}/catocli/parsers/customParserApiClient.py

@@ -350,7 +350,9 @@ def createRequest(args, configuration):
                                 print(f"Saved CSV report to: {output_path}")
                             
                             # Return structured response similar to export functions
-                            return [{"success": True, "output_file": output_path, "operation": operation_name}]
+                            # Normalize path separators for better cross-platform display
+                            display_path = output_path.replace(os.sep, '/')
+                            return [{"success": True, "output_file": display_path, "operation": operation_name}]
                         elif csv_output is None:
                             # Formatter returned None, indicating we should fall back to raw response
                             print("INFO: No processable data found, returning raw API response")
@@ -1844,7 +1846,9 @@ def createPrivateRequest(args, configuration):
                                 print(f"Saved CSV report to: {output_path}")
                             
                             # Return structured response similar to export functions
-                            return [{"success": True, "output_file": output_path, "operation": csv_operation, "private_command": private_command}]
+                            # Normalize path separators for better cross-platform display
+                            display_path = output_path.replace(os.sep, '/')
+                            return [{"success": True, "output_file": display_path, "operation": csv_operation, "private_command": private_command}]
                         else:
                             print("WARNING: CSV formatter returned empty result")
                             return response

{catocli-3.0.22 → catocli-3.0.25}/catocli/parsers/query_appStatsTimeSeries/README.md

@@ -58,6 +58,7 @@ catocli query appStatsTimeSeries '{
             "fieldName": "application_name"
         }
     ],
+    "perSecond": false,
     "measure": [
         {
             "aggType": "sum",
@@ -99,6 +100,7 @@ catocli query appStatsTimeSeries '{
             "fieldName": "user_name"
         }
     ],
+    "perSecond": false,
     "measure": [
         {
             "aggType": "sum",

{catocli-3.0.22 → catocli-3.0.25}/catocli/parsers/utils/export_utils.py

@@ -183,9 +183,11 @@ def write_json_export(
         if verbose:
             print(f"Successfully exported data to JSON: {filepath}")
         
+        # Normalize path separators for better cross-platform display
+        display_path = filepath.replace(os.sep, '/')
         return {
             'success': True,
-            'output_file': filepath,
+            'output_file': display_path,
             'format': 'json',
             'record_count': len(data) if isinstance(data, (list, dict)) else 1
         }
@@ -232,9 +234,11 @@ def write_csv_export(
         if verbose:
             print(f"Successfully exported {len(data)} records to CSV: {filepath}")
         
+        # Normalize path separators for better cross-platform display
+        display_path = filepath.replace(os.sep, '/')
         return {
             'success': True,
-            'output_file': filepath,
+            'output_file': display_path,
             'format': 'csv',
             'record_count': len(data)
         }

{catocli-3.0.22 → catocli-3.0.25}/models/mutation.policy.antiMalwareFileHash.addRule.json

@@ -1859,26 +1859,6 @@
                                                                                                         "non_null": false
                                                                                                     },
                                                                                                     "varName": "name"
-                                                                                                },
-                                                                                                "subPolicyId": {
-                                                                                                    "args": {},
-                                                                                                    "deprecationReason": null,
-                                                                                                    "description": null,
-                                                                                                    "id_str": "antiMalwareFileHash___addRule___rule___rule___section___subPolicyId",
-                                                                                                    "isDeprecated": false,
-                                                                                                    "name": "subPolicyId",
-                                                                                                    "path": "antiMalwareFileHash.addRule.rule.rule.section.subPolicyId",
-                                                                                                    "requestStr": "$subPolicyId:ID ",
-                                                                                                    "required": false,
-                                                                                                    "responseStr": "subPolicyId:$subPolicyId ",
-                                                                                                    "type": {
-                                                                                                        "kind": [
-                                                                                                            "SCALAR"
-                                                                                                        ],
-                                                                                                        "name": "ID",
-                                                                                                        "non_null": false
-                                                                                                    },
-                                                                                                    "varName": "subPolicyId"
                                                                                                 }
                                                                                             },
                                                                                             "inputFields": null,