Multicast Python Module

Mcast Logo

Introduction

The multicast package is a Python library that simplifies sending and receiving multicast network messages. It provides classes and tools for implementing multicast communication in Python applications, making it straightforward to work with multicast sockets.

Features

  • Easy Multicast Communication: Send and receive messages over multicast networks with simple Python interfaces.

  • Command-Line Tools: Includes command-line utilities for quick multicast prototyping.

  • Cross-Python Compatibility: Designed to work with multiple Python versions.

  • Support for UDP: Works with UDP via IPv4 multicast addresses.

Status

Master (Development)

CircleCI Minimal Acceptance Tests CI Appveyor Documentation Status Code Coverage Coverage Status Bandit Style Status CodeFactor Size Scc Count Badge Scc Count Badge Scc Count Badge Scc Count Badge Commits-since

Stable (Mainstream)

Stable CI Stable Appveyor Stable Code Coverage CodeQL

Installation

Install the package using pip:

pip install multicast
Alternative Methods

There are many ways to install the module besides using pip, but unless you have a specific need, using pip is recommended for most users.

PEP-668 and externally-managed-environment installs

Users using Homebrew may require additional flags to use pip:

python3 -m pip install --use-pep517 --break-system-packages --user 'multicast>=2.0.8'

Install from Source

Source builds require development tools including (but not limited to): git, and make

Stable builds (Release Candidates)

# clone the multicast source repository
git clone "https://github.com/reactive-firewall-org/multicast.git" multicast
cd multicast
# switch to the stable branch
git checkout stable
# build the multicast module
make -f Makefile build
# install the build
make user-install
# Optionally check the install
python3 -m multicast --version

Developer builds

[!WARNING] Development Builds (e.g., Cutting-Edge) are not intended as full-fledged releases, however updates to the Development Builds are more frequent than releases.

# clone the multicast source repository
git clone "https://github.com/reactive-firewall-org/multicast.git" multicast
cd multicast
# switch to the default "master" branch
git checkout master
# build the multicast module
make -f Makefile build
# install the build
make user-install
# Optionally check the install
python3 -m multicast --version

Legacy egg style install

[!WARNING] Egg Style Builds (Deprecated) are not supported since version 2.1 :shrug:

pip install -e "git+https://github.com/reactive-firewall-org/multicast.git#egg=multicast"

Getting Started

Below are basic examples to help you start using the multicast package.

Sending Multicast Messages

from multicast import send

# Create a multicast sender
sender = send.McastSAY()

# Send a message
sender(group='224.0.0.1', port=59259, ttl=1, data='Hello, Multicast!')

Receiving Multicast Messages

from multicast import recv

# Create a multicast receiver
receiver = recv.McastRECV()

# Receive a message
message = receiver(group='224.0.0.1', port=59259, ttl=1)
print('Received:', message)

Listening for Multicast Messages

  • Depending on what needs to be done with received data, each case will be a bit different.

# setup console logging as example
import logging
multicast_logging_sink = logging.getLogger()
handler = logging.StreamHandler()  # example trivial log handler
multicast_logging_sink.setLevel(logging.INFO)  # increase default logging from multicast module
multicast_logging_sink.addHandler(handler)

# import multicast
from multicast import hear

# Create a multicast listener
listener = hear.McastHEAR()

# Listen for messages indefinitely (use control+C to stop)
listener(group='224.0.0.1', port=59259, ttl=1)

[!TIP] While this trivial example just scratches the surface, the multicast.hear module provides an extendable implementation of the default handler for customizing the listening behavior well beyond just logging.

Command-Line Usage

The multicast package provides command-line tools for multicast communication prototyping.

  • Read the Usage for details.

FAQ

  • Read the FAQ for common answers.

Default Settings

  • Multicast Group Address: 224.0.0.1 (link-local multicast as per RFC 5771)

  • Default Port: 59259 (within the dynamic/private port range defined by RFC 6335)

  • Time-to-Live (TTL): 1 (as recommended by RFC 1112 Section 6.1 ; messages do not leave the local network)

Security Considerations

In the realm of network communication, security is paramount. When using multicast communication, be vigilant about potential vulnerabilities:

  • Data Sanitization: Always sanitize incoming data to prevent injection attacks (CWE-20, CWE-74).

  • Network Scope: Be mindful of the TTL settings to limit message propagation to the intended network segment. Inappropriate TTL values might expose your multicast traffic beyond the local network, potentially leading to information disclosure (CWE-200).

  • Validation and Error Handling: Implement robust validation and error handling to prevent misuse or disruption of multicast services. (CWE-351).

As Bruce Schneier aptly puts it, “Security is a process, not a product.” Always be proactive in assessing and mitigating risks in your implementations and use of multicast.

OpenSSF Best Practices

Documentation

For more detailed documentation and advanced usage, please refer to the documentation.

Contributing

Contributions are welcome! Please read the contributing guidelines for more information.

Next steps

Next steps and bug fixes are tracked by the Multicast Project Board.

License