Security Advisories (4)

CVE-2026-57079 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl write files outside the download directory via path traversal in peer-supplied metadata. Net::BitTorrent validates file path components only on the .torrent-file ingest path. The peer and magnet metadata path (_on_metadata_received, reached from the BEP09 ut_metadata extension) passes attacker-supplied file names straight to Storage::add_file and Storage::_parse_file_tree, where Path::Tiny's child() does not collapse "..". A v2 file tree key, a v1 files[].path element, or a single-file name containing ".." segments therefore resolves outside the download directory. Because the peer also controls the piece hashes and the served bytes, content verification passes, so a malicious magnet or peer writes attacker-chosen content to an attacker-chosen path on the downloading host.

https://github.com/sanko/Net-BitTorrent.pm/security/advisories/GHSA-5wc6-r65f-62rr

CVE-2026-57080 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl allow remote memory exhaustion via an uncapped peer-wire message-length prefix. The peer-wire framing in _process_messages trusts the 4-byte length prefix sent by a connected peer with no upper bound, while receive_data appends every inbound byte to the input buffer. A peer announces a length prefix of up to about 4 GiB and then streams bytes; the decoder waits until the buffer holds the full message before processing it, so the buffer grows without limit. Peer connections are unauthenticated, so any peer in the swarm exhausts the downloading process's memory. The largest legitimate message is a 16 KiB piece block, so any announced length far above that is anomalous.

https://github.com/sanko/Net-BitTorrent.pm/security/advisories/GHSA-7jr6-2jf4-6qc4

CVE-2026-57082 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl generate the MSE Diffie-Hellman private key with a non-cryptographic PRNG. The MSE (Message Stream Encryption) handshake derives its 160-bit Diffie-Hellman private key from Perl's rand(), a non-cryptographic drand48-class generator seeded once per process, in KeyExchange.pm. The shared secret and the RC4 keys derived from it (the SHA-1 of "keyA" or "keyB", the shared secret, and the infohash) therefore depend entirely on a predictable PRNG. The same handshake sends, in cleartext, random padding drawn from the same rand() sequence in _random_pad, immediately after the public key and the private-key draw. A passive observer of the handshake recovers the PRNG state from the cleartext padding, reconstructs the private key, computes the shared secret from the peer's public key on the wire, derives the RC4 keys, and decrypts the connection, defeating the passive-observation obfuscation MSE provides.

https://github.com/sanko/Net-BitTorrent.pm/security/advisories/GHSA-g444-x2c5-94hc

CVE-2026-57081 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl allow remote memory exhaustion via deeply nested bencoded input. bdecode recurses once per nested list or dictionary level with no depth cap, and each recursive call receives the remaining buffer by value while the list and dictionary branches capture the whole remainder, so every live recursion frame keeps its own copy of the shrinking buffer (O(N^2) bytes for an N-deep input). The decoder runs on every untrusted bencode source: .torrent files, BEP09 metadata fetched from peers, DHT messages, and tracker responses. A bencoded input of roughly 150,000 nested lists (about 150 KB on the wire) drives multi-gigabyte peak memory, so one short message from any peer, or one crafted .torrent file or magnet link, terminates the client.

https://github.com/sanko/Net-BitTorrent.pm/security/advisories/GHSA-mv44-v82p-89xv

NAME

Net::BitTorrent::Torrent - High-level Torrent/Swarm Manager

SYNOPSIS

my $torrent = $client->add_magnet( $uri, './downloads');

# Monitor progress
$torrent->on( piece_verified => sub ($t, $index) {
    printf "[%s] Progress: %.2f%%\n", $t->name, $t->progress;
});

# Wait for metadata (if magnet)
$torrent->on( status_update => sub ($t, $stats) {
    if ($t->is_metadata_complete) {
        say "Metadata received for " . $t->name;
        # Torrent will automatically transition state if start() was called
    }
});

# Example: Acting as a partial seeder
$torrent->on( started => sub ($t) {
    if ($t->is_seed) {
        say "Initial seeding complete, continuing to share...";
    }
});

$torrent->start( );

DESCRIPTION

Net::BitTorrent::Torrent represents a single BitTorrent swarm. It orchestrates the interaction between peers, the piece picker, and the storage layer.

Lifecycle States:

STATE_STOPPED: No network activity.
STATE_METADATA: (Magnet mode) Fetching the info dictionary via BEP 09.
STATE_STARTING: Initializing storage and announcing to trackers.
STATE_RUNNING: Actively downloading and uploading data.
STATE_PAUSED: Connections are maintained, but no data is transferred.

METHODS

`start( )`

Starts the swarm.

$torrent->start();

This method triggers DHT lookups, tracker announces, and local peer discovery. It transitions the swarm to the STARTING or METADATA state.

`stop( )`

Stops the swarm.

$torrent->stop();

This method stops network activity, disconnects peers, and flushes storage.

`pause( )`

Pauses the swarm.

$torrent->pause();

This method keeps connections alive but stops data transfer.

`resume( )`

Resumes a paused swarm.

$torrent->resume();

This method resumes data transfer on existing connections.

`on( $event, $callback )`

Registers a callback for swarm events.

$torrent->on(piece_verified => sub ($t, $idx) { ... });

This method allows listening for events specific to this torrent.

Expected parameters:

$event: The name of the event to listen for. Supported events: piece_verified, piece_failed, status_update, peer_discovered, started, stopped, paused, resumed.
$callback: The code reference to execute when the event is emitted.

`name( )`

Returns a human-readable name for the torrent.

say 'Downloading: ' . $torrent->name;

This method returns the name from the metadata if available, or a hex infohash as a fallback.

`progress( )`

Returns the download completion percentage.

printf 'Done: %.2f%%\r', $torrent->progress;

This method returns a floating-point number between 0.0 and 100.0 representing the completion status.

`is_finished( )`

Checks if the download is complete.

say 'Download complete!' if $torrent->is_finished;

This method returns true if the download is 100% complete and verified.

`is_seed( )`

Checks if the client is seeding.

if ($torrent->is_seed) { ... }

This method returns true if the client has all pieces and is acting as a seeder.

`is_metadata_complete( )`

Checks if metadata is loaded.

if ($torrent->is_metadata_complete) { ... }

This method returns true if the info dictionary is available.

`is_running( )`

Checks if the swarm is active.

if ($torrent->is_running) { ... }

This method returns true if the state is STARTING, RUNNING, or METADATA.

`primary_pieces_root( )`

Returns the pieces root for the first file (v2).

my $root = $torrent->primary_pieces_root();

This method returns the SHA-256 Merkle tree root for the primary file in a BitTorrent v2 torrent.

`set_piece_priority( $index, $priority )`

Sets the priority for a specific piece.

$torrent->set_piece_priority( 5, 0 );

This method allows adjusting the download priority of individual pieces. A priority of 0 means the piece will not be downloaded.

Expected parameters:

$index: The zero-based piece index.
$priority: The priority level (0 = do not download, 1 = normal, higher values = higher priority).

`set_picking_strategy( $strategy )`

Sets the piece picking algorithm.

$torrent->set_picking_strategy(PICK_SEQUENTIAL);

This method changes how the client selects pieces to download. Available strategies are defined in Net::BitTorrent::Types.

Expected parameters:

$strategy: The strategy constant to use (e.g., PICK_RAREST_FIRST, PICK_SEQUENTIAL).

`infohash_v1( )`

Returns the v1 infohash.

my $ih = $torrent->infohash_v1;

This method returns the 20-byte binary SHA-1 infohash for BitTorrent v1. Returns undef if not available.

`infohash_v2( )`

Returns the v2 infohash.

my $ih = $torrent->infohash_v2;

This method returns the 32-byte binary SHA-256 infohash for BitTorrent v2. Returns undef if not available.

`files( )`

Returns a list of file paths.

my $paths = $torrent->files;

This method returns an array reference containing the absolute paths of all files in the torrent.

`discovered_peers( )`

Returns a list of known peers.

my $peers = $torrent->discovered_peers;

This method returns an array reference of peer structures discovered via various mechanisms.

`dump_state( )`

Exports the torrent state.

my $state = $torrent->dump_state;

This method returns a data structure representing the current state of the torrent, suitable for persistence.

`load_state( $state )`

Restores the torrent state.

$torrent->load_state($state);

This method restores the torrent state from a previously dumped structure.

Expected parameters:

$state: The state data structure (hash reference).

`get_superseed_piece( $peer )`

Retrieves a piece index for super-seeding.

my $idx = $torrent->get_superseed_piece($peer);

This method selects a piece to offer to a peer when in super-seeding mode (BEP 16).

Expected parameters:

$peer: The Net::BitTorrent::Peer object.

`metadata_received_count( )`

Returns the number of metadata bytes received.

my $count = $torrent->metadata_received_count();

This method returns the total number of bytes of the info dictionary currently received.

`set_limit_up( $val )`

Sets the upload rate limit for this torrent.

$torrent->set_limit_up( 512 * 1024 );

This method sets the maximum upload rate in bytes per second for this specific swarm.

Expected parameters:

$val: The limit in bytes per second. Use 0 for unlimited.

`set_limit_down( $val )`

Sets the download rate limit for this torrent.

$torrent->set_limit_down( 1024 * 1024 );

This method sets the maximum download rate in bytes per second for this specific swarm.

Expected parameters:

$val: The limit in bytes per second. Use 0 for unlimited.

`can_read( $amount )`

Checks if a download amount is allowed by rate limits.

my $allowed = $torrent->can_read( 16384 );

This method checks both global and per-torrent rate limits and returns the amount that can be consumed.

Expected parameters:

$amount: The requested number of bytes to download.

`can_write( $amount )`

Checks if an upload amount is allowed by rate limits.

my $allowed = $torrent->can_write( 16384 );

This method checks both global and per-torrent rate limits and returns the amount that can be consumed.

Expected parameters:

$amount: The requested number of bytes to upload.

`tick( [$delta] )`

Performs periodic maintenance for the swarm.

$torrent->tick( 0.1 );

This method handles peer connections, piece requests, choking logic, and tracker announces for this swarm.

Expected parameters:

$delta - optional: The time elapsed since the last tick in seconds. Defaults to 0.1.

`add_peer( $peer )`

Adds a discovered peer to the swarm.

$torrent->add_peer({ ip => '1.2.3.4', port => 6881 });

This method adds a peer to the list of potential connections.

Expected parameters:

$peer: A hash reference or object containing ip and port.

`add_dht_nodes( $nodes )`

Adds DHT nodes to the search frontier.

$torrent->add_dht_nodes( $nodes_list );

This method adds nodes discovered via the DHT to the search frontier for this torrent.

Expected parameters:

$nodes: An array reference of node structures.

`ban_peer( $ip, $port )`

Bans a peer from the swarm.

$torrent->ban_peer( '1.2.3.4', 6881 );

This method removes a peer and prevents reconnection for a period of time.

Expected parameters:

$ip: The IP address of the peer.
$port: The port number of the peer.

`register_peer_object( $peer_obj )`

Registers an active peer connection.

$torrent->register_peer_object( $peer );

This method registers a Net::BitTorrent::Peer object as an active connection for this swarm.

Expected parameters:

$peer_obj: The Net::BitTorrent::Peer object.

`start_dht_lookup( )`

Manually triggers a DHT lookup for peers.

$torrent->start_dht_lookup();

This method initiates an iterative DHT search for peers on all supported infohashes.

`peer_id( )`

Returns the local peer ID used for this torrent.

my $id = $torrent->peer_id();

This method returns the 20-byte binary peer ID.

`trackers( )`

Returns the list of trackers.

my $trackers = $torrent->trackers();

This method returns an array reference of Net::BitTorrent::Tracker::Base objects.

Specifications

BEP 03: Core Peer Wire Protocol
BEP 06: Fast Extension
BEP 09: Metadata Exchange
BEP 11: Peer Exchange (PEX)
BEP 16: Super-seeding Logic
BEP 33: DHT Scraping
BEP 52: BitTorrent v2 (Hybrid support)

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

To install Net::BitTorrent, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::BitTorrent

CPAN shell

perl -MCPAN -e shell
install Net::BitTorrent

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Lifecycle States:

METHODS

start( )

stop( )

pause( )

resume( )

on( $event, $callback )

name( )

progress( )

is_finished( )

is_seed( )

is_metadata_complete( )

is_running( )

primary_pieces_root( )

set_piece_priority( $index, $priority )

set_picking_strategy( $strategy )

infohash_v1( )

infohash_v2( )

files( )

discovered_peers( )

dump_state( )

load_state( $state )

get_superseed_piece( $peer )

metadata_received_count( )

set_limit_up( $val )

set_limit_down( $val )

can_read( $amount )

can_write( $amount )

tick( [$delta] )

add_peer( $peer )

add_dht_nodes( $nodes )

ban_peer( $ip, $port )

register_peer_object( $peer_obj )

start_dht_lookup( )

peer_id( )

trackers( )

Specifications

AUTHOR

COPYRIGHT

Module Install Instructions

Keyboard Shortcuts

`start( )`

`stop( )`

`pause( )`

`resume( )`

`on( $event, $callback )`

`name( )`

`progress( )`

`is_finished( )`

`is_seed( )`

`is_metadata_complete( )`

`is_running( )`

`primary_pieces_root( )`

`set_piece_priority( $index, $priority )`

`set_picking_strategy( $strategy )`

`infohash_v1( )`

`infohash_v2( )`

`files( )`

`discovered_peers( )`

`dump_state( )`

`load_state( $state )`

`get_superseed_piece( $peer )`

`metadata_received_count( )`

`set_limit_up( $val )`

`set_limit_down( $val )`

`can_read( $amount )`

`can_write( $amount )`

`tick( [$delta] )`

`add_peer( $peer )`

`add_dht_nodes( $nodes )`

`ban_peer( $ip, $port )`

`register_peer_object( $peer_obj )`

`start_dht_lookup( )`

`peer_id( )`

`trackers( )`