Metadata-Version: 2.4
Name: CodexShield
Version: 1.0.3
Summary: Compile and protect Python scripts from decompilation
License: MIT
Project-URL: Homepage, https://github.com/yourname/codexshield
Project-URL: Issues, https://github.com/yourname/codexshield/issues
Keywords: compiler,obfuscator,protection,cython,exe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Security
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cython>=3.0
Requires-Dist: setuptools>=68.0
Requires-Dist: wheel>=0.41
Provides-Extra: exe
Requires-Dist: pyinstaller>=6.0; extra == "exe"
Provides-Extra: process-guard
Requires-Dist: psutil>=5.9; extra == "process-guard"
Provides-Extra: all
Requires-Dist: pyinstaller>=6.0; extra == "all"
Requires-Dist: psutil>=5.9; extra == "all"

# CodexShield

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

## Install

```bash
pip install CodexShield
```

Or from source:

```bash
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](https://upx.github.io) |

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

---

## Usage

### Command line (like Nuitka)

```bash
# 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

```python
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

```python
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`:

```python
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
```
