Loader

A secure, production-ready payload loader that fetches encrypted blobs, decrypts them in-memory using AEAD (Authenticated Encryption with Associated Data), and safely consumes the plaintext as JSON configuration.

Features

Secure Decryption: In-memory AEAD decryption with SHA-256 integrity verification
Flexible URL Resolution: Plain URLs, reversed strings, or base64-encoded URLs
No Code Injection: Safe JSON deserialization—no dynamic code execution
Dry-run Mode: Validate container integrity without decryption
Local Blob Support: Decrypt .scf files from disk
Memory Safe: Optional disk output with security warnings
Structured Logging: Debug-friendly tracing with configurable verbosity
Input Validation: Strict key length and format validation
Configuration Files: Load settings from TOML/JSON config (optional)
Metrics & Observability: Built-in timing and throughput metrics

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    CLI Entry Point                           │
│  (parse args, route to command handler)                     │
└────────────┬────────────────────────────────────────────────┘
             │
      ┌──────┴────────┬──────────────┬──────────────┐
      ▼               ▼              ▼              ▼
   Run cmd      DryRun cmd      Decrypt cmd    GenJson cmd
     │               │               │             │
     └───────────────┼───────────────┴─────────────┘
                     ▼
            ┌─────────────────────────────┐
            │   Shared Utilities          │
            │ - validate_key()            │
            │ - consume_payload()         │
            │ - resolve_url()             │
            │ - log metrics               │
            └──────────┬──────────────────┘
                       ▼
            ┌─────────────────────────────┐
            │   mal_dev_core Crate        │
            │ - AEAD decryption           │
            │ - Base64/SHA256 utils       │
            │ - HTTP transport            │
            └─────────────────────────────┘

Installation

Clone the repository and build:

cargo build --release

Binary will be at target/release/loader.

Usage

Basic Commands

1. Full Pipeline (Fetch + Decrypt + Consume)

# Using direct URL
loader run \
  --url "https://example.com/payload.scf" \
  --key-b64 "YOUR_BASE64_ENCODED_32_BYTE_KEY"

# Using reversed URL (obfuscation)
loader run \
  --url-rev "fcs/daolyap/moc.elpmaxe//:sptth" \
  --key-b64 "YOUR_BASE64_ENCODED_32_BYTE_KEY"

# Using base64-encoded URL
loader run \
  --url-b64 "aHR0cHM6Ly9leGFtcGxlLmNvbS9wYXlsb2FkLnNjZg==" \
  --key-b64 "YOUR_BASE64_ENCODED_32_BYTE_KEY"

# Optional: write decrypted plaintext to disk (not recommended)
loader run \
  --url "https://example.com/payload.scf" \
  --key-b64 "YOUR_BASE64_ENCODED_32_BYTE_KEY" \
  --out /tmp/decrypted.json

2. Dry Run (Validate without Decryption)

loader dry-run --url "https://example.com/payload.scf"

# Output: container version, algorithm, ciphertext SHA-256

3. Local Decryption

loader decrypt \
  --input ./payload.scf \
  --key-b64 "YOUR_BASE64_ENCODED_32_BYTE_KEY"

# Optional: write to disk
loader decrypt \
  --input ./payload.scf \
  --key-b64 "YOUR_BASE64_ENCODED_32_BYTE_KEY" \
  --out ./plaintext.json

4. Generate Sample JSON

loader gen-json --out ./sample_payload.json

Configuration File

Create a config file (loader.toml):

[default]
aad = "scf-aad-v1"
key_b64 = "YOUR_BASE64_ENCODED_32_BYTE_KEY"
url = "https://example.com/payload.scf"

# or use reversed URL
# url_rev = "fcs/daolyap/moc.elpmaxe//:sptth"

# or use base64-encoded URL
# url_b64 = "aHR0cHM6Ly9leGFtcGxlLmNvbS9wYXlsb2FkLnNjZg=="

# Optional: output path (memory-only if omitted)
# output = "/tmp/decrypted.json"

[profile.prod]
aad = "scf-aad-v1-prod"
key_b64 = "PROD_BASE64_ENCODED_32_BYTE_KEY"
url = "https://prod.example.com/payload.scf"

[profile.staging]
aad = "scf-aad-v1-staging"
key_b64 = "STAGING_BASE64_ENCODED_32_BYTE_KEY"
url = "https://staging.example.com/payload.scf"

Then use it:

loader run --config loader.toml --profile default
loader run --config loader.toml --profile prod

Logging

Control verbosity via RUST_LOG:

# Info level (default)
RUST_LOG=info loader run --url "..." --key-b64 "..."

# Debug level (verbose)
RUST_LOG=debug loader run --url "..." --key-b64 "..."

# Trace level (very verbose)
RUST_LOG=trace loader run --url "..." --key-b64 "..."

Security Considerations

Memory Safety

Plaintext stays in-memory: Decrypted data is not written to disk unless explicitly requested
Warning on disk writes: If you use --out, a warning is logged
Key sanitization: Keys are not logged, even in debug mode

Cryptography

AEAD: Authenticated Encryption with Associated Data (ChaCha20-Poly1305 or AES-GCM)
Key Length: Must be exactly 32 bytes (256 bits)
AAD: Authenticated Additional Data must match encryption-time value
Nonce: 12-byte nonce is part of the SCF container

Transport Security

HTTPS Only: Network fetches should use HTTPS (enforced in production builds)
Certificate Validation: Standard TLS validation (no insecure mode)
Rate Limiting: Built-in backoff for transient errors

Best Practices

Never hardcode keys: Use environment variables or secure configuration stores
Rotate keys: Implement key rotation every 90 days (or more frequently for high-value data)
Audit logs: Monitor all load operations with structured logging
Test dry-run first: Always validate container before decryption in production
Use memory-only mode: Avoid --out for sensitive payloads

Performance

Expected throughput:

Small payloads (< 1 MB): 10-50 ms (including network fetch)
Large payloads (10-100 MB): 50-200 ms (network-bound)

See benches/ for detailed benchmarks.

Testing

Run full test suite:

cargo test
cargo test -- --nocapture  # Show output

Run specific tests:

cargo test validate_key
cargo test integration::

Run benchmarks:

cargo bench

Development

Project Structure

loader/
├── src/
│   ├── main.rs            # Entry point, CLI handlers
│   ├── config.rs          # Configuration file parsing
│   ├── metrics.rs         # Observability & metrics
│   └── security.rs        # Key sanitization, rate limiting
├── tests/
│   ├── integration_tests.rs
│   └── cli_tests.rs
├── benches/
│   └── throughput.rs
├── Cargo.toml
├── loader.example.toml    # Example config file
└── README.md

Building

cargo build          # Debug build
cargo build --release   # Release build (optimized)

Linting & Formatting

cargo fmt            # Format code
cargo clippy         # Lint & suggestions

GitHub Actions CI/CD

Automated on push and PR:

Build: Compile for Linux/macOS/Windows
Test: Run all unit and integration tests
Security: Run cargo-audit for dependency vulnerabilities
Benchmarks: Track performance regressions
Release: Automated builds and GitHub Releases

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT or Apache-2.0 (dual-licensed)

Support

For issues or questions:

GitHub Issues: Create an issue
Security Concerns: Email security@example.com (do not open public issues)

payload-loader 0.1.0