Stegosaurus is a steganography tool
that allows embedding arbitrary payloads in
Python bytecode (pyc or pyo) files. The embedding process does not alter the
runtime behavior or file size of the carrier file and typically results in a low
encoding density. The payload is dispersed throughout the bytecode so tools like
strings will not show the actual payload. Python's dis module will
return the same results for bytecode before and after Stegosaurus is used to embed
a payload. At this time, no prior work or detection methods are known for this type
of payload delivery.
Stegosaurus requires Python 3.6 or later.
$ python3 -m stegosaurus -h
usage: stegosaurus.py [-h] [-p PAYLOAD] [-r] [-s] [-v] [-x] carrier
positional arguments:
carrier Carrier py, pyc or pyo file
optional arguments:
-h, --help show this help message and exit
-p PAYLOAD, --payload PAYLOAD
Embed payload in carrier file
-r, --report Report max available payload size carrier supports
-s, --side-by-side Do not overwrite carrier file, install side by side
instead.
-v, --verbose Increase verbosity once per use
-x, --extract Extract payload from carrier file
Assume we wish to embed a payload in the bytecode of the following Python script, named example.py:
"""Example carrier file to embed our payload in.
"""
import math
def fibV1(n):
if n == 0 or n == 1:
return n
return fibV1(n - 1) + fibV1(n - 2)
def fibV2(n):
if n == 0 or n == 1:
return n
return int(((1 + math.sqrt(5))**n - (1 - math.sqrt(5))**n) / (2**n * math.sqrt(5)))
def main():
result1 = fibV1(12)
result2 = fibV2(12)
print(result1)
print(result2)
if __name__ == "__main__":
main()
The first step is to use Stegosaurus to see how many bytes our payload can contain without changing the size of the carrier file.
$ python3 -m stegosaurus example.py -r
Carrier can support a payload of 20 bytes
We can now safely embed a payload of up to 20 bytes. To help show the before and after the
-s option can be used to install the carrier file side by side with the untouched
bytecode:
$ python3 -m stegosaurus example.py -s --payload "root pwd: 5+3g05aW"
Payload embedded in carrier
Looking on disk, both the carrier file and original bytecode file have the same size:
$ ls -l __pycache__/example.cpython-36*
-rw-r--r-- 1 jherron staff 743 Mar 10 00:58 __pycache__/example.cpython-36-stegosaurus.pyc
-rw-r--r-- 1 jherron staff 743 Mar 10 00:58 __pycache__/example.cpython-36.pyc
Note: If the -s option is omitted, the original bytecode would have been overwritten.
The payload can be extracted by passing the -x option to Stegosaurus:
$ python3 -m stegosaurus __pycache__/example.cpython-36-stegosaurus.pyc -x
Extracted payload: root pwd: 5+3g05aW
The payload does not have to be an ascii string, shellcode is also supported:
$ python3 -m stegosaurus example.py -s --payload "\xeb\x2a\x5e\x89\x76"
Payload embedded in carrier
$ python3 -m stegosaurus __pycache__/example.cpython-36-stegosaurus.pyc -x
Extracted payload: \xeb\x2a\x5e\x89\x76
To show that the runtime behavior of the Python code remains after Stegosaurus embeds the payload:
$ python3 example.py
144
144
$ python3 __pycache__/example.cpython-36.pyc
144
144
$ python3 __pycache__/example.cpython-36-stegosaurus.pyc
144
144
Output of strings after Stegosaurus embeds the payload (notice the payload is
not shown):
$ python3 -m stegosaurus example.py -s --payload "PAYLOAD_IS_HERE"
Payload embedded in carrier
$ strings __pycache__/example.cpython-36-stegosaurus.pyc
.Example carrier file to embed our payload in.
fibV1)
example.pyr
math
sqrt)
fibV2
print)
result1
result2r
main
__main__)
__doc__r
__name__r
<module>
$ python3 -m stegosaurus __pycache__/example.cpython-36-stegosaurus.pyc -x
Extracted payload: PAYLOAD_IS_HERE
Sample output of Python's dis module, which shows no difference before and after
Stegosaurus embeds its payload:
Before:
20 LOAD_GLOBAL 0 (int)
22 LOAD_CONST 2 (1)
24 LOAD_GLOBAL 1 (math)
26 LOAD_ATTR 2 (sqrt)
28 LOAD_CONST 3 (5)
30 CALL_FUNCTION 1
32 BINARY_ADD
34 LOAD_FAST 0 (n)
36 BINARY_POWER
38 LOAD_CONST 2 (1)
40 LOAD_GLOBAL 1 (math)
42 LOAD_ATTR 2 (sqrt)
44 LOAD_CONST 3 (5)
46 CALL_FUNCTION 1
48 BINARY_SUBTRACT
50 LOAD_FAST 0 (n)
52 BINARY_POWER
54 BINARY_SUBTRACT
56 LOAD_CONST 4 (2)
After:
20 LOAD_GLOBAL 0 (int)
22 LOAD_CONST 2 (1)
24 LOAD_GLOBAL 1 (math)
26 LOAD_ATTR 2 (sqrt)
28 LOAD_CONST 3 (5)
30 CALL_FUNCTION 1
32 BINARY_ADD
34 LOAD_FAST 0 (n)
36 BINARY_POWER
38 LOAD_CONST 2 (1)
40 LOAD_GLOBAL 1 (math)
42 LOAD_ATTR 2 (sqrt)
44 LOAD_CONST 3 (5)
46 CALL_FUNCTION 1
48 BINARY_SUBTRACT
50 LOAD_FAST 0 (n)
52 BINARY_POWER
54 BINARY_SUBTRACT
56 LOAD_CONST 4 (2)
Payloads, delivery and reciept methods are entirely up to the user. Stegosaurus only provides the means to embed and extract paylods from a given Python bytecode file. Due to the desire to leave file size intact, a relatively few number of bytes can be used to deliver the payload. This may require spreading larger payloads across multiple bytecode files, which has some advantages such as:
- Delivering a payload in pieces over time
- Portions of the payload can be spread over mutliple locations and joined when needed
- A single portion being compromised does not divulge the whole payload
- Thwarting detection of the entire payload by spreading it across multiple seemingly unrelated files
The means to spread large payloads across multiple Python bytecode files is not supported as this moment, see TODOs.
In order to embed a payload without increasing the file size, dead zones need to be identified within the bytecode. A dead zone is defined as any byte which if changed will not impact the behavior of the Python script. Python 3.6 introduced easy to exploit dead zones. Stepping back though, a little history to set the stage.
Python's reference interpreter, CPython has two types of opcodes - those with arguments and those without. In Python <= 3.5 instructions in the bytecode occupied either 1 or 3 bytes, depending on if the opcode took an arugment or not. In Python 3.6 this was changed so that all instructions occupy two bytes. Those without arguments simply set the second byte to zero and it is ignored during execution. This means that for each instruction in the bytecode that does not take an arugment, Stegosaurus can safely insert one byte of the payload.
Some examples of opcodes that do not take an argument:
BINARY_SUBTRACT
INPLACE_ADD
RETURN_VALUE
GET_ITER
YIELD_VALUE
IMPORT_STAR
END_FINALLY
NOP
...
To see an example of the changes in the bytecode, consider the following Python snippet:
def test(n):
return n + 5 + n - 3
Using dis with Python < 3.6 shows:
0 LOAD_FAST 0 (n)
3 LOAD_CONST 1 (5) <-- opcodes with an arg take 3 bytes
6 BINARY_ADD <-- opcodes without an arg take 1 byte
7 LOAD_FAST 0 (n)
10 BINARY_ADD
11 LOAD_CONST 2 (3)
14 BINARY_SUBTRACT
15 RETURN_VALUE
# :( no easy bytes to embed a payload
However with Python 3.6:
0 LOAD_FAST 0 (n)
2 LOAD_CONST 1 (5) <-- all opcodes now occupy two bytes
4 BINARY_ADD <-- opcodes without an arg leave 1 byte for the payload
6 LOAD_FAST 0 (n)
8 BINARY_ADD
10 LOAD_CONST 2 (3)
12 BINARY_SUBTRACT
14 RETURN_VALUE
# :) easy bytes to embed a payload
Passing -vv to Stegosaurus we can see how the payload is embedded in these dead zones:
$ python3 -m stegosaurus ../python_tests/loop.py -s -p "ABCDE" -vv
Read header and bytecode from carrier
BINARY_ADD (0)
BINARY_ADD (0)
BINARY_SUBTRACT (0)
RETURN_VALUE (0)
RETURN_VALUE (0)
Found 5 bytes available for payload
Payload embedded in carrier
BINARY_ADD (65) <-- A
BINARY_ADD (66) <-- B
BINARY_SUBTRACT (67) <-- C
RETURN_VALUE (68) <-- D
RETURN_VALUE (69) <-- E
Timestamps and debug levels removed from logs for readability
Currently this is the only dead zone that Stegosaurus exploits. Future improvements include more dead zone identification as mentioned in the TODOs.
- Add self destruct option
-dwhich will purge the payload from the carrier file after extraction - Support method to distribute payload across multiple carrier files
- Provide
-tflag to test if a payload may be present within a carrier file - Find more dead zones within the bytecode to place the payload, such as dead code
- Add a
-goption which will grow the size of the file to supported larger payloads for users that are not concerned with a change in file size (for instance if Stegosaurus is injected into a build pipeline)
Thanks to S0lll0s for:
- Prevent placing the payload in long runs of opcodes that do not take an argument
as this can lead to exposure of the payload through tools like
strings
For any questions, please contact the author:
Jon Herron
jon dot herron at yahoo.com