FortiGate Data Source Plugin for Grafana

Description

The FortiGate DataSource Plugin is a Grafana backend datasource plugin that enables on-demand querying and visualization of FortiGate security logs and monitoring data inside Grafana panels.

FortiGate is a network security appliance developed by Fortinet that provides unified threat management (UTM) capabilities including firewall, antivirus, intrusion prevention, web filtering, anti-spam, and VPN functionality. FortiGate devices generate comprehensive security logs that provide valuable insights into network traffic, security events, and system operations.

Features

• Query and visualize FortiGate logs directly within Grafana through the FortiGate REST API
• Support for multiple log categories: Traffic Logs, UTM Logs (Antivirus Stats, Webfilter), and Event Logs
• Support for multiple storage types: Disk (historical), Memory (real-time), and FortiCloud
• UTM webfilter monitoring for malicious URLs and trusted URLs in real-time
• Advanced filtering with multiple operators (==, !=, =@, !@, <=, <, >=, >, AND, OR)
• Automatic pagination handling for large datasets (5000 records per chunk)
• Built-in retry logic with exponential backoff for transient failures
• Rate limiting compliance (100 requests per minute)
• Three pre-built dashboards for immediate insight into network security data

Compatibility

Visuals

Configuration Editor

Query Editor

Installation

Requirements

• Grafana >= 12.3.0
• A FortiGate device with API access enabled
• An API Token for authentication

Obtaining API Credentials

Via GUI:

1. Login to the FortiGate web interface
2. Navigate to System > Administrators
3. Click Create New > REST API Admin
4. Configure the admin profile with appropriate permissions
5. Click OK to generate the API token
6. Copy the generated API token immediately (it won't be shown again)

Note: FortiGate API tokens do not expire unless a lifetime is specifically configured.

Install the Plugin

Install the plugin from the Grafana Plugin Catalog or using the Grafana CLI:

grafana cli plugins install crestdata-fortigate-datasource

After installation, restart the Grafana server for the plugin to be loaded.

Configure the Data Source

1. In Grafana, navigate to Connections > Data Sources > Add data source
2. Search for FortiGate and select it
3. Fill in the required configuration fields:

1. Click Save & Test. The health check will validate your credentials against the FortiGate API by calling testing endpoint.

Usage

Query Editor

Once the data source is configured, you can create panels using the query editor with the following parameters:

Filter Operators

The plugin supports advanced filtering with the following operators:

Example filters:

• srcip==10.40.1.242 - Match specific source IP
• action==deny&dstport>=8000 - Denied actions with destination port >= 8000
• srcip=@10.40,dstip=@192.168 - Source IP contains "10.40" OR destination IP contains "192.168"

Pagination and Data Fetching

The plugin automatically handles pagination for large datasets:

• Chunk size: 5000 records per request
• Session management: Maintains session ID across paginated requests
• Completion detection: Continues fetching until ready: true and completed: 100
• Filter changes: Regenerates session ID when filter criteria changes

Error Handling and Retry Strategy

Retries are performed only for transient failures:

• HTTP 429 (Too Many Requests) - Rate limit exceeded
• HTTP 502 (Bad Gateway) - Server acting as gateway received invalid response
• HTTP 503 (Service Unavailable) - Server temporarily unavailable
• HTTP 504 (Gateway Timeout) - Gateway timed out
• Network/connection-level errors

Retry configuration:

• Maximum retries: 3 attempts
• Initial backoff: 2 seconds
• Maximum backoff: 8 seconds
• Backoff pattern: Exponential (2s, 4s, 8s)

Non-retryable errors (HTTP 4xx such as 401, 403) are returned immediately with detailed error messages:

• 401 Unauthorized: Invalid API token or token format
• 403 Forbidden: API token lacks required permissions
• Connection Timeout: FortiGate device is unreachable or slow to respond
• TLS/SSL Errors: Certificate verification failed (enable "Skip TLS Verify" for self-signed certificates)

Pre-built Dashboards

The plugin ships three pre-built dashboards. All share these common default settings:

1. FortiGate Traffic Dashboard

High-level summary of all FortiGate Traffic, including total event count, traffic distribution by action, protocol, and service, and top source/destination IPs.

Features:

• Storage Type Selection: Dropdown to switch between Memory (real-time), Disk (historical), and FortiCloud storage
• Subtype Selection: Dropdown to filter by traffic subtype (forward, local, multicast, sniffer, fortiview, threat)
• Query Optimization: Uses query references to reduce API calls from 12 to 1 (92% reduction)
• Default Settings: Disk storage, Forward subtype

Panels:

• Top 10 Source IPs (Bar chart)
• Top 10 Destination IPs (Bar chart)
• Traffic by Action (Bar chart)
• Top 10 Services (Bar chart)
• Traffic by Protocol (Bar chart)
• Top 10 Source Ports (Bar chart)
• Top 10 Destination Ports (Bar chart)
• Traffic Logs (Table with filtering and sorting)
• Total Bytes Sent (Stat)
• Total Bytes Received (Stat)
• Top 10 IPs by Bytes Sent (Bar chart)
• Top 10 IPs by Bytes Received (Bar chart)

2. FortiGate Events Dashboard

Detailed analysis of FortiGate event logs across system, user, VPN, wireless, and router subtypes.

Panels:

• Events by Level (Bar chart) - Event count grouped by severity level
• Events by Status (Bar chart) - Event count grouped by status
• Events by Subtype (Horizontal bar chart) - Event count grouped by subtype
• Events by Action (Horizontal bar chart) - Event count grouped by action type
• Top Active Users (Horizontal bar chart) - Top 10 most active users
• System Event Logs (Table) - Detailed event log entries with key fields

3. FortiGate UTM Dashboard

Antivirus statistics and webfilter monitoring data for security threat analysis.

Panels:

• Scanned (Stat) - Total number of scanned items
• Clean (Stat) - Number of clean items detected
• Infected (Stat) - Number of infected items detected
• Suspicious (Stat) - Number of suspicious items detected
• Zero Hour (Stat) - Zero-hour threat detections
• File Hash External (Stat) - External file hash checks
• File Hash EMS (Stat) - EMS file hash checks
• File Hash Exempt (Stat) - Exempted file hash checks
• Inline Block (Stat) - Inline blocked items
• Webfilter - Malicious URLs (Table) - Monitoring of blocked malicious URLs detected by the webfilter
• Webfilter - Trusted URLs (Table) - Monitoring of allowed trusted URLs

Limitations and Recommendations

API Limitations:

• Event time filtering: The API does not support filtering using the eventtime field. So, filtering is implemented using the _metadata.timestamp field instead. This may lead to slight differences between actual event occurrence time and filtered results.

• Rate limiting: API requests are limited to 100 requests per minute. The plugin implements automatic rate limiting compliance.

• Chunk-based fetching: Data is fetched in smaller chunks (5000 records) due to large dataset sizes. If API rate limits are reached during fetching, the system must wait before making further requests. This can introduce delays in data retrieval, especially for large time ranges or high-volume data.

Recommended Grafana time ranges:

Support

For issues, questions, or feature requests, please open an issue in this repository.

Roadmap

See the open issues for a list of proposed features and known issues.

Contributing

Contributions are welcome! To get started with development:

cd crestdata-fortigate-datasource
Frontend
npm install
npm run dev        # development mode with watch
npm run build      # production build
Backend
mage -v            # build backend binaries
Tests
npm run test       # frontend tests (Jest)
npm run test:ci    # CI mode
go test ./…      # backend tests
Linting
npm run lint
npm run lint:fix
Local Grafana instance (Docker)
npm run server
E2E tests (Playwright)
npm run e2e

Before submitting a pull request:

1. Run the linter and ensure all tests pass
2. Validate the plugin using the Grafana Plugin Validator
3. Ensure any changes to plugin.json are intentional — a Grafana server restart is required after such changes

Authors and Acknowledgment

Developed by Crestdata.

License

This plugin is distributed under the Apache 2.0 License. See the LICENSE file for details.

References

• FortiOS REST API Documentation
• FortiGate Rate Limiting
• Grafana Plugin Development
• Grafana Plugin Publishing Best Practices