Basalt — pr0t31n

How It Works

🛡️ Sensitive Data Handling

This tool collects, processes, or stores data that may include sensitive, personally identifiable, or client-proprietary information — even when sourced from public repositories or non-client-controlled systems. Handle all collected data in accordance with your engagement’s data handling agreement, applicable privacy regulations (GDPR, CCPA, HIPAA), and your organization’s data classification policy. Store findings in encrypted, access-controlled locations and destroy data per the agreed retention schedule.

Basalt is an encrypted file-level backup and restore tool designed for secure evidence and configuration archival. It creates AES-256 encrypted tar archives from one or more source files or directories, protecting them with a passphrase-derived key and HMAC integrity verification.

During backup, Basalt builds a manifest of all source files, recording their relative paths, sizes, modification times, and SHA-256 checksums. The files are packed into an in-memory tar archive, then encrypted using AES-256-CBC with a key derived from the operator's passphrase via PBKDF2-HMAC-SHA256 with 600,000 iterations and a 32-byte random salt. An HMAC-SHA256 tag is computed over the entire ciphertext to guarantee integrity. The final output file uses the BSLT magic header, format version byte, salt, IV, HMAC, and encrypted payload.

During restore, Basalt reads the archive header, derives the encryption and HMAC keys from the passphrase and stored salt, verifies the HMAC tag before any decryption occurs (rejecting tampered archives immediately), then decrypts and extracts the tar contents. The manifest is verified post-extraction to confirm that all files match their original checksums.

Basalt operates as a standalone CLI tool with no network dependencies. It is cross-platform (Linux, macOS, Windows) and requires only the cryptography Python package for AES and HMAC operations. Passphrases can be provided interactively or via a passphrase file for scripted use.

Security

AES-256 encryption with HMAC-SHA256 authentication for tamper detection. PBKDF2 key derivation from passphrase with configurable iteration count. Passphrase can be supplied via --passphrase-file for scripted use (avoid passing on command line where it would appear in process listings).

Features

Archive Management

Multi-Source Backup

Accepts multiple files and directories as input sources, packing them into a single encrypted archive with a unified manifest.

Tar-Based Packaging

Uses Python's tarfile module internally, preserving directory structure, file permissions, and modification timestamps.

Encryption

AES-256-CBC Encryption

All archive contents are encrypted with AES-256 in CBC mode using a random 16-byte IV, ensuring data confidentiality at rest.

PBKDF2 Key Derivation

Encryption keys are derived from the operator's passphrase using PBKDF2-HMAC-SHA256 with 600,000 iterations and a 32-byte random salt, resisting brute-force attacks.

AES-256-CTR Encryption

Envelope encryption with AES-256-CTR and HMAC-SHA256 authentication (encrypt-then-MAC pattern)

6-Phase Restore

HMAC verify → decrypt → read manifest → create safety copies → extract → verify checksums, with automatic rollback on failure

Integrity

HMAC-SHA256 Verification

A full-archive HMAC tag is computed on creation and verified before decryption on restore, detecting any tampering or corruption.

SHA-256 Manifest Checksums

Every file in the archive is checksummed with SHA-256 at backup time and verified after extraction to confirm bit-perfect restoration.

Security

Deep Verification

Optional deep verify mode decrypts the entire archive and checks internal manifest checksums plus disk comparison

Usability

Interactive or Scripted Passphrase

Passphrases can be entered interactively with confirmation, or provided via a passphrase file for automated/scripted backup workflows.

Human-Readable Size Output

Displays backup and restore progress with human-readable file sizes (KB, MB, GB).

Cross-Platform

Works on Linux, macOS, and Windows with no platform-specific dependencies beyond Python and the cryptography package.

Use Cases

Evidence Archive Protection

After completing an assessment, the operator uses Basalt to create an encrypted archive of all evidence directories, ensuring chain-of-custody integrity and protecting sensitive findings at rest during transport or storage.

Configuration Backup

Before modifying tool configurations or engagement parameters, the operator creates an encrypted backup of the current state, enabling rollback if changes cause issues.

Secure Data Transfer

When findings or evidence need to be transferred between workstations or to a secure storage location, Basalt's encrypted archives ensure the data remains protected even if the transfer medium is compromised.

Scripted Automated Backups

Using the passphrase-file option, Basalt can be incorporated into automated backup scripts that run on a schedule, creating encrypted snapshots of critical assessment data.

CLI Reference

Command Examples

Create Encrypted Backup

python3 basalt.py backup /path/to/evidence --dest /path/to/backups

Create an AES-256 encrypted backup with integrity verification.

Restore from Backup

python3 basalt.py restore /path/to/backup.basalt --dest /path/to/restore

Decrypt and restore a backup. Automatic rollback on failure.

Verify Integrity

python3 basalt.py verify /path/to/backup.basalt

Verify HMAC and manifest hashes without decrypting.

Prune Old Backups

python3 basalt.py prune /path/to/backups --keep 5

Retain only the 5 most recent backups.

Invocation Methods

Method	Usage
CLI — Direct	`cd /opt/pr0t31n/Basalt && python3 basalt.py [OPTIONS]` Run directly with command-line arguments.

Integration

Third-Party Dependencies & Credits

Tool / Library	Developer	Type	Link
cryptography	Python Cryptographic Authority	python	https://github.com/pyca/cryptography

Metadata

Name	Basalt
Category	Utility
Version	1.0.3
Install Path	`/opt/pr0t31n/Basalt`
Main File	`basalt.py`
GitHub	https://github.com/pr0t31n/Basalt.git