ansible.asa

Ansible playbooks for managing and troubleshooting Cisco ASA firewalls. This collection provides tools for running diagnostic commands and packet traces against Cisco ASA devices over SSH.

Table of Contents

• Requirements
• Installation
• Configuration
• Playbooks
  • run_exec_command.yml
  • packet_tracer.yml
  • run_packet_tracer.yml
• Troubleshooting
• License

Requirements

• Ansible 2.7 or later
• Python 3.6 or later
• SSH access to one or more Cisco ASA devices
• A user account on the ASA with privilege level 15 (or sufficient privileges to run packet-tracer and show commands)

Installation

1. Clone this repository:

   git clone https://github.com/dacruz/ansible.asa.git
   cd ansible.asa

2. Install the required Ansible collection:

   ansible-galaxy collection install cisco.asa

Configuration

Inventory

Create an inventory file (e.g., hosts) listing your ASA devices:

[asa]
asa01 ansible_host=192.168.1.1
asa02 ansible_host=192.168.1.2

Connection Variables

The playbooks use the cli provider variable for SSH connectivity. Define these variables in your inventory or as extra vars:

cli:
  host: "{{ ansible_host }}"
  username: admin
  password: secret
  auth_pass: enable_secret   # optional, for enable mode

You can store these in a group vars file (e.g., group_vars/asa.yml) or pass them at runtime. It is strongly recommended to use Ansible Vault to encrypt sensitive credentials:

ansible-vault encrypt_string 'secret' --name 'password'

Playbooks

run_exec_command.yml

Runs an arbitrary exec-mode command on all target ASA devices and prints the output. Useful for quickly querying device state without writing a dedicated playbook.

Variables:

Variable	Required	Description
command	Yes	The exec command to run on the ASA

Example:

ansible-playbook -i hosts run_exec_command.yml \
  -e "command='show version'"

---

packet_tracer.yml

Runs Cisco ASA's packet-tracer command against every named interface on the device. This is useful when you don't know which interface a flow would ingress, and want to test all of them at once.

The playbook:

1. Enumerates all interface names from the running config (show run | in nameif)
2. Runs packet-tracer input <interface> ... detailed on each interface
3. Prints the command and result for each interface

Variables:

Variable	Required	Description
protocol	Yes	IP protocol: tcp, udp, icmp, etc.
src_address	Yes	Source IP address
dst_address	Yes	Destination IP address
dst_port	Yes	Destination port number

Example:

ansible-playbook -i hosts packet_tracer.yml \
  -e "protocol=tcp src_address=10.0.0.10 dst_address=203.0.113.50 dst_port=443"

---

run_packet_tracer.yml

Runs packet-tracer on a single, automatically-determined ingress interface. The playbook resolves the correct interface by looking up the routing table for the source address, falling back to the default route if no specific match is found.

The playbook:

1. Queries show route <src_address> to find the next-hop interface
2. Falls back to show route | include 0.0.0.0 0.0.0.0 (default route) if no specific route exists
3. Runs packet-tracer input <nameif> ... detailed
4. Prints the command, final verdict, and full output

Variables:

Variable	Required	Description
protocol	Yes	IP protocol: tcp, udp, icmp, etc.
src_address	Yes	Source IP address (used to resolve ingress interface)
dst_address	Yes	Destination IP address
dst_port	Yes	Destination port number

Example:

ansible-playbook -i hosts run_packet_tracer.yml \
  -e "protocol=tcp src_address=10.0.0.10 dst_address=203.0.113.50 dst_port=443"

Troubleshooting

asa_command module not found Ensure the cisco.asa collection is installed:

ansible-galaxy collection install cisco.asa

For older Ansible versions (< 2.9), the module may be available as asa_command without a collection prefix.

Authentication failures

• Verify the username/password in your cli provider vars.
• Confirm the user has privilege level 15 on the ASA, or that auth_pass is set correctly for enable-mode access.
• Ensure SSH is enabled on the ASA: ssh <management-ip> <mask> <interface>.

nameif variable undefined in run_packet_tracer.yml This occurs when neither the specific route lookup nor the default route lookup returns output. Verify that show route works on the device and that a default route (0.0.0.0 0.0.0.0) is configured.

Packet tracer returns no results for any interface Check that the source and destination addresses and ports are correct, and that the ASA has the interfaces configured with nameif values.

License

MIT © 2019 David Cruz