Metadata-Version: 2.4
Name: soar_locker
Version: 2.0.1
Summary: SOAR - Secure Obfuscated Archive Runtime (SOAR-Locker)
Author-email: "HuaiYu-Yang@dawlaishi122" <1710802268@qq.com>
License: MIT
Keywords: python encryption,secure python,code protection,machine binding,module encryption,python obfuscation,anti-tamper,aes encrypted python,python protect
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41.0.0
Dynamic: license-file

# SOAR-Locker

**Secure Obfuscated Archives Repository** is a Python source-code protection and device-bound execution utility for controlled deployment environments.

SOAR-Locker converts Python source files into encrypted `.soa` archives. At execution time, the archive is validated against a device fingerprint and decrypted in memory through a native Rust core. The project is designed for scenarios in which Python applications must be deployed to a target machine while reducing direct source-code exposure and limiting unauthorized migration to other devices.

SOAR-Locker is an engineering protection mechanism, not a substitute for formal software licensing, hardware-backed key management, or high-assurance anti-reverse-engineering systems.

## Features

- **Encrypted archive format**: converts `.py` files into binary `.soa` archives.
- **Device-bound execution**: archives are associated with the fingerprint of the machine on which they are generated.
- **Runtime validation**: execution requires a matching runtime environment and device fingerprint.
- **In-memory decryption**: decrypted source is not written back to disk during normal execution.
- **Dual archive modes**: `.soa` is the high-security execution format; `.sar` is the convenience format for importable protected modules.
- **Module import support**: `.sar` modules can be imported by normal Python after enabling the SOAR loader. `.soa` modules can import `.soa`, `.sar`, and `.py` modules only while running through the SOAR execution chain.
- **Automatic source backup**: original `.py` files are copied to `bak/` during encryption.
- **Cross-platform distribution**: the Python package is pure Python, while the native Rust core is distributed as platform-specific wheels.

## Supported Platforms

The Python package `soar-locker` supports CPython 3.8 through 3.13.

The native package `soar-core` is distributed through PyPI as prebuilt wheels. Current supported targets are:

- Windows amd64
- Linux x86_64
- Linux aarch64

During normal execution, SOAR-Locker detects the current operating system and architecture. If the native core is missing or incompatible, it installs the matching `soar-core` wheel before continuing.

## Installation

```bash
python -m pip install soar-locker
```

Manual repair is also available for diagnostics and offline wheelhouse workflows:

```bash
soar --repair-core
```

Inspect the runtime and core status:

```bash
soar --version
```

Example:

```text
SOAR-Locker version 2.0.1
runtime target: Linux / x86_64
soar_core: installed (1.5.0, compatible)
```

## Usage

Encrypt a single Python file in the default high-security mode:

```bash
soar script.py
```

This generates:

- `script.soa`
- `bak/script.py`

Create a convenience archive instead:

```bash
soar --sar script.py
```

This generates `script.sar`. Convenience archives are intended for cases where a normal Python entry point must import an obfuscated module:

```python
from soar import enable_loader

enable_loader()

import script
```

Encrypt a directory recursively:

```bash
soar ./project
```

Use convenience mode for a directory:

```bash
soar --mode convenience ./project
```

Run a protected archive:

```bash
soar program.soa
```

Security-mode archives are intentionally not importable from a normal Python program. A `.soa` archive can be run by `soar`, and code already running inside the SOAR execution chain can import other `.soa`, `.sar`, and `.py` modules. Normal Python code should use `.sar` when module-style imports are required.

Hide the warning banner for later commands:

```bash
soar --ignore-waring
```

The correctly spelled alias is also accepted:

```bash
soar --ignore-warning
```

Show the warning banner once without changing the saved preference:

```bash
soar --show-waring
```

Restore the default behavior:

```bash
soar --reset-waring
```

On Linux, if the original script uses an executable shebang workflow, the resulting archive can be executed after setting executable permissions:

```bash
chmod +x program.soa
./program.soa
```

## Distribution Architecture

SOAR-Locker is split into two packages:

- `soar-locker`: pure Python command-line interface, archive loader, packaging logic, and runtime coordination.
- `soar-core`: native Rust extension that provides the core fingerprint verification and decryption primitives.

The Rust component is intentionally distributed separately because native extension modules are specific to operating system and CPU architecture. PyPI selects the correct wheel automatically from the published wheel tags.

## Security Scope

SOAR-Locker is intended to raise the operational cost of casual source-code inspection and unauthorized redeployment in fixed-machine delivery contexts. It is suitable for internal tools, robotics deployments, embedded Linux systems, and controlled engineering environments.

It is not designed to provide formal resistance against determined reverse engineering, privileged attackers, memory inspection, or adversaries with full control over the runtime environment. Sensitive commercial or regulated deployments should combine SOAR-Locker with additional controls such as licensing infrastructure, hardware-backed secrets, access control, monitoring, and contractual safeguards.

## Version

Current release:

```text
soar-locker 2.0.1
soar-core   1.5.0
```
