# 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:
```bash
cargo build --release
```
Binary will be at `target/release/loader`.
## Usage
### Basic Commands
#### 1. Full Pipeline (Fetch + Decrypt + Consume)
```bash
# 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)
```bash
loader dry-run --url "https://example.com/payload.scf"
# Output: container version, algorithm, ciphertext SHA-256
```
#### 3. Local Decryption
```bash
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
```bash
loader gen-json --out ./sample_payload.json
```
### Configuration File
Create a config file (`loader.toml`):
```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:
```bash
loader run --config loader.toml --profile default
loader run --config loader.toml --profile prod
```
### Logging
Control verbosity via `RUST_LOG`:
```bash
# 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
1. **Never hardcode keys**: Use environment variables or secure configuration stores
2. **Rotate keys**: Implement key rotation every 90 days (or more frequently for high-value data)
3. **Audit logs**: Monitor all load operations with structured logging
4. **Test dry-run first**: Always validate container before decryption in production
5. **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:
```bash
cargo test
cargo test -- --nocapture # Show output
```
Run specific tests:
```bash
cargo test validate_key
cargo test integration::
```
Run benchmarks:
```bash
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
```bash
cargo build # Debug build
cargo build --release # Release build (optimized)
```
### Linting & Formatting
```bash
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
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT or Apache-2.0 (dual-licensed)
## Support
For issues or questions:
- GitHub Issues: [Create an issue](https://github.com/your-org/loader/issues)
- Security Concerns: Email security@example.com (do not open public issues)