Metadata-Version: 2.4
Name: pyouro
Version: 1.0.1
Summary: The Ultimate Cryptographic Trust Anchor for Python Applications
Home-page: https://github.com/Gabro29/PyOuro
Author: Gabriele
Author-email: gabriele.locascio99@gmail.com
Project-URL: Source Code, https://github.com/Gabro29/PyOuro
Project-URL: Bug Tracker, https://github.com/Gabro29/PyOuro/issues
Project-URL: Documentation, https://github.com/Gabro29/PyOuro#readme
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Requires-Dist: toml>=0.10.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: cython>=3.0.0
Provides-Extra: standalone
Requires-Dist: pyinstaller>=6.0.0; extra == "standalone"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">
  <h1>🛡️ PyOuro</h1>
  <p><strong>The Ultimate Cryptographic Trust Anchor for Python Applications</strong></p>
  <p>
    PyOuro is a military-grade DRM and anti-tampering framework designed to protect proprietary Python code, AI models, and intellectual property from reverse engineering, memory dumping, and software piracy.
  </p>
</div>

---

## 🚀 Why PyOuro?

Python is notoriously difficult to protect. Standard obfuscators and compilers like PyInstaller or Cython can be trivially reversed using bytecode decompilers and memory dumpers. 

PyOuro changes the paradigm. It doesn't just "obfuscate" your code; it **cryptographically seals it** into an impregnable vault that dynamically binds to the host operating system and hardware.

## 🔐 Core Security Architecture

### 1. Hardware Cryptographic Binding (Fail-Secure)
Licenses are not verified via easily-hookable boolean checks (`if valid: ...`). Instead, PyOuro implements **Cryptographic Binding**. The developer's Master Key is encrypted using an AES-GCM cipher derived directly from the physical Hardware ID (UUID, BIOS, SMART Data) of the client's machine. 
If the software is copied to another PC, the AES decryption mathematically fails (`InvalidTag`), making tampering impossible without a rootkit.

### 2. Multi-Layer AES-GCM Encryption
Your source code is compiled down to bytecode, serialized, and deeply encrypted using AES-GCM (`payload.pyob`). The payload is decrypted strictly in-memory during execution. No unencrypted files ever touch the disk.

### 3. Dynamic Cython Bootloader & Hash-Map Integrity
The application is launched via a secure C-extension bootloader (`.pyd` / `.so`) written in Cython. At build time, the Bootloader dynamically maps all encrypted dependencies and verifies their SHA-256 hashes against a hardcoded internal ledger. Any file substitution triggers an immediate cryptographic crash.

### 4. Cross-Platform Interpreter Anti-Tampering (PyInstaller)
When deployed as a standalone executable via PyInstaller (`--target onedir`), PyOuro locates the native Python Interpreter library (e.g., `python310.dll` or `libpython3.so`) and seals its hash into the bootloader. If an attacker replaces the Python DLL to intercept the execution engine and dump the bytecode, the application will forcefully exit.

### 5. Asymmetric RSA-PSS Licensing
All licenses (`license.sig`) are strictly verified via RSA-PSS signatures. The Private Key never leaves the developer's machine, while the Public Key is mathematically embedded inside the Cython bootloader.

### 6. Opaque Runtime Failure (Static Analysis Resistance)
All distributed binary modules (`.pyd` / `.so`) are hardened against static analysis. No descriptive error strings are embedded in the distributed code — every runtime failure exits silently with `sys.exit(1)` or raises an opaque code (e.g. `E01`). An attacker using `strings` on the compiled binaries cannot discover which protections are active, how many checks exist, or what each check validates.

## 📦 Installation & Setup

1. Install PyOuro requirements:
   ```bash
   pip install pyouro
   ```
   *(Optional) To build standalone executables with PyInstaller:*
   ```bash
   pip install pyouro[standalone]
   ```

   **Core dependencies** (installed automatically): `cryptography`, `toml`, `pyyaml`, `keyring`, `cython`.

2. Initialize your project:
   ```bash
   pyouro init --entry-point main.py --payload core.py
   ```
   This generates your `private.pem`, `public.pem`, and `pyouro.toml` configuration.

## 🛠️ Usage

### Building the Project
To compile your Python scripts into a secure PyOuro bundle:
```bash
# Protected Mode (Requires Python on client machine)
pyouro build 

# Standalone Executable Mode (Bundles Python & Native Libraries)
pyouro build --target onedir
```

### Issuing Licenses
When a client purchases your software, they provide their Hardware ID. You generate their unique license using:
```bash
pyouro license --hw-id "MB_12345|OS_67890" --type FULL
```
For a demo version expiring in 30 days:
```bash
pyouro license --hw-id "MB_12345|OS_67890" --type DEMO --expiry 30d
```

### System Health Check
To verify the integrity of your PyOuro environment:
```bash
pyouro doctor
```

### Cleaning the Project
To remove all cryptographic artifacts and distribution files (with automatic backup):
```bash
pyouro clean
```
> ⚠️ This is a **destructive** operation. You will be asked for explicit confirmation (`YES`) unless `--force` is used.

### Rebuilding the Project
To wipe all cryptographic artifacts and perform a clean build in one step:
```bash
pyouro rebuild [--target onedir]
```
> ⚠️ This is a **destructive** operation. A timestamped backup of `.pyouro/` is created automatically before any deletion.

## 🧪 Running Tests

The test suite validates the cryptographic engine and the full license cycle:
```bash
python -m pytest tests/ -v
```

## 🛡️ Roadmap & Advanced Mitigations

The `docs/SECURITY_ROADMAP.md` file tracks the full history of resolved vulnerabilities and upcoming mitigations, including:
- **OS-Level Anti-Debugging (Memory Protection)**: Integrating `ptrace(PT_DENY_ATTACH)` (macOS/Linux) and `CheckRemoteDebuggerPresent` (Windows) at the C-level to prevent GDB/Cheat Engine from dumping the RAM.
- **Native C/C++ Hardware Fingerprinting**: Bypassing `subprocess` completely and querying kernel-level APIs (`DeviceIoControl`, `IOKit`) to prevent OS-level Hardware ID spoofing.

## ⚖️ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

PyOuro is an open-source project aimed at researching and democratizing software protection techniques. Contributions are welcome!
