securepickle
A jar of pickles comes tamper-proof. So should your code.
Installation
pip install almeida-securepickle
Optional dependencies:
pip install almeida-securepickle[fast] # xxhash for 5x faster mode
pip install almeida-securepickle[encrypt] # cryptography for AES-256-GCM
pip install almeida-securepickle[all] # both
Why?
Regular pickle.load() will execute ANY code inside the file:
class Evil:
def __reduce__(self):
return (os.system, ('whoami',))
# Attacker sends this. You pickle.load(). Game over.
This is real. __reduce__ tells pickle how to reconstruct an object - and attackers use it to reconstruct your system into their system.
Solution
securepickle checks the seal BEFORE opening the jar:
- Signs every pickle with HMAC-SHA256
- Verifies the signature before loading
- Refuses to open if tampered
from secure_pickle import secure_dump, secure_load
# Save (signs it)
secure_dump(data, "safe.pkl")
# Load (verifies first)
data = secure_load("safe.pkl")
Modes
| Mode | Security | Speed | Use Case |
|---|---|---|---|
mode="secure" |
HMAC-SHA256 | Normal | Default, production |
mode="fast" |
xxhash | 5x faster | Caches only (NOT attack-resistant) |
encrypt=True |
AES-256-GCM | Slower | Secrets, credentials, PII |
# Fast mode - corruption detection only, NOT attack-resistant
secure_dump(data, "cache.pkl", mode="fast")
# Encrypted - requires cryptography package
secure_dump(secrets, "vault.pkl", encrypt=True)
Performance
v1.2.0 uses optimized I/O patterns:
| Size | vs Raw Pickle |
|---|---|
| <16KB | Faster than raw! |
| 16-256KB | +30-40% |
| 256KB-2MB | +50-100% |
| >2MB | +30-50% |
API
Functions
secure_dump(obj, path, key=None, encrypt=False, mode="secure")
secure_load(path, key=None, encrypt=None)
secure_dumps(obj, key=None, encrypt=False, mode="secure") -> bytes
secure_loads(data, key=None, encrypt=None) -> object
is_secure_pickle(path) -> bool
migrate_pickle(old_path, new_path=None, encrypt=False)
Key Management
By default, keys are stored in ~/.secure_pickle/key. Override with:
from secure_pickle import set_key_path
set_key_path("/custom/path")
Or environment variable:
export SECURE_PICKLE_KEY_DIR=/custom/path
CLI
# Check if file is secure
securepickle check data.pkl
# Migrate unsigned pickle
securepickle migrate old.pkl --output new.pkl
# Verify signature
securepickle verify data.pkl
Security Notes
- HMAC-SHA256 provides cryptographic integrity (mode="secure")
- xxhash provides fast corruption detection only (mode="fast")
- AES-256-GCM provides authenticated encryption (encrypt=True)
- Keys are auto-generated with
os.urandom(32) - Key files have
0600permissions - Signatures verified with timing-safe comparison
Pop. Verify. Trust.
Apache 2.0 License | Copyright 2025 Almeida Industries
Metadata
Release files for almeida-securepickle 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| almeida_securepickle-1.2.0.tar.gz | 11.6 kB | Without provenance | Details for almeida_securepickle-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| almeida_securepickle-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for almeida_securepickle-1.2.0-py3-none-any.whl |
Total release size: 33.1 kB
Release files / almeida_securepickle-1.2.0.tar.gz
| Download URL | almeida_securepickle-1.2.0.tar.gz |
|---|---|
| Size | 11.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6a29093cc3c03a89066dfd0cd4d167c6501d73ebd15fbd222a739cfcab71db39
|
|
BLAKE2b-256 checksum How to use checksums |
bfcfd2e175002d0e3a0fa7fdc42c74df050bf7e1e63497dcfcddb8298e229118
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / almeida_securepickle-1.2.0-py3-none-any.whl
| Download URL | almeida_securepickle-1.2.0-py3-none-any.whl |
|---|---|
| Size | 21.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95e68c0b00e73d4a68b15ca5ffbb2d836b65175f07e5ac9a5dbf4cfa13e1e7b8
|
|
BLAKE2b-256 checksum How to use checksums |
02d523f24c079ee8e70f0be25be177575078f8947f954eedef6d7ec0ba04c3e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for almeida-securepickle 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.