aerleon / aerleon Goto Github PK

Multi-platform ACL generation system

Home Page: https://aerleon.readthedocs.io/

License: Apache License 2.0

Python 99.94% Shell 0.04% C++ 0.02%

aerleon's Introduction

Aerleon

Generate firewall configs for multiple firewall platforms from a single platform-agnostic configuration language through a command line tool and Python API.

Aerleon is a fork of Capirca with the following major additions:

YAML policy and network definition files and pol2yaml, a converter from Capirca policy DSL to YAML.
Network definitions with FQDN data.
New firewall platforms can be added through plugins.
Typed Python APIs for ACL generation and aclcheck queries.
A SLSA-compatible verifiable release process.
A detailed regression test suite.
Many bug fixes and performance enhancements.

Install

Aerleon requires Python 3.8 or higher.

pip install aerleon

To install via brew:

brew install aerleon

Overview

Aerleon provides a command line tool and a Python API that will generate configs for multiple firewall platforms from a single platform-agnostic configuration language. It can generate configs for Cisco, Juniper, Palo Alto Networks and many other firewall vendors.

A getting started guide walking through the basics of using Aerleon is available on the docs website.

Documentation

Documentation can be found at https://aerleon.readthedocs.io/en/latest/.

Contributing

Contributions are welcome. Please review the contributing guidelines and code of conduct for this project.

Contact

Official channels for communicating issues is via Github Issues.

General discussions can be had either in Github Discussions or in our Slack Server.

Contact Maintainers

You can always reach out to us on Slack. You many also reach out to us via e-mail.

Rob Ankeny ([email protected])

Jason Benterou ([email protected])

Resources

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Ken Celenza}
📖

_{Axel F}
📖

_{Brandon Bennett}
💻

_{Bastian Triller}
💻

_{Arzhel Younsi}
💻

This project follows the all-contributors specification. Contributions of any kind welcome!

Credit

Files and code included in this project from Capirca are copyright Google and are included under the terms of the Apache License, Version 2.0. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Contributors who wish to modify files bearing a copyright notice are obligated by the terms of the Apache License, Version 2.0 to include at the top of the file a prominent notice stating as much. Copyright notices must not be removed from files in this repository.

This README file and other documentation files may contain phrases and sections that are copyright Google. This file and other documentation files are modified from the original by the Aerleon Project Team.

aerleon's People

Contributors

Stargazers

Watchers

aerleon's Issues

[LEGACY ISSUE PR224] Update cisco.py to handle using raw protocol numbers in policy

Set up Contributor Guide

Bug: Non-determinism in Arista TP output

Aclgen will render the policy file sample_arista_tp.pol differently on each run. The order of counter terms is not consistent.

E   -    counter ipsec-esp ssh ospf ipsec-ike tacacs-requests icmp-loopback ntp-replies tacacs-replies default-discard reject-imap-requests ssh-replies dns-replies bgp-replies bgp-requests radius-replies vrrp ntp-request wonky-prots-loopback large-dns-counter
E   +    counter large-dns-counter tacacs-replies tacacs-requests bgp-requests vrrp ssh dns-replies ipsec-esp radius-replies ntp-request icmp-loopback reject-imap-requests ntp-replies ipsec-ike default-discard wonky-prots-loopback bgp-replies ospf ssh-replies

Steps to reproduce

Run aclgen.py which will process all sample policy files. You may wish to temporarily remove all policy files besides sample_arista_tp.pol to speed things up. Run multiple times and notice that on each run the contents of the output file sample_arista_tp.atp will vary.

Document noverbose for cisco and its derivatives.

https://github.com/ankben/aerleon/blob/main/aerleon/lib/cisco.py#L1006

[LEGACY ISSUE 186] Capirca doesn't render established keyword for Cisco object-group syntax

[Final check] [Silent Launch] Apache License copyright compliance

Every file that contains copyrighted Google code needs to say so (including docs and README)
Every file that contains a mix of Google content and our content needs an additional message (including docs and README)

[LEGACY ISSUE 181] Caprica is does not render an ICMP protocol term with the fragments option

Validation for forwarding_class

Presently there is no validation around forwarding_class beyond "one or more strings". It's a Juniper-only field with some documentation available online¹. If we can do so accurately let's implement some validation on the field.

https://www.juniper.net/documentation/us/en/software/junos/cos-security-devices/topics/concept/cos-forwarding-class-overview.html ↩

[LEGACY ISSUE 252] Cisco ASA generator has no way to enable ipv6 address processing

[LEGACY ISSUE 298] Cisco object-group ACLs don't properly render ICMP type and code

[New Generator] Add support in Cisco WLC ACL

Perf: slow trace on sample policies

Processing the sample policy files takes about 5 minutes. A review of a perf trace showed that a single call to RenderFile runs for the majority of those 5 minutes. Some significant time is spent in _TranslatePolicy for the paloalto generator.

Fortinet Support

Fortinet has been a requested generator by the community for a long time. Multiple people have asked for it over the NTC slack. Batfish has asked for progress and would likely wish to use it for their own customers.

Check repository for debug logs that should be info/warning

[Silent Launch] Release automation: push to PyPI on release

Hoist "expiration" impl into core

Currently the implementation of the 'expiration' property is handled through a block of copy-paste code in every generator. Should a generator author forget to paste in this code, expiration won't work.

The core application should handle the expiration implementation and not even pass it through to the generator.

[LEGACY ISSUE 273] Paloalto generator should correctly support other protocols than TCP/UDP and ICMP/ICMPv6

Deprecate bookkeeping fields on Term data model

The Term data model has some fields that must not be set by users and are for internal use only. These fields are listed here with a brief summary and a suggestion for how to migrate the workload that relies on them.

term.translated: Used internally to indicate processing was already performed on this Term. Ignored by all generators. I will remove this as part of the parser / model builder cleanup currently underway.
term.inactive: Set by Juniper generators when the option 'inactive' is present in term.options. Ignored by all non-Juniper generators. It does not serve any real purpose besides unnecessarily memoizing the expression if 'inactive' in term.option. It can be removed from the core data model with no loss of function as it is not an error for Juniper generators to set garbage attributes on the object.
term.flattened
term.flattened_addr
term.flattened_saddr
term.flattened_daddr: Used internally to memoize the result of address flattening, which is somewhat expensive. Some generators actually read these values directly. The model cleanup change currently underway will move these out of the model and into the view model (PolicyView / TermView).

[PENDING VERIFICATION][LEGACY ISSUE #121] fix proposal for conflicting srx address-sets and ios object-group definitions due to optimization and parent_token usage

Verify this issue exists still

YAML support for .net/.svc files

Add metadata for logging for integrity checking

When ACLs are deployed it is desired to make sure that the firewall continues to have the desired set of ACLs present. This can be complex given firewalls may be updated on a cadence that does not match updates to the files output by aerleon. We also would want to allow an analyst to be able to recreate the inputs.

We are discussing solutions to this and have come up with a couple

Logging information that allows an analyst to understand how an ACL was created
Provide the ability to check some amount of the integrity of the ACL with hashing

This can be complicated by the fact that our ACLs will likely be consumed by other tools and we have no guarantees that they will not be mangled. We also know of platforms where comments where this metadata would exist is not preserved.

Remove six package

six was made to help ease the transition between python 2 to python 3. We will never support python 2 so we should remove these where present.

[LEGACY ISSUE 174a] Cisco Object Groups do not properly support options/icmp types

[LEGACY ISSUE PR236] Cisco ASA: Add enable_dsmo header option

[LEGACY ISSUE 271] Paloalto generator should provide more informational/warning logs

Publish release cycle and versioning semantics content

[LEGACY ISSUE 254] port group optimization for same src/dst rules

Migrate from setup.py to pyproject.toml

Seems this is the newer way to define project dependencies and metadata.
https://peps.python.org/pep-0621/
https://peps.python.org/pep-0660/
https://stackoverflow.com/questions/62983756/what-is-pyproject-toml-file-for

[LEGACY ISSUE 295] Support for IOSXR IPv6 Object Group ACLs

Experiment with fstrings and templating for faster policy rendering

fstrings are new in python 3.0 and offer a lot of improvements to string manipulation. There are also templating frameworks that offer some advanced functionality. A lot of what we are doing could be assisted by templating. We should profile the current generators and compare that to implementations using those newer features. Comparing usability/readability to performance gains/losses will indicate if this is a path to go down for all generators.

Investigate IPAM exporting functionality

We want to make it easy for people to import IPs and other information into the address book. Investigating IPAM solutions and their export functionality will let us know what is available. JSON, CSV, YAML, etc

[LEGACY ISSUE 326] Add support in ArubaOS-Switch and AOS-CX-Switch

[LEGACY ISSUE 174] established not added when using object-groups on cisco or ciscoxr

Test Harness 2

[LEGACY ISSUE 330] Add a generator for NSX-T

[LEGACY ISSUE 170] Platform Cisco wrong numeric protocol rendering

Docs for generator developer internals

Developers creating new generators will use a few internal interfaces that are not intended for end users. The goal here is to create some light documentation of these interfaces for the audience of generator developers.

Suggested interfaces include:

policy.Policy
policy.Term
aclgenerator.ACLGenerator
aclgenerator.Term
nacaddr.IP

[LEGACY ISSUE 327] Add support in HP Advanced ACL

Explore optimizers for policy

Will add more soon but this is to cover our talks about ways to optimize policy. Policy can be optimized for # of rules, TCAM space, etc.

[LEGACY ISSUE 322] Juniper ethernet-switching for EX or QFX

[LEGACY ISSUE 292] Support for Juniper Wildcard Zones

@jtwb Capirca does not want to change this

We'd prefer to not modify the parser to handle * as a legal character.

Their solution is to add a special string to signify the * character being used as a wildcard for juniper srx zone names. I was not even aware of this feature myself.

[LEGACY ISSUE 189] Capirca should support UDP / TCP / ICMP fragments in Cisco IOS

[LEGACY ISSUE 304] Installer doesn't put capirca command in ~/.local/bin

Believe this should be fine since we are using poetry. Should comb the documentation for where this may be mentioned though.

Add Getting Started content in the README

[LEGACY ISSUE PR235] Cisco: Add ports to PortMap class: rtsp, sip

Evaluate STATELESS_REPLY

stateless_reply is a field on the Term data model. Its addition was motivated by the desire to have stateful firewalls ignore terms that contain the reverse rules needed by stateless firewalls. ¹ It allows a single policy to be shared by both stateful and stateless firewalls.

The question of what to do with stateless_reply arises from some gaps in the existing implementation:

stateless_reply cannot actually be set in Policy files. The file parser has no support for this field. Similarly it cannot be set by Python users creating a Policy data model from a string representation of a Policy file.
stateless_reply cannot be set by Python users constructing a Policy data model through the AddObject / AddFilter methods. Users can set fields on Policy data models directly but in doing so bypass code in the model that performs validation, sanity checking, address collapsing, and address book assembly.
stateless_reply is implemented as a boolean value but Policy files have no canonical value expression that represents a boolean.
It is implemented for each firewall at the discretion of each firewall generator. I haven't done a full pass over the code, but it feels like there could be one or more stateful firewalls that don't support this field.

A couple suggestions have been made from early discussion. The field is only partially user-facing. Dropping the option completely would certainly break Google's use-case. Rolling the option out as-is to all users by adding support in Policy files is possible. In any case this is a good opportunity for a thoughtful proposal on how reverse routes might best be represented in Aerleon.

To start the conversation I would ask whether return path rules should be expressed as Terms in the conventional sense or whether they make more sense in the context of another Term. They cannot stand alone and wouldn't need to use the full range of options available to a normal rule. I wonder whether it might be possible to invert the procedure and produce them automatically from a Term when some field is set.

For example, maybe there is some key value like 'stateless_reply: auto' which you can set on a Term to have Aerleon automatically generate return. Other values on the right hand side could potentially select from different modes of return path generation. In YAML we can even have sub-flags should the user need to provide configuration options.

I would also suggest that the knowledge of whether a firewall is stateless / stateful should be known to Aerleon's core. If it were we could use an approach similar to what we are doing with address books where the core system pre-processes the Policy before handing it off to a Generator. In this case we would generate or eliminate return path rules before the Generator sees them (depending on which approach we choose, whether return routes should be generated from other Terms or if we continue to have one Term per return route but use the 'stateless_reply' field to flag them).

https://github.com/google/capirca/commit/525ec58cab3b2039d8755b8b8bf825beda2a8755 ↩