Hello Cato Community! 👋

While Cato's built-in dashboards provide comprehensive visibility into your network, security, and user activity, there are times when you need custom, ad-hoc reporting tailored to your specific business needs, and potentially integrated with 3^rd party platforms. That's where the Cato CLI Custom Reports capability shines!

NOTE: All of the data and reports in this article are also available in the Cato MCP server and can be accessed with your favorite AI GPT client.

Why Custom Reports?

The Cato Management Application offers beautiful, detailed dashboards for monitoring your environment. However, what if you need to:

• Generate reports on a custom schedule for compliance requirements
• Analyze specific time periods or unusual patterns
• Correlate data across multiple dimensions not available in standard dashboards
• Export specific datasets for executive presentations or third-party analysis tools
• Build automated reporting workflows integrated with your existing systems

Custom Reports give you direct access to the Cato API to extract exactly the data you need, when you need it, in the format you need it.

First, you will need to install the catocli, instructions referenced here.

pip3 install catocli
catocli configure set
catocli -h

Getting Started - Run Your First Report

catocli query appStats '{
    "dimension": [{"fieldName": "user_name"}],
    "measure": [{"aggType": "sum", "fieldName": "traffic"}],
    "timeFrame": "last.P1D"
}' -f csv --csv-filename=my_first_report.csv

Integrate! Forward any cli json output to a network endpoint host and port:

catocli query appStats '{
    "dimension": [{"fieldName": "user_name"}],
    "measure": [{"aggType": "sum", "fieldName": "traffic"}],
    "timeFrame": "last.P1D"
}' -n 1.2.3.4:514

______________________________________________________________

Available Example Custom Report Types

The Cato CLI provides six powerful report categories, each designed for specific analytical needs, and many of these are documented directly in the help menu of the CLI (click here for more examples):

📊 Account Metrics - Network Performance Analytics

What it does: Provides detailed network performance metrics broken down by site, user, or interface over specified time periods.

Use cases:

• Monitor site-level bandwidth utilization trends
• Identify performance bottlenecks by interface
• Track latency and packet loss across your global network
• Capacity planning and bandwidth forecasting

Example: Site Performance Analysis

catocli query accountMetrics '{
    "dimension": [
        {"fieldName": "site_name"},
        {"fieldName": "interface_name"}
    ],
    "measure": [
        {"aggType": "avg", "fieldName": "latency"},
        {"aggType": "sum", "fieldName": "bandwidth_usage"},
        {"aggType": "max", "fieldName": "packet_loss"}
    ],
    "timeFrame": "last.P7D"
}' -f csv --csv-filename=site_performance_weekly.csv

Sample Output:

---------------------------------------------------------------------------------

📱 Application Statistics - User Activity & Application Analysis

What it does: Aggregated analysis of user activity and application usage, showing total traffic, flow counts, and bandwidth consumption.

Use cases:

• Identify top bandwidth consumers by user or application
• Security risk assessment based on application risk scores
• SaaS application adoption tracking
• Chargeback reporting by department or user

Example 1: High-Traffic Users (with Post-Aggregation Filter)

catocli query appStats '{
    "dimension": [
        {"fieldName": "user_name"}
    ],
    "measure": [
        {"aggType": "sum", "fieldName": "traffic"},
        {"aggType": "sum", "fieldName": "flows_created"}
    ],
    "appStatsPostAggFilter": [
        {
            "aggType": "sum",
            "filter": {
                "fieldName": "traffic",
                "operator": "gt",
                "values": ["1073741824"]
            }
        }
    ],
    "timeFrame": "last.P2D"
}' -f csv --csv-filename=high_traffic_users.csv

Sample Output:

What is appStatsPostAggFilter?

Post-aggregation filters allow you to filter results after metrics are calculated, similar to a SQL HAVING clause. This is powerful because regular filters (appStatsFilter) apply before aggregation, while post-aggregation filters apply after the metrics are computed.

Key Capabilities:

• Filter on aggregated values (sum, avg, max, min, count, count_distinct)
• Find users/apps exceeding thresholds (e.g., >1GB traffic)
• Identify values within specific ranges (e.g., 100-1000 flows)
• Detect outliers based on statistical measures

Supported Operators: is, is_not, gt, gte, lt, lte, between, not_between

Post-Aggregation Filter Examples (postAggFilters)

High-Traffic Users (>1GB Total Traffic)

Find users whose total traffic exceeds 1GB over the last 2 days:

catocli query appStats '{
    "dimension": [
        {"fieldName": "user_name"}
    ],
    "measure": [
        {"aggType": "sum", "fieldName": "traffic"},
        {"aggType": "sum", "fieldName": "flows_created"}
    ],
    "appStatsPostAggFilter": [
        {
            "aggType": "sum",
            "filter": {
                "fieldName": "traffic",
                "operator": "gt",
                "values": ["1073741824"]
            }
        }
    ],
    "appStatsSort": [
        {"fieldName": "traffic", "order": "desc"}
    ],
    "timeFrame": "last.P2D"
}' -f csv --csv-filename=appstats_high_traffic_users.csv

Applications with Average Traffic Above Threshold

Identify applications where average traffic per flow exceeds 10MB:

catocli query appStats '{
    "dimension": [
        {"fieldName": "application_name"}
    ],
    "measure": [
        {"aggType": "avg", "fieldName": "traffic"},
        {"aggType": "count", "fieldName": "flows_created"},
        {"aggType": "sum", "fieldName": "traffic"}
    ],
    "appStatsPostAggFilter": [
        {
            "aggType": "avg",
            "filter": {
                "fieldName": "traffic",
                "operator": "gte",
                "values": ["10485760"]
            }
        }
    ],
    "appStatsSort": [
        {"fieldName": "traffic", "order": "desc"}
    ],
    "timeFrame": "last.P7D"
}' -f csv --csv-filename=appstats_high_avg_traffic_apps.csv

---------------------------------------------------------------------------------

📈 Application Statistics Time Series - Traffic Analysis Over Time

What it does: Shows application and user traffic patterns over time with hourly/daily/custom time bucket breakdowns.

Use cases:

• Peak usage analysis and capacity planning
• Identify traffic trends and seasonal patterns
• Anomaly detection (unusual spikes or drops)
• Business hours vs. after-hours usage comparison

Example: Hourly Traffic Breakdown

catocli query appStatsTimeSeries '{
    "buckets": 24,
    "dimension": [
        {"fieldName": "application_name"},
        {"fieldName": "user_name"}
    ],
    "perSecond": false,
    "measure": [
        {"aggType": "sum", "fieldName": "upstream"},
        {"aggType": "sum", "fieldName": "downstream"},
        {"aggType": "sum", "fieldName": "traffic"}
    ],
    "timeFrame": "last.P1D"
}' -f csv --csv-filename=hourly_traffic_patterns.csv

Why use perSecond: false? When analyzing throughput statistics (upstream, downstream, traffic), set "perSecond": false to get accurate byte counts instead of rates. This gives you actual data transfer volumes over time.

______________________________________________________________

🔒 Events Time Series - Security Events & Threat Analysis

What it does: Time-based analysis of security events, including IPS alerts, threat detections, connectivity events, and policy violations.

Use cases:

• Security incident trending and correlation
• IPS/IDS event pattern analysis
• Threat actor tracking over time
• Compliance reporting for security events

Example: IPS Events Trending

catocli query eventsTimeSeries '{
    "buckets": 168,
    "dimension": [
        {"fieldName": "event_type"},
        {"fieldName": "threat_severity"}
    ],
    "measure": [
        {"aggType": "count", "fieldName": "event_id"}
    ],
    "eventsFilter": [
        {
            "fieldName": "event_category",
            "operator": "in",
            "values": ["IPS", "Threat Prevention"]
        }
    ],
    "timeFrame": "last.P7D"
}' -f csv --csv-filename=ips_events_weekly.csv

______________________________________________________________

🔌 Socket Port Metrics - Socket Interface Performance Analysis

What it does: Aggregated performance metrics for Socket (SD-WAN) ports/interfaces, including bandwidth utilization, packet statistics, and error rates.

Use cases:

• WAN interface health monitoring
• Compare primary vs. backup link performance
• Interface utilization and capacity planning
• Troubleshoot connectivity issues

{
  "socketPortMetricsDimension": [    // Fields to group results by
    {"fieldName": "socket_interface"},
    {"fieldName": "device_id"},
    {"fieldName": "site_name"}
  ],
  "socketPortMetricsFilter": [],     // Filters to apply to data
  "socketPortMetricsMeasure": [      // Metrics to calculate
    {"aggType": "sum", "fieldName": "bytes_upstream"},
    {"aggType": "sum", "fieldName": "bytes_downstream"},
    {"aggType": "sum", "fieldName": "bytes_total"}
  ],
  "socketPortMetricsSort": [],       // Sort criteria
  "timeFrame": "last.P1D"           // Time range for analysis
}

______________________________________________________________

⏱️ Socket Port Time Series - Socket Performance Metrics Over Time

What it does: Time-based analysis of Socket interface metrics, tracking performance trends, utilization patterns, and health indicators across time buckets.

Use cases:

• Peak traffic period identification
• Link failover event correlation
• Performance degradation detection
• Historical bandwidth utilization trending

Daily Traffic Patterns

Analyze interface traffic patterns throughout the day:

catocli query socketPortMetricsTimeSeries '{
    "buckets": 24,
    "socketPortMetricsDimension": [
        {"fieldName": "socket_interface"},
        {"fieldName": "site_name"}
    ],
    "socketPortMetricsMeasure": [
        {"aggType": "sum", "fieldName": "bytes_downstream"},
        {"aggType": "sum", "fieldName": "bytes_upstream"},
        {"aggType": "sum", "fieldName": "bytes_total"}
    ],
    "perSecond": false,
    "timeFrame": "last.P1D"
}' -f csv --csv-filename socketPortMetricsTimeSeries_daily_traffic_patterns.csv

Peak Hour Identification

Identify peak traffic hours with high-resolution monitoring:

______________________________________________________________

catocli query socketPortMetricsTimeSeries '{
    "buckets": 96,
    "socketPortMetricsDimension": [
        {"fieldName": "socket_interface"}
    ],
    "socketPortMetricsMeasure": [
        {"aggType": "sum", "fieldName": "bytes_total"}
    ],
    "perSecond": false,
    "timeFrame": "last.P1D"
}' -f csv --csv-filename socketPortMetricsTimeSeries_peak_hour_analysis.csv

______________________________________________________________

Additional Resources

📚 Comprehensive Documentation:

• User Activity Report Format
• Cato CLI GitHub Repository
• Cato API Documentation

💡 Pro Tips:

• Use --append-timestamp to add timestamps to filename for historical tracking
• Export to CSV for easy analysis in Excel, Tableau, or other BI tools
• Set up scheduled scripts (cron/Task Scheduler) for automated reporting

Combine multiple queries to build comprehensive dashboards

Real-World Use Case Examples

Compliance Reporting

Generate monthly bandwidth usage reports by user for chargeback:

catocli query appStats '{
    "dimension": [{"fieldName": "user_name"}, {"fieldName": "department"}],
    "measure": [{"aggType": "sum", "fieldName": "traffic"}],
    "timeFrame": "last.P1M"
}' -f csv --csv-filename=monthly_usage_chargeback.csv --append-timestamp

Security Operations

Daily high-risk application usage tracking:

catocli query appStats '{
    "appStatsFilter": [{"fieldName": "risk_score", "operator": "gte", "values": ["7"]}],
    "dimension": [{"fieldName": "application_name"}, {"fieldName": "user_name"}],
    "measure": [{"aggType": "sum", "fieldName": "traffic"}],
    "timeFrame": "last.P1D"
}' -f csv --csv-filename=high_risk_apps_daily.csv --append-timestamp

Capacity Planning

Track site bandwidth trends for capacity planning:

catocli query accountMetrics '{
    "dimension": [{"fieldName": "site_name"}],
    "measure": [
        {"aggType": "avg", "fieldName": "bandwidth_usage"},
        {"aggType": "max", "fieldName": "bandwidth_usage"}
    ],
    "timeFrame": "last.P3M"
}' -f csv --csv-filename=site_capacity_quarterly.csv

______________________________________________________________

Community Feedback

We'd love to hear how you're using Custom Reports! Share your:

• 📊 Creative use cases and analysis scenarios
• 🔧 Automation scripts and workflows
• 💡 Tips and best practices
• ❓ Questions and feature requests

Happy reporting! 🎉

For technical support or feature requests, please visit and post the Cato Community or open an issue on the Cato CLI GitHub repository.