From b5cfba0a077dcaa6309b3af301670962b86d72ca Mon Sep 17 00:00:00 2001 From: Jimmy Holland <6574404+jamesholland-uk@users.noreply.github.com> Date: Wed, 9 Aug 2023 12:22:38 +0100 Subject: [PATCH] docs: More example content and author update --- docs/source/authors.rst | 1 + docs/source/examples.rst | 152 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 145 insertions(+), 8 deletions(-) diff --git a/docs/source/authors.rst b/docs/source/authors.rst index bd8c70579..c406b6975 100644 --- a/docs/source/authors.rst +++ b/docs/source/authors.rst @@ -17,6 +17,7 @@ Contributors - Vinay Venkataraghavan (@vinayvenkat) - Michael Richardson (@mrichardson03) - Joshua Colson (@freakinhippie) +- James Holland (@jamesholland-uk) Credits diff --git a/docs/source/examples.rst b/docs/source/examples.rst index d3580361f..62231b80b 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -285,21 +285,26 @@ Event-Driven Ansible (EDA) Event-Driven Ansible is a responsive automation solution that can process events containing discrete, actionable intelligence. The `extensions/plugins/event_source/logs.py` plugin is capable of -receiving JSON structured messages from a PAN-OS firewall, restructure the -payload as a Python dictionary, determine the appropriate response -to the event and then execute automated actions to address or remediate. +receiving JSON structured messages from a PAN-OS firewall, restructures +the payload as a Python dictionary, determines the appropriate response +to the event, and then executes automated actions to address or remediate +based on the situation. -There are four components needed to implement EDA with PAN-OS: +There are four components needed to implement this example EDA use case +with PAN-OS: - HTTP server profile: A PAN-OS firewall configuration that defines how the PAN-OS firewall(s) should send events to the EDA server. -- rulebook: A YAML file that defines the conditions and actions to be - taken when a condition is met. -- inventory: A YAML file that defines the PAN-OS firewall(s) to be +- EDA rulebook: A YAML file which describes events of interest, and how to + EDA respond to them based on conditions. +- Inventory: A YAML file that defines the PAN-OS firewall(s) to be executed against when a condition is met. -- playbook: A YAML file that defines the Ansible tasks to be executed +- Ansible playbook: A YAML file that defines the Ansible tasks to be executed when a condition is met. +The four components are described here in the context of a use case of +detecting decryption issues based on the Decryption Logs, and responding +by placing the relevant URLs into a category used for decryption bypass. HTTP Server Profile ------------------- @@ -335,10 +340,95 @@ send logs to the EDA server. "type": "decryption" } +This HTTP Server Profile could be configured in its entirety using the +following tasks in an Ansible playbook: + +.. code-block:: yaml + + - name: Create a HTTP Server Profile for Decyption Logs + paloaltonetworks.panos.panos_http_profile: + provider: '{{ device }}' + name: '{{ server_profile_name_decrypt }}' + decryption_name: 'decryption-logs-to-eda' + decryption_uri_format: 'https://test' + decryption_payload: > + { + "category": "network", + "details": { + "action": "$action", + "app": "$app", + "cn": "$cn", + "dst": "$dst", + "device_name": "$device_name", + "error": "$error", + "issuer_cn": "$issuer_cn", + "root_cn": "$root_cn", + "root_status": "$root_status", + "sni": "$sni", + "src": "$src", + "srcuser": "$srcuser" + }, + "receive_time": "$receive_time", + "rule": "$rule", + "rule_uuid": "$rule_uuid", + "serial": "$serial", + "sessionid": "$sessionid", + "severity": "informational", + "type": "decryption" + } + + - name: Create http server + paloaltonetworks.panos.panos_http_server: + provider: '{{ device }}' + http_profile: '{{ server_profile_name_decrypt }}' + name: 'my-http-server' + address: '192.168.1.5' + http_method: 'GET' + + - name: Add a HTTP header to HTTP Server Profile + paloaltonetworks.panos.panos_http_profile_header: + provider: '{{ device }}' + http_profile: '{{ server_profile_name_decrypt }}' + log_type: 'decryption' + header: 'Content-Type' + value: 'application/json' + + - name: Add a param to the config log type + paloaltonetworks.panos.panos_http_profile_param: + provider: '{{ device }}' + http_profile: '{{ server_profile_name_decrypt }}' + log_type: 'decryption' + param: 'serial' + value: '$serial' + +The HTTP Server Profile would be used in a Log Forwarding Profile +with a filter for only forwarding Decryption Logs when there has +been an issue with decryption. Here are example Ansible tasks to +create a Log Forwarding Profile: + +.. code-block:: yaml + + - name: Create log forwarding profile + paloaltonetworks.panos.panos_log_forwarding_profile: + provider: '{{ provider }}' + name: 'default' + enhanced_logging: true + + - name: Create log forwarding profile match list + paloaltonetworks.panos.panos_log_forwarding_profile_match_list: + provider: '{{ provider }}' + log_forwarding_profile: 'default' + name: 'eda-decryption-forwarding' + log_type: 'decryption' + filter: '( err_index neq None ) and ( proxy_type eq Forward )' + Rulebook - rulebook.yml ----------------------- +This rulebook shows an example of how to configure EDA to receive +the decryption logs from PAN-OS, and execute a remediation playbook: + .. code-block:: yaml --- @@ -370,6 +460,10 @@ Rulebook - rulebook.yml Inventory --------- +The inventory for this example use case is one that defines all hosts +(firewalls) to be local connectivity, as this is how Ansible communicates +with PAN-OS: + .. code-block:: yaml all: @@ -382,6 +476,10 @@ Inventory Playbook - decryption_remediation.yml ------------------------------------- +The playbook executed when the conditions in the rulebook are met, in +this example use case, performs tasks to add the relevant URL into a +category used to bypass decryption, thus remediating the problem: + .. code-block:: yaml --- @@ -443,3 +541,41 @@ Playbook - decryption_remediation.yml - name: Output commit results ansible.builtin.debug: msg: "Commit with Job ID: {{ results.jobid }} had output: {{ results }}" + +An alternative remediation if the web server hosting the URL is not presenting +the relevant intermediate certificate, would be to add the intermediate +certificate into the PAN-OS certificate store, and not use a bypass (which weakens +visibility by leaving more traffic encrypted) like the previous example: + +.. code-block:: yaml + + tasks: + - name: Get intermediate certificate URL + ansible.builtin.set_fact: + intermediate_cert_url: "{{ ansible_eda.event.payload.details.error | regex_search(regex_query, ignorecase=True) }}" + vars: + regex_query: '(http(s)?:\/\/.)?(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)' + + - name: Get intermediate certificate filename + ansible.builtin.set_fact: + intermediate_cert_name: "{{ intermediate_cert_url | regex_search(regex_query, ignorecase=True) }}" + vars: + regex_query: '[^\/\\&\?]+\.\w{3,4}(?=([\?&].*$|$))' + + - name: Download intermediate certificate + ansible.builtin.get_url: + url: '{{ intermediate_cert_url }}' + dest: '{{ intermediate_cert_name }}' + + - name: Convert intermediate certificate from DER format to PEM format + ansible.builtin.command: openssl x509 -inform DER -outform PEM -in {{ intermediate_cert_name }} -out {{ intermediate_cert_name }}.pem + register: output + changed_when: output.rc != 0 + + - name: Import intermediate certificate to NGFW + paloaltonetworks.panos.panos_import: + provider: '{{ device }}' + category: 'certificate' + certificate_name: '{{ intermediate_cert_name }}' + format: 'pem' + filename: '{{ intermediate_cert_name }}.pem'