Metadata-Version: 2.4
Name: bxshield
Version: 0.1.0
Summary: Practical Python source hardening toolkit by BXCODE
Author: BXCODE Contributors
License-Expression: MIT
Keywords: python,source-protection,obfuscation,build-tool
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=41
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Dynamic: license-file

# BXShield

**BXShield** is a practical Python source-hardening toolkit from **BXCODE**. It combines conservative AST transformations, optional reversible string encoding, CPython bytecode output, SHA-256 integrity manifests, static analysis, and offline Ed25519 license verification.

> BXShield raises the effort required for casual inspection and copying. It is not a security boundary and cannot make client-side Python impossible to reverse engineer.

## What it protects against

- Casual source browsing through optional formatting reduction, conservative local-variable renaming, and reversible string encoding.
- Accidental or untracked modification of build artifacts through a SHA-256 manifest.
- Basic local license-file forgery when users verify signatures against a trusted public key.

## What it does not protect against

- A determined analyst can inspect bytecode, decode strings, patch the program, or extract runtime data.
- Bytecode is Python-version-specific and is not impossible to reverse engineer.
- Base64 string wrapping is **encoding/obfuscation, not encryption**. It offers no secrecy against an analyst who can inspect the decoder.
- A client-side license check is not perfect DRM; software under the customer's control can be modified.
- BXShield does not hide malware, evade security products, or execute source during analysis/build.

## Installation

```bash
python -m pip install .
# Development installation with tests and tools
python -m pip install '.[dev]'
```

Python 3.10+ is supported. License signing and verification use the `cryptography` package.

## Quick start

```bash
bxshield build examples/hello.py --output dist --profile strong
bxshield verify dist
bxshield analyze examples/hello.py
```

Python API:

```python
from bxshield import Shield, ShieldConfig

config = ShieldConfig.profile_config("strong", seed=12345, preserve=["main"])
result = Shield(config).protect("examples/hello.py", output="dist")
if not result.success:
    raise RuntimeError(result.errors)
print(result.output, result.files_processed, result.transformations)
```

`Shield.protect` accepts either a `.py` file or a project directory and returns a structured `BuildResult`. It never imports or executes source files. Directory builds also copy non-Python assets while respecting exclusion globs.

## CLI

```text
bxshield --help
bxshield --version
bxshield build project/ --output dist/ --profile strong --seed 12345
bxshield analyze project/ --json
bxshield verify dist/
bxshield config init
```

Build prints measured phase durations and writes `build-report.json`. Analysis is static and reports Python version, source files, function/class counts, imports, strings, approximate complexity, and conservative renaming candidates.

## Configuration

Create a starter file with `bxshield config init`:

```toml
[project]
name = "MyApp"
version = "1.0.0"

[protection]
profile = "strong"
minify = true
rename = true
strings = true
compile = true
integrity = true
preserve = ["main", "MyPublicClass", "API_VERSION"]
exclude = ["tests/**", "generated_*.py"]
string_exclude = ["PUBLIC_TEXT"]

[rename]
prefix = "_bx_"
seed = 12345

[output]
directory = "dist"
```

`ShieldConfig` offers the same controls through Python. Exclusion patterns apply to project-relative paths. `string_exclude` names preserve assigned literals with those target names. Renaming intentionally limits itself to function-local assigned names in simple scopes; function arguments, module-level names, imports, class APIs, reflective/dynamic scopes and explicit preserved/excluded names remain unchanged to avoid common semantic breaks. A seed makes chosen local names reproducible.

## Profiles

- **light**: minification, conservative renaming, integrity metadata.
- **strong**: light layers plus reversible string encoding and bytecode output.
- **maximum**: strong layers with docstring removal; still reversible and version-dependent, not “unbreakable.”

Every layer can be switched independently in `ShieldConfig` or TOML. The `compile` layer writes `.pyc` artifacts using the running interpreter's format; distribute and run with a compatible Python version.

## Integrity verification

Builds with integrity enabled include `integrity.json` containing SHA-256 digests of packaged artifacts. `Shield().verify("dist")` returns a structured result, identifying changed or missing files. The manifest is not signed and does not authenticate itself; an attacker who can replace both artifacts and manifest can recompute it. Use a trusted signed release channel when authenticity matters.

## Offline licensing

Create a developer keypair, keep the private key offline, sign a license, then verify using the distributed public key:

```bash
bxshield license keygen --private-key issuer-private.pem --public-key app-public.pem
bxshield license create --product MyApp --license-id BX-1234 \
  --private-key issuer-private.pem --expires-at 2027-01-01 --output license.json
bxshield license verify license.json --public-key app-public.pem --product MyApp
```

Never embed a private signing key in an application or commit it. Client-side licensing cannot provide perfect DRM. Protect and back up the developer private key independently.

## Security and safe operation

- Parsing and transformation use Python's AST; target files are never executed by analysis or build.
- There is no anti-debugging, persistence, process injection, hidden network traffic, or AV/EDR evasion.
- Do not place credentials, permanent secrets, or private signing keys in protected code.
- See [SECURITY.md](SECURITY.md), [docs/security.md](docs/security.md), and [docs/architecture.md](docs/architecture.md).

## Development

```bash
python -m compileall bxshield
python -m pytest
ruff check .
python -m build
```

Tests are local and require no network once development dependencies are installed. `examples/hello.py` is a smoke-test target. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Publishing

Build a wheel and source archive with `python -m build`, inspect the artifacts, and publish only through your trusted release process. Do not include signing private keys, credentials, build caches, or personal data.

---

Made with ❤️ by BXCODE  
https://t.me/bxcode
