Skip to content

Commit 7f44034

Browse files
mjwolfmjwolf
authored
[fortinet_fortigate] Update Fortigate documentation (#15825)
Update documentation for the fortinet_fortigate integration. The documentation now more complete, with expanded information on supported use-cases and data types that can be collected, more details on how to completely configure the integration, and more troubleshooting information. This also includes a new packages/fortinet_fortigate/docs/knowledge_base/service_info.md file, which will be included in the built package, and can be used by other tools which use information from the package, such as LLM tools.
1 parent f5948d6 commit 7f44034

File tree

6 files changed

+821
-173
lines changed

6 files changed

+821
-173
lines changed

‎packages/fortinet_fortigate/_dev/build/docs/README.md‎

Lines changed: 208 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,218 @@
1-
# Fortinet FortiGate Integration
1+
# Fortinet FortiGate Firewall Logs Integration for Elastic
22

3-
This integration is for Fortinet FortiGate logs sent in the syslog format.
3+
## Overview
44

5-
## Compatibility
5+
The Fortinet FortiGate Firewall Logs integration for Elastic enables the collection of logs from Fortinet FortiGate firewalls. This allows for comprehensive security monitoring, threat detection, and network traffic analysis within the Elastic Stack. By ingesting FortiGate logs, users can gain visibility into firewall activity, monitor for security threats, audit policy compliance, and troubleshoot network issues.
6+
7+
This integration facilitates:
8+
- Security monitoring and threat detection
9+
- Network traffic analysis and monitoring
10+
- Firewall policy compliance and auditing
11+
- Intrusion detection and prevention system (IPS) event monitoring
12+
- VPN connection monitoring and troubleshooting
13+
- Web filtering and application control monitoring
14+
15+
### Compatibility
616

717
This integration has been tested against FortiOS versions 6.x and 7.x up to 7.4.1. Newer versions are expected to work but have not been tested.
818

9-
## Note
19+
This integration is compatible with Elastic Stack version 8.11.0 or higher.
20+
21+
### How it works
22+
23+
This integration collects logs from FortiGate firewalls by receiving syslog data over TCP or UDP, or by reading directly from log files. An Elastic Agent is deployed on a host that is configured as a syslog receiver or has access to the log files. The agent forwards the logs to your Elastic deployment, where they can be monitored or analyzed.
24+
25+
## What data does this integration collect?
26+
27+
The Fortinet FortiGate Firewall Logs integration collects the following types of logs:
28+
* **Traffic logs**: Records of firewall decisions to allow or deny traffic.
29+
* **UTM (Unified Threat Management) logs**: Includes events from antivirus, web filter, application control, IPS, and DNS filter modules.
30+
* **Event logs**: System-level events, high-availability (HA) events, and configuration changes.
31+
* **Authentication logs**: Records of VPN, administrator, and user authentication events.
32+
33+
### Supported use cases
34+
35+
Integrating Fortinet FortiGate logs with Elastic provides a powerful solution for enhancing security posture and operational visibility. Key use cases include:
36+
- **Real-time Threat Detection**: Leverage Elastic SIEM to detect and respond to threats identified in firewall logs.
37+
- **Network Traffic Analysis**: Use Kibana dashboards to visualize and analyze network traffic patterns, helping to identify anomalies and optimize network performance.
38+
- **Compliance and Auditing**: Maintain a searchable, long-term archive of firewall logs to meet compliance requirements and conduct security audits.
39+
- **Incident Response**: Accelerate incident investigation by correlating firewall data with other security and observability data sources within Elastic.
40+
41+
## What do I need to use this integration?
42+
43+
- A FortiGate firewall with administrative access to configure syslog settings.
44+
- Network connectivity between the FortiGate firewall and the Elastic Agent host.
45+
- Elastic Stack version 8.11.0 or higher.
46+
47+
## How do I deploy this integration?
48+
49+
### Agent-based deployment
50+
51+
Elastic Agent must be installed on a host that will receive the syslog data or has access to the log files from the FortiGate firewall. For detailed installation instructions, refer to the Elastic Agent [installation guide](docs-content://reference/fleet/install-elastic-agents.md). Only one Elastic Agent is needed per host.
52+
53+
### Vendor set up steps
54+
55+
#### Syslog Configuration
56+
57+
You can configure FortiGate to send logs to the Elastic Agent using either the GUI or the CLI.
58+
59+
**GUI Configuration:**
60+
61+
1. Log in to the FortiGate web-based manager (GUI).
62+
2. Navigate to **Log & Report -> Log Settings**.
63+
3. Enable **Send Logs to Syslog**.
64+
4. In the IP address field, enter the IP address of the host where the Elastic Agent is installed.
65+
5. Click **Apply**.
66+
6. Under **Log Settings**, ensure that **Event Logging** and all desired log subtypes are enabled to generate and send the necessary logs.
67+
68+
**CLI Configuration:**
69+
70+
1. Log in to the FortiGate CLI.
71+
2. Use the following commands to configure the syslog server settings:
72+
73+
```sh
74+
config log syslogd setting
75+
set status enable
76+
set server "<elastic_agent_ip>"
77+
set port <port> // Default syslog ports are 514 for UDP and TCP
78+
// For TCP with reliable syslog mode, ensure framing is set to rfc6587
79+
set mode reliable
80+
set format rfc6587
81+
end
82+
```
83+
84+
3. Configure the appropriate log types and severity levels to be sent to the syslog server. For example:
85+
86+
```sh
87+
config log syslogd filter
88+
set severity information
89+
set forward-traffic enable
90+
set local-traffic enable
91+
set web enable
92+
set antivirus enable
93+
// Enable other UTM and event logs as needed
94+
end
95+
```
96+
97+
For more detailed information, refer to the [FortiGate CLI reference](https://docs.fortinet.com/document/fortigate/7.4.0/cli-reference/405620/config-log-syslogd-setting).
98+
99+
### Onboard / configure in Kibana
100+
101+
1. In Kibana, navigate to **Management > Integrations**.
102+
2. Search for "Fortinet FortiGate Firewall Logs" and select the integration.
103+
3. Click **Add Fortinet FortiGate Firewall Logs**.
104+
4. Configure the integration by selecting an input type and providing the necessary settings. This integration supports `TCP`, `UDP`, and `Log file` inputs.
105+
106+
#### TCP Input Configuration
107+
108+
This input collects logs over a TCP socket.
109+
110+
| Setting | Description |
111+
|---|---|
112+
| **Listen Address** | The bind address for the TCP listener (e.g., `localhost`, `0.0.0.0`). |
113+
| **Listen Port** | The TCP port number to listen on (e.g., `9004`). |
114+
| **Preserve original event** | If checked, a raw copy of the original log is stored in the `event.original` field. |
115+
116+
Under **Advanced Options**, you can configure the following optional parameters:
117+
118+
| Setting | Description |
119+
|---|---|
120+
| **Internal/External interfaces** | Define your network interfaces to correctly map network direction. |
121+
| **Internal networks** | Specify your internal network ranges (defaults to private address spaces). Supports CIDR notation and named ranges like `private`. |
122+
| **SSL Configuration** | Configure SSL options for encrypted communication. See the [SSL documentation](https://www.elastic.co/guide/en/beats/filebeat/current/configuration-ssl.html#ssl-common-config) for details. |
123+
| **Custom TCP Options** | `framing`: Specifies how messages are framed. Defaults to `rfc6587`, which is required for FortiGate's reliable syslog mode. <br> `max_message_size`: The maximum size of a log message (e.g., `50KiB`). <br> `max_connections`: The maximum number of simultaneous connections. |
124+
| **Timezone** | Specify an IANA timezone or offset (e.g., `+0200`) for logs with no timezone information. |
125+
| **Timezone Map** | A mapping of timezone strings from logs to standard IANA timezone formats. |
126+
| **Processors** | Add custom processors to enhance or reduce event fields before parsing. |
127+
128+
#### UDP Input Configuration
129+
130+
This input collects logs over a UDP socket.
131+
132+
| Setting | Description |
133+
|---|---|
134+
| **Listen Address** | The bind address for the UDP listener (e.g., `localhost`, `0.0.0.0`). |
135+
| **Listen Port** | The UDP port number to listen on (e.g., `9004`). |
136+
| **Preserve original event** | If checked, a raw copy of the original log is stored in the `event.original` field. |
137+
138+
Under **Advanced Options**, you can configure the following optional parameters:
139+
140+
| Setting | Description |
141+
|---|---|
142+
| **Internal/External interfaces** | Define your network interfaces to correctly map network direction. |
143+
| **Internal networks** | Specify your internal network ranges (defaults to private address spaces). |
144+
| **Custom UDP Options** | `read_buffer`: The size of the read buffer for the UDP socket (e.g., `100MiB`). <br> `max_message_size`: The maximum size of a log message (e.g., `50KiB`). <br> `timeout`: The read timeout for the UDP socket (e.g., `300s`). |
145+
| **Timezone** | Specify an IANA timezone or offset (e.g., `+0200`) for logs with no timezone information. |
146+
| **Timezone Map** | A mapping of timezone strings from logs to standard IANA timezone formats. |
147+
| **Processors** | Add custom processors to enhance or reduce event fields before parsing. |
148+
149+
#### Log file Input Configuration
150+
151+
This input collects logs directly from log files on the host where the Elastic Agent is running.
152+
153+
| Setting | Description |
154+
|---|---|
155+
| **Paths** | A list of file paths to monitor (e.g., `/var/log/fortinet-firewall.log`). |
156+
| **Preserve original event** | If checked, a raw copy of the original log is stored in the `event.original` field. |
157+
158+
Under **Advanced Options**, you can configure the following optional parameters:
159+
160+
| Setting | Description |
161+
|---|---|
162+
| **Internal/External interfaces** | Define your network interfaces to correctly map network direction. |
163+
| **Internal networks** | Specify your internal network ranges (defaults to private address spaces). |
164+
| **Timezone** | Specify an IANA timezone or offset (e.g., `+0200`) for logs with no timezone information. |
165+
| **Timezone Map** | A mapping of timezone strings from logs to standard IANA timezone formats. |
166+
| **Processors** | Add custom processors to enhance or reduce event fields before parsing. |
167+
168+
After configuring the input, assign the integration to an agent policy and click **Save and continue**.
169+
170+
### Validation
171+
172+
1. First, verify on the FortiGate device that logs are being actively sent to the configured Elastic Agent host.
173+
2. In Kibana, navigate to **Discover**.
174+
3. In the search bar, enter `data_stream.dataset: "fortinet_fortigate.log"` and check for incoming documents.
175+
4. Verify that events are appearing with recent timestamps.
176+
5. Navigate to **Management > Dashboards** and search for "Fortinet FortiGate Overview" to see if the visualizations are populated with data.
177+
6. Generate some test traffic that would be logged by the firewall and confirm that the corresponding logs appear in Kibana.
178+
179+
## Troubleshooting
180+
181+
For help with Elastic ingest tools, check [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems).
182+
183+
### Common Configuration Issues
184+
185+
- **No data is being collected**:
186+
* Verify network connectivity (e.g., using `ping` or `netcat`) between the FortiGate firewall and the Elastic Agent host.
187+
* Ensure there are no firewalls or network ACLs blocking the syslog port.
188+
* Confirm that the listening port configured in the Elastic integration matches the destination port configured on the FortiGate device.
189+
- **TCP framing issues**:
190+
* When using TCP input with reliable syslog mode, both the FortiGate configuration and the integration settings must have framing set to `rfc6587`. Mismatched framing settings will result in parsing errors or lost logs.
191+
192+
### Vendor Resources
193+
194+
- [FortiGate CLI Reference - Syslog Settings](https://docs.fortinet.com/document/fortigate/7.4.0/cli-reference/405620/config-log-syslogd-setting)
195+
- [Fortinet Documentation Library](https://docs.fortinet.com/)
196+
- [FortiGate Administration Guide](https://docs.fortinet.com/product/fortigate)
197+
198+
## Performance and Scaling
199+
200+
For more information on architectures that can be used for scaling this integration, check the [Ingest Architectures](https://www.elastic.co/docs/manage-data/ingest/ingest-reference-architectures) documentation. A common approach for large-scale syslog collection is to place a load balancer or a dedicated syslog collector like Logstash between the FortiGate devices and the Elastic Agents.
201+
202+
## Reference
203+
204+
### log
205+
206+
The `log` data stream collects all log types from the FortiGate firewall, including traffic, UTM, event, and authentication logs.
207+
208+
#### log fields
10209
11-
- When using the TCP input, be careful with the configured TCP framing. According to the [Fortigate reference](https://docs.fortinet.com/document/fortigate/7.4.0/cli-reference/405620/config-log-syslogd-setting), framing should be set to `rfc6587` when the syslog mode is reliable.
210+
{{ fields "log" }}
12211
13-
### Log
212+
#### log sample event
14213
15-
The `log` dataset collects Fortinet FortiGate logs.
214+
{{ event "log" }}
16215
17-
{{event "log"}}
216+
### Inputs used
18217
19-
{{fields "log"}}
218+
{{ inputDocs }}

‎packages/fortinet_fortigate/changelog.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
# newer versions go on top
2+
- version: "1.36.2"
3+
changes:
4+
- description: Update documentation
5+
type: bugfix
6+
link: https://github.com/elastic/integrations/pull/15825
27
- version: "1.36.1"
38
changes:
49
- description: Properly parse user names for login events messages.

0 commit comments

Comments
 (0)