Crate rustypipe_botguard

Source
Expand description

§RustyPipe Botguard

Current crates.io version License Docs CI status

RustyPipe Botguard is a CLI tool to run YouTube’s Botguard challenges and generate Proof-of-origin tokens (PO tokens).

It is based on the reverse-engineering work of LuanRT (https://github.com/LuanRT/BgUtils).

Since the Botguard challenges are intended to run in a full browser environment and the dependencies needed to replicate it are quite large, I decided against including it in RustyPipe directly and instead released it as a seperate CLI tool. This also has the advantage that rustypipe-botguard can be integrated into any YouTube downloader/client.

§How it works

Since August 2024 YouTube requires PO tokens to access streams with web-based clients. Otherwise streams will return a 403 error.

PO tokens are used by YouTube as proof that the user is accessing YouTube from a real browser. The tokens are generated by a proprietary virtual machine implemented in JavaScript. The process works as follows:

  • Fetch the VM script and Botguard program from YouTube’s API (api/jnn/v1/Create)
  • Load the VM script into the JS environment
  • Run the program using the VM and submit the result to YouTube’s api/jnn/v1/GenerateITendpoint
  • YouTube returns an integrity token
  • The VM script generates PO tokens using the integrity token and an identifier

RustyPipe-Botguard uses a stripped-down version of the Deno JavaScript runtime along with JSDOM to replicate a browser environment and pass Botguard challenges. It can also store a snapshot of its JS environment after successfully solving a challenge. This greatly speeds up subsequent requests.

PO tokens are currently used in the following places when fetching YouTube videos:

  • Player requests need a serviceIntegrityDimensions.poToken parameter set to a content-bound token (video ID as an identifier)
  • Stream URLs need to have a pot URL parameter with a session-bound PO token (using the visitor data ID as an identifier)

§Usage

Call rustypipe-botguard with one or multiple identifiers as arguments. The tool returns a list of PO tokens separated with a space.

After the tokens it outputs a space-separated list of metadata items in the format key=value:

  • valid_until: Unix timestamp when the PO token will expire
  • from_snapshot: true if the Botguard runtime was created from a snapshot

More metadata items may be added in the future, so your implementation has to ignore unknown keys.

Since YouTube video IDs can start with a dash and may be interpreted as CLI options, you should use a double dash seperator between the options and the identifiers.

$ rustypipe-botguard -- pPvd8UxmSbQ Cgtnelk4ZmJWMXN4cyjpmYi9BjIKCgJERRIEEgAgNA%3D%3D
MlOClAt8t6x0HYKon9J8I-SCEWj3aOQKzLam6LXdLRXW3ypcXHdygoyg4slY9Z9kW0HXdWGKbBep7vWCgE2rjynS1YrhUJYiQfCZTS7FqeJz3MEFIg== MnR3PvWN5T_RRHcCYSMusEHb5MIJmbaZae9TQkssf4Zzht_2ooYgESn5F2OmBM33_hgi3597PoQMtwAofrz5HIyLICAfocSxBZCT1frOBEoXUIOMeXjtctrmfccXNJn9kFq0IvboUu2uKbAYQVVKjHa4gxmoSQ== valid_until=1738715307 from_snapshot=false

§Options

  • --snapshot-file By default, rustypipe-botguard stores its snapshot in the RustyPipe data folder located at ~/.local/share/rustypipe/bg_snapshot.bin. If you want to specify a custom file path, use this option.
  • --no-snapshot Do not load/store a snapshot of the Botguard runtime
  • --user-agent Set a custom user agent for fetching Botguard challenges.

Structs§

Botguard
RustyPipe Botguard client
BotguardBuilder
Builder to construct a new RustyPipe Botguard client

Enums§

Error
Error type for the rustypipe-botguard library

Constants§

VERSION
Version of the RustyPipe Botguard crate