🐍 PyCry

A terminal-based Python obfuscation and multi-layer encoding toolkit.

Encode, obfuscate, and wrap Python payloads through a modular RedTiger-inspired CLI.

Features · Installation · Usage · Architecture · Roadmap · Contributing · FAQ

---

⚠️ IMPORTANT DISCLAIMER — PyCry is an educational tool for exploring Python obfuscation techniques, encoding pipelines, and CLI architecture. It does not provide cryptographic security or encryption in any meaningful security sense. It must never be used to protect sensitive data, bypass security controls, or facilitate malicious activity. See the Security Disclaimer for full details.

---

📖 Overview

PyCry is a Python developer utility and learning project that demonstrates how code obfuscation, encoding, and multi-layer payload wrapping work at a practical level.

It is built as a terminal UI application inspired by RedTiger-style CLI aesthetics — modular menus, banner-driven navigation, and chainable encode/decode operations. The goal is to give developers and students a hands-on toolkit for exploring:

• How Python bytecode and source can be transformed through encoding pipelines
• How exec() wrappers and self-unpacking payloads work conceptually
• How to build modular, menu-driven CLI applications in Python
• How multi-layer compression + encoding affects code readability and size

PyCry is explicitly not a security tool. It does not implement cryptographic primitives, does not protect data from a determined analyst, and should never be positioned as doing so.

---

✨ Features

✅ Currently Implemented

Feature	Description
Code Encrypt Direct	Obfuscate Python source code pasted directly into the terminal
Code Decrypt Direct	Reverse-process an obfuscated payload back to readable source
File Encrypt	Apply obfuscation pipeline to a .py file on disk
File Decrypt	Decode a previously obfuscated .py file
Multi-layer Payload Wrapping	Chain zlib compression, base64 encoding, and byte reversal
Exec Wrapper Generation	Produce self-unpacking Python stubs
Modular Menu System	Categorised terminal UI with keyboard-driven navigation
Banner & Color UI	RedTiger-inspired ASCII art banners and ANSI color output

🔜 Planned Features (Roadmap)

Feature	Category	Status
Base64 Encode / Decode	Encoding Utilities	Planned
Hex Encode / Decode	Encoding Utilities	Planned
URL Encode / Decode	Encoding Utilities	Planned
Code Analyzer	Analysis Tools	Planned
Code Beautifier	Formatting Tools	Planned
Code Minifier	Formatting Tools	Planned
Variable Renamer	Obfuscation Tools	Planned
Comment Remover	Obfuscation Tools	Planned
Batch File Processing	Workflow	Planned
Plugin System	Architecture	Planned

---

📸 Screenshots

Screenshots will be added once the v1.0.0 terminal UI is finalised.

[ Banner / Main Menu Screenshot Here ]

[ File Encryption Workflow Screenshot Here ]

[ Code Obfuscation Output Screenshot Here ]

[ Multi-layer Decode Demo Screenshot Here ]

---

🛠 Installation

Requirements

• Python 3.8 or higher
• pip (bundled with Python 3.8+)
• Terminal with ANSI color support (Linux, macOS, Windows Terminal)

Option 1 — Clone and Run (Development)

# Clone the repository
git clone https://github.com/YOUR_USERNAME/pycry.git
cd pycry

# (Recommended) Create a virtual environment
python -m venv .venv
source .venv/bin/activate      # Linux / macOS
.venv\Scripts\activate         # Windows

# Install dependencies
pip install -r requirements.txt

# Launch PyCry
python -m pycry

Option 2 — Install via pip (once published)

pip install pycry
pycry

Option 3 — pipx (isolated install, recommended for CLI tools)

pipx install pycry
pycry

---

🚀 Usage

Launching the CLI

python -m pycry

You will be presented with the main menu:

╔══════════════════════════════════════════╗
║              P Y C R Y  v1.0             ║
║     Python Obfuscation & Encoding Kit    ║
╠══════════════════════════════════════════╣
║  [1] Code Operations                     ║
║  [2] File Operations                     ║
║  [3] Encoding Utilities                  ║
║  [4] Analysis Tools                      ║
║  [5] Settings                            ║
║  [0] Exit                                ║
╚══════════════════════════════════════════╝

Example: Obfuscate a Python file

# Interactive mode (recommended)
python -m pycry

# Navigate: File Operations → File Encrypt → enter path

# CLI flags (planned for v1.1)
python -m pycry encrypt --input script.py --output obfuscated.py --layers 3

Example: Decode an obfuscated payload

python -m pycry decrypt --input obfuscated.py --output recovered.py

Example: Direct code input

python -m pycry encrypt --code "print('hello world')" --layers 2

Python API (programmatic use)

from pycry.core import encoder, decoder

# Obfuscate source code
source = "print('hello, world')"
obfuscated = encoder.encode(source, layers=3)

# Recover original
recovered = decoder.decode(obfuscated)
print(recovered)

---

🏗 Architecture

How the Obfuscation Pipeline Works

PyCry chains multiple reversible transformations to produce an obfuscated but executable Python payload:

Input Source Code
       │
       ▼
┌─────────────────┐
│  1. zlib        │  ← Compress source bytes
│     Compress    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  2. Byte        │  ← Reverse the compressed byte sequence
│     Reversal    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  3. Base64      │  ← Encode to printable ASCII
│     Encode      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  4. exec()      │  ← Wrap in self-unpacking Python stub
│     Wrapper     │
└────────┬────────┘
         │
         ▼
  Obfuscated Output (.py)
  (still valid Python — runs via exec chain)

Each layer is fully reversible. The decode pipeline simply inverts the steps. This is not encryption — anyone with Python knowledge can reverse this manually in minutes.

Directory Structure (current)

pycry/
├── pycry/                    # Main package
│   ├── __init__.py
│   ├── __main__.py           # Entry point: python -m pycry
│   ├── cli/                  # Menu system & terminal UI
│   │   ├── __init__.py
│   │   ├── menu.py           # Main menu router
│   │   ├── banners.py        # ASCII art & ANSI colors
│   │   └── navigation.py     # Input handling & flow control
│   ├── core/                 # Business logic (pure functions)
│   │   ├── __init__.py
│   │   ├── encoder.py        # Encoding/obfuscation pipeline
│   │   ├── decoder.py        # Decoding/deobfuscation pipeline
│   │   └── transforms/       # Individual transform steps
│   │       ├── __init__.py
│   │       ├── compression.py
│   │       ├── base64_ops.py
│   │       ├── byte_ops.py
│   │       └── wrappers.py
│   ├── analysis/             # Code analysis tools (planned)
│   │   ├── __init__.py
│   │   ├── analyzer.py
│   │   ├── beautifier.py
│   │   └── minifier.py
│   ├── encoding/             # Encoding utility tools (planned)
│   │   ├── __init__.py
│   │   ├── base64_util.py
│   │   ├── hex_util.py
│   │   └── url_util.py
│   └── utils/                # Shared utilities
│       ├── __init__.py
│       ├── file_io.py        # Safe file read/write helpers
│       ├── validators.py     # Input validation
│       └── logging_conf.py   # Logging setup
├── tests/                    # Test suite
│   ├── __init__.py
│   ├── test_encoder.py
│   ├── test_decoder.py
│   └── test_transforms/
│       ├── test_compression.py
│       ├── test_base64_ops.py
│       └── test_byte_ops.py
├── examples/                 # Usage examples & demo scripts
│   ├── basic_encode.py
│   ├── multi_layer_demo.py
│   └── file_workflow_demo.py
├── docs/                     # Extended documentation
│   ├── architecture.md
│   ├── transforms.md
│   └── contributing.md
├── .github/
│   ├── workflows/
│   │   ├── ci.yml            # Lint + test on push/PR
│   │   └── release.yml       # PyPI publish on tag
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── PULL_REQUEST_TEMPLATE.md
├── pyproject.toml            # Build config (PEP 517/518)
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── LICENSE
└── .gitignore

---

🔧 Development Setup

Install in editable mode with dev dependencies

pip install -e ".[dev]"

Run the test suite

pytest tests/ -v --cov=pycry --cov-report=term-missing

Lint and format

ruff check .
ruff format .
mypy pycry/

Pre-commit hooks

pip install pre-commit
pre-commit install

---

📦 pyproject.toml Reference

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "pycry"
version = "1.0.0"
description = "A terminal-based Python obfuscation and multi-layer encoding toolkit"
readme = "README.md"
license = { file = "LICENSE" }
requires-python = ">=3.8"
authors = [{ name = "Your Name", email = "you@example.com" }]
keywords = [
  "obfuscation", "encoding", "cli", "python", "educational",
  "developer-tools", "terminal", "payload-encoding"
]
classifiers = [
  "Development Status :: 4 - Beta",
  "Environment :: Console",
  "Intended Audience :: Developers",
  "Intended Audience :: Education",
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.8",
  "Programming Language :: Python :: 3.9",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Topic :: Software Development :: Libraries :: Python Modules",
  "Topic :: Utilities",
]
dependencies = [
  "rich>=13.0.0",         # Terminal formatting
  "click>=8.0.0",         # CLI framework
  "black>=24.0.0",        # Code beautifier backend
  "pyminifier>=2.1",      # Minifier backend (or custom impl)
]

[project.optional-dependencies]
dev = [
  "pytest>=8.0",
  "pytest-cov",
  "ruff",
  "mypy",
  "pre-commit",
]

[project.scripts]
pycry = "pycry.__main__:main"

[project.urls]
Homepage = "https://github.com/YOUR_USERNAME/pycry"
Repository = "https://github.com/YOUR_USERNAME/pycry"
Issues = "https://github.com/YOUR_USERNAME/pycry/issues"
Changelog = "https://github.com/YOUR_USERNAME/pycry/CHANGELOG.md"

[tool.ruff]
line-length = 100
target-version = "py38"

[tool.mypy]
python_version = "3.8"
strict = true
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=pycry"

---

🗺 Roadmap

v1.0.0 — Foundation (current target)

• Core encode/decode pipeline
• File encrypt/decrypt workflow
• Direct code input processing
• Multi-layer payload wrapping
• Terminal UI with banners
• Full test coverage (>80%)
• pyproject.toml packaging
• Published to PyPI

v1.1.0 — Encoding Utilities

• Base64 encode/decode utility
• Hex encode/decode utility
• URL encode/decode utility
• CLI flag interface (--input, --output, --layers)
• Rich-powered terminal UI upgrade

v1.2.0 — Analysis Tools

• Code analyzer (metrics: LOC, complexity, token count)
• Code beautifier (black integration)
• Code minifier
• Comment remover
• Variable renamer (AST-based)

v1.3.0 — Workflow & Architecture

• Batch file processing (--batch ./src/)
• Plugin system (register custom transforms)
• Pipeline config files (YAML/TOML-defined chains)
• Output format options (raw, exec-wrapped, base64-only)

v2.0.0 — Extended Platform

• Web UI (optional Flask/FastAPI companion)
• VSCode extension integration
• Jupyter notebook widget
• REST API mode

---

🔐 Security Disclaimer

READ THIS CAREFULLY.

PyCry is an educational obfuscation tool. It does:

• ✅ Encode Python source code through reversible transformations
• ✅ Wrap payloads in exec() chains for self-unpacking
• ✅ Demonstrate encoding pipeline concepts clearly

PyCry does NOT:

• ❌ Provide cryptographic security of any kind
• ❌ Protect sensitive data, secrets, or credentials
• ❌ Prevent a skilled analyst from reading the original source
• ❌ Implement any recognised encryption standard (AES, RSA, ChaCha20, etc.)
• ❌ Provide tamper resistance or integrity guarantees

If you need to protect real secrets or sensitive code, use proper cryptographic tools such as PyNaCl, cryptography, or hardware-backed secret stores.

The obfuscation produced by PyCry can be reversed by any developer with basic Python knowledge and a few minutes of time. It is not a security boundary.

---

⚠️ Educational Use Disclaimer

This project is provided for educational and research purposes only.

• Do not use this tool to obfuscate malicious code, malware, or scripts intended to harm systems or users.
• Do not use this tool to bypass security controls, scanners, or monitoring systems.
• Do not distribute obfuscated code without making clear to recipients what it contains.

The author(s) accept no responsibility for misuse of this software. By using PyCry you agree that you are solely responsible for how you apply it.

---

🤝 Contributing

Contributions are very welcome! PyCry is an educational project and a great place to learn CLI design, pipeline architecture, and Python packaging.

How to contribute

1. Fork this repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/pycry.git
3. Create a branch: git checkout -b feature/your-feature-name
4. Make your changes with tests
5. Run the test suite: pytest tests/ -v
6. Lint your code: ruff check . && ruff format .
7. Open a Pull Request — fill in the PR template

Good first issues for new contributors

• 🟢 Add type hints to existing functions
• 🟢 Write unit tests for the base64 transform
• 🟢 Improve docstrings across core modules
• 🟡 Implement the hex encode/decode utility
• 🟡 Implement the URL encode/decode utility
• 🟡 Add --version and --help CLI flags
• 🔴 Implement AST-based variable renamer
• 🔴 Design and implement the plugin system interface

Please read CONTRIBUTING.md before opening a pull request.

---

📋 FAQ

Q: Is this real encryption?

No. PyCry uses encoding and compression, not cryptographic encryption. Anyone with Python can reverse it quickly. Do not use it to protect sensitive information.

Q: Why does it use exec()?

The self-unpacking stub pattern relies on exec() to evaluate the decoded source at runtime. This is a common educational demonstration of how dynamic code execution works in Python. Many static analysis tools will flag exec() usage — this is expected and intentional in this context.

Q: Can I add custom transform steps?

Not yet directly, but the plugin system (planned for v1.3.0) will support registering custom transform functions. For now, you can add a module to pycry/core/transforms/ and wire it into the pipeline manually.

Q: Does this work on Windows?

Yes. ANSI color output requires Windows Terminal or a terminal emulator that supports ANSI escape codes. The legacy Windows console (cmd.exe without Windows Terminal) may show garbled output.

Q: Why not use an existing obfuscation tool like PyArmor?

PyCry is not intended to compete with production obfuscation tools. It is built to be readable, educational, and hackable — the goal is to understand how these pipelines work, not to produce unbreakable obfuscation.

Q: Can I use this in a university course or workshop?

Absolutely. That is exactly what this is designed for. Pair it with a lesson on Python's ast module, bytecode, and exec() semantics.

Q: What Python versions are supported?

Python 3.8 and above. Older versions are not tested and may not work.

---

📄 License

MIT License

Copyright (c) 2024 [Your Name]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

See LICENSE for full text.

---

👤 Author

Your Name

• GitHub: @x0010100
• Project: PyCry

---

PyCry — educational obfuscation & encoding toolkit

⭐ Star this repo if you found it useful for learning!