Skip to content

Conversation

@coreyleavitt
Copy link
Owner

Summary

  • Add structured debug logging throughout kdbxtool for troubleshooting
  • Follow Python library best practices (NullHandler, logging.getLogger(__name__))
  • Never log sensitive data (passwords, keys, decrypted content)

Changes

File Logging Added
__init__.py NullHandler to prevent warnings
parsing/header.py Version, cipher, compression, KDF params
parsing/kdbx4.py Decryption/encryption progress, HMAC verification
parsing/kdbx3.py Decryption progress, block verification
security/kdf.py KDF start/complete, composite key (booleans only)
security/crypto.py Cipher initialization
security/keyfile.py Format detection, keyfile creation
security/yubikey.py Device count, challenge-response
database.py Open/save/create/reload, entry/group counts

Usage

import logging
logging.basicConfig(level=logging.DEBUG)

from kdbxtool import Database
db = Database.open("test.kdbx", password="test")

Test plan

  • All 706 tests pass
  • Verified no sensitive data is logged (passwords, keys, salts, decrypted content)
  • NullHandler prevents warnings when logging not configured

Closes #29

Add logging throughout kdbxtool following Python library best practices:

- Add NullHandler to root logger in __init__.py to prevent warnings
- Use logging.getLogger(__name__) in each module
- Log at INFO level for high-level operations (open, save, create)
- Log at DEBUG level for internal details (KDF params, block counts)
- Never log sensitive data (passwords, keys, decrypted content)

Logged information includes:
- KDBX version detection and cipher/compression settings
- KDF parameters (Argon2 memory/iterations, AES-KDF rounds)
- Decryption/encryption progress and verification steps
- Keyfile format detection
- YubiKey challenge-response operations
- Database open/save/reload operations with entry/group counts

Users can enable logging with:
  import logging
  logging.basicConfig(level=logging.DEBUG)

Closes #29
@coreyleavitt coreyleavitt merged commit bf7998c into master Jan 20, 2026
6 checks passed
@coreyleavitt coreyleavitt deleted the feat/debug-logging branch January 20, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add debug logging for troubleshooting

2 participants