nopasaran 0.2.118
NoPASARAN is an advanced network tool designed to detect, fingerprint, and locate network middleboxes in a unified framework.
Requires Python: >=3.8

# NoPASARAN
        
        [![Docker](https://github.com/BenIlies/NoPASARAN/actions/workflows/docker-image.yml/badge.svg)](https://github.com/BenIlies/NoPASARAN/actions/workflows/docker-image.yml)
        [![Documentation Status](https://readthedocs.org/projects/nopasaran/badge/?version=latest)](https://nopasaran.readthedocs.io/en/latest/?badge=latest)
        [![Maintainability](https://api.codeclimate.com/v1/badges/68f1d2f9ef6af3f65864/maintainability)](https://codeclimate.com/github/BenIlies/NoPASARAN/maintainability)
        [![Test Coverage](https://api.codeclimate.com/v1/badges/68f1d2f9ef6af3f65864/test_coverage)](https://codeclimate.com/github/BenIlies/NoPASARAN/test_coverage)
        [![PyPI version](https://badge.fury.io/py/nopasaran.svg)](https://badge.fury.io/py/nopasaran)
        [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://app.gitter.im/#/room/#nopasaran:gitter.im)
        [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html)
        
        NoPASARAN is a distributed network tool designed to detect, fingerprint, and locate network middleboxes in a unified framework. Written in Python, NoPASARAN uses finite state machines to describe test cases.
        
        ## Table of Contents
        
        - [Framework Architecture](#-important-nopasaran-is-a-multi-repository-framework)
        - [Features](#features)
        - [Requirements](#requirements)
        - [Installation](#installation)
          - [Installing from Source Code](#installing-from-source-code)
          - [Installing as a Python Package](#installing-as-a-python-package)
        - [Usage](#usage)
          - [Additional Options](#additional-options)
        - [Docker](#docker)
        - [Documentation](#documentation)
        - [Gitter](#gitter)
        - [Acknowledgements](#acknowledgements)
        - [License](#license)
        
        ## 🚨 Important: NoPASARAN Is a Multi-Repository Framework
        
        This repository is **one component** of the broader **NoPASARAN distributed testing framework**.
        
        The full system is composed of **multiple tightly-coupled repositories**, each responsible for a critical part of test definition, orchestration, execution, and coordination. **Most users and contributors will need to reference these projects together.**
        
        👉 **Start here:**  
        📁 **[`framework-projects/`](framework-projects)** — canonical index of all NoPASARAN framework components.
        
        ### Framework Components at a Glance
        
        | Component          | Purpose                                                  |
        | ------------------ | -------------------------------------------------------- |
        | 🧠 **Tests-Trees** | Decision trees defining conditional test execution logic |
        | 🧪 **Tests**       | Reusable, reviewed test definitions executed by workers  |
        | ⚙️ **Endpoint**    | Runtime node acting as master or worker                  |
        | 🌐 **Coordinator** | Control plane, certificate authority, and user interface |
        
        ➡️ **If you are looking for tests, orchestration logic, or distributed execution details, you will not find them all in this repository alone.**  
        ➡️ Always refer to **`framework-projects/README.md`** for the complete picture.
        
        ## Features
        
        - Detection, fingerprinting, and location of network middleboxes.
        - Utilization of finite state machines for test case description.
        - Flexible roles for network nodes and proxies.
        - Support for JSON-based test files for state machine configurations.
        
        ## Requirements
        
        - Python 3.8 or later
        - Scapy
        - Twisted
        
        ## Installation
        
        You can install and use NoPASARAN either by cloning the source code from GitHub or by installing it as a Python package.
        
        ### Installing from Source Code
        
        1. Clone the NoPASARAN repository:
        
           ```bash
           git clone https://github.com/BenIlies/NoPASARAN.git
           ```
        
        2. Navigate into the NoPASARAN directory:
        
           ```bash
           cd NoPASARAN
           ```
        
        3. Install the necessary Python packages:
        
           ```bash
           pip install -r requirements.txt
           ```
        
        ### Installing as a Python Package
        
        - Alternatively, you can install NoPASARAN as a Python package using pip:
        
          ```bash
          pip install nopasaran
          ```
        
        ## Usage
        
        To run NoPASARAN, you need to specify a JSON file for the state machine indicating the test the application has to run.
        
        - From the source code:
        
          ```bash
          python main.py --test=<path-to-json-test-file>
          ```
        
        - As a package:
        
          ```bash
          nopasaran --test=<path-to-json-test-file>
          ```
        
        ### Additional Options
        
        You can further customize the behavior of NoPASARAN with the following options:
        
        - `--verbose` or `-v`: Enable verbose output.
        - `--log=<path-to-log-file>` or `-l=<path-to-log-file>`: Specify the path to the log file (default is "conf.log").
        - `--log-level=<log-level>` or `-ll=<log-level>`: Specify the log level for output. Valid choices are "debug", "info", "warning", and "error".
        
        Replace `<path-to-json-test-file>` with the path to your actual JSON test file.
        
        For any further assistance, use the `--help` argument with any command for additional information.
        
        ## Docker
        
        You can also use Docker to download and run a NoPASARAN node.
        
        1. Pull the latest node image:
        
           ```bash
           docker pull benilies/nopasaran:latest
           ```
        
        2. Run the node container:
        
           ```bash
           docker run -it benilies/nopasaran:latest
           ```
        
        The node container is now ready for use.
        
        ## Documentation
        
        For more detailed guides and information about NoPASARAN, please visit our [documentation](https://nopasaran.readthedocs.io).
        
        ## Gitter
        
        Join the discussion on [Gitter](https://app.gitter.im/#/room/#nopasaran:gitter.im).
        
        ## Acknowledgements
        
        This software is based on the research paper titled "NoPASARAN: a Novel Platform to Analyse Semi Active elements in Routes Across the Network" by Ilies Benhabbour and Marc Dacier, published in 2022.
        
        ```bibtex
        @article{benhabbour2022nopasaran,
        title={NoPASARAN: a Novel Platform to Analyse Semi Active elements in Routes Across the Network},
        author={Benhabbour, Ilies and Dacier, Marc},
        year={2022},
        publisher={Index Copernicus}
        }
        ```
        
        ## License
        
        NoPASARAN is released under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).