diff --git a/packages/cisco_ftd/_dev/build/docs/README.md b/packages/cisco_ftd/_dev/build/docs/README.md index 86d44f65773..4286a8611f3 100644 --- a/packages/cisco_ftd/_dev/build/docs/README.md +++ b/packages/cisco_ftd/_dev/build/docs/README.md @@ -1,38 +1,109 @@ -# Cisco FTD Integration +{{- generatedHeader }} +# 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 newer. -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). + +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. + +## Scaling + +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. + +## 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 }} \ No newline at end of file diff --git a/packages/cisco_ftd/changelog.yml b/packages/cisco_ftd/changelog.yml index ae56bce7f02..b115b2bb69b 100644 --- a/packages/cisco_ftd/changelog.yml +++ b/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. diff --git a/packages/cisco_ftd/docs/README.md b/packages/cisco_ftd/docs/README.md index 8880037cd63..fd92fb1cf68 100644 --- a/packages/cisco_ftd/docs/README.md +++ b/packages/cisco_ftd/docs/README.md @@ -1,199 +1,103 @@ -# 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 newer. -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. -An example event for `log` looks as following: +## How do I deploy this integration? -```json -{ - "@timestamp": "2019-08-16T09:39:02.000Z", - "agent": { - "ephemeral_id": "477973c4-b380-4791-ad68-919bc71782eb", - "id": "dc57df32-adfa-4d1e-9386-d4519fc2d1e9", - "name": "elastic-agent-79310", - "type": "filebeat", - "version": "8.18.0" - }, - "cisco": { - "ftd": { - "rule_name": "malware-and-file-policy", - "security": { - "file_storage_status": "Not Stored (Disposition Was Pending)", - "threat_name": "Win.Ransomware.Eicar::95.sbx.tg" - }, - "security_event": { - "application_protocol": "HTTP", - "client": "cURL", - "dst_ip": "81.2.69.144", - "dst_port": 80, - "file_action": "Malware Cloud Lookup", - "file_direction": "Download", - "file_name": "eicar_com.zip", - "file_policy": "malware-and-file-policy", - "file_sandbox_status": "File Size Is Too Small", - "file_sha256": "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad", - "file_size": 184, - "file_type": "ZIP", - "first_packet_second": "2019-08-16T09:39:02Z", - "protocol": "tcp", - "sha_disposition": "Unavailable", - "spero_disposition": "Spero detection not performed on file", - "src_ip": "10.0.1.20", - "src_port": 46004, - "uri": "http://www.eicar.org/download/eicar_com.zip", - "user": "No Authentication Required" - }, - "threat_category": "Win.Ransomware.Eicar::95.sbx.tg" - } - }, - "data_stream": { - "dataset": "cisco_ftd.log", - "namespace": "84072", - "type": "logs" - }, - "destination": { - "address": "81.2.69.144", - "geo": { - "city_name": "London", - "continent_name": "Europe", - "country_iso_code": "GB", - "country_name": "United Kingdom", - "location": { - "lat": 51.5142, - "lon": -0.0931 - }, - "region_iso_code": "GB-ENG", - "region_name": "England" - }, - "ip": "81.2.69.144", - "port": 80 - }, - "ecs": { - "version": "8.17.0" - }, - "elastic_agent": { - "id": "dc57df32-adfa-4d1e-9386-d4519fc2d1e9", - "snapshot": false, - "version": "8.18.0" - }, - "event": { - "action": "malware-detected", - "agent_id_status": "verified", - "category": [ - "malware", - "file" - ], - "code": "430005", - "dataset": "cisco_ftd.log", - "ingested": "2025-05-20T10:32:02Z", - "kind": "event", - "original": "2019-08-16T09:39:03Z firepower %FTD-1-430005: SrcIP: 10.0.1.20, DstIP: 81.2.69.144, SrcPort: 46004, DstPort: 80, Protocol: tcp, FileDirection: Download, FileAction: Malware Cloud Lookup, FileSHA256: 2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad, SHA_Disposition: Unavailable, SperoDisposition: Spero detection not performed on file, ThreatName: Win.Ransomware.Eicar::95.sbx.tg, FileName: eicar_com.zip, FileType: ZIP, FileSize: 184, ApplicationProtocol: HTTP, Client: cURL, User: No Authentication Required, FirstPacketSecond: 2019-08-16T09:39:02Z, FilePolicy: malware-and-file-policy, FileStorageStatus: Not Stored (Disposition Was Pending), FileSandboxStatus: File Size Is Too Small, URI: http://www.eicar.org/download/eicar_com.zip", - "severity": 1, - "start": "2019-08-16T09:39:02Z", - "timezone": "UTC", - "type": [ - "info" - ] - }, - "file": { - "hash": { - "sha256": "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad" - }, - "name": "eicar_com.zip", - "size": 184 - }, - "host": { - "hostname": "firepower" - }, - "input": { - "type": "udp" - }, - "log": { - "level": "alert", - "source": { - "address": "192.168.249.3:51934" - } - }, - "network": { - "application": "curl", - "community_id": "1:jk2uwniJ2oCG0t73HeZ9w8gtA8E=", - "direction": "outbound", - "iana_number": "6", - "protocol": "http", - "transport": "tcp" - }, - "observer": { - "hostname": "firepower", - "product": "ftd", - "type": "idps", - "vendor": "Cisco" - }, - "related": { - "hash": [ - "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad" - ], - "hosts": [ - "firepower" - ], - "ip": [ - "10.0.1.20", - "81.2.69.144" - ] - }, - "rule": { - "ruleset": "malware-and-file-policy" - }, - "source": { - "address": "10.0.1.20", - "ip": "10.0.1.20", - "port": 46004 - }, - "tags": [ - "preserve_original_event", - "private_is_internal", - "cisco-ftd", - "forwarded" - ], - "url": { - "domain": "www.eicar.org", - "extension": "zip", - "original": "http://www.eicar.org/download/eicar_com.zip", - "path": "/download/eicar_com.zip", - "scheme": "http" - } -} -``` +### 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). + +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. + +## Scaling + +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. + +## Reference + +### log + +The `log` data stream collects logs from Cisco Firepower Threat Defense (FTD) devices. + +#### log fields **Exported fields** @@ -531,3 +435,247 @@ An example event for `log` looks as following: | user_agent.original | Unparsed user_agent string. | keyword | | user_agent.original.text | Multi-field of `user_agent.original`. | match_only_text | + +#### log sample event + +An example event for `log` looks as following: + +```json +{ + "@timestamp": "2019-08-16T09:39:02.000Z", + "agent": { + "ephemeral_id": "477973c4-b380-4791-ad68-919bc71782eb", + "id": "dc57df32-adfa-4d1e-9386-d4519fc2d1e9", + "name": "elastic-agent-79310", + "type": "filebeat", + "version": "8.18.0" + }, + "cisco": { + "ftd": { + "rule_name": "malware-and-file-policy", + "security": { + "file_storage_status": "Not Stored (Disposition Was Pending)", + "threat_name": "Win.Ransomware.Eicar::95.sbx.tg" + }, + "security_event": { + "application_protocol": "HTTP", + "client": "cURL", + "dst_ip": "81.2.69.144", + "dst_port": 80, + "file_action": "Malware Cloud Lookup", + "file_direction": "Download", + "file_name": "eicar_com.zip", + "file_policy": "malware-and-file-policy", + "file_sandbox_status": "File Size Is Too Small", + "file_sha256": "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad", + "file_size": 184, + "file_type": "ZIP", + "first_packet_second": "2019-08-16T09:39:02Z", + "protocol": "tcp", + "sha_disposition": "Unavailable", + "spero_disposition": "Spero detection not performed on file", + "src_ip": "10.0.1.20", + "src_port": 46004, + "uri": "http://www.eicar.org/download/eicar_com.zip", + "user": "No Authentication Required" + }, + "threat_category": "Win.Ransomware.Eicar::95.sbx.tg" + } + }, + "data_stream": { + "dataset": "cisco_ftd.log", + "namespace": "84072", + "type": "logs" + }, + "destination": { + "address": "81.2.69.144", + "geo": { + "city_name": "London", + "continent_name": "Europe", + "country_iso_code": "GB", + "country_name": "United Kingdom", + "location": { + "lat": 51.5142, + "lon": -0.0931 + }, + "region_iso_code": "GB-ENG", + "region_name": "England" + }, + "ip": "81.2.69.144", + "port": 80 + }, + "ecs": { + "version": "8.17.0" + }, + "elastic_agent": { + "id": "dc57df32-adfa-4d1e-9386-d4519fc2d1e9", + "snapshot": false, + "version": "8.18.0" + }, + "event": { + "action": "malware-detected", + "agent_id_status": "verified", + "category": [ + "malware", + "file" + ], + "code": "430005", + "dataset": "cisco_ftd.log", + "ingested": "2025-05-20T10:32:02Z", + "kind": "event", + "original": "2019-08-16T09:39:03Z firepower %FTD-1-430005: SrcIP: 10.0.1.20, DstIP: 81.2.69.144, SrcPort: 46004, DstPort: 80, Protocol: tcp, FileDirection: Download, FileAction: Malware Cloud Lookup, FileSHA256: 2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad, SHA_Disposition: Unavailable, SperoDisposition: Spero detection not performed on file, ThreatName: Win.Ransomware.Eicar::95.sbx.tg, FileName: eicar_com.zip, FileType: ZIP, FileSize: 184, ApplicationProtocol: HTTP, Client: cURL, User: No Authentication Required, FirstPacketSecond: 2019-08-16T09:39:02Z, FilePolicy: malware-and-file-policy, FileStorageStatus: Not Stored (Disposition Was Pending), FileSandboxStatus: File Size Is Too Small, URI: http://www.eicar.org/download/eicar_com.zip", + "severity": 1, + "start": "2019-08-16T09:39:02Z", + "timezone": "UTC", + "type": [ + "info" + ] + }, + "file": { + "hash": { + "sha256": "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad" + }, + "name": "eicar_com.zip", + "size": 184 + }, + "host": { + "hostname": "firepower" + }, + "input": { + "type": "udp" + }, + "log": { + "level": "alert", + "source": { + "address": "192.168.249.3:51934" + } + }, + "network": { + "application": "curl", + "community_id": "1:jk2uwniJ2oCG0t73HeZ9w8gtA8E=", + "direction": "outbound", + "iana_number": "6", + "protocol": "http", + "transport": "tcp" + }, + "observer": { + "hostname": "firepower", + "product": "ftd", + "type": "idps", + "vendor": "Cisco" + }, + "related": { + "hash": [ + "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad" + ], + "hosts": [ + "firepower" + ], + "ip": [ + "10.0.1.20", + "81.2.69.144" + ] + }, + "rule": { + "ruleset": "malware-and-file-policy" + }, + "source": { + "address": "10.0.1.20", + "ip": "10.0.1.20", + "port": 46004 + }, + "tags": [ + "preserve_original_event", + "private_is_internal", + "cisco-ftd", + "forwarded" + ], + "url": { + "domain": "www.eicar.org", + "extension": "zip", + "original": "http://www.eicar.org/download/eicar_com.zip", + "path": "/download/eicar_com.zip", + "scheme": "http" + } +} +``` + + +### Inputs used +These inputs can be used with this integration: +
+logfile + +## Setup +For more details about the logfile input settings, check the [Filebeat documentation](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-log). + +### Collecting logs from logfile + +To collect logs via logfile, select **Collect logs via the logfile input** and configure the following parameter: + +- Paths: List of glob-based paths to crawl and fetch log files from. Supports glob patterns like + `/var/log/*.log` or `/var/log/*/*.log` for subfolder matching. Each file found starts a + separate harvester. +
+
+tcp + +## Setup + +For more details about the TCP input settings, check the [Filebeat documentation](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-tcp). + +### Collecting logs from TCP + +To collect logs via TCP, select **Collect logs via TCP** and configure the following parameters: + +**Required Settings:** +- Host +- Port + +**Common Optional Settings:** +- Max Message Size - Maximum size of incoming messages +- Max Connections - Maximum number of concurrent connections +- Timeout - How long to wait for data before closing idle connections +- Line Delimiter - Character(s) that separate log messages + +## SSL/TLS Configuration + +To enable encrypted connections, configure the following SSL settings: + +**SSL Settings:** +- Enable SSL*- Toggle to enable SSL/TLS encryption +- Certificate - Path to the SSL certificate file (`.crt` or `.pem`) +- Certificate Key - Path to the private key file (`.key`) +- Certificate Authorities - Path to CA certificate file for client certificate validation (optional) +- Client Authentication - Require client certificates (`none`, `optional`, or `required`) +- Supported Protocols - TLS versions to support (e.g., `TLSv1.2`, `TLSv1.3`) + +**Example SSL Configuration:** +```yaml +ssl.enabled: true +ssl.certificate: "/path/to/server.crt" +ssl.key: "/path/to/server.key" +ssl.certificate_authorities: ["/path/to/ca.crt"] +ssl.client_authentication: "optional" +``` +
+
+udp + +## Setup + +For more details about the UDP input settings, check the [Filebeat documentation](https://www.elastic.co/docs/reference/beats/filebeat/filebeat-input-udp). + +### Collecting logs from UDP + +To collect logs via UDP, select **Collect logs via UDP** and configure the following parameters: + +**Required Settings:** +- Host +- Port + +**Common Optional Settings:** +- Max Message Size - Maximum size of UDP packets to accept (default: 10KB, max: 64KB) +- Read Buffer - UDP socket read buffer size for handling bursts of messages +- Read Timeout - How long to wait for incoming packets before checking for shutdown +
diff --git a/packages/cisco_ftd/docs/knowledge_base/system_info.md b/packages/cisco_ftd/docs/knowledge_base/system_info.md new file mode 100644 index 00000000000..e4c797698b0 --- /dev/null +++ b/packages/cisco_ftd/docs/knowledge_base/system_info.md @@ -0,0 +1,215 @@ +# Service Info + +## Common use cases +- Network security monitoring and threat detection +- Firewall log analysis and compliance reporting +- Malware detection and file transfer monitoring +- VPN connection tracking and analysis +- Access control rule monitoring +- SSL/TLS inspection and policy enforcement +- URL filtering and web application identification +- DNS query monitoring +- Network flow analysis and connection tracking + +## Data types collected +- Security events (malware detection, file transfers, threat intelligence) +- Access control events (rule matches, connection allows/blocks) +- VPN events (connection establishment, termination, user authentication) +- SSL/TLS inspection events +- DNS query and response events +- Network flow information (source/destination IPs, ports, protocols) +- File transfer events (uploads, downloads, file analysis results) +- User authentication and authorization events (AAA) +- System events (failover, updates, configuration changes) + +## Compatibility +- Compatible with Cisco Firepower Threat Defense (FTD) devices +- Supports syslog message collection via TCP, UDP, or logfile input +- Tested with various Cisco Firepower device models and FTD software versions +- Requires Elastic Stack version ^8.11.0 || ^9.0.0 + +## Scaling and Performance +- Supports high-volume syslog ingestion via TCP and UDP inputs +- Can handle multiple concurrent connections when using TCP input +- UDP input provides low-latency log collection suitable for high-throughput environments +- Logfile input allows reading from local log files for batch processing or archival data +- Performance depends on network bandwidth, Elastic Agent resources, and Elasticsearch cluster capacity +- For high-volume deployments, consider using multiple Elastic Agents with load balancing + +# Set Up Instructions + +## Vendor prerequisites +- Cisco Firepower Threat Defense (FTD) device configured and operational +- Network connectivity between FTD device and Elastic Agent host +- Syslog logging enabled on the FTD device +- Appropriate firewall rules to allow syslog traffic from FTD to Elastic Agent (if applicable) +- Access to FTD management interface for configuration changes + +## Elastic prerequisites +- Elastic Stack version ^8.11.0 || ^9.0.0 +- Elastic Agent installed and configured +- Sufficient network bandwidth and system resources for log ingestion +- Appropriate Elasticsearch cluster capacity for expected log volume + +## Vendor set up steps + +### TCP Input Configuration +1. Log into the FTD management interface (Firepower Management Center or FDM) +2. Navigate to the device-specific configuration page +3. Search for or navigate to "FTD Logging" or "Configure Logging on FTD" page +4. Configure syslog server settings: + - Set the syslog server IP address to the Elastic Agent host IP + - Set the syslog port (default: 9003 for TCP) + - Select TCP as the transport protocol + - Enable the appropriate log types (security events, connection events, etc.) +5. Save and deploy the configuration to the FTD device +6. Verify syslog connectivity by checking for test messages + +### UDP Input Configuration +1. Log into the FTD management interface +2. Navigate to the device-specific configuration page +3. Search for or navigate to "FTD Logging" or "Configure Logging on FTD" page +4. Configure syslog server settings: + - Set the syslog server IP address to the Elastic Agent host IP + - Set the syslog port (default: 9003 for UDP) + - Select UDP as the transport protocol + - Enable the appropriate log types (security events, connection events, etc.) +5. Save and deploy the configuration to the FTD device +6. Verify syslog connectivity by checking for test messages + +### Logfile Input Configuration +1. Ensure FTD device is configured to write logs to a file system accessible by Elastic Agent +2. Identify the log file path(s) on the system (e.g., `/var/log/cisco-ftd.log`) +3. Ensure Elastic Agent has read permissions for the log file(s) +4. Configure log rotation if needed to prevent disk space issues + +Note: 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. + +## Kibana set up steps +1. Log into Kibana +2. Navigate to **Integrations** > **Browse integrations** +3. Search for "Cisco FTD" and select the integration +4. Click **Add Cisco FTD** +5. Configure the integration: + - **Name**: Provide a name for the integration instance + - **Data stream**: Select "Cisco FTD logs" + - **Input type**: Choose TCP, UDP, or Log file based on your configuration + - **TCP/UDP Configuration**: + - Set the host and port to match your Elastic Agent configuration + - Configure timezone offset if needed (default: UTC) + - Enable "Preserve original event" if you want to keep raw log messages + - Configure internal/external zones if needed for network direction detection + - **Logfile Configuration**: + - Specify the log file path(s) + - Configure timezone offset if needed + - Set internal/external zones if applicable +6. Click **Save and continue** +7. Add the integration to an agent policy or create a new agent policy +8. Deploy the agent policy to your Elastic Agents +9. Verify the agent is receiving data by checking the agent status in Kibana + +# Validation Steps +1. **Verify Agent Status**: + - In Kibana, navigate to **Management** > **Fleet** > **Agents** + - Confirm the Elastic Agent shows as "Healthy" and has the Cisco FTD integration assigned + - Check the agent logs for any connection errors + +2. **Trigger Test Events**: + - Generate test network traffic through the FTD device (e.g., web browsing, file download) + - Or trigger a security event by accessing a known malicious URL or downloading a test file + - Verify the FTD device is sending syslog messages (check FTD logs or management interface) + +3. **Verify Data Ingestion**: + - In Kibana, navigate to **Discover** + - Select the `logs-cisco_ftd.log-*` data stream + - Verify events are appearing with recent timestamps + - Check that events contain expected fields such as `cisco.ftd.*`, `source.ip`, `destination.ip`, etc. + +4. **Validate Event Fields**: + - Open a sample event and verify: + - `@timestamp` is correctly parsed + - `cisco.ftd.message_id` is present + - Network fields (`source.ip`, `destination.ip`, `source.port`, `destination.port`) are populated + - Security event fields are present for security-related events + - `event.original` contains the raw syslog message (if preserve_original_event is enabled) + +5. **Check for Parsing Errors**: + - Filter for `event.outcome: failure` or check for `error.message` fields + - Review any events with parsing issues + - Verify timezone configuration if timestamps appear incorrect + +# Troubleshooting + +## Common Configuration Issues + +**Issue**: No data appearing in Kibana Discover +- **Solution**: + - Verify Elastic Agent is running and healthy + - Check network connectivity between FTD device and Elastic Agent + - Verify syslog server configuration on FTD device matches Elastic Agent host/port + - Check firewall rules allow syslog traffic + - Review Elastic Agent logs for connection errors + - Verify the integration is properly assigned to the agent policy + +**Issue**: Service failed to start +- **Solution**: + - Check Elastic Agent logs for specific error messages + - Verify port is not already in use by another service + - Ensure Elastic Agent has necessary permissions (especially for logfile input) + - Check system resources (CPU, memory, disk space) + +**Issue**: Incorrect timezone in events +- **Solution**: + - Configure the `tz_offset` parameter in the integration settings + - Use IANA timezone format (e.g., "America/New_York") or offset format (e.g., "+0500") + - Verify FTD device timezone settings match your configuration + +**Issue**: Network direction not correctly identified +- **Solution**: + - Configure internal and external zones in the integration settings + - Ensure zone names match exactly with FTD device zone configuration + - Verify `private_is_internal` setting matches your network topology + - Check that `cisco.ftd.ingress_zone` and `cisco.ftd.egress_zone` fields are present in events + +## Ingestion Errors + +**Issue**: Events showing parsing errors or missing fields +- **Solution**: + - Check `event.original` field to see the raw syslog message + - Verify FTD device is sending logs in expected syslog format + - Review Elastic Agent logs for parsing error details + - Ensure FTD device software version is compatible with the integration + - Check if custom message formats require pipeline modifications + +**Issue**: `cisco.ftd.security` field contains flattened data but aggregations fail +- **Solution**: + - Starting from version 2.21.0, known security fields are moved to `cisco.ftd.security_event` for better aggregation support + - Use `cisco.ftd.security_event.*` fields for aggregations instead of `cisco.ftd.security.*` + - To add more fields to `cisco.ftd.security_event`, create a custom ingest pipeline: + 1. Navigate to **Stack Management** > **Ingest Pipelines** + 2. Create pipeline named `logs-cisco_ftd.log@custom` + 3. Add Rename processors to move fields from `cisco.ftd.security.*` to `cisco.ftd.security_event.*` + 4. Optionally add Convert processors to set correct data types + +**Issue**: Missing or incorrect field mappings +- **Solution**: + - Review the exported fields documentation in the integration README + - Verify FTD message IDs are supported by checking sample events + - Some fields may be vendor-specific and require custom mapping + - Check integration version changelog for recent field additions + +## API Authentication Errors +- **Not applicable**: This integration uses syslog protocol and does not require API authentication + +## Vendor Resources +- [Cisco Secure Firewall Management Center Examples](https://www.cisco.com/c/en/us/support/security/defense-center/products-configuration-examples-list.html) +- [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) +- [Configure FMC to Send Audit Logs to a Syslog Server](https://www.cisco.com/c/en/us/support/docs/security/secure-firewall-management-center/221019-configure-fmc-to-send-audit-logs-to-a-sy.html) + +# Documentation sites +- [Cisco Secure Firewall Management Center Examples](https://www.cisco.com/c/en/us/support/security/defense-center/products-configuration-examples-list.html) +- [Cisco Firepower Threat Defense Product Page](https://www.cisco.com/c/en/us/support/security/firepower-ngfw/series.html) +- [Cisco FTD Software Release and Sustaining Bulletin](https://www.cisco.com/c/en/us/products/collateral/security/firewalls/bulletin-c25-743178.html) +- [Elastic Integrations Documentation](https://www.elastic.co/guide/en/integrations/index.html) +- [Elastic Agent Documentation](https://www.elastic.co/guide/en/fleet/current/index.html) +- [Elastic Ingest/Fleet Common problems](https://www.elastic.co/docs/troubleshoot/ingest/fleet/common-problems) diff --git a/packages/cisco_ftd/manifest.yml b/packages/cisco_ftd/manifest.yml index fbd0de9b679..a1c265aa879 100644 --- a/packages/cisco_ftd/manifest.yml +++ b/packages/cisco_ftd/manifest.yml @@ -1,7 +1,7 @@ format_version: "3.0.3" name: cisco_ftd title: Cisco FTD -version: "3.12.0" +version: "3.13.0" description: Collect logs from Cisco FTD with Elastic Agent. type: integration categories: