https://github.com/ElNiak/PANTHER
This tool presents a novel approach to bolstering network protocol verification by integrating the Shadow network simulator with the Ivy formal verification tool to check time properties. Furthermore, it extends Ivy’s capabilities with a dedicated time module, enabling the verification of complex quantitative-time properties.
https://github.com/ElNiak/PANTHER
cve cybersecurity docker docker-compose formal-methods formal-verification ivy network-analysis network-security network-simulator protocol protocol-tester quic reproducible-research test-automation testing testing-tools tests time-proof transport-layer-protocol
Last synced: 6 days ago
JSON representation
This tool presents a novel approach to bolstering network protocol verification by integrating the Shadow network simulator with the Ivy formal verification tool to check time properties. Furthermore, it extends Ivy’s capabilities with a dedicated time module, enabling the verification of complex quantitative-time properties.
- Host: GitHub
- URL: https://github.com/ElNiak/PANTHER
- Owner: ElNiak
- License: mit
- Created: 2021-11-09T14:13:45.000Z (almost 4 years ago)
- Default Branch: production
- Last Pushed: 2025-01-06T16:39:14.000Z (9 months ago)
- Last Synced: 2025-01-14T10:10:45.486Z (9 months ago)
- Topics: cve, cybersecurity, docker, docker-compose, formal-methods, formal-verification, ivy, network-analysis, network-security, network-simulator, protocol, protocol-tester, quic, reproducible-research, test-automation, testing, testing-tools, tests, time-proof, transport-layer-protocol
- Language: C
- Homepage: https://elniak.github.io/PANTHER/
- Size: 1.2 GB
- Stars: 32
- Watchers: 2
- Forks: 3
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-formal-verification - Panther - This tool presents a novel approach to bolstering network protocol verification by integrating the Shadow network simulator with the Ivy formal verification tool to check time properties. Furthermore, it extends Ivy's capabilities with a dedicated time module, enabling the verification of complex quantitative-time properties. (Software Verification / Tools)
- awesome-ai-cybersecurity - PANTHER - PANTHER combines advanced techniques in network protocol verification, integrating the Shadow network simulator with the Ivy formal verification tool. This framework allows for detailed examination of time properties in network protocols and identifies real-world implementation errors. It supports multiple protocols and can simulate advanced persistent threats (APTs) in network protocols. (Using AI for Pentesting / Prevention)
README
# PANTHER — Protocol Analysis and Testing Harness for Extensible Research
[](https://doi.org/10.5281/zenodo.10819552)
[](https://github.com/ElNiak/PANTHER/actions/workflows/pr-generate-docs.yaml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/pages/pages-build-deployment)
[](https://github.com/ElNiak/PANTHER/actions/workflows/dependabot/dependabot-updates)
[](https://github.com/ElNiak/PANTHER/actions/workflows/python-app.yml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/python-package.yml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/python-publish.yml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/unittests_codecov.yml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/greetings.yml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/pre-commit.yml)
[](https://github.com/ElNiak/PANTHER/actions/workflows/codeql.yml)
[](https://app.codacy.com/gh/ElNiak/PANTHER/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[](https://github.com/ElNiak/PANTHER/actions/workflows/qodana_code_quality.yml)
   
PANTHER is a **plugin‑based, research‑grade test harness** that lets you design, reproduce, and analyse complex **network‑protocol experiments** without hand‑rolling scripts or bespoke infrastructure.
!!! info "What PANTHER Solves"
- **Protocol Validation**: Test QUIC or custom protocol implementations under failure, jitter, or adverse timing
- **Performance Profiling**: Analyze CPU, heap, and syscall characteristics across different builds or OS kernels
- **Formal Verification**: Run conformance checks (Ivy) in deterministic network simulation (Shadow)
**Core characteristics:**
▸ **Reproducible:** every experiment is defined in a single YAML file and executed in an isolated container environment.
▸ **Extensible:** a plugin system adds new protocols, services, profilers, or network back‑ends with minimal boilerplate.
▸ **Multi‑audience:** useful to academic researchers, industrial developers, security analysts, SRE teams, and educators.esting Harness for Extensible Research
---
## 🔄 Quick Workflow Overview
PANTHER experiments follow a **4-phase execution model**:
### Phase 1: Initialization
* Load configurations and validate experiment setup
* Initialize plugin system and service managers
* Create test case instances
### Phase 2: Plugin Loading & Service Setup
* Discover and load protocol/implementation plugins
* Create service managers for each IUT (Implementation Under Test)
* Generate deployment and execution commands
### Phase 3: Environment Deployment
* Setup network environment (Docker Compose, localhost, or Shadow NS)
* Build container images for protocol implementations
* Deploy services with proper networking and monitoring
### Phase 4: Test Execution
* Start services and execute test scenarios
* Monitor execution with automatic packet capture
* Collect results, logs, and performance metrics
* Teardown environment and generate reports
**Key Features:**
* **Reproducible**: Every experiment defined in single YAML configuration
* **Containerized**: Isolated execution environments with Docker
* **Event-driven**: Real-time monitoring and coordination
* **Extensible**: Plugin architecture for new protocols and environments
For detailed workflow documentation, see [workflow.md](workflow.md).
---
## System Requirements
| Component | Minimum | Notes |
|-----------|---------|-------|
| Python | 3.10 | Use `venv` for isolation for main functionality. |
| Docker | 27.x | Required for all orchestration modes. |
`pyproject.toml` is the source of truth for Python dependencies.
`requirements.txt` is a frozen snapshot—**do not edit**.
**Note**: We propose to install [`slim`](https://github.com/slimtoolkit/slim) in our builder, fasten container size.
---
## 📑 Table of Contents
### Getting Started
1. [Installation Guide](INSTALL.md)
2. [Quick Start](QUICK_START.md)
3. [Configuration](panther/config/README.md)
4. [Workflows](workflow.md)
5. [Core](panther/core/README.md)
6. [Web Application Workflows](panther/webapp/README.md)
### System Features
7. [Fast-Fail System](FAST_FAIL_SYSTEM.md) - Intelligent experiment termination and error handling
8. [Experiment Reporting](EXPERIMENT_REPORTING.md) - Automatic generation of experiment reports and status summaries
9. [Configuration Management](panther/config/README.md) - Advanced configuration validation, auto-fixing, and protocol-aware port management
### Plugins
PANTHER's extensible plugin architecture enables seamless integration of new protocols, implementations, testing frameworks, and environments. The modern inheritance-based system provides 47.2% average code reduction while ensuring consistent behavior across all plugin types.
**Core Plugin Categories:**
10. [Overview](panther/plugins/README.md) - Architecture and design patterns
11. [Inventory](panther/plugins/plugins_inventory.md) - Complete plugin catalog
12. **Environment Plugins** - Network simulation and execution environments
* [Overview](panther/plugins/environments/README.md) - Environment plugin architecture
* [Network Environment](panther/plugins/environments/network_environment/README.md) - Docker Compose, localhost, Shadow NS
* [Execution Environment](panther/plugins/environments/execution_environment/README.md) - Performance profiling and analysis
13. **Protocol Plugins** - Protocol definitions and behavioral specifications
* [Overview](panther/plugins/protocols/README.md) - Protocol plugin patterns
* [Client-Server Protocols](panther/plugins/protocols/client_server/README.md) - QUIC, HTTP, TCP/UDP variants
* [Peer-to-Peer Protocols](panther/plugins/protocols/peer_to_peer/README.md) - BitTorrent, WebRTC protocols
14. **Service Plugins** - Implementation testing and verification services
* [Overview](panther/plugins/services/README.md) - Service plugin architecture
* [Implementation Under Tests (IUTs)](panther/plugins/services/iut/README.md) - picoquic, aioquic, quiche, quinn
* [Testing Services](panther/plugins/services/testers/README.md) - Ivy formal verification, custom testers
**Plugin System Features:**
- **Automatic Discovery**: Decorator-based registration with metadata validation
- **Dependency Management**: Semantic versioning and automatic dependency resolution
- **Version Configurations**: Protocol version-specific configurations (RFC9000, draft-29, etc.)
- **Event Integration**: Built-in event emission and coordination across plugin lifecycle
- **Configuration Schema**: JSON Schema-based validation with auto-fixing capabilities
- **Performance Optimization**: Class caching and lazy loading for improved startup time
### Developer Guide
15. [Contributing](CONTRIBUTING.md)
16. **Plugin Development**
* [Overview](panther/plugins/development.md)
* **Environment Plugins**
* [Overview](panther/plugins/environments/development.md)
* [Network Environment](panther/plugins/environments/network_environment/development.md)
* [Execution Environment](panther/plugins/environments/execution_environment/development.md)
* [Protocol Plugins](panther/plugins/protocols/development.md)
* **Service Plugins**
* [Overview](panther/plugins/services/development.md)
* [Implementation Under Tests (IUTs)](panther/plugins/services/iut/development.md)
* [Testing Services](panther/plugins/services/testers/development.md)
### Project Information
17. [Changelog](CHANGELOG.md)
18. [License](LICENSE.md)
19. [Code Reference](https://elniak.github.io/PANTHER/panther/)
## Documentation
For detailed information on using PANTHER, see the:
* [elniak.github.io/PANTHER](elniak.github.io/PANTHER)
## Contributing
Contributions are welcome! To get started:
* Fork the repository.
* Create a new branch for your feature or bug fix.
* Submit a pull request with a clear description of your changes.
For more details, see the [Contribution Guide](CONTRIBUTING.md).
## Contact
For support or inquiries, please contact:
* ElNiak
* Open an issue on the GitHub repository.
---
## :book: References
For further reading and context on the topics and methodologies used in this tool, refer to the following articles:
* Crochet, C., Aoga, J., & Legay, A. (2024). Formally Discovering and Reproducing Network Protocols Vulnerabilities (NordSec24).
```
@techreport{crochet2024formally,
title={Formally Discovering and Reproducing Network Protocols Vulnerabilities},
author={Crochet, Christophe and Aoga, John and Legay, Axel},
year={2024}
url={https://dial.uclouvain.be/pr/boreal/object/boreal:292503}
}
```
* Rousseaux, T., Crochet, C., Aoga, J., Legay, A. (2024). Network Simulator-Centric Compositional Testing. In: Castiglioni, V., Francalanza, A. (eds) Formal Techniques for Distributed Objects, Components, and Systems. FORTE 2024. Lecture Notes in Computer Science, vol 14678. Springer, Cham.
```
@inproceedings{rousseaux2024network,
title={Network Simulator-Centric Compositional Testing},
author={Rousseaux, Tom and Crochet, Christophe and Aoga, John and Legay, Axel},
booktitle={International Conference on Formal Techniques for Distributed Objects, Components, and Systems},
pages={177--196},
year={2024},
organization={Springer},
doi={https://doi.org/10.1007/978-3-031-62645-6_10}
}
```
* Crochet, C., Rousseaux, T., Piraux, M., Sambon, J.-F., & Legay, A. (2021). Verifying quic implementations using ivy. In *Proceedings of the 2021 Workshop on Evolution, Performance and Interoperability of QUIC*. [DOI](10.1145/3488660.3493803)
```
@inproceedings{crochet2021verifying,
title={Verifying QUIC implementations using Ivy},
author={Crochet, Christophe and Rousseaux, Tom and Piraux, Maxime and Sambon, Jean-Fran{\c{c}}ois and Legay, Axel},
booktitle={Proceedings of the 2021 Workshop on Evolution, Performance and Interoperability of QUIC},
pages={35--41},
year={2021},
url={https://dl.acm.org/doi/abs/10.1145/3488660.3493803}
}
```
* Crochet, C., & Sambon, J.-F. (2021). Towards verification of QUIC and its extensions. (Master's thesis, UCL - Ecole polytechnique de Louvain). Available at [UCLouvain](http://hdl.handle.net/2078.1/thesis:30559). Keywords: QUIC, Formal Verification, RFC, IETF, Specification, Ivy, Network.
```
@article{crochettowards,
title={Towards verification of QUIC and its extensions},
author={Crochet, Christophe and Sambon, Jean-Fran{\c{c}}ois}
year={2021},
url={https://dial.uclouvain.be/downloader/downloader.php?pid=thesis%3A30559&datastream=PDF_01&cover=cover-mem}
}
```
For other useful resources, see the following:
* McMillan, K. L., & Padon, O. (2018). Deductive Verification in Decidable Fragments with Ivy. In A. Podelski (Ed.), *Static Analysis - 25th International Symposium, SAS 2018, Freiburg, Germany, August 29-31, 2018, Proceedings* (pp. 43–55). Springer. [DOI](10.1007/978-3-319-99725-4_4) - [PDF](SAS18.pdf)
* Taube, M., Losa, G., McMillan, K. L., Padon, O., Sagiv, M., Shoham, S., Wilcox, J. R., & Woos, D. (2018). Modularity for decidability of deductive verification with applications to distributed systems. In *Proceedings of the 39th ACM SIGPLAN Conference on Programming Language Design and Implementation, PLDI 2018, Philadelphia, PA, USA, June 18-22, 2018* (pp. 662–677). ACM. [DOI](10.1145/3192366.3192414)
* Padon, O., Hoenicke, J., McMillan, K. L., Podelski, A., Sagiv, M., & Shoham, S. (2018). Temporal Prophecy for Proving Temporal Properties of Infinite-State Systems. In *2018 Formal Methods in Computer Aided Design, FMCAD 2018, Austin, TX, USA, October 30 - November 2, 2018* (pp. 1–11). IEEE. [DOI](10.23919/FMCAD.2018.8603008) - [PDF](FMCAD18.pdf)
* Padon, O., McMillan, K. L., Panda, A., Sagiv, M., & Shoham, S. (2016). Ivy: safety verification by interactive generalization. In *Proceedings of the 37th ACM SIGPLAN Conference on Programming Language Design and Implementation, PLDI 2016, Santa Barbara, CA, USA, June 13-17, 2016* (pp. 614–630). ACM. [DOI](10.1145/2908080.2908118)
* McMillan, K. L. (2016). Modular specification and verification of a cache-coherent interface. In *2016 Formal Methods in Computer-Aided Design, FMCAD 2016, Mountain View, CA, USA, October 3-6, 2016* (pp. 109–116). [DOI](10.1109/FMCAD.2016.7886668)
* McMillan, K. L., & Zuck, L. D. (2019). Formal specification and testing of QUIC. In *Proceedings of ACM Special Interest Group on Data Communication (SIGCOMM’19)*. ACM. Note: to appear. [PDF](SIGCOMM19.pdf)
* [Ivy Documentation](https://microsoft.github.io/ivy/)
* [Ivy GitHub Repository](https://github.com/microsoft/ivy)
