Trigger: a Python network automation toolkit built around Twisted and device metadata

What Trigger does and where it came from

Trigger is a network automation toolkit written in Python, designed for interfacing with network devices and for managing network configuration and security policy. The stated purpose is to increase the speed and efficiency of managing large-scale networks while reducing the risk of human error.

The origin explains the design. It was started by the AOL Network Security team in 2006 and was originally designed for security policy management on firewalls, routers and switches, and it has since been expanded into a full network automation toolkit. The project explains the reason for its existence plainly: with a high number of network devices on the AOL network, the application is invaluable to performance and reliability.

That origin is visible in what the tool emphasises. The access list and firewall policy parser is a first-class feature rather than an afterthought, because a security team that managed ACLs across a large estate needed to test whether access is permitted and to convert ACLs from one format to another. The metadata interface is the other one, described as powerful, for performing complex queries to group and associate network devices by name, manufacturer, type, location and more. A tool that pushes a config change to a thousand devices needs a way to say which thousand.

The supported platforms are Cisco IOS, NX-OS and ASA software, Juniper Junos and ScreenOS, the Force10 router and switch platforms running FTOS, and the Arista Networks 7000-family switches, with the documentation holding the full list. The project is MIT-style in the packaging metadata, though the licence handling needs attention later in this article.

The last push was on 2026-10-01, the same day as the v2.3.3 release, and the recent tags are v2.3.1 from 2026-06-03, v2.3.2 from 2026-09-30 and v2.3.3 from 2026-10-01, so the release cadence at the moment is tight.

The Python version ceiling, and how to install it

The Python support window is narrow and it is the first thing to check.

Trigger v2.0.0 and later require Python 3.10 or 3.11. Python 3.12 and later is not yet supported, and the reason given is SimpleParse C extension compatibility issues. That is a specific and fairly common kind of constraint, a Python library with a C extension that has not been ported to a newer ABI, and it means the project is currently pinned to versions that are themselves approaching end of life. Python 2.7 support ended with v1.6.0, which was the last Python 2.7 compatible release.

The install itself is a normal pip install with three documented variants:

# Install the latest version
pip install trigger

# Install in development mode
pip install -e ".[dev]"

# Using uv (faster)
uv pip install trigger

For anyone still on Python 2.7, the documented fallback is the old release:

pip install trigger==1.6.0

There is a development setup path too, which uses prek as a fast pre-commit framework:

# Install prek (fast pre-commit framework)
uv tool install prek  # or: pip install prek

# Enable hooks in your clone
prek install

# Hooks will now run automatically on git commit

The hook step matters more than it looks for a project with this many contributors, because a toolkit that parses device configuration formats has a lot of formatting-sensitive code, and hooks that run on every commit catch it before review rather than after.

The dependency list in the project metadata is instructive about the architecture. Twisted with TLS support is the core, with crochet for running the reactor in a thread, cryptography and bcrypt for credential handling, pyasn1 and service-identity for certificate and identity handling, SimpleParse for the configuration grammar, textfsm for parsing device output, netaddr for address handling, pytz for timezones, redis, peewee for the metadata database, pyparsing and PTable. The framework classifier lists Twisted explicitly.

Upgrading from v1.6.0 is a documented migration rather than a version bump, with the instructions in the migration guide in the official documentation.

The Twisted event model and the job runner

The architectural core is Twisted, and the feature list describes what that buys.

Trigger supports SSH, Telnet and Juniper's Junoscript XML API for transport, which covers both the modern SSH-based vendors and the older Telnet-only estate that a network with a 2006 origin still has. It can get an interactive shell or execute commands asynchronously, and the description calls out advanced event-driven functionality to manage any number of jobs in parallel and handle output or errors as they return.

That last phrase is the design decision, and it is different from the Ansible model. In Ansible, a play is a run that produces a report at the end. In Trigger, jobs are concurrent and their results arrive as events, so a failure on one device is handled while the rest keep running. For a fleet of a thousand devices that is the difference between a tool that tells you about the first failure and a tool that tells you about all of them.

The asynchronous interactive shell is the other half, and it is what makes a fast local session possible. Rather than waiting on a serial connection, you get a prompt that can have several devices attached at once, which is how you compare two boxes during an incident without writing a script.

The Twisted model also explains some of the dependencies. crochet exists to run the Twisted reactor inside a thread so the library can be used from an ordinary synchronous application, pyasn1 and service-identity handle the certificate and identity checks that SSH and TLS need, and cryptography plus bcrypt sit behind the encrypted credential storage.

The repository layout shows the testing and examples side of the project. There is a `tests/` directory, a `benchmarks/` directory, an `examples/` directory with a commando reactorless example, a normalizer example, an sshendpoint_updatecmdb example that updates a CMDB from an SSH endpoint, and an xmlrpc_server example, and a `twisted/` directory at the top level. A `SANDIA.md` file at the root is a name worth knowing about in a network security tool, and the `bin/` directory holds the command line entry points that the packaging metadata lists as console scripts.

The command line tools, and what the ACL parser does

The packaging metadata lists the console scripts, and the names describe the workflow better than any documentation summary.

There is `acl` and `acl_script`, plus `aclconv` for converting access lists between formats, `check_access` for testing whether access is permitted, `find_access` for the inverse question of what a rule does, `check_syntax` for validating a rule without applying it, and `load_acl` for loading one into a device. That is a complete ACL workbench, and the pair of `check_access` and `find_access` is the one that shows the intent: one asks whether a connection is allowed, the other asks what a given address or port combination would reach.

Then there are the device tools. `netdev` is the main network device command, `run_cmds` runs commands, `fe` and `gong` are the interactive helpers, `gnng` is the shell for a device, `load_config` loads configuration, and `optimizer` optimises ACL rules.

The ACL workbench is what separates Trigger from a general configuration management tool, and it is the part of the 2006 design that has aged best. Being able to load a firewall policy, ask what it actually permits, and convert it to another vendor's syntax is the kind of question a security team asks during a migration, and answering it by hand is exactly the kind of work that introduces errors.

The metadata side of the tool is the other half of the picture, and the repository shows how it is populated. You can import your metadata from an existing RANCID installation or from a CSV file to get up and running quickly, and there is an example script named sshendpoint_updatecmdb.py, which suggests the pattern of pulling device details from a source of truth and writing them back into a CMDB. The metadata is stored through peewee, and the `configs/` directory at the top level holds the configuration layer.

Beyond the ACL work, the feature list includes detailed support for timezones and maintenance windows, which matters for change management, and a suite of tools for simplifying many common tasks.

Where Trigger is the wrong choice

The first limit is the Python ceiling. SimpleParse compatibility blocks Python 3.12 and later, so you are pinned to 3.10 or 3.11. On an organisation standardising on a recent Python, that means a separate virtual environment, a container base image that still supports those versions, and a dependency that will eventually need porting before the project can move. This is the kind of constraint that is cheap to accept today and expensive to unwind later, and it is worth raising with the maintainers if you depend on it.

The second limit is the model of deployment. Trigger is a library and a command line toolkit, not a service. There is no web interface, no job history database, no role-based access model and no approval workflow built in. The metadata layer is a database you populate yourself. For a team that wants a change management portal with audit trails, Trigger is the engine you would build that on, not the product.

The third is that it is a large, opinionated codebase with a long history. There are 20 years of accumulated behaviour, a custom parser for device configuration, a custom metadata schema and a set of command line tools that each have their own conventions. That depth is exactly what you want at scale and exactly what makes onboarding slow.

The fourth is the vendor coverage. The listed platforms are Cisco, Juniper, Force10 and Arista, and the documentation holds the full list, but the depth of support per platform is uneven. Force10 running FTOS is a platform that barely exists as a product any more, and its presence tells you the toolkit's centre of gravity is a decade old.

Compare that with Ansible's network modules. Ansible is a much larger ecosystem, it has modules for far more vendors, it is supported on current Python, and it has an execution model everyone already understands, and in exchange it does not give you the ACL parser, the Twisted event model or the device metadata query language. The difference in approach is that Ansible is a general-purpose orchestration tool you extend with modules, while Trigger is a domain-specific toolkit whose depth is inside the domain. For firewall policy work, Trigger goes further. For everything else, Ansible is the shorter road.

Licence, maintenance and what to check before you install it

The licence needs a specific note, because two sources disagree. The platform classifies the repository as having a custom licence that it cannot classify, and points you at the LICENSE file. The packaging metadata in the project file states `license = "BSD-3-Clause"` and names Jathan McCollum as the author. The repository top level does contain a LICENSE.md file, so there is a licence text in the tree. If you are deploying this inside a company, read LICENSE.md and confirm the terms with whoever handles licensing for you rather than relying on either label.

The maintenance picture is good. The repository is not archived, the last push was on 2026-10-01, and the recent releases are dense, with v2.3.1 on 2026-06-03 followed by v2.3.2 and v2.3.3 on consecutive days in late September and October. The project classifier calls it mature, the CI workflow badge is present, and the release process is automated through python-semantic-release in the dev dependencies, which is why two patch versions landed a day apart.

The documentation lives on Read the Docs at trigger.readthedocs.org, and the project points there rather than duplicating instructions, with a separate migration guide for the v1.6.0 upgrade. The repository has a CHANGELOG and a CHANGELOG.md, a CONTRIBUTING-adjacent CLAUDE.md for development documentation, a `docs/` directory, a `tools/` directory, a `uv.lock` for reproducible installs, and a TODO.md.

What to check before you install is a short list. Confirm your Python version is 3.10 or 3.11, because the alternative is an environment you will have to maintain separately. Then decide how metadata enters the system, since Trigger's power comes from its metadata layer and both documented routes, RANCID import or CSV, are one-time loads that you will have to keep fresh.

Then look at the credential storage before you wire it into anything. The feature list promises encrypted storage of login credentials so you can interact without being prompted, which is the right behaviour for a fleet, and it means there is a key to manage and a store to protect, and neither is described in the project description.

Finally, if you are upgrading from v1.6.0, work through the migration guide rather than assuming the CLI is the same, because a version 2.0 rewrite of the configuration layer and the device interaction model is not a small change even where the command names are similar.

Editorial conclusion

Trigger fits a network team that already has device metadata and wants to push policy changes across hundreds of devices with a job model that reports errors as they come back, and it fits anyone whose firewall rules need to be analysed and converted rather than merely applied. It does not fit a team on Python 3.12 or later, because the SimpleParse C extension blocks it, and it does not fit a small network where Ansible's simplicity beats a toolkit you have to configure with metadata and a CMDB. Before you adopt it, read the migration guide if you are coming from v1.6.0, confirm you can run Python 3.10 or 3.11, and check the LICENSE.md file, since the project metadata states BSD-3-Clause while the repository also carries a LICENSE.md file of its own.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. trigger/trigger on GitHub