{"id":15117280,"url":"https://github.com/ElNiak/PANTHER","last_synced_at":"2025-09-27T23:30:41.624Z","repository":{"id":38343985,"uuid":"426255598","full_name":"ElNiak/PANTHER","owner":"ElNiak","description":"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.","archived":false,"fork":false,"pushed_at":"2025-01-06T16:39:14.000Z","size":1287777,"stargazers_count":32,"open_issues_count":7,"forks_count":3,"subscribers_count":2,"default_branch":"production","last_synced_at":"2025-01-14T10:10:45.486Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://elniak.github.io/PANTHER/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElNiak.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-09T14:13:45.000Z","updated_at":"2024-12-29T10:29:08.000Z","dependencies_parsed_at":"2023-10-20T16:50:32.055Z","dependency_job_id":"b1f8ac00-85d7-412b-b242-63531946e1b2","html_url":"https://github.com/ElNiak/PANTHER","commit_stats":null,"previous_names":["elniak/pfv","elniak/panther"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElNiak%2FPANTHER","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElNiak%2FPANTHER/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElNiak%2FPANTHER/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElNiak%2FPANTHER/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElNiak","download_url":"https://codeload.github.com/ElNiak/PANTHER/tar.gz/refs/heads/production","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234470271,"owners_count":18838628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-09-26T01:45:53.374Z","updated_at":"2025-09-27T23:30:41.605Z","avatar_url":"https://github.com/ElNiak.png","language":"C","funding_links":[],"categories":["Using AI for Pentesting","Software Verification"],"sub_categories":["Prevention","Tools"],"readme":"# PANTHER — Protocol Analysis and Testing Harness for Extensible Research\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10819552.svg)](https://doi.org/10.5281/zenodo.10819552)\n[![mkdocs](https://github.com/ElNiak/PANTHER/actions/workflows/pr-generate-docs.yaml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/pr-generate-docs.yaml)\n[![pages-build-deployment](https://github.com/ElNiak/PANTHER/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/pages/pages-build-deployment)\n[![dependabot](https://github.com/ElNiak/PANTHER/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/dependabot/dependabot-updates)\n[![Python application](https://github.com/ElNiak/PANTHER/actions/workflows/python-app.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/python-app.yml)\n[![Python package](https://github.com/ElNiak/PANTHER/actions/workflows/python-package.yml/badge.svg?branch=production)](https://github.com/ElNiak/PANTHER/actions/workflows/python-package.yml)\n[![pypi](https://github.com/ElNiak/PANTHER/actions/workflows/python-publish.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/python-publish.yml)\n[![pytest](https://github.com/ElNiak/PANTHER/actions/workflows/unittests_codecov.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/unittests_codecov.yml)\n[![Greetings](https://github.com/ElNiak/PANTHER/actions/workflows/greetings.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/greetings.yml)\n[![pre-commit](https://github.com/ElNiak/PANTHER/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/pre-commit.yml)\n[![CodeQL](https://github.com/ElNiak/PANTHER/actions/workflows/codeql.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/codeql.yml)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/c8043e5320934d49a688e173db5a331d)](https://app.codacy.com/gh/ElNiak/PANTHER/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Qodana](https://github.com/ElNiak/PANTHER/actions/workflows/qodana_code_quality.yml/badge.svg)](https://github.com/ElNiak/PANTHER/actions/workflows/qodana_code_quality.yml)\n\n![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54) ![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white) ![C++](https://img.shields.io/badge/c++-%2300599C.svg?style=for-the-badge\u0026logo=c%2B%2B\u0026logoColor=white) ![Debian](https://img.shields.io/badge/Debian-D70A53?style=for-the-badge\u0026logo=debian\u0026logoColor=white)\n\nPANTHER 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.\n\n!!! info \"What PANTHER Solves\"\n    - **Protocol Validation**: Test QUIC or custom protocol implementations under failure, jitter, or adverse timing\n    - **Performance Profiling**: Analyze CPU, heap, and syscall characteristics across different builds or OS kernels\n    - **Formal Verification**: Run conformance checks (Ivy) in deterministic network simulation (Shadow)\n\n**Core characteristics:**\n\n▸ **Reproducible:** every experiment is defined in a single YAML file and executed in an isolated container environment.\n\n▸ **Extensible:** a plugin system adds new protocols, services, profilers, or network back‑ends with minimal boilerplate.\n\n▸ **Multi‑audience:** useful to academic researchers, industrial developers, security analysts, SRE teams, and educators.esting Harness for Extensible Research\n\n---\n\n## 🔄 Quick Workflow Overview\n\nPANTHER experiments follow a **4-phase execution model**:\n\n### Phase 1: Initialization\n\n* Load configurations and validate experiment setup\n* Initialize plugin system and service managers\n* Create test case instances\n\n### Phase 2: Plugin Loading \u0026 Service Setup\n\n* Discover and load protocol/implementation plugins\n* Create service managers for each IUT (Implementation Under Test)\n* Generate deployment and execution commands\n\n### Phase 3: Environment Deployment\n\n* Setup network environment (Docker Compose, localhost, or Shadow NS)\n* Build container images for protocol implementations\n* Deploy services with proper networking and monitoring\n\n### Phase 4: Test Execution\n\n* Start services and execute test scenarios\n* Monitor execution with automatic packet capture\n* Collect results, logs, and performance metrics\n* Teardown environment and generate reports\n\n**Key Features:**\n\n* **Reproducible**: Every experiment defined in single YAML configuration\n* **Containerized**: Isolated execution environments with Docker\n* **Event-driven**: Real-time monitoring and coordination\n* **Extensible**: Plugin architecture for new protocols and environments\n\nFor detailed workflow documentation, see [workflow.md](workflow.md).\n\n---\n\n## System Requirements\n\n| Component | Minimum | Notes |\n|-----------|---------|-------|\n| Python    | 3.10    | Use `venv` for isolation for main functionality. |\n| Docker    | 27.x    | Required for all orchestration modes. |\n\n`pyproject.toml` is the source of truth for Python dependencies.\n`requirements.txt` is a frozen snapshot—**do not edit**.\n\n**Note**: We propose to install [`slim`](https://github.com/slimtoolkit/slim) in our builder, fasten container size.\n\n---\n\n## 📑 Table of Contents\n\n### Getting Started\n\n1. [Installation Guide](INSTALL.md)\n2. [Quick Start](QUICK_START.md)\n3. [Configuration](panther/config/README.md)\n4. [Workflows](workflow.md)\n5. [Core](panther/core/README.md)\n6. [Web Application Workflows](panther/webapp/README.md)\n\n### System Features\n\n7. [Fast-Fail System](FAST_FAIL_SYSTEM.md) - Intelligent experiment termination and error handling\n8. [Experiment Reporting](EXPERIMENT_REPORTING.md) - Automatic generation of experiment reports and status summaries\n9. [Configuration Management](panther/config/README.md) - Advanced configuration validation, auto-fixing, and protocol-aware port management\n\n### Plugins\n\nPANTHER'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.\n\n**Core Plugin Categories:**\n\n10. [Overview](panther/plugins/README.md) - Architecture and design patterns\n11. [Inventory](panther/plugins/plugins_inventory.md) - Complete plugin catalog\n12. **Environment Plugins** - Network simulation and execution environments\n   * [Overview](panther/plugins/environments/README.md) - Environment plugin architecture\n   * [Network Environment](panther/plugins/environments/network_environment/README.md) - Docker Compose, localhost, Shadow NS\n   * [Execution Environment](panther/plugins/environments/execution_environment/README.md) - Performance profiling and analysis\n13. **Protocol Plugins** - Protocol definitions and behavioral specifications\n    * [Overview](panther/plugins/protocols/README.md) - Protocol plugin patterns\n    * [Client-Server Protocols](panther/plugins/protocols/client_server/README.md) - QUIC, HTTP, TCP/UDP variants\n    * [Peer-to-Peer Protocols](panther/plugins/protocols/peer_to_peer/README.md) - BitTorrent, WebRTC protocols\n14. **Service Plugins** - Implementation testing and verification services\n    * [Overview](panther/plugins/services/README.md) - Service plugin architecture\n    * [Implementation Under Tests (IUTs)](panther/plugins/services/iut/README.md) - picoquic, aioquic, quiche, quinn\n    * [Testing Services](panther/plugins/services/testers/README.md) - Ivy formal verification, custom testers\n\n**Plugin System Features:**\n- **Automatic Discovery**: Decorator-based registration with metadata validation\n- **Dependency Management**: Semantic versioning and automatic dependency resolution\n- **Version Configurations**: Protocol version-specific configurations (RFC9000, draft-29, etc.)\n- **Event Integration**: Built-in event emission and coordination across plugin lifecycle\n- **Configuration Schema**: JSON Schema-based validation with auto-fixing capabilities\n- **Performance Optimization**: Class caching and lazy loading for improved startup time\n\n### Developer Guide\n\n15. [Contributing](CONTRIBUTING.md)\n16. **Plugin Development**\n    * [Overview](panther/plugins/development.md)\n    * **Environment Plugins**\n      * [Overview](panther/plugins/environments/development.md)\n      * [Network Environment](panther/plugins/environments/network_environment/development.md)\n      * [Execution Environment](panther/plugins/environments/execution_environment/development.md)\n    * [Protocol Plugins](panther/plugins/protocols/development.md)\n    * **Service Plugins**\n      * [Overview](panther/plugins/services/development.md)\n      * [Implementation Under Tests (IUTs)](panther/plugins/services/iut/development.md)\n      * [Testing Services](panther/plugins/services/testers/development.md)\n\n### Project Information\n\n17. [Changelog](CHANGELOG.md)\n18. [License](LICENSE.md)\n19. [Code Reference](https://elniak.github.io/PANTHER/panther/)\n\n\n## Documentation\n\nFor detailed information on using PANTHER, see the:\n\n* [elniak.github.io/PANTHER](elniak.github.io/PANTHER)\n\n## Contributing\n\nContributions are welcome! To get started:\n\n* Fork the repository.\n* Create a new branch for your feature or bug fix.\n* Submit a pull request with a clear description of your changes.\n\nFor more details, see the [Contribution Guide](CONTRIBUTING.md).\n\n## Contact\n\nFor support or inquiries, please contact:\n\n* ElNiak\n* Open an issue on the GitHub repository.\n\n---\n\n## :book: References\n\nFor further reading and context on the topics and methodologies used in this tool, refer to the following articles:\n\n* Crochet, C., Aoga, J., \u0026 Legay, A. (2024). Formally Discovering and Reproducing Network Protocols Vulnerabilities (NordSec24).\n\n```\n@techreport{crochet2024formally,\n  title={Formally Discovering and Reproducing Network Protocols Vulnerabilities},\n  author={Crochet, Christophe and Aoga, John and Legay, Axel},\n  year={2024}\n  url={https://dial.uclouvain.be/pr/boreal/object/boreal:292503}\n}\n```\n\n* 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. \u003chttps://doi.org/10.1007/978-3-031-62645-6_10\u003e\n\n```\n@inproceedings{rousseaux2024network,\n  title={Network Simulator-Centric Compositional Testing},\n  author={Rousseaux, Tom and Crochet, Christophe and Aoga, John and Legay, Axel},\n  booktitle={International Conference on Formal Techniques for Distributed Objects, Components, and Systems},\n  pages={177--196},\n  year={2024},\n  organization={Springer},\n  doi={https://doi.org/10.1007/978-3-031-62645-6_10}\n}\n```\n\n* Crochet, C., Rousseaux, T., Piraux, M., Sambon, J.-F., \u0026 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)\n\n```\n@inproceedings{crochet2021verifying,\n  title={Verifying QUIC implementations using Ivy},\n  author={Crochet, Christophe and Rousseaux, Tom and Piraux, Maxime and Sambon, Jean-Fran{\\c{c}}ois and Legay, Axel},\n  booktitle={Proceedings of the 2021 Workshop on Evolution, Performance and Interoperability of QUIC},\n  pages={35--41},\n  year={2021},\n  url={https://dl.acm.org/doi/abs/10.1145/3488660.3493803}\n}\n```\n\n* Crochet, C., \u0026 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.\n\n```\n@article{crochettowards,\n  title={Towards verification of QUIC and its extensions},\n  author={Crochet, Christophe and Sambon, Jean-Fran{\\c{c}}ois}\n  year={2021},\n  url={https://dial.uclouvain.be/downloader/downloader.php?pid=thesis%3A30559\u0026datastream=PDF_01\u0026cover=cover-mem}\n}\n```\n\nFor other useful resources, see the following:\n\n* McMillan, K. L., \u0026 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)\n\n* Taube, M., Losa, G., McMillan, K. L., Padon, O., Sagiv, M., Shoham, S., Wilcox, J. R., \u0026 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)\n\n* Padon, O., Hoenicke, J., McMillan, K. L., Podelski, A., Sagiv, M., \u0026 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)\n\n* Padon, O., McMillan, K. L., Panda, A., Sagiv, M., \u0026 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)\n\n* 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)\n\n* McMillan, K. L., \u0026 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)\n\n* [Ivy Documentation](https://microsoft.github.io/ivy/)\n\n* [Ivy GitHub Repository](https://github.com/microsoft/ivy)\n\n\u003cpicture\u003e\n  \u003csource\n    media=\"(prefers-color-scheme: dark)\"\n    srcset=\"\n      https://api.star-history.com/svg?repos=ElNiak/PANTHER\u0026type=Date\u0026theme=dark\n    \"\n  /\u003e\n  \u003csource\n    media=\"(prefers-color-scheme: light)\"\n    srcset=\"\n      https://api.star-history.com/svg?repos=ElNiak/PANTHER\u0026type=Date\n    \"\n  /\u003e\n  \u003cimg\n    alt=\"Star History Chart\"\n    src=\"https://api.star-history.com/svg?repos=ElNiak/PANTHER\u0026type=Date\"\n  /\u003e\n\u003c/picture\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FElNiak%2FPANTHER","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FElNiak%2FPANTHER","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FElNiak%2FPANTHER/lists"}