CodexShield 1.0.5

Compile and protect Python scripts from decompilation

CodexShield

Compile and protect Python scripts from decompilation — works like Nuitka, protects better.

Install

pip install CodexShield

Or from source:

git clone https://github.com/yourname/CodexShield
cd CodexShield
pip install -e ".[all]"

Dependencies:

Package	Purpose
cython	Compile Python → native machine code
pyinstaller	Bundle into standalone EXE
psutil (optional)	Process-name anti-debug check
UPX (optional binary)	Compress the EXE — upx.github.io

A C compiler is also required: MSVC on Windows, GCC/Clang on Linux/macOS.

---

Usage

Command line (like Nuitka)

# Basic — produces dist/myscript.exe
python -m CodexShield myscript.py

# or after pip install:
CodexShield myscript.py

# Custom name + icon, hide console window
CodexShield myscript.py --output-filename=MyApp --icon=app.ico --windows-disable-console

# Output to a specific folder
CodexShield myscript.py --output-dir=build

# Compile to .pyd/.so only (no EXE)
CodexShield myscript.py --module

# Just print obfuscated source (no compile)
CodexShield myscript.py --obfuscate-only

# Directory bundle instead of single file
CodexShield myscript.py --onedir

# Disable specific protection layers
CodexShield myscript.py --no-flatten --no-junk

# Show version
CodexShield --version

Python API

import CodexShield

# Full pipeline — returns path to EXE
exe = CodexShield.compile("myscript.py")

# With options
exe = CodexShield.compile(
    "myscript.py",
    output_dir="build",
    output_filename="MyApp",
    windows_disable_console=True,
    icon="app.ico",
    enable_upx=True,
)

Advanced — use CompileOptions directly

from CodexShield.core.options import CompileOptions
from CodexShield.core.pipeline import Pipeline

opts = CompileOptions(
    source="myscript.py",
    output_dir="build",
    output_filename="MyApp",
    onefile=True,
    windows_disable_console=True,
    rename_symbols=True,
    encrypt_strings=True,
    flatten_flow=True,
    inject_opaques=True,
    inject_junk=True,
)

exe = Pipeline(opts).run()
print(f"Built: {exe}")

Add anti-debug to your script

Put this at the very top of myscript.py:

from CodexShield.antidbg import guard
guard()  # silently exits if a debugger or RE tool is detected

def main():
    print("Hello, protected world!")

---

Protection layers

Layer	What it defeats
Symbol renaming	All function/class/variable names → random gibberish
String encryption	Every string XOR-encrypted with a per-file random key
Control flow flattening	Function bodies → while True dispatch loops with random state IDs
Opaque predicates	Always-false dead branches injected everywhere
Junk code injection	Harmless noise statements scattered throughout
Cython native compile	Real .pyd/.so machine code — zero Python bytecode in the binary
Symbol stripping	All debug symbols removed
UPX compression	Binary packed and compressed
Anti-debug runtime	Detects x64dbg, IDA, OllyDbg, GDB, Cheat Engine, Frida, etc.

How it compares

	PyInstaller	Nuitka	CodexShield
Python bytecode in EXE	✅ yes	partial	❌ none
pyinstxtractor works	✅ yes	❌ no	❌ no
uncompyle6 works	✅ yes	partial	❌ no
Symbol names visible	✅ yes	✅ yes	❌ no
Strings visible in binary	✅ yes	✅ yes	❌ no
Control flow readable	✅ yes	partial	❌ no
Anti-debug	❌ no	❌ no	✅ yes

CLI reference

usage: CodexShield [options] source.py

positional:
  source                    Python source file

output:
  --output-dir DIR          Output directory (default: dist)
  --output-filename NAME    Override binary name

build mode:
  --standalone              Bundle all deps into EXE (default)
  --module                  Compile to .pyd/.so only
  --obfuscate-only          Print obfuscated source, no compile

exe options:
  --onefile                 Single EXE (default)
  --onedir                  Directory bundle
  --windows-disable-console Hide console window
  --icon FILE               .ico / .icns icon path
  --no-upx                  Disable UPX compression

obfuscation:
  --no-rename               Disable symbol renaming
  --no-encrypt              Disable string encryption
  --no-flatten              Disable control flow flattening
  --no-opaques              Disable opaque predicates
  --no-junk                 Disable junk code

misc:
  --keep-temp               Keep intermediate build files
  --quiet / -q              Suppress output
  --version / -V            Show version