catocli 3.0.22__tar.gz → 3.0.24__tar.gz

catocli-3.0.24/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: catocli
+Version: 3.0.24
+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 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.24/README.md

@@ -0,0 +1,150 @@
+# 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 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.24/catocli/__init__.py

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

{catocli-3.0.22 → catocli-3.0.24}/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.24}/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.24}/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,

{catocli-3.0.22 → catocli-3.0.24}/models/mutation.policy.antiMalwareFileHash.addSection.json

@@ -980,89 +980,6 @@
                                                             "description": null,
                                                             "enumValues": null,
                                                             "fields": {
-                                                                "access": {
-                                                                    "args": {},
-                                                                    "deprecationReason": null,
-                                                                    "description": null,
-                                                                    "id_str": "antiMalwareFileHash___addSection___section___access",
-                                                                    "isDeprecated": false,
-                                                                    "name": "access",
-                                                                    "path": "antiMalwareFileHash.addSection.section.access",
-                                                                    "requestStr": "$entityAccess:EntityAccess ",
-                                                                    "required": false,
-                                                                    "responseStr": "access:$entityAccess ",
-                                                                    "type": {
-                                                                        "definition": {
-                                                                            "description": null,
-                                                                            "enumValues": null,
-                                                                            "fields": {
-                                                                                "action": {
-                                                                                    "args": {},
-                                                                                    "deprecationReason": null,
-                                                                                    "description": null,
-                                                                                    "id_str": "antiMalwareFileHash___addSection___section___access___action",
-                                                                                    "isDeprecated": false,
-                                                                                    "name": "action",
-                                                                                    "path": "antiMalwareFileHash.addSection.section.access.action",
-                                                                                    "requestStr": "$action:RBACAction! ",
-                                                                                    "required": true,
-                                                                                    "responseStr": "action:$action ",
-                                                                                    "type": {
-                                                                                        "definition": {
-                                                                                            "description": null,
-                                                                                            "enumValues": [
-                                                                                                {
-                                                                                                    "deprecationReason": null,
-                                                                                                    "description": null,
-                                                                                                    "isDeprecated": false,
-                                                                                                    "name": "NONE"
-                                                                                                },
-                                                                                                {
-                                                                                                    "deprecationReason": null,
-                                                                                                    "description": null,
-                                                                                                    "isDeprecated": false,
-                                                                                                    "name": "VIEW"
-                                                                                                },
-                                                                                                {
-                                                                                                    "deprecationReason": null,
-                                                                                                    "description": null,
-                                                                                                    "isDeprecated": false,
-                                                                                                    "name": "EDIT"
-                                                                                                }
-                                                                                            ],
-                                                                                            "fields": null,
-                                                                                            "inputFields": null,
-                                                                                            "interfaces": null,
-                                                                                            "kind": "ENUM",
-                                                                                            "name": "RBACAction",
-                                                                                            "possibleTypes": null
-                                                                                        },
-                                                                                        "indexType": "enum",
-                                                                                        "kind": [
-                                                                                            "NON_NULL",
-                                                                                            "ENUM"
-                                                                                        ],
-                                                                                        "name": "RBACAction",
-                                                                                        "non_null": false
-                                                                                    },
-                                                                                    "varName": "action"
-                                                                                }
-                                                                            },
-                                                                            "inputFields": null,
-                                                                            "interfaces": [],
-                                                                            "kind": "OBJECT",
-                                                                            "name": "EntityAccess",
-                                                                            "possibleTypes": null
-                                                                        },
-                                                                        "indexType": "object",
-                                                                        "kind": [
-                                                                            "OBJECT"
-                                                                        ],
-                                                                        "name": "EntityAccess",
-                                                                        "non_null": false
-                                                                    },
-                                                                    "varName": "entityAccess"
-                                                                },
                                                                 "audit": {
                                                                     "args": {},
                                                                     "deprecationReason": null,
@@ -1272,26 +1189,6 @@
                                                                                         "non_null": false
                                                                                     },
                                                                                     "varName": "name"
-                                                                                },
-                                                                                "subPolicyId": {
-                                                                                    "args": {},
-                                                                                    "deprecationReason": null,
-                                                                                    "description": null,
-                                                                                    "id_str": "antiMalwareFileHash___addSection___section___section___subPolicyId",
-                                                                                    "isDeprecated": false,
-                                                                                    "name": "subPolicyId",
-                                                                                    "path": "antiMalwareFileHash.addSection.section.section.subPolicyId",
-                                                                                    "requestStr": "$subPolicyId:ID ",
-                                                                                    "required": false,
-                                                                                    "responseStr": "subPolicyId:$subPolicyId ",
-                                                                                    "type": {
-                                                                                        "kind": [
-                                                                                            "SCALAR"
-                                                                                        ],
-                                                                                        "name": "ID",
-                                                                                        "non_null": false
-                                                                                    },
-                                                                                    "varName": "subPolicyId"
                                                                                 }
                                                                             },
                                                                             "inputFields": null,