catocli 3.0.14__py3-none-any.whl → 3.0.18__py3-none-any.whl

catocli/Utils/clidriver.py

@@ -48,22 +48,22 @@ 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_site import query_site_parse
 from ..parsers.query_groups import query_groups_parse
+from ..parsers.query_policy import query_policy_parse
 from ..parsers.mutation_xdr import mutation_xdr_parse
 from ..parsers.mutation_policy import mutation_policy_parse
 from ..parsers.mutation_site import mutation_site_parse
 from ..parsers.mutation_sites import mutation_sites_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
 from ..parsers.mutation_licensing import mutation_licensing_parse
 from ..parsers.mutation_hardware import mutation_hardware_parse
 from ..parsers.mutation_groups import mutation_groups_parse
 from ..parsers.mutation_enterpriseDirectory import mutation_enterpriseDirectory_parse
+from ..parsers.mutation_admin import mutation_admin_parse
 
 def show_version_info(args, configuration=None):
     print(f"catocli version {catocli.__version__}")
@@ -183,22 +183,22 @@ 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_site_parser = query_site_parse(query_subparsers)
 query_groups_parser = query_groups_parse(query_subparsers)
+query_policy_parser = query_policy_parse(query_subparsers)
 mutation_xdr_parser = mutation_xdr_parse(mutation_subparsers)
 mutation_policy_parser = mutation_policy_parse(mutation_subparsers)
 mutation_site_parser = mutation_site_parse(mutation_subparsers)
 mutation_sites_parser = mutation_sites_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)
 mutation_licensing_parser = mutation_licensing_parse(mutation_subparsers)
 mutation_hardware_parser = mutation_hardware_parse(mutation_subparsers)
 mutation_groups_parser = mutation_groups_parse(mutation_subparsers)
 mutation_enterpriseDirectory_parser = mutation_enterpriseDirectory_parse(mutation_subparsers)
+mutation_admin_parser = mutation_admin_parse(mutation_subparsers)
 
 
 def parse_headers(header_strings):
@@ -269,7 +269,7 @@ def main(args=None):
             if custom_headers:
                 configuration.custom_headers.update(custom_headers)
             # Handle account ID override (applies to all commands except raw)
-            if hasattr(args, 'func') and args.func.__name__ not in ["createRawRequest"]:
+            if args.func.__name__ not in ["createRawRequest"]:
                 if hasattr(args, 'accountID') and args.accountID is not None:
                     # Command line override takes precedence
                     configuration.accountID = args.accountID
@@ -295,7 +295,7 @@ def main(args=None):
     except Exception as e:
         if isinstance(e, AttributeError):
             print('Missing arguments. Usage: catocli <operation> -h')
-            if hasattr(args, 'v') and args.v==True:
+            if args.v==True:
                 print('ERROR: ',e)
                 traceback.print_exc()
         else:

catocli/Utils/help_formatter.py

@@ -159,7 +159,7 @@ class JSONExample:
                 
         elif isinstance(obj, str):
             # Use double quotes and escape internal quotes
-            escaped_str = obj.replace('"', '`"')
+            escaped_str = obj.replace('"', '"')
             return f'"{escaped_str}"'
         elif isinstance(obj, bool):
             return "$true" if obj else "$false"

catocli/__init__.py

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

catocli/parsers/custom/query_eventsFeed/README.md

@@ -0,0 +1,94 @@
+
+## CATO-CLI - Enhanced query.eventsFeed:
+[Click here](https://api.catonetworks.com/documentation/#query-query.eventsFeed) for documentation on this operation.
+
+### Basic Usage for query.eventsFeed:
+
+```bash
+# Show help for all available options
+catocli query eventsFeed -h
+
+# Standard eventsFeed query (basic GraphQL mode)
+catocli query eventsFeed '{"marker": ""}'
+
+# Start from beginning of event queue
+catocli query eventsFeed '{"marker": ""}' -p
+
+# Use a JSON file for complex queries
+catocli query eventsFeed "$(cat query.eventsFeed.json)"
+```
+
+### Enhanced Usage (with advanced features):
+
+The enhanced eventsFeed supports additional features like marker persistence, continuous polling, filtering, and streaming.
+
+```bash
+# Basic enhanced mode: fetch once and print events
+catocli query eventsFeed --print-events --prettify
+
+# Start from beginning with run mode (continuous polling)
+catocli query eventsFeed --run --print-events -v
+
+# Use marker file for persistent position tracking
+catocli query eventsFeed --marker-file=./events-marker.txt --print-events
+
+# Continuous mode with marker persistence
+catocli query eventsFeed --run --marker-file=./events-marker.txt --print-events -v
+
+# Filter by event types
+catocli query eventsFeed --print-events --event-types="Connectivity,Security"
+
+# Filter by event sub-types
+catocli query eventsFeed --print-events --event-sub-types="Internet Firewall,WAN Firewall"
+
+# Network streaming with newlines
+catocli query eventsFeed --run -n 192.168.1.100:8000 --append-new-line -v
+
+# Send to Azure Sentinel
+catocli query eventsFeed --run -z "workspace-id:shared-key"
+
+# Combined: display locally AND stream to network
+catocli query eventsFeed --run --print-events --prettify -n 192.168.1.100:8000 -anl
+
+# With fetch and runtime limits
+catocli query eventsFeed --run --print-events --fetch-limit=50 --runtime-limit=3600
+
+# Very verbose debugging
+catocli query eventsFeed --marker-file=./marker.txt --print-events -vv
+```
+
+
+#### Operation Arguments for query.eventsFeed ####
+
+##### Core GraphQL Arguments:
+`accountIDs` [ID[]] - (required) List of Unique Account Identifiers.    
+`eventFeedFieldFilterInput` [EventFeedFieldFilterInput[]] - (required) N/A    
+`fieldNames` [EventFieldName[]] - (required) N/A Default Value: ['access_method', 'account_id', 'action', 'actions_taken', 'ad_name', 'alert_id', 'always_on_configuration', 'analyst_verdict', 'api_name', 'api_type', 'app_activity', 'app_activity_category', 'app_activity_type', 'app_stack', 'application_id', 'application_name', 'application_risk', 'auth_method', 'authentication_type', 'bgp_cato_asn', 'bgp_cato_ip', 'bgp_error_code', 'bgp_peer_asn', 'bgp_peer_ip', 'bgp_route_cidr', 'bgp_suberror_code', 'bypass_duration_sec', 'bypass_method', 'bypass_reason', 'categories', 'cato_app', 'classification', 'client_cert_expires', 'client_cert_name', 'client_class', 'client_version', 'collaborator_name', 'collaborators', 'confidence_level', 'configured_host_name', 'congestion_algorithm', 'connect_on_boot', 'connection_origin', 'connector_name', 'connector_status', 'connector_type', 'container_name', 'correlation_id', 'criticality', 'custom_category_id', 'custom_category_name', 'dest_country', 'dest_country_code', 'dest_group_id', 'dest_group_name', 'dest_ip', 'dest_is_site_or_vpn', 'dest_pid', 'dest_port', 'dest_process_cmdline', 'dest_process_parent_path', 'dest_process_parent_pid', 'dest_process_path', 'dest_site_id', 'dest_site_name', 'detection_name', 'detection_stage', 'device_categories', 'device_certificate', 'device_id', 'device_manufacturer', 'device_model', 'device_name', 'device_os_type', 'device_posture_profile', 'device_type', 'directory_host_name', 'directory_ip', 'directory_sync_result', 'directory_sync_type', 'disinfect_result', 'dlp_fail_mode', 'dlp_profiles', 'dlp_scan_types', 'dns_protection_category', 'dns_query', 'domain_name', 'egress_pop_name', 'egress_site_name', 'email_subject', 'endpoint_id', 'engine_type', 'epp_engine_type', 'epp_profile', 'event_count', 'event_id', 'event_message', 'event_sub_type', 'event_type', 'failure_reason', 'file_hash', 'file_name', 'file_operation', 'file_size', 'file_type', 'final_object_status', 'flows_cardinality', 'full_path_url', 'guest_user', 'host_ip', 'host_mac', 'http_request_method', 'incident_aggregation', 'incident_id', 'indication', 'indicator', 'initial_object_status', 'internalId', 'ip_protocol', 'is_admin', 'is_admin_activity', 'is_compliant', 'is_managed', 'is_sanctioned_app', 'is_sinkhole', 'ISP_name', 'key_name', 'labels', 'link_health_is_congested', 'link_health_jitter', 'link_health_latency', 'link_health_pkt_loss', 'link_type', 'logged_in_user', 'login_type', 'matched_data_types', 'mitre_attack_subtechniques', 'mitre_attack_tactics', 'mitre_attack_techniques', 'network_access', 'network_rule', 'notification_api_error', 'notification_description', 'object_id', 'object_name', 'object_type', 'office_mode', 'os_type', 'os_version', 'out_of_band_access', 'owner', 'pac_file', 'parent_connector_name', 'pop_name', 'precedence', 'processes_count', 'producer', 'projects', 'prompt_action', 'provider_name', 'public_ip', 'qos_priority', 'qos_reported_time', 'quarantine_folder_path', 'quarantine_uuid', 'raw_data', 'recommended_actions', 'reference_url', 'referer_url', 'region_name', 'registration_code', 'resource_id', 'risk_level', 'rule_id', 'rule_name', 'service_name', 'severity', 'sharing_scope', 'sign_in_event_types', 'signature_id', 'socket_interface', 'socket_interface_id', 'socket_new_version', 'socket_old_version', 'socket_reset', 'socket_role', 'socket_serial', 'socket_version', 'split_tunnel_configuration', 'src_country', 'src_country_code', 'src_ip', 'src_is_site_or_vpn', 'src_isp_ip', 'src_pid', 'src_port', 'src_process_cmdline', 'src_process_parent_path', 'src_process_parent_pid', 'src_process_path', 'src_site_id', 'src_site_name', 'static_host', 'status', 'story_id', 'subnet_name', 'subscription_name', 'targets_cardinality', 'tcp_acceleration', 'tenant_id', 'tenant_name', 'tenant_restriction_rule_name', 'threat_confidence', 'threat_name', 'threat_reference', 'threat_score', 'threat_type', 'threat_verdict', 'time', 'time_str', 'title', 'tls_certificate_error', 'tls_error_description', 'tls_error_type', 'tls_inspection', 'tls_rule_name', 'tls_version', 'traffic_direction', 'translated_client_ip', 'translated_server_ip', 'trigger', 'trust_type', 'trusted_networks', 'tunnel_ip_protocol', 'tunnel_protocol', 'upgrade_end_time', 'upgrade_initiated_by', 'upgrade_start_time', 'url', 'user_agent', 'user_awareness_method', 'user_id', 'user_name', 'user_reference_id', 'user_risk_level', 'vendor', 'vendor_collaborator_id', 'vendor_device_id', 'vendor_device_name', 'vendor_event_id', 'vendor_policy_description', 'vendor_policy_id', 'vendor_policy_name', 'vendor_user_id', 'visible_device_id', 'vpn_lan_access', 'vpn_user_email', 'windows_domain_name', 'xff']   
+`marker` [String] - (required) Marker to use to get results from    
+
+##### Enhanced Features Arguments:
+`--run` [Flag] - Enable run mode with continuous polling and advanced features
+`--print-events` [Flag] - Print event records to console  
+`--prettify` [Flag] - Prettify JSON output  
+`--marker` [String] - Initial marker value (default: "", start of queue)  
+`--marker-file` [String] - Marker file location for persistence (default: ./events-marker.txt)  
+`--event-types` [String] - Comma-separated list of event types to filter on  
+`--event-sub-types` [String] - Comma-separated list of event sub types to filter on  
+`--fetch-limit` [Integer] - Stop if a fetch returns less than this number of events (default: 1)  
+`--runtime-limit` [Integer] - Stop after this many seconds (default: unlimited)  
+`-vv, --very-verbose` [Flag] - Print detailed debug information  
+`--append-new-line, -anl` [Flag] - Append newline character (\n) to events sent via -n or -z  
+`-n, --stream-events` [String] - Send events to host:port TCP  
+`-z, --sentinel` [String] - Send to Azure Sentinel customerid:sharedkey  
+`-v` [Flag] - Verbose output (inherited from catocli)  
+`-p` [Flag] - Pretty print (inherited from catocli)
+
+##### Key Features:
+- **Native Authentication**: Uses ~/.cato profile credentials automatically  
+- **Compression**: Leverages catocli's built-in gzip compression for performance  
+- **Marker Persistence**: Automatically saves position in event queue  
+- **Continuous Polling**: Supports long-running event collection  
+- **Advanced Filtering**: Filter by event types and sub-types  
+- **Network Streaming**: Stream events to TCP endpoints  
+- **Azure Sentinel**: Direct integration with Microsoft Sentinel  
+- **Rate Limiting**: Built-in API rate limit handling

catocli/parsers/custom/scim/README.md

@@ -0,0 +1,346 @@
+# SCIM (System for Cross-domain Identity Management) Commands
+
+The Cato CLI provides comprehensive support for SCIM operations to manage users and groups via the Cato SCIM API. This enables automated user provisioning and group management for identity providers and custom integrations.
+
+## Prerequisites
+
+Before using SCIM commands, you need to configure SCIM credentials in your profile:
+
+1. **SCIM URL**: The SCIM service endpoint provided by Cato
+   - Format: `https://scimservice.catonetworks.com:4443/scim/v2/{accountId}/{sourceId}`
+   - Example: `https://scimservice.catonetworks.com:4443/scim/v2/12345/67890`
+
+2. **SCIM Bearer Token**: Authentication token for SCIM access
+   - Example: `cfda146dc7c12345abcde`
+
+## Configuration
+
+### Add SCIM Credentials to Profile
+
+```bash
+# Interactive configuration (recommended)
+catocli configure set
+
+# Non-interactive configuration
+catocli configure set --scim-url "https://scimservice.catonetworks.com:4443/scim/v2/12345/67890" --scim-token "your-bearer-token"
+
+# Add SCIM credentials to specific profile
+catocli configure set --profile production --scim-url "your-scim-url" --scim-token "your-bearer-token"
+```
+
+### View Profile with SCIM Credentials
+
+```bash
+catocli configure show
+```
+
+For detailed setup instructions, see: [Using the Cato SCIM API for Custom SCIM Apps](https://support.catonetworks.com/hc/en-us/articles/29492743031581-Using-the-Cato-SCIM-API-for-Custom-SCIM-Apps)
+
+## User Management Commands
+
+### Get All Users
+
+```bash
+# Get all SCIM users
+catocli scim get_users
+
+# With verbose output
+catocli scim get_users --verbose
+
+# With pretty-printed JSON
+catocli scim get_users --pretty
+```
+
+### Get Specific User
+
+```bash
+# Get user by SCIM ID
+catocli scim get_user "6283630dfd7ec758a8bf4b61"
+
+# With verbose output
+catocli scim get_user "6283630dfd7ec758a8bf4b61" --verbose
+```
+
+### Find Users
+
+```bash
+# Find users by email
+catocli scim find_users email "john.doe@company.com"
+
+# Find users by username
+catocli scim find_users userName "john.doe"
+
+# Find users by given name (first name)
+catocli scim find_users givenName "John"
+
+# Find users by family name (last name)
+catocli scim find_users familyName "Doe"
+```
+
+### Create User
+
+```bash
+# Create a new user (password will be auto-generated)
+catocli scim create_user "jane.doe@company.com" "Jane" "Doe" "external123"
+
+# Create user with specific password
+catocli scim create_user "jane.doe@company.com" "Jane" "Doe" "external123" --password "SecurePass123!"
+
+# Create inactive user
+catocli scim create_user "jane.doe@company.com" "Jane" "Doe" "external123" --inactive
+
+# Create active user (default behavior)
+catocli scim create_user "jane.doe@company.com" "Jane" "Doe" "external123" --active
+```
+
+### Update User
+
+```bash
+# Update user with complete user data (JSON format)
+catocli scim update_user "6283630dfd7ec758a8bf4b61" '{
+  "userName": "john.doe@company.com",
+  "name": {
+    "givenName": "John",
+    "familyName": "Doe"
+  },
+  "emails": [
+    {
+      "primary": true,
+      "value": "john.doe@company.com",
+      "type": "work"
+    }
+  ],
+  "active": true
+}'
+```
+
+### Disable User
+
+```bash
+# Disable a user by SCIM ID
+catocli scim disable_user "6283630dfd7ec758a8bf4b61"
+
+# With verbose output
+catocli scim disable_user "6283630dfd7ec758a8bf4b61" --verbose
+```
+
+## Group Management Commands
+
+### Get All Groups
+
+```bash
+# Get all SCIM groups
+catocli scim get_groups
+
+# With verbose output
+catocli scim get_groups --verbose
+
+# With pretty-printed JSON
+catocli scim get_groups --pretty
+```
+
+### Get Specific Group
+
+```bash
+# Get group by SCIM ID
+catocli scim get_group "6283630dfd7ec758a8bf4b62"
+
+# With verbose output
+catocli scim get_group "6283630dfd7ec758a8bf4b62" --verbose
+```
+
+### Find Groups
+
+```bash
+# Find groups by display name
+catocli scim find_group "Development Team"
+
+# With verbose output
+catocli scim find_group "Development Team" --verbose
+```
+
+### Create Group
+
+```bash
+# Create a new group without members
+catocli scim create_group "Marketing Team" "marketing-external-id"
+
+# Create group with initial members
+catocli scim create_group "Sales Team" "sales-external-id" '[
+  {"value": "6283630dfd7ec758a8bf4b61"},
+  {"value": "6283630dfd7ec758a8bf4b62"}
+]'
+```
+
+### Update Group
+
+```bash
+# Update group with complete group data
+catocli scim update_group "6283630dfd7ec758a8bf4b62" '{
+  "displayName": "Updated Team Name",
+  "members": [
+    {
+      "value": "6283630dfd7ec758a8bf4b61",
+      "display": "john.doe@company.com"
+    }
+  ]
+}'
+```
+
+### Rename Group
+
+```bash
+# Rename a group
+catocli scim rename_group "6283630dfd7ec758a8bf4b62" "New Team Name"
+
+# With verbose output
+catocli scim rename_group "6283630dfd7ec758a8bf4b62" "New Team Name" --verbose
+```
+
+### Disable Group
+
+```bash
+# Disable a group by SCIM ID
+catocli scim disable_group "6283630dfd7ec758a8bf4b62"
+
+# With verbose output
+catocli scim disable_group "6283630dfd7ec758a8bf4b62" --verbose
+```
+
+## Group Membership Management
+
+### Add Members to Group
+
+```bash
+# Add single member to group
+catocli scim add_members "6283630dfd7ec758a8bf4b62" '[{"value": "6283630dfd7ec758a8bf4b61"}]'
+
+# Add multiple members to group
+catocli scim add_members "6283630dfd7ec758a8bf4b62" '[
+  {"value": "6283630dfd7ec758a8bf4b61"},
+  {"value": "6283630dfd7ec758a8bf4b63"},
+  {"value": "6283630dfd7ec758a8bf4b64"}
+]'
+
+# With verbose output
+catocli scim add_members "group-id" '[{"value": "user-id"}]' --verbose
+```
+
+### Remove Members from Group
+
+```bash
+# Remove single member from group
+catocli scim remove_members "6283630dfd7ec758a8bf4b62" '[{"value": "6283630dfd7ec758a8bf4b61"}]'
+
+# Remove multiple members from group
+catocli scim remove_members "6283630dfd7ec758a8bf4b62" '[
+  {"value": "6283630dfd7ec758a8bf4b61"},
+  {"value": "6283630dfd7ec758a8bf4b63"}
+]'
+```
+
+## Common Options
+
+All SCIM commands support these common options:
+
+- `--verbose` or `-v`: Show detailed output and progress information
+- `--pretty` or `-p`: Pretty print JSON output for better readability
+
+## Error Handling
+
+If SCIM credentials are missing or invalid, you'll see helpful error messages:
+
+```bash
+$ catocli scim get_users
+ERROR: Profile 'default' is missing SCIM credentials: scim_url, scim_token
+Run 'catocli configure set --profile default' to add SCIM credentials.
+For more information, see: https://support.catonetworks.com/hc/en-us/articles/29492743031581-Using-the-Cato-SCIM-API-for-Custom-SCIM-Apps
+```
+
+## JSON Format Examples
+
+### User JSON Structure
+
+```json
+{
+  "id": "6283630dfd7ec758a8bf4b61",
+  "userName": "john.doe@company.com",
+  "name": {
+    "givenName": "John",
+    "familyName": "Doe"
+  },
+  "emails": [
+    {
+      "primary": true,
+      "value": "john.doe@company.com",
+      "type": "work"
+    }
+  ],
+  "active": true
+}
+```
+
+### Group JSON Structure
+
+```json
+{
+  "id": "6283630dfd7ec758a8bf4b62",
+  "displayName": "Development Team",
+  "members": [
+    {
+      "value": "6283630dfd7ec758a8bf4b61",
+      "display": "john.doe@company.com"
+    }
+  ]
+}
+```
+
+### Member Array Format
+
+```json
+[
+  {"value": "6283630dfd7ec758a8bf4b61"},
+  {"value": "6283630dfd7ec758a8bf4b62"}
+]
+```
+
+## Integration Examples
+
+### Bulk User Creation from CSV
+
+```bash
+#!/bin/bash
+# Read CSV file and create users
+while IFS=',' read -r email given_name family_name; do
+    catocli scim create_user "$email" "$given_name" "$family_name" --verbose
+done < users.csv
+```
+
+### Group Membership Sync
+
+```bash
+#!/bin/bash
+# Add users to a group
+GROUP_ID="6283630dfd7ec758a8bf4b62"
+USER_IDS=("6283630dfd7ec758a8bf4b61" "6283630dfd7ec758a8bf4b63")
+
+# Build members JSON array
+MEMBERS_JSON="["
+for i in "${!USER_IDS[@]}"; do
+    if [ $i -ne 0 ]; then
+        MEMBERS_JSON+=","
+    fi
+    MEMBERS_JSON+="{\"value\": \"${USER_IDS[$i]}\"}"
+done
+MEMBERS_JSON+="]"
+
+# Add members to group
+catocli scim add_members "$GROUP_ID" "$MEMBERS_JSON" --verbose
+```
+
+## Support
+
+For SCIM API setup and configuration assistance, refer to:
+- [Using the Cato SCIM API for Custom SCIM Apps](https://support.catonetworks.com/hc/en-us/articles/29492743031581-Using-the-Cato-SCIM-API-for-Custom-SCIM-Apps)
+
+For CLI-specific issues, use the `--verbose` flag to get detailed error information and check your profile configuration with `catocli configure show`.