Skip to content

Commit f5948d6

Browse files
jrmolinjrmolin
authored
[cisco_ftd] update documentation with LLM
* create a knowledge base to enforce known-good information * use an LLM and examples to produce new documentation that follows the template
1 parent 292cef3 commit f5948d6

File tree

5 files changed

+703
-205
lines changed

5 files changed

+703
-205
lines changed

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

Lines changed: 123 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,138 @@
1-
# Cisco FTD Integration
1+
{{- generatedHeader }}
2+
# Cisco FTD Integration for Elastic
23

3-
This integration is for [Cisco](https://www.cisco.com/c/en/us/support/security/index.html) Firepower Threat Defence (FTD) device's logs. The package processes syslog messages from Cisco Firepower devices
4+
## Overview
45

5-
It includes the following datasets for receiving logs over syslog or read from a file:
6+
The Cisco Firepower Threat Defense (FTD) integration for Elastic collects logs from Cisco FTD devices, enabling comprehensive monitoring, threat detection, and security analysis within the Elastic Stack. This integration parses syslog messages from Cisco FTD, providing real-time visibility into network traffic, security events, and system activity. By centralizing these logs, you can enhance your security posture, streamline incident response, and gain deep insights into your network's operations.
67

7-
- `log` dataset: supports Cisco Firepower Threat Defense (FTD) logs.
8+
### Compatibility
89

9-
## Configuration
10+
This integration is compatible with Cisco FTD devices that support syslog export. It requires Elastic Stack version 8.11.0 or newer.
1011

11-
Cisco provides a range of Firepower devices, which may have different configuration steps. We recommend users navigate to the device specific configuration page, and search for/go to the "FTD Logging" or "Configure Logging on FTD" page for the specific device.
12+
### How it works
1213

13-
## Handling security fields
14+
The integration works by receiving syslog data sent from a Cisco FTD device. Elastic Agent can be configured to listen for these logs on a specific TCP or UDP port, or to read them directly from a log file. Once received, the agent processes and parses the logs before sending them to Elasticsearch.
1415

15-
Due to unknown amount of sub-fields present under the field `cisco.ftd.security`, it is mapped as [`flattened` datatype](https://www.elastic.co/guide/en/elasticsearch/reference/current/flattened.html). This limited certain operations, such as aggregations, to be performed on sub-fields of `cisco.ftd.security`. See [flattened dataype limitations](https://www.elastic.co/guide/en/elasticsearch/reference/current/flattened.html#supported-operations) for more details.
16+
## What data does this integration collect?
1617

17-
After analyzing more example logs, starting Cisco FTD integration version `2.21.0`, a new field `cisco.ftd.security_event` is added with a known set of fields moved over from `cisco.ftd.security`. With this, users can now perform aggregations on sub-fields of `cisco.ftd.security_event`. In addition to already moved fields, if users desire to add more fields onto `cisco.ftd.security_event` from `cisco.ftd.security`, they can make use of [`@custom` ingest pipeline](https://www.elastic.co/guide/en/elasticsearch/reference/current/ingest.html#pipelines-for-fleet-elastic-agent) that is automatically applied on every document at the end of the existing default pipeline.
18+
The Cisco FTD integration collects logs containing detailed information about:
19+
* **Connection Events**: Firewall traffic, network address translation (NAT), and connection summaries.
20+
* **Security Events**: Intrusion detection and prevention (IPS/IDS) alerts, file and malware protection events, and security intelligence data.
21+
* **System Events**: Device health, system status, and configuration changes.
1822

19-
To create and [add processors](https://www.elastic.co/guide/en/elasticsearch/reference/current/processors.html) to this `@custom` pipeline for Cisco FTD, users must follow below steps:
20-
1. In Kibana, navigate to `Stack Management -> Ingest Pipelines`.
21-
2. Click `Create Pipeline -> New Pipeline`.
22-
3. Add `Name` as `logs-cisco_ftd.log@custom` and an optional `Description`.
23-
4. Add processors to rename appropriate fields from `cisco.ftd.security` to `cisco.ftd.security_event`.
24-
- Under `Processors`, click `Add a processor`.
25-
- Say, you want to move field `threat_name` from `cisco.ftd.security` into `cisco.ftd.security_event`, then add a `Rename` processor with `Field` as `cisco.ftd.security.threat_name` and `Target field` as `cisco.ftd.security_event.threat_name`.
26-
- Optionally add `Convert` processor to convert the datatype of the renamed field under `cisco.ftd.security_event`.
23+
### Supported use cases
2724

28-
Now that the fields are available under `cisco.ftd.security_event`, users can perform aggregations of sub-fields under `cisco.ftd.security_event` as desired.
25+
- **Real-time Threat Detection**: Use Elastic SIEM to identify and respond to threats like malware, intrusions, and policy violations.
26+
- **Network Traffic Analysis**: Visualize and analyze network traffic patterns to identify anomalies, troubleshoot connectivity issues, and optimize performance.
27+
- **Security Auditing and Compliance**: Maintain a searchable archive of all firewall activity to support compliance requirements and forensic investigations.
28+
- **Operational Monitoring**: Track the health and status of your FTD devices to ensure they are functioning correctly.
2929

30-
## Logs
30+
## What do I need to use this integration?
3131

32-
### FTD
32+
Elastic Agent must be installed on a host that is reachable by your Cisco FTD device over the network. For more details, check the Elastic Agent [installation instructions](docs-content://reference/fleet/install-elastic-agents.md). You can install only one Elastic Agent per host.
3333

34-
The `log` dataset collects the Cisco Firepower Threat Defense (FTD) logs.
34+
Elastic Agent is required to stream data from the syslog or log file receiver and ship the data to Elastic, where the events will then be processed through the integration's ingest pipelines.
3535

36-
{{event "log"}}
36+
## How do I deploy this integration?
3737

38-
{{fields "log"}}
38+
### Onboard / configure
39+
40+
#### 1. Configure Cisco FTD to send Syslog Data
41+
42+
You must configure your Cisco FTD device to forward syslog messages to the Elastic Agent. The specific steps may vary depending on whether you are using Firepower Device Manager (FDM) or Firepower Management Center (FMC).
43+
44+
1. **Define the Elastic Agent as a Syslog Server**:
45+
* In your FDM or FMC interface, navigate to the syslog configuration section (for example, **Objects > Syslog Servers** or **Device > System Settings > Logging**).
46+
* Add a new syslog server, providing the IP address and port of the machine where the Elastic Agent is running.
47+
* Ensure the protocol (TCP or UDP) matches the input you configure in the integration.
48+
49+
2. **Configure Logging Rules**:
50+
* Create or edit a logging rule to send specific event classes to the newly configured syslog server.
51+
* It is recommended to send all relevant message IDs to ensure comprehensive data collection.
52+
53+
3. **Deploy Changes**:
54+
* Save and deploy your configuration changes to the FTD device.
55+
56+
Refer to the Cisco instructions on how to [configure Logging on FTD via FMC](https://www.cisco.com/c/en/us/support/docs/security/firepower-ngfw/200479-Configure-Logging-on-FTD-via-FMC.html).
57+
58+
#### 2. Add the Cisco FTD Integration in Elastic
59+
60+
1. In Kibana, navigate to **Management > Integrations**.
61+
2. In the search bar, enter **Cisco FTD**.
62+
3. Click the integration to see more details and then click **Add integration**.
63+
4. Configure the integration settings. You must select the input method that matches your Cisco FTD configuration (TCP, UDP, or log file).
64+
* **For TCP/UDP**: Specify the `host` and `port` where the Elastic Agent should listen for syslog messages. This must match the destination you configured on your FTD device.
65+
* **For Log File**: Provide the file `paths` that the agent should monitor.
66+
5. Click **Save and continue** to add the integration policy to an Elastic Agent.
67+
68+
#### 3. Validate that the integration is working
69+
70+
Navigate to the **Discover** tab in Kibana. Filter for the `cisco_ftd.log` dataset (`data_stream.dataset : "cisco_ftd.log"`) and verify that logs from your FTD device are being ingested. You can also check the pre-built dashboards for this integration by searching for "Cisco FTD" in the **Dashboards** section.
71+
72+
## Troubleshooting
73+
74+
1. **Verify Agent Status**:
75+
- In Kibana, navigate to **Management** > **Fleet** > **Agents**
76+
- Confirm the Elastic Agent shows as "Healthy" and has the Cisco FTD integration assigned
77+
- Check the agent logs for any connection errors
78+
79+
2. **Trigger Test Events**:
80+
- Generate test network traffic through the FTD device (for example, web browsing, file download)
81+
- Or trigger a security event by accessing a known malicious URL or downloading a test file
82+
- Verify the FTD device is sending syslog messages (check FTD logs or management interface)
83+
84+
3. **Verify Data Ingestion**:
85+
- In Kibana, navigate to **Discover**
86+
- Select the `logs-cisco_ftd.log-*` data stream
87+
- Verify events are appearing with recent timestamps
88+
- Check that events contain expected fields such as `cisco.ftd.*`, `source.ip`, `destination.ip`, etc.
89+
90+
4. **Validate Event Fields**:
91+
- Open a sample event and verify:
92+
- `@timestamp` is correctly parsed
93+
- `cisco.ftd.message_id` is present
94+
- Network fields (`source.ip`, `destination.ip`, `source.port`, `destination.port`) are populated
95+
- Security event fields are present for security-related events
96+
- `event.original` contains the raw syslog message (if preserve_original_event is enabled)
97+
98+
5. **Check for Parsing Errors**:
99+
- Filter for `event.outcome: failure` or check for `error.message` fields
100+
- Review any events with parsing issues
101+
- Verify timezone configuration if timestamps appear incorrect
102+
103+
For help with Elastic ingest tools, check [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems).
104+
105+
A field named `cisco.ftd.security` contains a variable number of sub-fields, which is mapped as a [`flattened` datatype](https://www.elastic.co/guide/en/elasticsearch/reference/current/flattened.html). This mapping limits certain operations, such as aggregations, on its sub-fields.
106+
107+
To enable aggregations on common security-related fields, the integration automatically moves a known set of fields from `cisco.ftd.security` to a new field, `cisco.ftd.security_event`. If you need to perform aggregations on additional fields within `cisco.ftd.security`, you can create a custom ingest pipeline to move them.
108+
109+
To create this custom pipeline:
110+
1. In Kibana, navigate to **Stack Management > Ingest Pipelines**.
111+
2. Click **Create Pipeline > New Pipeline**.
112+
3. Set the `Name` to `logs-cisco_ftd.log@custom`.
113+
4. Add a **Rename** processor:
114+
* Set `Field` to the source field, for example, `cisco.ftd.security.threat_name`.
115+
* Set `Target field` to the destination, for example, `cisco.ftd.security_event.threat_name`.
116+
5. Add more processors as needed and save the pipeline. This `@custom` pipeline will be automatically applied to all incoming Cisco FTD logs.
117+
118+
## Scaling
119+
120+
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.
121+
122+
## Reference
123+
124+
### log
125+
126+
The `log` data stream collects logs from Cisco Firepower Threat Defense (FTD) devices.
127+
128+
#### log fields
129+
130+
{{ fields "log" }}
131+
132+
#### log sample event
133+
134+
{{ event "log" }}
135+
136+
137+
### Inputs used
138+
{{ inputDocs }}

‎packages/cisco_ftd/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: "3.13.0"
3+
changes:
4+
- description: Update documentation to the new template.
5+
type: enhancement
6+
link: https://github.com/elastic/integrations/pull/15887
27
- version: "3.12.0"
38
changes:
49
- description: Preserve event.original on pipeline error.

0 commit comments

Comments
 (0)