vladimirs-git / cisco-acl

Python package to parse and manage Cisco ACLs

cisco-acl

Python package to parse and manage Cisco ACL (Access Control List).

Supported platforms:

• Cisco IOS (tested on ISR4331/K9, IOS XE version 16.09.06)
• Cisco Nexus NX-OS (tested on N3K-C3172TQ-XL, NXOS version 7.0(3)I7(8))

Main features:

• Supports wildcards, converts wildcards to prefixes
• Supports uni-dimensional address groups (address-group inside other address-group is not supported)
• Represents TCP/UDP ports and IP protocols as numbers or well-known names
• Converts IOS syntax to NX-OS and vice vera
• Generates sequence numbers for ACEs
• Looks for and removes ACEs in the shadow (rules without hits)
• Groups ACEs to blocks. After sorting, the order of ACEs within a group does not change

Contents

• Acronyms
• Requirements
• Installation
• acls()
• aces()
• addrgroups()
• range_ports()
• range_protocols()
• Objects

Acronyms

Acronym	Definition
ACL	Access Control List
ACE	Access Control Entry
ACEs	Multiple Access Control Entries

Requirements

Python >=3.8

Installation

Install the package from pypi.org release

pip install cisco-acl

or install the package from github.com release

pip install https://github.com/vladimirs-git/cisco-acl/archive/refs/tags/3.3.3.tar.gz

or install the package from github.com repository

pip install git+https://github.com/vladimirs-git/cisco-acl

acls()

cisco_acl.acls(config, kwargs) Creates Acl objects based on the "show running-config" output. Support address group objects. Each ACE line is treated as an independent Ace (default) or ACE lines can be grouped to AceGroup by text in remarks (param group_by)

Parameter	Type	Description
config	str	Cisco config, "show running-config" output
platform	str	Platform: "ios" (default), "nxos"
version	str	Software version, default is "0".
names	List[str]	Parses only ACLs with specified names, skips any other
max_ncwb	int	Max count of non-contiguous wildcard bits
indent	str	ACE lines indentation (default " ")
protocol_nr	bool	Well-known ip protocols as numbers, True - all ip protocols as numbers, False - well-known ip protocols as names (default)
port_nr	bool	Well-known TCP/UDP ports as numbers, True - all tcp/udp ports as numbers, False - well-known tcp/udp ports as names (default)
group_by	str	Startswith in remark line. ACEs group, starting from the Remark, where line startswith group_by, will be applied to the same AceGroup, until next Remark that also startswith group_by

Return

List of Acl objects

Examples

./examples/functions_acls.py

aces()

cisco_acl.aces(config, kwargs) Creates Ace objects based on the "show running-config" output

Parameter	Type	Description
config	str	Cisco config, "show running-config" output
platform	str	Platform: "ios" (default), "nxos"
version	str	Software version, default is "0".
max_ncwb	int	Max count of non-contiguous wildcard bits
protocol_nr	bool	Well-known ip protocols as numbers, True - all ip protocols as numbers, False - well-known ip protocols as names (default)
port_nr	bool	Well-known TCP/UDP ports as numbers, True - all tcp/udp ports as numbers, False - well-known tcp/udp ports as names (default)
group_by	str	Startswith in remark line. ACEs group, starting from the Remark, where line startswith group_by, will be applied to the same AceGroup, until next Remark that also startswith group_by

Return

List of Ace objects

Examples

./examples/functions_aces.py

addrgroups()

cisco_acl.addrgroups(config, kwargs) Creates AddrGroup objects based on the "show running-config" output

Parameter	Type	Description
config	str	Cisco config, "show running-config" output
platform	str	Platform: "ios" (default), "nxos"
version	str	Software version, default is "0".
max_ncwb	int	Max count of non-contiguous wildcard bits
indent	str	ACE lines indentation (default " ")

Return

List of AddrGroup objects

range_ports()

cisco_acl.range_ports(srcports, dstports, line, platform, port_nr) Generates ACEs in required range of TCP/UDP source/destination ports

Parameter	Type	Description
srcports	str	Range of TCP/UDP source ports
dstports	str	Range of TCP/UDP destination ports
line	str	ACE pattern, on whose basis new ACEs will be generated (default "permit tcp any any", operator "eq")
platform	str	Platform: "ios" (default), "nxos"
version	str	Software version, default is "0".
port_nr	bool	Well-known TCP/UDP ports as numbers, True - all tcp/udp ports as numbers, False - well-known tcp/udp ports as names (default)

Return

List of newly generated ACE lines

Examples

./examples/functions_range_ports.py

range_protocols()

cisco_acl.range_protocols(protocols, line, platform, protocol_nr) Generates ACEs in required range of IP protocols

Parameter	Type	Description
protocols	str	Range of IP protocols
line	str	ACE pattern, on whose basis new ACEs will be generated (default "permit ip any any")
platform	str	Platform: "ios" (default), "nxos"
version	str	Software version, default is "0".
protocol_nr	bool	Well-known ip protocols as numbers, True - all ip protocols as numbers, False - well-known ip protocols as names (default)

Return

List of newly generated ACE lines

Examples

./examples/functions_range_protocols.py

Objects

Documentation of objects for deep-code divers

./docs/objects.rst

cisco-acl's Issues

Does this support other types of ACLs?

Love this so far. Just wondering, does this support standard ACL's and IPv6? It seems to only pickup IPv4 extended access-lists. Thanks in advance.

Seems to fail parsing ACL's when object groups contain network-object's

My config contains the following lines:

object-group network NETWORK_1
 network-object object ApplicationOut-xx.xxx.xx.xxx
 network-object object XXXXX-network-27

When attempting to parse the config I receive the following error:

>>> acls = cisco_acl.acls(config=config, platform="ios")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/functions.py", line 83, in acls
    _add_addgr_to_aces(acls_, parser)
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/functions.py", line 321, in _add_addgr_to_aces
    addgrs: LAddrGroup = [AddrGroup(**d) for d in parsed_addgrs]
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/functions.py", line 321, in <listcomp>
    addgrs: LAddrGroup = [AddrGroup(**d) for d in parsed_addgrs]
                          ^^^^^^^^^^^^^^
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/addr_group.py", line 70, in __init__
    self.items = items
    ^^^^^^^^^^
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/addr_group.py", line 153, in items
    item_: OAddressAg = self._line_to_address(line)
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/addr_group.py", line 389, in _line_to_address
    addr_o = AddressAg(line=line, platform=self._platform, max_ncwb=self.max_ncwb)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/address_ag.py", line 87, in __init__
    self.line = line
    ^^^^^^^^^
  File "/root/miniconda3/lib/python3.11/site-packages/cisco_acl/address_ag.py", line 140, in line
    raise ValueError(f"invalid address {line=}")
ValueError: invalid address line='network-object object ApplicationOut-xx.xxx.xx.xxx'

It appears as though the code base doesn't have any implementation to parse network-object's when reading in the object-group lines.