Refactor pwnlib.encoders.encode() to be more nice to bytes objects

[heapcrash]

• Add byteset() to misc which does "the right thing" and returns a set of bytes objects
• Make bytes_avoid be a bytes() object instead of a set
• Update documentation to note that functions take bytes() and not str()
• Move Encoder class to its own module so that it doesn't show up in docs
• Remove documentation for individual encoders, ideally people should only use the public APIs

Example Script (examples/encoder.py)

This requires running from make -C extra/docker develop in order for the current username to be "pwntools".

#!/usr/bin/env python3
from pwn import *

context.randomize = False
context.log_level = 'error'

def go():
    info('========== %s ==========', context.arch)
    with context.silent:
        sc = asm(shellcraft.sh())
        avoid=b'\x00\n\t '
        enc = encode(sc, avoid=avoid, force=1)

    assert not (byteset(avoid) & byteset(enc))
    assert enc != sc

    with context.silent:
        io = ELF.from_bytes(enc).process()
        io.sendline('whoami')

    try:
        info('%r', io.recvline() == b'pwntools\n')
    except EOFError:
        info('EOFError')

    with context.silent:
        io.close()


context.clear(arch='i386')
go()

context.clear(arch='amd64')
go()

context.clear(arch='arm')
go()

context.clear(arch='mips')
go()

Python3

$ python3 examples/encoder.py
[*] ========== i386 ==========
[*] True
[*] ========== amd64 ==========
[*] True
[*] ========== arm ==========
[*] True
[*] ========== mips ==========
[*] True

Python2

$ python2 examples/encoder.py
[*] ========== i386 ==========
[*] True
[*] ========== amd64 ==========
[*] True
[*] ========== arm ==========
[*] True
[*] ========== mips ==========
[*] True

[Arusekk]

Personally I would prefer the set to be a set of numbers, but looks good.

[heapcrash]

Personally I would prefer the set to be a set of numbers, but looks good.

The issue with this is the difference between Py2 and Py3. I think there's value in keeping the behavior of the two as close as possible, for making the code as simple as possible.

Py2

>>> set(b'asdf')
{'a', 'd', 'f', 's'}
>>> byteset(b'asdf')
{'a', 'd', 'f', 's'}

Py3

>>> set(b'asdf')
{97, 100, 102, 115}
>>> byteset(b'asdf')
{b'a', b'd', b'f', b's'}

[Arusekk]

Yes, I only meant the new common behavior to be based on what py3 already does normally, and only adding a layer of py2 compatibility. This will make it easier to drop py2 support eventually (since we want to drop it in some Pwntools 5000, right?).

…

-- Wysłane z mojego urządzenia Sailfish

[heapcrash]

I hereby vote the next release is Pwntools v5.000 😛

[heapcrash]

I vote even when we drop Py2 support entirely, having a `byteset` or similar construct is useful, as would be an e.g. bytesiter. Working with bytes() ALL THE TIME is much easier than working with int() on occasion.

…

On Fri, Jun 25, 2021 at 8:15 AM Arusekk ***@***.***> wrote: Yes, I only meant the new common behavior to be based on what py3 already does normally, and only adding a layer of py2 compatibility. This will make it easier to drop py2 support eventually (since we want to drop it in some Pwntools 5000, right?). -- Wysłane z mojego urządzenia Sailfish — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1923 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/APYTIFJHWJKG5L3OWLNBW3TTUR6PZANCNFSM47JVFSZA> .

[peace-maker]

Thank you! Allowing to run the encoders again at least is great.

[peace-maker]

I agree with having a byteset and maybe byteiter helper. It's not really 100% relevant to this PR, but a way to implement it. You don't have to use it, but there were occasions where I wanted the bytes and had to p8(x) again while looping over some bytes.

[peace-maker]

The ASCII encoder isn't added to the encoder mapping in the Encoder class. We should keep the docs for that one, since it has to be used explicitly.

It has extra settings worth documenting and decodes the shellcode onto the stack, so a jmp esp is required afterwards.