python-obfuscation-framework 1.6.2__tar.gz → 1.7.2__tar.gz

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.2}/MANIFEST.in

@@ -1,5 +1,6 @@
 recursive-include pof *.py
 include pof/utils/generator/names.txt
+include pof/utils/generator/comments.txt
 include pof/utils/se/homoglyphs.txt
 
 recursive-include tests *

{python_obfuscation_framework-1.6.2/python_obfuscation_framework.egg-info → python_obfuscation_framework-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-obfuscation-framework
-Version: 1.6.2
+Version: 1.7.2
 Summary: Python Obfuscation Framework
 Author-email: deoktr <35725720+deoktr@users.noreply.github.com>
 Maintainer-email: deoktr <35725720+deoktr@users.noreply.github.com>
@@ -29,9 +29,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: rope>=1.0.0
 Requires-Dist: Pillow>=10.0.0
+Requires-Dist: black>=25.0.0
 Provides-Extra: dev
-Requires-Dist: ruff==0.8.0; extra == "dev"
-Requires-Dist: black==24.10.0; extra == "dev"
+Requires-Dist: ruff==0.14.4; extra == "dev"
+Requires-Dist: black==25.9.0; extra == "dev"
 Requires-Dist: pyinstrument; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
@@ -46,26 +47,25 @@ Dynamic: license-file
 
 [![python-obfuscation-framework-pypi](https://img.shields.io/pypi/v/python-obfuscation-framework.svg)](https://pypi.org/project/python-obfuscation-framework)
 
-Python Obfuscation Framework.
+Python Obfuscation Framework, a complete Python offensive security toolkit to generate staged obfuscated payloads.
 
-Combine and chain obfuscation methods on a single Python source file.
-
-Install:
+pof will allow you to:
 
-```bash
-pip install python-obfuscation-framework
-```
+- **Create staged payloads**, store stages inside images, on trusted sites, encrypt, compress, or encode them, and much more.
+- **Slow down static analysis** of the payload or the stage.
+- **Evade sandbox** by checking host information like MAC addresses, CPU count, memory count, uptime, and much more.
+- **Add guardrails** to ensure the payload only execute on the desired target host by verifying for username, hostname, domainame and much more.
+- **Prevent dynamic analysis** by detecting debugging or tracing via malloc.
+- **Enable automation** to produce numerous variant of the same payload.
 
-Source:
+The main benefit of POF is customizability, you can generate your payload however you want, choose the obfuscation you want and combine them.
 
-```python
-print('Hello, world')
-```
+Most obfuscation work very well when combined. For example obfuscating an int from `42` to `int("42")` allows the string obfuscator to obfuscate it, turning it into `int("".join([chr(ord(i)-3)for i in'75']))`. And we now have multiple int and strings that we can once again obfuscate.
 
-Run:
+Example obfuscation:
 
-```bash
-pof in.py -o out.py
+```python
+print("Hello, world")
 ```
 
 Output:
@@ -76,33 +76,108 @@ from base64 import b85decode as _5269
 globals()["".join([chr(ord(i)-3)for i in'bbvqlwolxebb'[::-1]])].__dict__[_5269('').decode().join([chr(ord(i)-3)for i in"".join([chr(ord(i)-3)for i in'mruhgry'])])]()[_5269(''[::-1]).decode().join([globals()[''[::-1].join([chr(ord(i)-3)for i in expected_data('YmJleGxvd2xxdmJi').decode()])].__dict__["".join([chr(ord(i)-3)for i in"".join([chr(ord(i)-3)for i in'inx'])])](__builtins__.__dict__.__getitem__("".join([chr(ord(i)-3)for i in'']).join([chr(ord(i)-3)for i in expected_data('cnVn').decode()]))(i)-(__name__.__len__().__class__(__builtins__.__dict__.__getitem__(_5269('X>N1').decode())("".join([chr(ord(i)-3)for i in'3\u007b5']),0)+__builtins__.__getattribute__('egapraeytamrofel'[::-1].replace('egapraeytamrof'[::-1],expected_data('bg==').decode()))(expected_data("".join([chr(ord(i)-3)for i in']j@@'])).decode()))))for i in"".join([chr(ord(i)-3)for i in'eeh{olsy7bdgguvtyee']).replace(_5269('X>fKlUtwfqa&r').decode(),_5269('Z+C0').decode())])].__dict__[''[::-1].join([chr(ord(i)-3)for i in''[::-1]]).join([globals()[expected_data('XordinalidWlsdGlucordinalf'.replace('ordinal','19')).decode()].__dict__[expected_data('yh2Y'[::-1]).decode()](globals()[_5269(expected_data('VXRlTiVYPjQ/OVpnWEU+').decode()).decode()].__dict__[_5269('fold_countV'.replace('fold_count','Z*p')).decode()](i)-__builtins__.__getattribute__(expected_data("".join([chr(ord(i)-3)for i in'dZ83'])).decode())('quaencode_7or8bits'.replace('encode_7or8bit','ntile').replace("".join([chr(ord(i)-3)for i in'txdqwlohv']),"".join([chr(ord(i)-3)for i in'6']))))for i in expected_data('').decode().join([chr(ord(i)-3)for i in'ztoxv'[::-1]])])](expected_data(_5269('Q%6>FVKQQ0ad38HZFp+').decode().replace('pq_b2a'[::-1],'\u0062\u00478\u0073\u0049\u0048\u0064')).decode())
 ```
 
-More examples and usage can be found in `examples/` or in the section bellow.
-
-## Goals
+<details>
+<summary>Same output formatted:</summary>
 
-The goals of this project are to create a toolkit to obfuscate Python source code, mainly to create payload for offensive security.
-
-pof will allow you to:
-
-- create **payloads**: store the code inside images, have multiple stages, use LOTL techniques
-- create **stager**: easily create multi stages payloads
-- do **evasion**: AV, EDR, DPI, sandbox and other analysis techniques
-- slow **analysis**: slow down human analysis of the payload
-- enable **automation**: automate the whole process, to produce numerous variant of the payload
-- be **cross-platform**: works on Linux, Windows, and macOS
-- have **fun**: because it's always fun to see what's possible to do with Python
-
-This project also tries to combine all other Python obfuscation tools available, because most of them only provide a single method, and it's pretty basic. So you should be able to do everything that those other tools do, but without having to use multiple.
+```python
+from base64 import b64decode as expected_data
+from base64 import b85decode as _5269
 
-Python is not exactly the best language to create payloads with, especially for Windows if the interpreter is not already installed. This project was made for learning, and discovering new ways of bypassing security, it's a great way to test obfuscations techniques.
+globals()["".join([chr(ord(i) - 3) for i in "bbvqlwolxebb"[::-1]])].__dict__[
+    _5269("")
+    .decode()
+    .join([chr(ord(i) - 3) for i in "".join([chr(ord(i) - 3) for i in "mruhgry"])])
+]()[
+    _5269(""[::-1])
+    .decode()
+    .join(
+        [
+            globals()[
+                ""[::-1].join(
+                    [
+                        chr(ord(i) - 3)
+                        for i in expected_data("YmJleGxvd2xxdmJi").decode()
+                    ]
+                )
+            ].__dict__[
+                "".join(
+                    [chr(ord(i) - 3) for i in "".join([chr(ord(i) - 3) for i in "inx"])]
+                )
+            ](
+                __builtins__.__dict__.__getitem__(
+                    "".join([chr(ord(i) - 3) for i in ""]).join(
+                        [chr(ord(i) - 3) for i in expected_data("cnVn").decode()]
+                    )
+                )(i)
+                - (
+                    __name__.__len__().__class__(
+                        __builtins__.__dict__.__getitem__(_5269("X>N1").decode())(
+                            "".join([chr(ord(i) - 3) for i in "3\u007b5"]), 0
+                        )
+                        + __builtins__.__getattribute__(
+                            "egapraeytamrofel"[::-1].replace(
+                                "egapraeytamrof"[::-1], expected_data("bg==").decode()
+                            )
+                        )(
+                            expected_data(
+                                "".join([chr(ord(i) - 3) for i in "]j@@"])
+                            ).decode()
+                        )
+                    )
+                )
+            )
+            for i in "".join([chr(ord(i) - 3) for i in "eeh{olsy7bdgguvtyee"]).replace(
+                _5269("X>fKlUtwfqa&r").decode(), _5269("Z+C0").decode()
+            )
+        ]
+    )
+].__dict__[
+    ""[::-1]
+    .join([chr(ord(i) - 3) for i in ""[::-1]])
+    .join(
+        [
+            globals()[
+                expected_data(
+                    "XordinalidWlsdGlucordinalf".replace("ordinal", "19")
+                ).decode()
+            ].__dict__[expected_data("yh2Y"[::-1]).decode()](
+                globals()[
+                    _5269(expected_data("VXRlTiVYPjQ/OVpnWEU+").decode()).decode()
+                ].__dict__[_5269("fold_countV".replace("fold_count", "Z*p")).decode()](
+                    i
+                )
+                - __builtins__.__getattribute__(
+                    expected_data("".join([chr(ord(i) - 3) for i in "dZ83"])).decode()
+                )(
+                    "quaencode_7or8bits".replace("encode_7or8bit", "ntile").replace(
+                        "".join([chr(ord(i) - 3) for i in "txdqwlohv"]),
+                        "".join([chr(ord(i) - 3) for i in "6"]),
+                    )
+                )
+            )
+            for i in expected_data("")
+            .decode()
+            .join([chr(ord(i) - 3) for i in "ztoxv"[::-1]])
+        ]
+    )
+](
+    expected_data(
+        _5269("Q%6>FVKQQ0ad38HZFp+")
+        .decode()
+        .replace("pq_b2a"[::-1], "\u0062\u00478\u0073\u0049\u0048\u0064")
+    ).decode()
+)
+```
 
-This project could also give you ideas to implement in other languages, such as powershell where it would make sens to obfuscate the source code. Or in C, C#, C++, Go or Rust where it would make sens to stage payloads, compress them, encrypt them and obfuscate strings.
+</details>
 
-You could also use most of the stagers to stage payload that are not built in Python.
+More examples and usage can be found in `examples/` or in the section bellow.
 
 ## Install
 
-There are 4 installation options, with PIP, a virtualenv, a Docker container, or with Nix.
+There are multiple installation options, with PIP, a virtualenv, a container, or with Nix.
+
+There is also the option to run the web server, see [server/README.md](./server/README.md).
 
 ### 1. PIP
 
@@ -139,6 +214,12 @@ Run inside Docker from a local file `in.py`:
 docker run --rm -v $(pwd):/tmp ghcr.io/deoktr/pof:latest /tmp/in.py -o /tmp/out.py
 ```
 
+Or pipe input and output:
+
+```bash
+cat in.py | docker run --rm -i ghcr.io/deoktr/pof:latest > out.py
+```
+
 ### 4. Docker Source
 
 ```bash
@@ -195,7 +276,7 @@ pof in.py -f obfuscator -k BuiltinsObfuscator |\
     pof -f stager -k PasteRsStager > out.py
 ```
 
-You can also use the Python API directly, you can find examples in the corresponding directory or bellow.
+You can also use the Python API directly, you can find examples or see API usage bellow.
 
 ## Examples
 
@@ -217,6 +298,48 @@ echo "print('Hello, world')" | pof -f obfuscator -k UUIDObfuscator | python
 
 ### Obfuscator
 
+`NamesObfuscator` the most basic obfuscator is changing variables, classes, function names, and imports.
+
+Source in `examples/source.py`.
+
+```python
+import random as dZoHe5KQ5T
+import string as BOu1uhdV
+
+def hrEnWnn_d():
+    """This is a docstring."""
+    return dZoHe5KQ5T.choice(BOu1uhdV.ascii_lowercase)
+
+def a_D(wYKTr7D5Ex):
+    JfQdd = hrEnWnn_d()
+    for kEw73z in range(wYKTr7D5Ex - 1):
+        JfQdd += hrEnWnn_d()
+    return JfQdd
+
+def VLBQn3():
+    mxO = a_D(8)
+    tBceS = 'My pet is name: ' + mxO
+    print(tBceS)
+VLBQn3()
+```
+
+> [!WARNING]
+> Right now this obfuscator can fail under very specific circumstances, see `pof/obfuscator/names.py`.
+
+An alternative is `DefinitionsObfuscator`, that will only obfuscate function declarations.
+
+> [!NOTE]
+> There is an alternative implementation at `NamesRopeObfuscator` that uses `rope`, it's a work in progress and currently does not obfuscate variables declared inside functions.
+
+Other very basic obfuscation functions are done by specific obfuscators like:
+
+- Removing comments with `CommentsObfuscator`.
+- Replacing exception messages with `ExceptionObfuscator`.
+- Reducing indentation to a single space with `IndentsObfuscator`.
+- Replace log messages with `LoggingObfuscator` or remove them with `LoggingRemoveObfuscator`.
+- Remove empty lines with `NewlineObfuscator`.
+- Remove print statements with `PrintObfuscator`.
+
 #### StringsObfuscator
 
 ```python
@@ -265,22 +388,37 @@ print(len('bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'))
 print((True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True+True))
 ```
 
-#### DefinitionsObfuscator
+#### ConstantsObfuscator
 
-Source:
+Move every variable at the top of the file with random names.
 
 ```python
-def say_hello(t):
-    print(t)
-say_hello("Hello, world")
-```
+gfdd_j=print
+uVu8Mq=8
+GqTsw9ZK="My pet is name: "
+u4F5X=range
+rSO2F=1
+# source file that will be obfuscated
+import random
+import string
 
-Obfuscated:
+def get_random_letter():
+    """This is a docstring."""
+    return random.choice(string.ascii_lowercase)
 
-```python
-def sczCWV(t):
-  print(t)
-sczCWV('Hello, world')
+def get_random_name(name_len):
+# this is a comment
+    name=get_random_letter()
+    for _ in u4F5X(name_len-rSO2F):
+        name+=get_random_letter()
+    return name
+
+def present_my_pet():
+    pet_name=get_random_name(uVu8Mq)
+    message=GqTsw9ZK+pet_name
+    gfdd_j(message)
+
+present_my_pet()
 ```
 
 #### BuiltinsObfuscator
@@ -297,16 +435,6 @@ globals()['__builtins__'].__dict__['print']('Hello, world')
 __builtins__.__dict__.__getitem__('print')('Hello, world')
 ```
 
-#### ConstantsObfuscator
-
-Move every variable at the top of the file.
-
-```python
-vVlJ='Hello, world'
-t4Bo=print
-t4Bo(vVlJ)
-```
-
 #### ExtractVariablesObfuscator
 
 Extract variables in the same context level, meaning if inside a function will add the variable at the beginning of it.
@@ -325,6 +453,35 @@ print(var)
 print.__call__('Hello, world')
 ```
 
+#### GlobalsObfuscator
+
+Replaces call of global functions with `globals()['func_name']()`.
+
+Source in `examples/source.py`.
+
+```python
+import random
+import string
+
+def get_random_letter():
+    """This is a docstring."""
+    return random.choice(string.ascii_lowercase)
+
+def get_random_name(name_len):
+# this is a comment
+    name=globals()['get_random_letter']()
+    for _ in range(name_len-1):
+        name+=globals()['get_random_letter']()
+    return name
+
+def present_my_pet():
+    pet_name=globals()['get_random_name'](8)
+    message="My pet is name: "+pet_name
+    print(message)
+
+globals()['present_my_pet']()
+```
+
 #### ShiftObfuscator
 
 ```python
@@ -504,6 +661,25 @@ Source: `print('h')`
 print(oct.__doc__[8])
 ```
 
+#### AddCommentsObfuscator
+
+```python
+# This is a random comment
+print("Hello, world!")
+```
+
+The list of comments available is inside a file, all the comments have been extracted from Python standard library.
+
+#### AddNewlinesObfuscator
+
+Add random new lines everywhere it's possible.
+
+```python
+
+print("Hello, world!")
+
+```
+
 ### Stager
 
 #### DownloadStager
@@ -640,6 +816,22 @@ The `out2.py` and `out3.py` files are identical, they both contain the source co
 > [!NOTE]
 > By default pof uses a custom `Untokenizer` that removes useless spaces (`NoSpaceUntokenizer` defined in `./pof/utils/tokens.py`), so first generation (in the example `out.py`) will not have spaces present in the subsquent outputs.
 
+### Format
+
+You can choose to automatically format the output code using black.
+
+From the CLI add the `--format` flag.
+
+From lib:
+
+```py
+from pof.utils.format import black_format
+
+obf = ExampleObfuscator().obfuscate(...)
+out = black_format(obf)
+print(out)
+```
+
 ### Generators
 
 Generators are used to generate new names, they can be used to classes, variables, functions, constants or any other.
@@ -689,7 +881,6 @@ Yes they are valid Python variable name.
 Usage:
 
 ```python
-
 from pof.utils.generator import UnicodeGenerator
 
 gen = UnicodeGenerator().katakana_generator()
@@ -697,6 +888,21 @@ for _ in range(4):
     print(next(gen))
 ```
 
+You can also combine generators to pick randomly but with weights associated:
+
+```python
+from pof.utils.generator import *
+
+gen_dict = {
+    86: AdvancedGenerator.realistic_generator(),
+    10: BasicGenerator.alphabet_generator(),
+    4: BasicGenerator.number_name_generator(length=random.randint(2, 5)),
+}
+gen = AdvancedGenerator.multi_generator(gen_dict)
+for _ in range(4):
+    print(next(gen))
+```
+
 ### Homoglyphs
 
 [Homoglyphs](https://en.wikipedia.org/wiki/Homoglyph) are glyphs that have the same shape and appear identical. There is a generator to help create them.
@@ -838,7 +1044,7 @@ class ExampleObfuscator(BaseObfuscator):
 print(ExampleObfuscator().obfuscate(open("source.py", "r").read()))
 ```
 
-In this example we can see that first we remove comments, logging, print statements, and change the content of exceptions, and then we start to obfuscate constants, names, globals, builtins, strings, then strings and numbers multiple times, and we finally convert the tokens back to code.
+In this example we can see that first we remove comments, logging, print statements, and change the content of exceptions. And then we start to obfuscate constants, names, globals, builtins, strings. Then strings and numbers multiple times, and we finally convert the tokens back to code.
 
 By chaining multiple obfuscations techniques we can create very complex and custom output.
 
@@ -856,19 +1062,19 @@ yara --no-warnings yara/python.yar file.py
 
 ## Development
 
-Project:
+Project directory structure:
 
-- `pof`: contains all the pof source code
-  - `pof/obfuscator`: contains obfuscators
-  - `pof/stager`: contains satgers
-  - `pof/evasion`: contains evasions
-  - `pof/utils`: all shared code between stager, obfuscator and evasion
-- `wip`: work in progress code that will eventually make its way inside the main code base
-- `tests`: unit tests for pof
-- `scripts`: some useful scripts to develop or use pof
-- `yara`: some yara rules to detect pof obfuscated code
+- `pof`: contains all the pof source code.
+  - `pof/obfuscator`: contains obfuscators.
+  - `pof/stager`: contains satgers.
+  - `pof/evasion`: contains evasions.
+  - `pof/utils`: all shared code between stager, obfuscator and evasion.
+- `wip`: work in progress code that will eventually make its way inside the main code base.
+- `tests`: unit tests for pof.
+- `scripts`: some useful scripts to develop or use pof.
+- `yara`: some yara rules to detect pof obfuscated code.
 
-Setup:
+Setup dev environment:
 
 ```bash
 python3 -m venv venv
@@ -876,13 +1082,13 @@ python3 -m venv venv
 # activate it (or equivalent for your shell)
 source ./venv/bin/activate
 
-# install dep
+# install dependencies
 pip install -e .
-pip install -e .[dev]
-pip install -e .[test]
+pip install -e ".[dev]"
+pip install -e ".[test]"
 ```
 
-Run pof:
+Run pof CLI:
 
 ```bash
 ./pof.py --help
@@ -897,7 +1103,6 @@ pytest
 Format:
 
 ```bash
-black .
 ruff format .
 ```
 
@@ -910,7 +1115,8 @@ ruff check .
 Test build package:
 
 ```bash
-pip install -e .[build]
+# install dependencies
+pip install -e ".[build]"
 
 check-manifest --ignore "tests/**"
 python3 -m build
@@ -921,11 +1127,32 @@ python3 -m twine check dist/*
 
 No effort is made to support Python 2, most obfuscator, stagers, and evasion should work out of the box, but they are not tested.
 
+## Alternatives
+
+Other Python obfuscation projects:
+
+- [0x-Apollyon/Papyrus](https://github.com/0x-Apollyon/Papyrus)
+- [Hnfull/Intensio-Obfuscator](https://github.com/Hnfull/Intensio-Obfuscator)
+- [lepotekil/MsfMania](https://github.com/lepotekil/MsfMania)
+- [billythegoat356/Hyperion](https://github.com/billythegoat356/Hyperion)
+- [spyboy-productions/ObfuXtreme](https://github.com/spyboy-productions/ObfuXtreme)
+- [chris-rands/emojify](https://github.com/chris-rands/emojify)
+- [0sir1ss/Anubis](https://github.com/0sir1ss/Anubis)
+- [0sir1ss/Carbon](https://github.com/0sir1ss/Carbon)
+- [billythegoat356/Apollyon](https://github.com/billythegoat356/Apollyon)
+- [billythegoat356/Berserker](https://github.com/billythegoat356/Berserker)
+- [brandonasuncion/Python-Code-Obfuscator](https://github.com/brandonasuncion/Python-Code-Obfuscator)
+- [CSM-BlueRed/Impostor](https://github.com/CSM-BlueRed/Impostor)
+- [ImInTheICU/ExtraLayer](https://github.com/ImInTheICU/ExtraLayer)
+- [root4031/pyobfuscate](https://github.com/root4031/pyobfuscate)
+- [therealOri/PolyLock](https://github.com/therealOri/PolyLock)
+- [FlorianREGAZ/PyObfuscator](https://github.com/FlorianREGAZ/PyObfuscator)
+
 ## TODO
 
-- Fix `NamesObfuscator`
-- Add option to prepend a shebang, and add ability to customize it
-- Fix multi line strings
+- Fix `NamesObfuscator`.
+- Fix multi line strings.
+- Add option to prepend a shebang, and add ability to customize it.
 
 ## License