Metadata-Version: 2.4
Name: mimic-shield
Version: 1.0.0
Summary: Advanced Polymorphic Python Script Protector, Bytecode Obfuscator & Execution Shield.
Author-email: MimicPy Team <team@mimicpy.dev>
License: MIT
Project-URL: Homepage, https://github.com/mimicpy/mimic-shield
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# MimicShield 🛡️
> **Advanced Polymorphic Python Script Protector, Bytecode Obfuscator & Execution Shield**

[![PyPI - Version](https://img.shields.io/pypi/v/mimic-shield)](https://pypi.org/project/mimic-shield/)
[![Python Versions](https://img.shields.io/pypi/pyversions/mimic-shield)](https://pypi.org/project/mimic-shield/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MimicShield (mimic-shield) is a multi-layered Python script protection framework developed as a collaborative 4-person engineering project. Unlike standard packers that simply base64-encode strings, MimicShield compiles your Python source into compiled AST bytecode, compresses it through dual-stage LZMA/zlib algorithms, seals it with an HMAC-SHA256 integrity checksum, and executes directly in memory using a rolling XOR polymorphic loader.

---

## 👥 4-Person Architecture & Contribution Matrix

This project is cleanly modularized into 4 independent sub-systems, each handled by one dedicated team member:

| Member | Module | Primary Role & Responsibilities |
| :--- | :--- | :--- |
| **Member 1** | [`mimicpy/encoder.py`](file:///c:/Users/unixb/OneDrive/Desktop/wasim-encz/mimicpy/encoder.py) | **Core Encryption & Bytecode Serialization**<br>• AST compilation into bytecode (`marshal`)<br>• Dual-stage compression (LZMA + zlib)<br>• Dynamic rolling XOR feedback stream cipher<br>• Base85 payload armoring |
| **Member 2** | [`mimicpy/verifier.py`](file:///c:/Users/unixb/OneDrive/Desktop/wasim-encz/mimicpy/verifier.py) | **Anti-Reverse Engineering & Integrity Verification**<br>• Active debugger detection (`sys.gettrace`, `pydevd`, `ptvsd`)<br>• Delta timing discrepancy checks (anti-stepping)<br>• HMAC-SHA256 digital signature tamper-seal<br>• Anti-clock rollback network time validation (HTTP/NTP) |
| **Member 3** | [`mimicpy/generator.py`](file:///c:/Users/unixb/OneDrive/Desktop/wasim-encz/mimicpy/generator.py) | **Polymorphic Stub Synthesizer & Obfuscator**<br>• Dynamic identifier generator (memory-offset spoofing)<br>• Opaque mathematical predicates & dead-code injection<br>• Direct-to-RAM bytecode loader (zero disk touching)<br>• Memory frame eradication & variable wiping |
| **Member 4** | [`mimicpy/cli.py`](file:///c:/Users/unixb/OneDrive/Desktop/wasim-encz/mimicpy/cli.py) | **CLI Interface & Pipeline Orchestrator**<br>• High-performance CLI argument parser (`argparse`)<br>• Interactive terminal interface with banner<br>• End-to-end pipeline orchestration across all modules<br>• Compression & payload metric reporting |

---

## 🔒 Why Reverse Engineering & AI Analysis Fail

Traditional obfuscators fail because they pass plain strings to `exec()`, which anyone can intercept with `print()`. MimicShield uses multi-barrier defenses:

1. **No Plaintext Source in Output:** The original code is compiled into raw Python bytecode and serialized with `marshal`. Static deobfuscators and LLMs see only base85 ciphertext.
2. **Anti-Stepping & Breakpoint Defense:** If an analyst sets breakpoints in an IDE or runs step-through debuggers, high-precision delta counters detect the execution latency and terminate immediately.
3. **Anti-Tampering HMAC Seal:** Modifying even a single character in the payload or attempting to replace variables invalidates the HMAC-SHA256 signature, immediately aborting execution.
4. **Opaque Predicates to Confuse AI Analyzers:** Dynamic junk branches and mathematical noise prevent AI reasoning engines and static CFG (Control Flow Graph) builders from tracing execution flow.
5. **Anti-Rollback Time Lock:** The expiration mechanism queries external authoritative HTTP/NTP date headers to verify timestamps even if an attacker alters their local system clock.

---

## 🚀 Installation

Install via pip:

```bash
pip install mimic-shield
```

Or install locally in editable development mode:

```bash
git clone https://github.com/mimicpy/mimicpy.git
cd mimicpy
pip install -e .
```

---

## 💻 Usage

### 1. Interactive CLI Mode

Simply run the command:

```bash
mimic
# or
mimicpy
```

Follow the prompts:
1. Enter the target script filename (e.g. `main.py`).
2. Select protection preset:
   - **Preset 1:** High Protection (Anti-Debug + Timing Check + No Expiration).
   - **Preset 2:** Timed License (High Protection + Set Hard Expiry Date & Time).
   - **Preset 3:** Custom Protections.

Output is generated as `mimic_<script_name>.py`.

### 2. Command Line Automation Mode

For headless builds and automated scripting:

```bash
# Basic high-protection armor
mimic -i bot.py -o protected_bot.py

# With network-verified hard expiration
mimic -i bot.py -o protected_bot.py -e "2026-12-31 23:59"

# Without anti-debugging check (e.g. for development testing)
mimic -i bot.py -o protected_bot.py --no-anti-debug
```

---

## 🏗️ Architecture Flow

```
[Raw Python Script]
       │
       ▼ [Member 1: encoder.py]
  AST Compile ──► Marshal Bytes ──► Dual Compress (LZMA+Zlib) ──► Rolling XOR
       │
       ▼ [Member 2: verifier.py]
  HMAC-SHA256 Seal + Anti-Debug + Timing Probe + Network Expiry Logic
       │
       ▼ [Member 3: generator.py]
  Opaque Predicate Injection + Polymorphic Identifiers + Direct Memory Loader
       │
       ▼ [Member 4: cli.py]
  Assembled Executable: mimic_<script>.py (Direct RAM Execution via marshal.loads)
```

---

## 📜 License

Distributed under the MIT License. See `LICENSE` for more information.
