Cisco ftd update documentation

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

@@ -1,38 +1,106 @@
-# Cisco FTD Integration
+# Cisco FTD Integration for Elastic
 
-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 
+## Overview
 
-It includes the following datasets for receiving logs over syslog or read from a file:
+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, organizations can enhance their security posture, streamline incident response, and gain deep insights into their network's operations.
 
-- `log` dataset: supports Cisco Firepower Threat Defense (FTD) logs.
+### Compatibility
 
-## Configuration
+This integration is compatible with Cisco FTD devices that support syslog export. It requires Elastic Stack version 8.11.0 or higher.
 
-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.
+### How it works
 
-## Handling security fields
+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.
 
-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.
+## What data does this integration collect?
 
-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.
+The Cisco FTD integration collects logs containing detailed information about:
+*   **Connection Events**: Firewall traffic, network address translation (NAT), and connection summaries.
+*   **Security Events**: Intrusion detection and prevention (IPS/IDS) alerts, file and malware protection events, and security intelligence data.
+*   **System Events**: Device health, system status, and configuration changes.
 
-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:
-1. In Kibana, navigate to `Stack Management -> Ingest Pipelines`.
-2. Click `Create Pipeline -> New Pipeline`.
-3. Add `Name` as `logs-cisco_ftd.log@custom` and an optional `Description`.
-4. Add processors to rename appropriate fields from `cisco.ftd.security` to `cisco.ftd.security_event`.
-    - Under `Processors`, click `Add a processor`.
-    - 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`.
-    - Optionally add `Convert` processor to convert the datatype of the renamed field under `cisco.ftd.security_event`.
+### Supported use cases
 
-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.
+- **Real-time Threat Detection**: Use Elastic SIEM to identify and respond to threats like malware, intrusions, and policy violations.
+- **Network Traffic Analysis**: Visualize and analyze network traffic patterns to identify anomalies, troubleshoot connectivity issues, and optimize performance.
+- **Security Auditing and Compliance**: Maintain a searchable archive of all firewall activity to support compliance requirements and forensic investigations.
+- **Operational Monitoring**: Track the health and status of your FTD devices to ensure they are functioning correctly.
 
-## Logs
+## What do I need to use this integration?
 
-### FTD
+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.
 
-The `log` dataset collects the Cisco Firepower Threat Defense (FTD) logs.
+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 via the integration's ingest pipelines.
 
-{{event "log"}}
+## How do I deploy this integration?
 
-{{fields "log"}}
+### Onboard / configure
+
+#### 1. Configure Cisco FTD to send Syslog Data
+
+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).
+
+1.  **Define the Elastic Agent as a Syslog Server**:
+    *   In your FDM or FMC interface, navigate to the syslog configuration section (e.g., **Objects > Syslog Servers** or **Device > System Settings > Logging**).
+    *   Add a new syslog server, providing the IP address and port of the machine where the Elastic Agent is running.
+    *   Ensure the protocol (TCP or UDP) matches the input you configure in the integration.
+
+2.  **Configure Logging Rules**:
+    *   Create or edit a logging rule to send specific event classes to the newly configured syslog server.
+    *   It is recommended to send all relevant message IDs to ensure comprehensive data collection.
+
+3.  **Deploy Changes**:
+    *   Save and deploy your configuration changes to the FTD device.
+
+For detailed, step-by-step instructions, refer to the official Cisco documentation, such as [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).
+
+#### 2. Add the Cisco FTD Integration in Elastic
+
+1.  In Kibana, navigate to **Management > Integrations**.
+2.  In the search bar, enter **Cisco FTD**.
+3.  Click the integration to see more details and then click **Add integration**.
+4.  Configure the integration settings. You must select the input method that matches your Cisco FTD configuration (TCP, UDP, or log file).
+    *   **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.
+    *   **For Log File**: Provide the file `paths` that the agent should monitor.
+5.  Click **Save and continue** to add the integration policy to an Elastic Agent.
+
+### Validation
+
+To validate that the integration is working, 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.
+
+## Troubleshooting
+
+For help with Elastic ingest tools, check [Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems).
+
+### Handling `security` fields
+
+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.
+
+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.
+
+To create this custom pipeline:
+1.  In Kibana, navigate to **Stack Management > Ingest Pipelines**.
+2.  Click **Create Pipeline > New Pipeline**.
+3.  Set the `Name` to `logs-cisco_ftd.log@custom`.
+4.  Add a **Rename** processor:
+    *   Set `Field` to the source field, e.g., `cisco.ftd.security.threat_name`.
+    *   Set `Target field` to the destination, e.g., `cisco.ftd.security_event.threat_name`.
+5.  Add more processors as needed and save the pipeline. This `@custom` pipeline will be automatically applied to all incoming Cisco FTD logs.
+
+## Reference
+
+### log
+
+The `log` data stream collects logs from Cisco Firepower Threat Defense (FTD) devices.
+
+#### log fields
+
+{{ fields "log" }}
+
+#### log sample event
+
+{{ event "log" }}
+
+
+### Inputs used
+{{ inputDocs }}

packages/cisco_ftd/changelog.yml

@@ -1,4 +1,9 @@
 # newer versions go on top
+- version: "3.13.0"
+  changes:
+    - description: Update documentation to the new template.
+      type: enhancement
+      link: https://github.com/elastic/integrations/pull/15887
 - version: "3.12.0"
   changes:
     - description: Preserve event.original on pipeline error.