asadbg

Preliminary note: we recommend you to use this as part of asatools but it can also be used standalone.

asadbg is a framework of tools to aid in automating live debugging of Cisco ASA devices, as well as automating interaction with the Cisco CLI over serial/ssh to quickly perform repetitive tasks.

• It wraps gdb
• It supports an asadbg.cfg configuration file to enable debugging different versions easily
• It supports both real hardware and GNS3
• Optionally it uses ret-sync to allow a better debugging experience from IDA Pro
• It supports executing additional gdb scripts at boot
• It provides libraries that can be useful for automating tests across multiple firmware versions on real hardware

The main tool is asadbg.py and it will execute most of the other helper scripts. Note that you may need to initially use asafw to unpack firmware to get the best flavour of asadbg.

• asadbg.py: main tool used to debug ASAs
• asdbg_hunt.py/asadbg_rename.py: IDA Python script to use with idahunt to import symbols for new targets

The following are automatically imported by asadbg.py but we give you some information on what they are for:

• asa_lib*.py: gdb Python scripts to use libdlmalloc, libptmalloc and libmempool.
• asa_sync.py: gdb Python script to use ret-sync
• comm.py: set of functions to communicate over serial, SSH, telnet.
• find_lina_pid.py: find the lina PID using SSH commands
• template_gdbinit: gdbinit template patched by asadbg.py for every targets we debug

Requirements

• Python3 only
  • pip3 install pyserial paramiko
• Heavily tested on Linux (but could work on OS X to)
• Preloaded firmware on the flash of real ASA device or ASA emulator configured in GNS3

You initially need to modify asadbg/env.sh to match your environment. It will allow you to define paths to the tools used by all the scripts as well as some variables matching your ASA environment. Note there is a simmilar asafw/env.sh but only one is required to be used for both projects. We recommend that you add it to your ~/.bashrc:

source /path/to/asadbg/env.sh

Automated debugging

One of the main benefits of using asadbg is that you can automate your use of both emulated (GNS3) and real Cisco ASA devices. This can include just generally automating booting and running various firmwares and configs, or specifically automating the debugging process of lina using gdb. This is mostly done through the asadbg.py script. The main idea is to preload some flash on the ASA device with firmware and configuration files that you want to use on the device. For each firmware that you want to debug, you can use something like the asafw tool to mine different symbols and then you can automatically generate gdbinit files using those symbols. By default asadbg.py will use a file template_gdbinit to automate building a version-specific gdbinit file at runtime using whatever symbols are present in the database.

Quickly boot a real device (no debugging)

You can quickly boot a given version by specifying the firmware and configuration files which must already be on the CF card.

asadbg$ ./asadbg.py --firmware-type normal --serial-port /dev/ttyUSB0 --firmware asa802-k8.bin --config config-802

Debugging a GNS3 device with config file

The following example shows how you can setup the configuration files to debug a GNS3 device. First we define an asadbg.cfg configuration file similar to below. It contains the GNS3 IP/port for the configured firewall that we obtain from GSN3 itself.

[GLOBAL]
gns3_host=192.168.5.1
asadb_file=asadb.json

[asav941200]
version=941200
arch=gns3
rootfs_path= /home/user/_asav941-200.qcow2.extracted/rootfs
gns3_port=12005
attach_gdb=yes

It also points to the ASA database asadb.json file containing the addresses required. What is important here is that the version=941200 and arch=gns3 specified in asadbg.cfg allow to match the firmware in asadb.json below. Also we indicate we want to attach gdb.

{
    "ASLR": false,
    "addresses": {
        "clock_interval": 59514112,
        "socks_proxy_server_start": 22139744,
        "aaa_admin_authenticate": 418288
    },
    "fw": "asav941-200.qcow2",
    "lina_imagebase": 4194304,
    "version": "9.4.1.200",
    "arch": 64
}

Now we start debugging and clock_interval will be automatically patched:

asadbg$ ./asadbg.py --name asav941200 --asadbg-config asadbg.cfg
[asadbg] Using config file: asadbg.cfg
[asadbg] Found section: 'asav941200' in config
[asadbg] Using gdb: '/usr/bin/gdb'
[asadbg] Using architecture: gns3
[asadbg] Trying lina: /home/user/_asav941-200.qcow2.extracted/rootfs/asa/bin/lina
[asadbg] Going to debug...
[asadbg] Using GNS3 emulator 192.168.5.1:12005
[asadbg] Starting gdb now...
[gdbinit_941200] Configuring paths...
[gdbinit_941200] Disabling pagination...
[gdbinit_941200] Connecting over TCP/IP...
0x0000003655201190 in ?? () from /home/user/_asav941-200.qcow2.extracted/rootfs/lib64/ld-linux-x86-64.so.2
[gdbinit_941200] Connected.
[gdbinit_941200] Watchdog disabled
[gdbinit_941200] heap debugging plugins loaded
[gdbinit_941200] Additional gdb scripts loaded
[gdbinit_941200] Done.
(gdb) c
Continuing.

Debugging a real device with config file

The following example shows how you can setup the configuration files to debug a real Cisco ASA device over a serial console.

[GLOBAL]
serial_port=/dev/ttyUSB0
asadb_file=asadb.json

[asa924-gdb]
version=924
arch=32
rootfs_path=/home/user/_asa924-k8.bin.extracted/rootfs
firmware=asa924-k8-debugshell-gdbserver.bin
config=config-924
firmware_type=gdb
attach_gdb=yes

Note also that we need to specify a firmware_type which indicates if the firmware is unmodified, rooted, has a serial shell enabled or if gdb has been enabled at boot. This is because we will do different things at boot depending on the format. Here we can see that we use a modified firmware asa924-k8-debugshell-gdbserver.bin which has gdbserver enabled at boot and contains a debug shell. We see below that when the bootrom starts, asadbg automatically interrupts the sequence in order to load the firmware and config files already on the CF card.

asadbg$ ./asadbg.py --name asa924-gdb --asadbg-config asadbg.cfg
[asadbg] Using config file: asadbg.cfg
[asadbg] Found section: 'asa924-gdb' in config
[asadbg] Using gdb: '/usr/bin/gdb'
[asadbg] Using architecture: 32
[asadbg] Trying lina: /home/user/_asa924-k8.bin.extracted/rootfs/asa/bin/lina
[asadbg] Going to debug...
[asadbg] Using serial port: /dev/ttyUSB0
[asadbg] Loading 'asa924-k8-debugshell-gdbserver.bin' with 'config-924'...
[comm] Waiting boot...
[SNIP]
Platform ASA5505

Use BREAK or ESC to interrupt boot.
Use SPACE to begin boot immediately.
Boot interrupted.

[SNIP]
rommon #0> boot asa924-k8-debugshell-gdbserver.bin cfg=config-924
Launching BootLoader...
Boot configuration file contains 1 entry.