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

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.0}/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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-obfuscation-framework
-Version: 1.6.2
+Version: 1.7.0
 Summary: Python Obfuscation Framework
 Author-email: deoktr <35725720+deoktr@users.noreply.github.com>
 Maintainer-email: deoktr <35725720+deoktr@users.noreply.github.com>
@@ -29,6 +29,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: rope>=1.0.0
 Requires-Dist: Pillow>=10.0.0
+Requires-Dist: black>=24.10.0
 Provides-Extra: dev
 Requires-Dist: ruff==0.8.0; extra == "dev"
 Requires-Dist: black==24.10.0; extra == "dev"
@@ -46,26 +47,21 @@ 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.
+pof will allow you to:
 
-Install:
+- **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.
 
-```bash
-pip install python-obfuscation-framework
-```
-
-Source:
+Example obfuscation:
 
 ```python
-print('Hello, world')
-```
-
-Run:
-
-```bash
-pof in.py -o out.py
+print("Hello, world")
 ```
 
 Output:
@@ -78,31 +74,11 @@ globals()["".join([chr(ord(i)-3)for i in'bbvqlwolxebb'[::-1]])].__dict__[_5269('
 
 More examples and usage can be found in `examples/` or in the section bellow.
 
-## Goals
-
-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 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.
-
-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.
-
-You could also use most of the stagers to stage payload that are not built in Python.
-
 ## 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
 
@@ -640,6 +616,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.
@@ -838,7 +830,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 +848,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 +868,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
@@ -910,7 +902,8 @@ ruff check .
 Test build package:
 
 ```bash
-pip install -e .[build]
+# install dependencies
+pip install -e ".[build]"
 
 check-manifest --ignore "tests/**"
 python3 -m build
@@ -923,9 +916,9 @@ No effort is made to support Python 2, most obfuscator, stagers, and evasion sho
 
 ## TODO
 
-- Fix `NamesObfuscator`
-- Add option to prepend a shebang, and add ability to customize it
-- Fix multi line strings
+- Fix `NamesObfuscator`.
+- Add option to prepend a shebang, and add ability to customize it.
+- Fix multi line strings.
 
 ## License
 

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.0}/README.md

@@ -2,26 +2,21 @@
 
 [![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.
+pof will allow you to:
 
-Install:
+- **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.
 
-```bash
-pip install python-obfuscation-framework
-```
-
-Source:
+Example obfuscation:
 
 ```python
-print('Hello, world')
-```
-
-Run:
-
-```bash
-pof in.py -o out.py
+print("Hello, world")
 ```
 
 Output:
@@ -34,31 +29,11 @@ globals()["".join([chr(ord(i)-3)for i in'bbvqlwolxebb'[::-1]])].__dict__[_5269('
 
 More examples and usage can be found in `examples/` or in the section bellow.
 
-## Goals
-
-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 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.
-
-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.
-
-You could also use most of the stagers to stage payload that are not built in Python.
-
 ## 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
 
@@ -596,6 +571,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.
@@ -794,7 +785,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.
 
@@ -812,19 +803,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
@@ -832,13 +823,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
@@ -866,7 +857,8 @@ ruff check .
 Test build package:
 
 ```bash
-pip install -e .[build]
+# install dependencies
+pip install -e ".[build]"
 
 check-manifest --ignore "tests/**"
 python3 -m build
@@ -879,9 +871,9 @@ No effort is made to support Python 2, most obfuscator, stagers, and evasion sho
 
 ## TODO
 
-- Fix `NamesObfuscator`
-- Add option to prepend a shebang, and add ability to customize it
-- Fix multi line strings
+- Fix `NamesObfuscator`.
+- Add option to prepend a shebang, and add ability to customize it.
+- Fix multi line strings.
 
 ## License
 

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.0}/pof/cli.py

@@ -27,6 +27,7 @@ from pof.obfuscator import *  # noqa: F403
 from pof.obfuscator import __all__ as all_obfuscator
 from pof.stager import *  # noqa: F403
 from pof.stager import __all__ as all_stager
+from pof.utils.format import black_format
 
 handler = logging.StreamHandler()
 formatter = logging.Formatter("%(levelname)s %(message)s\x1b[39m")
@@ -137,6 +138,9 @@ def _handle(args) -> int:
 
     end = time.time()
 
+    if args.format:
+        out = black_format(out)
+
     time_diff = round(end - start, 4)
     logging.info(f"took: {time_diff}s")
     args.output.write(out)
@@ -175,6 +179,11 @@ def _cli() -> int:
         help="obfuscation function",
         default="obfuscate",
     )
+    parser.add_argument(
+        "--format",
+        action="store_true",
+        help="format output with black",
+    )
     parser.add_argument(
         "--logging",
         help="logging level, DEBUG, INFO, ERROR, CRITICAL",

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.0}/pof/cli_v2.py

@@ -26,6 +26,7 @@ from pof.errors import PofError
 from pof.evasion import *  # noqa: F403
 from pof.obfuscator import *  # noqa: F403
 from pof.stager import *  # noqa: F403
+from pof.utils.format import black_format
 
 handler = logging.StreamHandler()
 formatter = logging.Formatter("%(levelname)s %(message)s\x1b[39m")
@@ -344,6 +345,9 @@ def _handle(args) -> int:
 
     end = time.time()
 
+    if args.format_black:
+        out = black_format(out)
+
     time_diff = round(end - start, 4)
     logging.info("took: %ds", time_diff)
     args.output.write(out)
@@ -468,6 +472,11 @@ def _cli() -> int:
     parser.add_argument("--eva-uptime", action="store_true")
     parser.add_argument("--eva-utc", action="store_true")
 
+    # format
+    parser.add_argument(
+        "--format-black", action="store_true", help="format output with black"
+    )
+
     # control
     parser.add_argument(
         "--obf-count",

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.0}/pof/main.py

@@ -19,7 +19,7 @@
 import io
 import logging
 import random
-from tokenize import generate_tokens
+from tokenize import COMMENT, NEWLINE, generate_tokens
 
 from pof.evasion import (
     CPUCountEvasion,
@@ -65,6 +65,8 @@ from pof.utils.tokens import untokenize
 class BaseObfuscator:
     @staticmethod
     def _get_tokens(source: str):
+        # TODO (deoktr): this is not safe, the \r could be inside a string, probably
+        # should get tokens first, and update all the instances of newline
         if "\r" in source:
             source = source.replace("\r\n", "\n").replace("\r", "\n")
         if not source.endswith("\n"):
@@ -319,8 +321,6 @@ class Obfuscator(BaseObfuscator):
         tokens = IndentsObfuscator().obfuscate_tokens(tokens)
         tokens = NewlineObfuscator().obfuscate_tokens(tokens)
 
-        from tokenize import COMMENT, NEWLINE
-
         tokens = [(COMMENT, "# I love circles <3"), (NEWLINE, "\n"), *tokens]
 
         return self._untokenize(tokens)

python_obfuscation_framework-1.7.0/pof/obfuscator/junk/add_comments.py

@@ -0,0 +1,58 @@
+# POF, a free and open source Python obfuscation framework.
+# Copyright (C) 2022 - 2025  POF Team
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+# TODO (deoktr): calculate frequency based on the number of lines to distribute
+# the comment evenly across the code
+import random
+from tokenize import COMMENT, DEDENT, INDENT, NEWLINE
+
+from pof.utils.generator import CommentGenerator
+
+
+class AddCommentsObfuscator:
+    """Add comments to the code."""
+
+    def __init__(
+        self,
+        frequency=0.03,
+        generator=None,
+    ) -> None:
+        self.frequency = frequency
+
+        if generator is None:
+            generator = CommentGenerator.realistic_generator()
+
+        self.generator = generator
+
+    def get_comment(self):
+        return next(self.generator)
+
+    def obfuscate_tokens(self, tokens):
+        result = []  # obfuscated tokens
+        for toknum, tokval, *_ in tokens:
+            new_tokens = [(toknum, tokval)]
+
+            if (
+                toknum in [NEWLINE, INDENT, DEDENT]
+                and (random.randint(0, 100) / 100) <= self.frequency
+            ):
+                c = self.get_comment()
+                if c is not None:
+                    new_tokens.extend([(COMMENT, c), (NEWLINE, "\n")])
+
+            if new_tokens:
+                result.extend(new_tokens)
+        return result

python_obfuscation_framework-1.7.0/pof/utils/format.py

@@ -0,0 +1,35 @@
+# POF, a free and open source Python obfuscation framework.
+# Copyright (C) 2022 - 2025  POF Team
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+
+import logging
+
+try:
+    import black
+
+    BLACK_INSTALLED = True
+except ImportError:
+    BLACK_INSTALLED = False
+
+from pof.errors import PofError
+
+
+def black_format(src: str) -> str:
+    """Format raw source code using black."""
+    if not BLACK_INSTALLED:
+        logging.error("'black' is not installed, cannot format using it")
+        return src
+    return black.format_str(src, mode=black.FileMode())

{python_obfuscation_framework-1.6.2 → python_obfuscation_framework-1.7.0}/pof/utils/generator/__init__.py

@@ -17,17 +17,18 @@
 """Random names generators.
 
 https://docs.python.org/3/reference/lexical_analysis.html#identifiers.
-
-this is invisible unicode ? in VIM the second unicdoe doesn't appear !
-
-봀
-ݻ
-ࡡ
 """
 
 from .advanced import AdvancedGenerator
 from .base import BaseGenerator
 from .basic import BasicGenerator
+from .comments import CommentGenerator
 from .unicode import UnicodeGenerator
 
-__all__ = ["AdvancedGenerator", "BaseGenerator", "BasicGenerator", "UnicodeGenerator"]
+__all__ = [
+    "AdvancedGenerator",
+    "BaseGenerator",
+    "BasicGenerator",
+    "CommentGenerator",
+    "UnicodeGenerator",
+]

python_obfuscation_framework-1.7.0/pof/utils/generator/comments.py

@@ -0,0 +1,41 @@
+# POF, a free and open source Python obfuscation framework.
+# Copyright (C) 2022 - 2025  POF Team
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Random comments generators."""
+
+import random
+from pathlib import Path
+
+from .base import BaseGenerator
+
+
+class CommentGenerator(BaseGenerator):
+    @classmethod
+    def realistic_generator(cls):
+        """Random comment that can be variables."""
+        # the comments.txt file was generated from the source of all Python 3.13
+        # standard librairies, and the script used to generate it is present in
+        # scripts/extract_comments.py
+        file = Path(__file__).parent / "comments.txt"
+        with file.open() as file:
+            comment_list = [line.rstrip() for line in file]
+        previous = []
+        while True:
+            comment = random.choice(comment_list)
+            if not comment.startswith("#"):
+                continue
+            previous.append(comment)
+            yield comment