Metadata-Version: 2.1
Name: nopasaran
Version: 0.2.117
Summary: NoPASARAN is an advanced network tool designed to detect, fingerprint, and locate network middleboxes in a unified framework.
Home-page: https://github.com/BenIlies/NoPASARAN
Author: Ilies Benhabbour
Author-email: ilies.benhabbour@kaust.edu.sa
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: Twisted
Requires-Dist: pyOpenSSL
Requires-Dist: service-identity
Requires-Dist: psutil
Requires-Dist: scapy
Requires-Dist: h2==4.2.0
Requires-Dist: overload
Requires-Dist: dnspython
Requires-Dist: dnslib
Requires-Dist: aioquic

# 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).


