From 3d2cc103d70a5b6993c51df1d5d42a527823f82f Mon Sep 17 00:00:00 2001
From: ByteCorum <164874887+ByteCorum@users.noreply.github.com>
Date: Thu, 1 Oct 2026 14:15:08 +0200
Subject: [PATCH] docs(readme): rewrite readme to explain all new functionality
---
.gitignore | 3 +-
README.md | 416 +++++++++++++++++++++-----
docs/CONTRIBUTING.md | 118 +++++++-
src/commands/obfuscation/obfuscate.py | 14 +-
4 files changed, 452 insertions(+), 99 deletions(-)
diff --git a/.gitignore b/.gitignore
index e8b4245..4d709c5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -152,7 +152,6 @@ cython_debug/
.pyvenv/
pyvenv/
.vscode/
-#obfuscated/
-#src/test.py
pyguard
+pyguard/
tmp-exec/
diff --git a/README.md b/README.md
index 84e6081..78a6f0b 100644
--- a/README.md
+++ b/README.md
@@ -1,119 +1,373 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+PyGuard
+
+PyGuard is a Python obfuscation and anti-tampering library with modular architecture. It consists of a main obfuscation engine with multiple encryption layers, legacy obfuscation for backward compatibility, and runtime protection features.
+
+---
+
+Table of Contents
+
+
+
+---
+
+Overview
+
+PyGuard is a Python code protection tool that provides comprehensive obfuscation and anti-tampering capabilities. It offers two distinct obfuscation methods: a modern approach with layered encryption, runtime integrity checks, and anti-analysis protection; and a legacy method focused on preventing antivirus detection through compression and encryption layers.
+
+The tool is designed for developers who need to protect their Python applications from decompilation, reverse engineering, static analysis, unauthorized modification and antivirus detection. PyGuard supports both single file and multi-file project obfuscation, with options to include dependencies and create standalone protected executables.
+
+
+
+ 
+
---
-### ๐กpyguard๐ก
+Features
+
+**Multiple Encryption Layers**
+
+> - Fernet symmetric encryption
+> - AES-GCM-SIV for authenticated encryption
+> - XChaCha20-Poly1305 for modern stream cipher protection
+> - Base64 encoding with compression
+> - Combine multiple layers for defense-in-depth security
+
+**Advanced Obfuscation Techniques**
+
+> - SHA-512 string hashing to protect sensitive literals
+> - Recursive obfuscation with configurable depth
+> - Code compression and byte manipulation
+> - Randomized separators and identifiers
+> - AST-based transformation for robust code handling
+
+**Runtime Protection**
+
+> - Anti-debugging detection (pdb, ipdb, pudb)
+> - Profiler and tracer detection
+> - Environment analysis for hostile conditions
+> - Time-based anti-single-stepping protection
+> - Secure memory wiping of sensitive data
+> - Decoy code execution for hostile environments
+
+**File & Project Protection**
+
+> - Single file and multi-file project obfuscation
+> - Directory recursion for complete project protection
+> - Automatic import following for dependency management
+> - File integrity verification with SHA-512 hashing
+> - Tamper detection and prevention
+
+**Two Obfuscation Modes**
+
+> - **Modern Mode**: Maximum security with runtime protection, integrity checks, and native compilation
+> - **Legacy Mode**: Lightweight obfuscation optimized for antivirus evasion
+> - Both modes support multiple encryption algorithms and techniques
+
+**Developer-Friendly Features**
+
+> - Automatic import following for Nuitka compilation
+> - Configurable output directory
+> - Custom decoy code injection
+> - Verbose and debug modes for development
+> - Cross-platform support (Windows, Linux, macOS)
+> - Python 3.12+ compatibility
+
+**Build & Compilation**
-Tool/Library for Python used to obfuscate and protect your code in static and runtime from decompilation, reverse debug, etc. Also, can prevent detection by antiviruses.
+> - Cython-based executor compilation to native extensions
+> - Automatic platform detection (.pyd for Windows, .so for Unix)
+> - Clean build process with intermediate file removal
+> - Dead code elimination for unused protection layers
+
+
+
+
+
+
---
-### ๐ปSupported Platforms๐ป
+Installation and Usage
+
+Installation
+
+PyGuard requires **Python 3.12 or higher** and the following dependencies:
+
+- `cryptography` - for Fernet and AES-GCM-SIV encryption
+- `pycryptodome` - for ChaCha20-Poly1305 encryption
+- `cython` - for executor compilation
+- `nuitka` - for building standalone executables
+- `colorama` - for cross-platform colored output
+- `setuptools` - for build system integration
+
+You can get PyGuard directly from [release section](https://github.com/ByteCorum/pyguard/releases) or clone from source.
+
+**Cloning from source:**
+
+```bash
+git clone https://github.com/ByteCorum/pyguard.git
+cd pyguard
+
+# Virtual environment is recommended
+python -m venv .venv
+source .venv/bin/activate # Linux/macOS
+.\.venv\Scripts\activate # Windows
+
+python -m pip install --upgrade pip
+pip3 install -r requirements.txt
+```
+
+Usage
+
+After installation, you can run PyGuard from the source directory:
+
+```bash
+python -m src.main
+```
+
+Or build a standalone executable:
-- Python 3 up to latest
-- Windows
-- All Linux distributions
-- Mac OS
+```bash
+# Linux/macOS
+chmod +x build-scripts/build-linux.sh # or build-mac.sh
+./build-scripts/build-linux.sh
+
+# Windows
+build-scripts\build-win.cmd
+```
+
+This creates a single executable file (`pyguard` or `pyguard.exe`) that can be used directly.
+
+
+
+
+
+
---
-### ๐งMain Features๐ง
+Configuration
+
+PyGuard can be configured through command-line options. All commands support general options:
+
+Global Configuration
+
+| Option | Description |
+| -------------- | ---------------------------- |
+| `--help` | Show help for commands |
+| `--quiet` | Reduce output verbosity |
+| `--log ` | Duplicate all logs to a file |
+| `--no-color` | Disable colored output |
+| `--no-input` | Disable interactive prompts |
+
+> [!NOTE]
+> PyGuard offers two obfuscation methods: modern and legacy. We recommend using the modern method for maximum security with runtime protection and integrity checks. The legacy method is maintained for compatibility and antivirus evasion scenarios.
+
+Obfuscation Configuration
+
+The main obfuscation command supports extensive configuration:
+
+```bash
+# Enable all encryption layers
+pyguard obfuscate --hashdata --fernet --aes --chacha --base64 --recursive 5 main.py
+
+# For projects with imports
+pyguard obfuscate --hashdata --aes --follow-imports --dirs features/ --files config.py,logger.py main.py
-> **Static & Runtime Protection**
->
-> - Total advanced static and runtime protection from decompilation, reverse debug, etc.
+# With custom output and decoy code
+pyguard obfuscate --hashdata --chacha --decoy decoy.py --output protected/ main.py
-> **Hash Variables**
->
-> - Hash all variables and constants values in fragment of code.
-> - Protects variables and constants content.
+# For debug purposes with no integrity checks
+pyguard obfuscate --hashdata --chacha --no-integrity --debug-error --debug main.py
+```
-> **Recursive obfuscation**
->
-> - Recurseve encrypt fragment of code using base64 and zlib n times.
-> - Best way to decrease/prevent antiviruses detection.
+Legacy Obfuscation Configuration
-> **Best encryption algorithms**
->
-> - Fernet, AES-GCM, ChaCha20, Salsa20
-> - Symmetric cipher which offer strong confidentiality, and provide authentication and integrity to protect against tampering.
+The legacy mode offers simpler configuration:
-> **File Integrity Protection**
->
-> - Protect files against modification.
-> - Advanced file hash/content integrity check and comparison.
+```bash
+# Mode 4 with 6 loops
+pyguard obfuscatelegacy --mode 4 --loops 6 --seplen 32 --files script.py
+
+# For multiple files
+pyguard obfuscatelegacy --mode 3 --loops 3 --dirs utils/,features/ --files main.py --output obfuscated/
+```
+
+
+
+
+
+
---
-### ๐Quick start๐
-
-1. Clone repo
- ```
- git clone https://github.com/ByteCorum/pyguard.git
- ```
-2. Install requirements
- ```
- pip install -r requirements.txt
- ```
-3. Usage info
- ```
- pyguard --help
- ```
-4. Example
- ```
- pyguard obfuscate --hashdata --aes --chacha --follow-imports main.py
- ```
-5. Output
- ```
- #Obfuscated by pyguard 3.1.0.0
- from PyGuard.script_55958136 import PyGuard, _
- _(PyGuard(b'x\x9c\x05\xc1\xc7\xa2k@\x00\x00\xd0\x0f\xb2P\xa3,\xdeB\...')
- ```
-6. Example legacy
- ```
- pyguard obfuscatelegacy --loops 3 --mode 2 --file code.py
- ```
-7. Output legacy
- ```
- _=lambda __:__import__('zlib').decompress(__import__('cryptography.fernet').fernet.Fernet(__import__('base64').b64decode(((__import__('zlib').decompress(__))[::-1].split(b'eY3NTTr:S|dD'))[1])).decrypt(((__import__('zlib').decompress(__))[::-1].split(b'eY3NTTr:S|dD'))[0])[::-1]);exec((_x)(b'x\x9c\x15\x97U\xce\x86\...')
- ```
+Building Obfuscated Code
+
+PyGuard is designed to be compatible with various Python build systems and compilation tools. While obfuscated code remains fully functional as Python scripts, compiling it to a binary executable provides an additional layer of protection.
+
+**Recommended: Nuitka Integration**
+
+We highly recommend using Nuitka to compile your obfuscated code into a standalone executable. PyGuard provides seamless integration:
+
+```bash
+# Obfuscate with import following for Nuitka
+pyguard obfuscate --aes --chacha --follow-imports --output obfuscated/ main.py
+
+# Then compile with Nuitka
+nuitka --follow-imports --remove-output --mode="onefile" obfuscated/main.py
+```
+
+The `--follow-imports` flag automatically includes all necessary imports in your obfuscated code, making it compile-ready.
+
+**Other Build Systems**
+
+PyGuard works with any build system that processes Python code:
+
+- **PyInstaller**: Use with obfuscated scripts directly
+- **cx_Freeze**: Compatible with obfuscated code
+- **Docker containers**: Obfuscate before building your image
+- **Custom build scripts**: Integrate PyGuard into your pipeline
+
+If you encounter any compatibility issues with a specific build system, please [report it](https://github.com/ByteCorum/pyguard/issues/new?template=bug-report.yml) and we'll prioritize fixing it.
+
+
+
+
+
+
---
-### ๐Additional Info๐
+Contributing
+
+**Contributions are welcome**: bug reports, feature ideas, documentation improvements, and code.
+
+Before you start:
+
+- Read [CONTRIBUTING.md](docs/CONTRIBUTING.md) it covers the environment setup, branch and commit conventions, pull request expectations, and the AI-generated changes policy
+- Check [open issues](https://github.com/ByteCorum/pyguard/issues) or start a [discussion](https://github.com/ByteCorum/pyguard/discussions) before significant work, to avoid duplicating effort
> [!NOTE]
-> Obfuscation tool has 2 major versions legacy and main. This repo includes both of them, but we highly recommend you to use the main version, because it much more secure. Anyway, we won't end support of legacy version, so if u have issues, let us know.
+> By participating in this project, you agree to abide by the [Code of Conduct](docs/CODE_OF_CONDUCT.md).
+
+
+
+
+
+
+
+---
+
+Known Issues
+
+Known bugs and planned work are tracked in [TODO.md](docs/TODO.md).
+Everything listed there under "Known Issues" is either being fixed
+or scheduled to be; anything not listed is unknown, so please
+[report it](https://github.com/ByteCorum/pyguard/issues/new?labels=type%3A%20bug&template=bug_report.md).
> [!TIP]
-> We highly recommend compiling obfuscated script using Nuitka. Use `--follow imports` while obfuscating to tell Nuitka what to import
+> Before concluding something is a bug, check Troubleshooting below, as some behavior, that looks broken not depends on this project.
+
+
+
+
+
+
+
+---
+
+Troubleshooting
+
+
+
+So far nothing
+
+
+
+
+
+
---
-### ๐ฒContacts
+License
-
-
+Distributed under the GPLv3 license.
+
+Copyright (c) 2026 ByteCorum.
+
+
+
+
+
+
---
-### ๐ธSupport
+Contact
+
+Community
-
+> [!NOTE]
+> Before participating in this community, please read our [Code of Conduct](docs/CODE_OF_CONDUCT.md). By interacting with this repository or community you agree to abide by its terms.
+
+All ways to contact the community or get help are listed in [SUPPORT.md](docs/SUPPORT.md), but short recap provided below.
+
+- **Bug reports, feature requests, documentation issues** should be reported via issues using appropriate forms [here](https://github.com/ByteCorum/pyguard/issues/new/choose)
+- **Usage questions** are answered in [Discussions](https://github.com/ByteCorum/pyguard/discussions/new?category=q-a), not the issue tracker.
+- **Security Vulnerabilities** should be reported via Security and quality [tab](https://github.com/ByteCorum/pyguard/security/advisories/new)
+
+Contact the Owner
+
+Current contact options are listed in the [owner profile](https://github.com/ByteCorum)
+
+> [!IMPORTANT]
+> Do not email maintainers directly about support matters, because public questions get public answers, which benefits everyone.
+
+
+
+
+
+
---
-[โฌgo upโฌ](#up)
+Support the Project
+
+If this project is useful to you, consider supporting its development.
+
+All ways to donate are listed in the [author's profile](https://github.com/ByteCorum).
+
+
+
+
+
+
+
+---
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 6217561..dea2ca7 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -16,17 +16,117 @@ In particular:
## Environment Setup
-TODO
+### Prerequisites
-
+### Setup
+
+1. Clone the repository:
+
+ ```bash
+ git clone https://github.com/ByteCorum/pyguard.git
+ cd pyguard
+ ```
+
+2. Create and activate a virtual environment (recommended):
+
+ ```bash
+ python -m venv .venv
+ source .venv/bin/activate # Linux/macOS
+ .\.venv\Scripts\activate # Windows
+ ```
+
+3. Install dependencies:
+
+ ```bash
+ pip install -r requirements.txt
+ ```
+
+4. Install development tools:
+ ```bash
+ pip install pyrefly yamllint
+ ```
+
+### Build Command
+
+Build a standalone executable using Nuitka:
+
+```bash
+# Linux/macOS
+chmod +x build-scripts/build-linux.sh
+./build-scripts/build-linux.sh
+
+# Windows
+build-scripts\build-win.cmd
+```
+
+This creates `pyguard` (or `pyguard.exe` on Windows) in the repository root.
+
+### Test Command
+
+Run local tests using the test script:
+
+```bash
+# Run all tests
+./examples/test.sh
+
+# Run specific test group
+./examples/test.sh complex
+./examples/test.sh multifile
+./examples/test.sh onefile
+./examples/test.sh complex-legacy
+./examples/test.sh multifile-legacy
+./examples/test.sh onefile-legacy
+```
+
+All tests verify that obfuscated code produces the expected "hello world" output.
+
+### Lint / Format Command
+
+- **Type checking** (pyrefly):
+
+ ```bash
+ pyrefly check
+ ```
+
+- **YAML linting** (.github/workflows, .yamllint):
+
+ ```bash
+ yamllint .
+ ```
+
+- **EditorConfig**: Configure your editor to use the project's [.editorconfig](../.editorconfig) for consistent formatting:
+ - 4-space indentation
+ - UTF-8 encoding
+ - LF line endings
+ - Trim trailing whitespace
+
+## Codebase Map
+
+```
+src/
+โโโ main.py # Entry point
+โโโ pyguard.py # Core command processor
+โโโ config.py # Global configuration and base classes
+โโโ commands/ # Command implementations
+โ โโโ obfuscation/ # Obfuscation commands
+โ โ โโโ obfuscate.py # Modern obfuscation engine
+โ โ โโโ obfuscatelegacy.py # Legacy obfuscation methods
+โ โโโ basic/ # Utility commands
+โ โโโ help.py # Help system
+โ โโโ info.py # Program information
+โ โโโ dependencies.py # Dependency management
+โโโ utils/ # Core functionality
+ โโโ obfuscation.py # Main obfuscation logic
+ โโโ legacyObfuscation.py # Legacy obfuscation algorithms
+ โโโ crypto.py # Cryptographic implementations
+ โโโ langMgr.py # Source code processing
+ โโโ optionsParser.py # Command-line parsing
+ โโโ logger.py # Logging system
+```
## Making Changes
diff --git a/src/commands/obfuscation/obfuscate.py b/src/commands/obfuscation/obfuscate.py
index a45515e..b3e512e 100644
--- a/src/commands/obfuscation/obfuscate.py
+++ b/src/commands/obfuscation/obfuscate.py
@@ -22,7 +22,7 @@ class Obfuscate(Command):
"--base64": False,
"--recursive": 0,
- "--no-protect": False,
+ "--no-integrity": False,
"--enc-exec" : False,
"--follow-imports" : False,
"--debug-error": False,
@@ -56,7 +56,7 @@ class Obfuscate(Command):
--base64 -> encode entry and exit code with base64
--recursive -> fast recursive approach to prevent antivirus detection
- --no-protect -> disable file integrity checks
+ --no-integrity -> disable file integrity checks
--enc-exec -> obfuscate executor using legacy method; may weaken security
--follow-imports -> add all imports to the protected script to make building easy
--debug-error -> development builds only; executor will give verbose errors
@@ -113,9 +113,9 @@ def ValidateParams(self) -> None:
if self.options["--follow-imports"]:
Log.Info("Follow imports: Enabled")
- if type(self.options["--no-protect"]) != bool:
- raise TypeError(f"invalid \"--no-protect\" variable type: must be \"bool\", but it's \"{type(self.options["--no-protect"])}\"")
- if self.options["--no-protect"]:
+ if type(self.options["--no-integrity"]) != bool:
+ raise TypeError(f"invalid \"--no-integrity\" variable type: must be \"bool\", but it's \"{type(self.options["--no-integrity"])}\"")
+ if self.options["--no-integrity"]:
Log.Warning("File integrity checks: Disabled")
if type(self.options["--enc-exec"]) != bool:
@@ -268,7 +268,7 @@ def ValidateParams(self) -> None:
def ObfuscateFiles(self) -> None:
# pyrefly: ignore [bad-argument-type] - all those were already checked in ValidateParams
- self.obfuscation = MainObfuscation(self.options["--hashdata"], self.options["--fernet"], self.options["--aes"], self.options["--chacha"], self.options["--base64"], self.options["--recursive"], self.options["--no-protect"], self.options["--enc-exec"], self.options["--debug-error"], self.options["--debug"], self.decoySource)
+ self.obfuscation = MainObfuscation(self.options["--hashdata"], self.options["--fernet"], self.options["--aes"], self.options["--chacha"], self.options["--base64"], self.options["--recursive"], self.options["--no-integrity"], self.options["--enc-exec"], self.options["--debug-error"], self.options["--debug"], self.decoySource)
# pyrefly: ignore [not-iterable] - already checked in ValidateParams, self.options["--files"] can only be list[str]
for file in self.options["--files"]:
@@ -362,7 +362,7 @@ def FollowImports(self, content: str) -> None:
if self.options["--follow-imports"]:
modules:list[str] = GetImports(content)
- if not self.options["--no-protect"]:
+ if not self.options["--no-integrity"]:
modules += ["hashlib", "os"]
if self.options["--chacha"]: