Tweaks + Documentation

README.md

@@ -1 +1,266 @@
-# PrintShield
+# PrintShield
+
+**PrintShield** is a command-line framework for securing the 3D printing pipeline—from model creation through slicing to print execution. It provides cryptographic integrity verification, confidentiality through encryption, provenance tracking, secure transfer, real-time monitoring, and compliance mapping against industry standards.
+
+## What It Does
+
+PrintShield addresses security gaps in additive manufacturing by enabling:
+
+- **Integrity & Authenticity**: Hash files canonically and create detached cryptographic signatures
+- **Confidentiality**: Encrypt files with hybrid X25519+AES-256-GCM envelopes; sign on encrypt
+- **Provenance**: Embed or attach JSON manifests recording model metadata, slicer information, and upstream hashes
+- **Secure Transfer**: Upload bundles to printers/servers via SFTP, HTTPS, or OctoPrint REST API with verification
+- **Monitoring**: Watch directories for file drift; compare against baselines; detect unexpected changes
+- **Audit Trails**: Append-only, tamper-evident logs of all operations
+- **Compliance**: Map PrintShield features to NIST SP 800-171 and other policies; generate compliance reports
+
+## Supported Formats
+
+- **STL** (ASCII & Binary)
+- **OBJ** (with MTL materials)
+- **3MF** (ZIP-based container)
+- **AMF** (XML-based)
+- **G-code** (toolpath files)
+
+## Quick Start
+
+### Installation
+
+```bash
+git clone https://github.com/alimezar/PrintShield.git PrintShield
+
+cd PrintShield
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows
+
+# Install
+pip install -e .
+
+# Or If you prefer the GUI
+pip install -e.[gui]
+```
+
+### Basic Usage
+
+```bash
+# Verify CLI is ready
+printshield --help
+printshield version
+
+# Create a minimal config
+cat > ps.yaml <<EOF
+policy_id: nist-800-171
+audit:
+  path: ./audit.log
+EOF
+
+# Hash an STL file
+printshield --config ps.yaml hash model.stl
+
+# Sign it with your Ed25519 private key
+printshield sign model.stl --private-key my_key.pem
+
+# Encrypt for a recipient's X25519 public key
+printshield encrypt model.stl \
+  --recipient-key their_public_key.pem \
+  --sender-key my_private_key.pem
+
+# Verify the audit log
+printshield audit verify
+```
+
+## Documentation
+
+- **[Getting Started](docs/getting-started.md)** – Hands-on walkthrough with examples
+- **[CLI Reference](docs/cli.md)** – Complete command-by-command reference
+- **[G-code Security](docs/gcode.md)** – Canonical hashing, signing, and verification for toolpaths
+- **[Printer Monitoring](docs/monitor-printer.md)** – Live monitoring and verification with OctoPrint
+- **[Configuration Guide](docs/config.md)** – Schema, defaults, and customization
+- **[Server-Side Receive & Gate](docs/receive-gate.md)** – Decryption and policy enforcement on the server/printer side
+- **[Architecture](docs/architecture.md)** – System design and data flow
+- **[Format Specs](docs/formats/)** – Format-specific hashing and provenance details
+
+## Typical Workflows
+
+### Secure Design-to-Print
+
+```bash
+# 1. On workstation: encrypt & sign
+printshield encrypt model.stl -R printer_pubkey.pem -S my_privkey.pem
+
+# 2. Bundle for transfer
+printshield bundle create model.stl.psenc
+
+# 3. Upload to server/printer
+printshield transfer sftp model.stl.psenc.pshieldpkg \
+  --host printer.local --user admin --dest-dir /uploads
+
+# 4. On server/printer: decrypt & verify
+printshield receive model.stl.psenc.pshieldpkg \
+  --private-key printer_privkey.pem \
+  --expected-sender-pub my_pubkey.pem
+```
+
+### Monitor for Drift
+
+```bash
+# Baseline a directory
+printshield monitor scan --path jobs --format json > baseline.json
+
+# Later, detect changes
+printshield monitor diff --baseline baseline.json --path jobs
+
+# Or continuous watch
+printshield monitor watch --path jobs
+```
+
+### G-code Verification
+
+```bash
+# Create provenance for G-code with source model hash
+printshield provenance create output.gcode \
+  --source-model-hash abc123... \
+  --slicer-name PrusaSlicer \
+  --slicer-version 2.7.1
+
+# Sign the G-code
+printshield gcode sign output.gcode --private-key my_key.pem
+
+# On printer: verify G-code against source model
+printshield gcode gate output.gcode \
+  --source-hash abc123... \
+  --manifest output.gcode.provenance.json
+```
+
+### Compliance Reporting
+
+```bash
+# Generate NIST 800-171 compliance report
+printshield compliance run --policy nist-800-171 --format json > report.json
+
+# Or with a custom policy
+printshield compliance run --policy-file my-policy.yml
+```
+
+## Core Concepts
+
+### Audit Log
+
+Every operation (encrypt, sign, transfer, etc.) is recorded in an append-only audit log. The log is cryptographically verified to detect tampering:
+
+```bash
+printshield audit verify
+```
+
+### Configuration
+
+PrintShield reads a YAML config file specifying:
+- Policy ID (for compliance mapping)
+- Audit log path
+- Transfer endpoints
+- Monitoring rules
+
+See [Configuration Guide](docs/config.md) for details.
+
+### Bundles (`.pshieldpkg`)
+
+A bundle is a ZIP container holding:
+- Encrypted payload (`.psenc`)
+- Signed provenance manifest
+- Policy snapshot
+- Checksums
+
+Bundles provide a single self-contained unit for secure transfer.
+
+### Envelopes (`.psenc`)
+
+An envelope is a hybrid-encrypted file (X25519 + AES-256-GCM) with:
+- Ephemeral key exchange data
+- Payload SHA-256
+- Optional sender signature (for sign-on-encrypt)
+
+## Key Management
+
+PrintShield uses:
+- **Ed25519** for signatures (sign/verify)
+- **X25519** for encryption (encrypt/decrypt)
+
+Sample keys are provided in `examples/keys/` for testing:
+
+```text
+examples/keys/
+  ed25519/
+    sample_private_ed25519.pem
+    sample_public_ed25519.pem
+  x25519/
+    sample_private_x25519.pem
+    sample_public_x25519.pem
+```
+
+⚠️ **Never use these in production.**
+
+## Development
+
+### Run Tests
+
+```bash
+pytest tests/
+```
+
+### Linting & Type Checking
+
+```bash
+ruff check src/
+mypy src/
+```
+
+### Adding a New Command
+
+1. Define the command in `src/printshield/cli.py`
+2. Implement the underlying logic in `src/printshield/core/`
+3. Add unit tests in `tests/unit/`
+4. Update `docs/cli.md` with the command reference
+
+## Roadmap
+
+PrintShield is actively developed. Current milestones include:
+
+- ✅ M0: Project skeleton, CLI, config, logging
+- ✅ M1: Hash, sign, verify, audit chain
+- ✅ M2: Encryption, bundling, packaging
+- ✅ M3: Provenance manifests (STL/OBJ/3MF/AMF + G-code)
+- ✅ M4: Transfer (SFTP/HTTPS/OctoPrint) & receive gate
+- ✅ M5: Monitoring & drift detection
+- M6: Hardening & sandboxing (in progress)
+- ✅ M7: Compliance reporting (NIST 800-171 subset)
+- ⏳ Future: GUI improvements, additional policies, extended format support
+
+See [ROADMAP.md](ROADMAP.md) for detailed deliverables.
+
+## Limitations & Non-Goals
+
+- **Not a slicer**: PrintShield does not generate G-code; it secures files that already exist
+- **Not a PKI system**: Key distribution and revocation are out of scope; use your organization's PKI
+- **Not real-time enforcement**: Monitoring is for drift detection, not real-time access control
+- **Not a printer firmware**: PrintShield runs on workstations, servers, and OctoPrint—not the printer MCU
+
+## License
+
+See [LICENSE](LICENSE) file.
+
+## Contact & Support
+
+For questions, issues, or contributions:
+
+- Open an issue on the repository
+- Review [docs/troubleshooting.md](docs/troubleshooting.md) for common problems
+- Check existing tests in `tests/unit/` for usage examples
+
+## Acknowledgments
+
+PrintShield draws inspiration from:
+- NIST guidelines on 3D printing cybersecurity
+- Industry best practices for supply chain security
+- Cryptographic standards (Ed25519, X25519, AES-256-GCM)