Added docs, workflows, removed legacy dependency files, publishing to pypi, publishing docs to pages

Author: codeamt

.DS_Store

@@ -0,0 +1,70 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    name: "🧪 Build & Run Safety Suite"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "🦀 Set up Rust"
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+          components: clippy, rustfmt
+
+      - name: "🐍 Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: "🧱 Install dependencies"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install maturin pytest black ruff mypy
+          python -m pip install -e .[dev,training]
+
+      - name: "⚙️ Build Rust extension (develop mode)"
+        run: |
+          maturin develop --release
+
+      - name: "🧹 Lint and format check"
+        run: |
+          cargo fmt -- --check
+          cargo clippy -- -D warnings
+          black --check python/
+          ruff check python/
+          mypy python/
+
+      - name: "🧪 Run Safety Test Suite"
+        env:
+          PYTHONPATH: ./python
+        run: |
+          echo "Running pytest safety checks..."
+          pytest -v python/tests/test_safety.py
+
+      - name: "✅ Summary"
+        if: success()
+        run: echo "✅ All safety and CI checks passed."
+
+      - name: "❌ Failure notice"
+        if: failure()
+        run: echo "❌ Safety suite failed. Blocking release."
+
+  test:
+    runs-on: ubuntu-latest
+    name: "🧪 Python Tests (uv)"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Install dependencies
+        run: uv sync --group dev --group training
+      - name: Run tests
+        run: uv run pytest -q python

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v2
+      - name: Install docs dependencies
+        run: uv sync --group docs
+      - name: Build docs
+        run: uv run mkdocs build --strict
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+# 📘 License Appendix – Educational Use and Liability Statement
+
+**Project:** PE-Packer  
+**Primary License:** Apache-2.0  
+**Effective Date:** 2025-10-15  
+
+---
+
+## 1. Purpose of This Appendix
+
+This appendix supplements the main license file to clarify the **intended scope and ethical limitations** of the PE-Packer project.
+
+The purpose of PE-Packer is **educational and research-oriented learning** about the Windows Portable Executable (PE) format, static analysis, and safe unpacking.  
+It is **not designed or authorized** for use in software concealment, obfuscation, or malware deployment of any kind.
+
+This clarification does not alter the legal permissions of the MIT or Apache-2.0 license but provides additional binding terms of **responsible use** and **liability disclaimers** specific to this project.
+
+---
+
+## 2. Educational-Use Intent
+
+By obtaining, using, or redistributing this software, you acknowledge that:
+
+- The software is provided **solely for authorized research, teaching, academic, or defensive cybersecurity education**.  
+- It **must not** be used to disguise or distribute executables, payloads, or binaries outside a controlled educational or testing environment.  
+- You assume **full responsibility** for ensuring compliance with your institution’s and jurisdiction’s cybersecurity laws and policies.
+
+---
+
+## 3. Safety Controls
+
+PE-Packer enforces a **safety gating system**:
+
+1. Binary packing functionality is **disabled by default**.  
+2. Activation requires both:
+   - The environment variable `PE_PACKER_ALLOW_PACKING=1`, **and**
+   - The command-line flag `--force`.
+
+This gating mechanism exists to prevent accidental or unauthorized generation of packed executables.
+
+---
+
+## 4. No Warranty or Liability
+
+Consistent with the MIT and Apache-2.0 licenses:
+
+- The software is provided **“as is,” without warranty of any kind**, express or implied.  
+- Under no circumstances shall the authors, contributors, or affiliated institutions be liable for **any claim, damages, or other liability** arising from misuse, modification, or redistribution of this software.  
+- You are solely responsible for ensuring compliance with all applicable laws, export regulations, and institutional policies.
+
+---
+
+## 5. Academic Citation
+
+If you use PE-Packer in an academic, instructional, or research context, please cite the repository as follows:
+
+> **Tutu, A.M. (2025). PE-Packer: An Educational PE File Packing Laboratory.**  
+> Available at: [https://github.com/codeamt/rust-python-pe-packer](https://github.com/codeamt/rust-python-pe-packer)
+
+---
+
+## 6. Contact
+
+| Purpose | Contact |
+|----------|----------|
+| General inquiries | annmargaret.mailforce@gmail.com |
+| Security disclosures | annmargaret.mailforce@gmail.com |
+| License & institutional use | annmargaret.mailforce@gmail.com |
+
+---
+
+*This appendix is intended to reinforce ethical, transparent, and responsible software distribution practices in alignment with open-source security research standards.*

LICENSE-APPENDIX.md

@@ -285,4 +285,36 @@ install-tools:  ## Install development tools
 	cargo install cargo-watch
 	cargo install cargo-bloat
 	$(UV) pip install pre-commit
-	@echo "$(GREEN)Development tools installed$(NC)"
+	@echo "$(GREEN)Development tools installed$(NC)"
+
+# PyPI Educational Stub (safe wheel)
+.PHONY: stub-build
+stub-build:  ## Build educational stub wheel (PyPI-safe)
+	@echo "$(BLUE)Building educational stub wheel...$(NC)"
+	@test -d pypi-stub || { echo "missing pypi-stub/"; exit 1; }
+	@test -f pypi-stub/pyproject.toml || { echo "missing pypi-stub/pyproject.toml"; exit 1; }
+	$(UV) run $(PYTHON) -m pip install --upgrade build
+	cd pypi-stub && $(UV) run $(PYTHON) -m build
+	@echo "$(GREEN)Stub wheel built in pypi-stub/dist$(NC)"
+
+.PHONY: stub-publish
+stub-publish:  ## Publish educational stub to PyPI (requires ALLOW_PYPI_RELEASE=1 and PYPI_TOKEN configured in environment)
+	@echo "$(BLUE)Publishing educational stub to PyPI...$(NC)"
+	test "$(ALLOW_PYPI_RELEASE)" = "1" || (echo "Set ALLOW_PYPI_RELEASE=1 to enable publishing" && false)
+	$(UV) run $(PYTHON) -m pip install --upgrade twine
+	cd pypi-stub && $(UV) run $(PYTHON) -m twine upload --non-interactive dist/*
+	@echo "$(GREEN)Stub published to PyPI$(NC)"
+
+# MkDocs Documentation
+.PHONY: docs-serve
+docs-serve:  ## Serve MkDocs locally at http://127.0.0.1:8000
+	@echo "$(BLUE)Starting MkDocs dev server...$(NC)"
+	$(UV) run $(PYTHON) -m pip install -q mkdocs-material
+	$(UV) run mkdocs serve --watch .
+
+.PHONY: docs-build
+docs-build:  ## Build MkDocs site into ./site
+	@echo "$(BLUE)Building MkDocs site...$(NC)"
+	$(UV) run $(PYTHON) -m pip install -q mkdocs-material
+	$(UV) run mkdocs build --strict
+	@echo "$(GREEN)Docs built in ./site$(NC)"

Makefile

@@ -1,9 +1,15 @@
+[![CI](https://github.com/codeamt/rust-python-pe-packer/actions/workflows/ci.yml/badge.svg)](https://github.com/codeamt/rust-python-pe-packer/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://codeamt.github.io/rust-python-pe-packer/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green)](./LICENSE)
+
 # PE-Packer
 
-An educational PE (Portable Executable) packer built in Rust with Python bindings for generating packed malware samples to train machine learning-based malware detection models.
+An educational PE (Portable Executable) laboratory built in Rust with Python bindings for research and training on PE formats, safe unpacking workflows, and defensive ML evaluation.
 
 **⚠️ Educational Purpose Only**: This tool is designed for security research, malware analysis training, and building robust ML detection systems. Use only with legitimate, authorized benign samples.
 
+> Quick links: [Security Policy](./SECURITY.md) · [License Appendix (Educational Use)](./LICENSE-APPENDIX.md)
+
 ## Features
 
 - **Multiple Encryption Algorithms**: XOR, AES, or no encryption
@@ -24,24 +30,27 @@ An educational PE (Portable Executable) packer built in Rust with Python binding
 - Python 3.8+
 - pip or poetry
 
-### From PyPI
+### From PyPI (educational stub)
 
 ```bash
-pip install pe-packer
+pip install pe-packer-educational
 ```
 
+This PyPI package is a non-functional educational stub that prints guidance and links to the source. It does not ship packing code or native modules.
+
 ### From Source
 
 ```bash
 # Clone the repository
-git clone https://github.com/codeamt/pe-packer
-cd pe-packer
+git clone https://github.com/codeamt/rust-python-pe-packer
+cd rust-python-pe-packer
 
-# Install in development mode
-pip install -e .
+# Using uv (recommended)
+uv sync --group dev --group training
+uv run maturin develop --features python
 
-# Or build and install the wheel
-pip install maturin
+# Or using pip
+pip install -e .[dev,training]
 maturin develop
 ```
 
@@ -50,14 +59,21 @@ maturin develop
 ### Pack a Single File
 
 ```bash
-# Pack with default settings (XOR encryption)
+# Safety gate: actual packing requires BOTH
+#   PE_PACKER_ALLOW_PACKING=1  and  --force
+# Otherwise, the CLI runs in dry-run mode and prints analysis only.
+
+# Dry-run (no env, no --force)
 pe-packer pack malware.exe packed.exe
 
+# Actual packing (requires both env and --force)
+PE_PACKER_ALLOW_PACKING=1 pe-packer pack malware.exe packed.exe --force
+
 # Pack with AES encryption and anti-debugging
 pe-packer pack malware.exe packed.exe --encryption aes --anti-debug
 
-# Randomize sections and add benign metadata
-pe-packer pack malware.exe packed.exe \
+# Randomize sections and add benign metadata (with gates)
+PE_PACKER_ALLOW_PACKING=1 pe-packer pack malware.exe packed.exe --force \
   --encryption aes \
   --anti-debug \
   --random-sections \
@@ -81,6 +97,21 @@ pe-packer generate-training-data \
   --encryption xor,aes
 ```
 
+## Testing Dataset Generation (Checklist)
+
+- Ensure you have a local folder with benign PE files, for example: `./benign_samples/`
+- Run a small test to validate the pipeline end-to-end:
+
+```bash
+# Minimal smoke test: 1 variant, analysis-focused
+pe-packer generate-training-data ./benign_samples ./training_data --variants 1
+
+# Analyze the produced metadata
+pe-packer analyze-dataset ./training_data/dataset_metadata.json
+```
+
+- If you intend to actually generate packed binaries (not just analysis), ensure safety gates are consciously enabled when invoking direct packing commands (see Pack a Single File section). Dataset generation itself focuses on safe educational workflows and metadata.
+
 ### Analyze Generated Dataset
 
 ```bash
@@ -111,10 +142,11 @@ pe-packer pack INPUT OUTPUT [OPTIONS]
 - `--benign-metadata`: Add benign-looking metadata
 - `--stub-variation, -s`: Stub variation identifier (1-32) [default: 1]
 - `--verbose, -v`: Enable verbose logging
+ - `--force`: Required along with `PE_PACKER_ALLOW_PACKING=1` to perform actual packing
 
 **Example:**
 ```bash
-pe-packer pack sample.exe packed.exe \
+PE_PACKER_ALLOW_PACKING=1 pe-packer pack sample.exe packed.exe --force \
   --encryption aes \
   --key deadbeef \
   --anti-debug \
@@ -413,7 +445,7 @@ If you use PE-Packer in your research, please cite:
   title={PE-Packer: Educational PE Packer for Malware Detection Training},
   author={AnnMargaret Tutu},
   year={2025},
-  url={https://github.com/codeamt/pe-packer}
+  url={https://github.com/codeamt/rust-python-pe-packer}
 }
 ```