Skip to content

feat: add Logger interface and --verbose CLI flag - #20

Merged
moonD4rk merged 2 commits into
mainfrom
feat/add-verbose-logging
Apr 2, 2026
Merged

moonD4rk merged 2 commits into
mainfrom
feat/add-verbose-logging

Conversation

@moonD4rk

@moonD4rk moonD4rk commented Apr 2, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add Logger interface to the library with Debug/Info/Warn/Error levels, defaulting to silent (no-op)
  • Add WithLogger() OpenOption so callers can inject custom logger implementations
  • Add -v/--verbose CLI flag that prints non-sensitive structural diagnostics to stderr
  • Fix duplicate ErrWrongKey wrapping in error messages
  • Fix empty password treated as "no unlock method" instead of a valid attempt
  • Add missing CSSM table name constants (SchemaIndexes, SchemaParsingModule, AppleSharePassword)
  • Sort table log output by ID for deterministic ordering

Closes #19
Related: #18

Verbose output example

[INFO]  parsed header            signature=kych, version=65536
[DEBUG] parsed schema            tableCount=12
[DEBUG] parsed table             name=SchemaInfo, id=0x00000000, records=12
[DEBUG] parsed table             name=SymmetricKey, id=0x00000011, records=157
[DEBUG] parsed table             name=GenericPassword, id=0x80000000, records=141
[INFO]  parsed DBBlob            startCryptoBlob=120, totalLength=168, saltLen=20, ivLen=8, ciphertextLen=48
[INFO]  master key derived       method=PBKDF2-SHA1, iterations=1000, keyLen=24
[DEBUG] decrypting DB key        ciphertextLen=48
[ERROR] decrypt DB key failed    error=keychainbreaker: wrong key or password: invalid padding value 26
[DEBUG] GenericPasswords extracted total=141, decrypted=0, failed=138

Test plan

  • golangci-lint run - 0 issues
  • typos - no typos
  • go test -v -race ./... - 34 tests passed
  • Manual test: correct password with -v
  • Manual test: wrong password with -v
  • Manual test: empty password with -v

Add a Logger interface to the library so callers can receive non-sensitive
structural diagnostics during parsing and unlock. The CLI gains a -v/--verbose
flag that prints table structure, DBBlob metadata, unlock progress, and
per-type extraction summaries to stderr.

Also fixes:
- duplicate ErrWrongKey wrapping in error messages
- empty password treated as "no unlock method" instead of a valid attempt
- missing CSSM table names (SchemaIndexes, SchemaParsingModule, AppleSharePassword)
- non-deterministic table log order (now sorted by ID)

Closes #19
Copilot AI review requested due to automatic review settings April 2, 2026 05:55
@codecov

codecov Bot commented Apr 2, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 81.29496% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.81%. Comparing base (b93771d) to head (061482d).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
keychainbreaker.go 87.50% 12 Missing and 1 partial ⚠️
unlock.go 62.06% 10 Missing and 1 partial ⚠️
decrypt.go 50.00% 1 Missing ⚠️
logger.go 75.00% 1 Missing ⚠️
Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main      #20      +/-   ##
==========================================
+ Coverage   74.76%   75.81%   +1.04%     
==========================================
  Files           5        6       +1     
  Lines         638      769     +131     
==========================================
+ Hits          477      583     +106     
- Misses         89      112      +23     
- Partials       72       74       +2     
Flag Coverage Δ
unittests 75.81% <81.29%> (+1.04%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
parse.go 81.69% <ø> (ø)
decrypt.go 73.68% <50.00%> (ø)
logger.go 75.00% <75.00%> (ø)
unlock.go 61.02% <62.06%> (-0.09%) ⬇️
keychainbreaker.go 77.33% <87.50%> (+3.71%) ⬆️

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b93771d...061482d. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds opt-in diagnostic logging to the keychainbreaker library and exposes it via a new -v/--verbose CLI flag to help troubleshoot unlock/parse failures without leaking sensitive material.

Changes:

  • Introduces a Logger interface with a default no-op implementation, plus WithLogger() to inject custom loggers.
  • Adds verbose CLI support (-v/--verbose) that emits structural parse/unlock diagnostics to stderr.
  • Improves unlock behavior and diagnostics (empty password treated as set, deterministic table logging, additional CSSM table IDs, and removes duplicate ErrWrongKey wrapping).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
unlock.go Treats empty password as a valid attempt; adds unlock-stage logging.
parse.go Adds missing CSSM table ID constants and clarifies comment.
logger.go Adds Logger interface and default no-op logger.
keychainbreaker.go Wires logger through Open/parse, logs parse/DBBlob/table info deterministically.
decrypt.go Removes ErrWrongKey wrapping from padding errors to avoid duplicate wrapping upstream.
cmd/keychainbreaker/cmd/verbose.go Implements CLI logger that prints structured log lines to stderr.
cmd/keychainbreaker/cmd/root.go Adds -v/--verbose flag and wires it to WithLogger() during open.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread keychainbreaker.go
// WithLogger sets a custom logger for diagnostic output.
// By default, the library is silent (no-op logger).
func WithLogger(l Logger) OpenOption {
return func(c *openConfig) {

Copilot AI Apr 2, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WithLogger currently allows passing a nil Logger, which will propagate into parse()/Keychain and cause a panic when the code calls logger.Info/Debug/etc. Consider normalizing nil to a nop logger (either inside WithLogger, or in Open()/parse() by doing if logger == nil { logger = nopLogger{} }) so logging is always safe.

Suggested change
return func(c *openConfig) {
return func(c *openConfig) {
// Treat a nil logger as "use the existing/default logger" (typically a no-op logger).
if l == nil {
return
}

Copilot uses AI. Check for mistakes.
Comment thread unlock.go Outdated
Comment on lines +75 to +79
kc.logger.Info("master key derived",
"method", deriveMethod(&cfg),
"iterations", pbkdf2Iter,
"keyLen", len(masterKey),
)

Copilot AI Apr 2, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The unlock log always emits "iterations"=pbkdf2Iter even when the unlock method is a raw hex key (deriveMethod="hex-key"). This makes verbose diagnostics misleading. Consider only logging iterations when cfg.passwordSet is true (or omit/set it to 0 for non-PBKDF2 methods).

Suggested change
kc.logger.Info("master key derived",
"method", deriveMethod(&cfg),
"iterations", pbkdf2Iter,
"keyLen", len(masterKey),
)
fields := []interface{}{
"method", deriveMethod(&cfg),
"keyLen", len(masterKey),
}
if cfg.passwordSet {
fields = append(fields, "iterations", pbkdf2Iter)
}
kc.logger.Info("master key derived", fields...)

Copilot uses AI. Check for mistakes.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread keychainbreaker.go
Comment on lines +62 to +70
// WithLogger sets a custom logger for diagnostic output.
// By default, the library is silent (no-op logger).
func WithLogger(l Logger) OpenOption {
return func(c *openConfig) {
if l != nil {
c.logger = l
}
}
}

Copilot AI Apr 2, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WithLogger only checks l != nil, but a typed-nil logger (e.g. var l *MyLogger = nil) will pass this check and overwrite the default nopLogger{} with a nil underlying value. That can lead to panics or lost logging when methods are invoked. Consider defensively treating typed-nil as nil (e.g. via reflection) or normalizing nil to nopLogger{} in Open/parse.

Copilot uses AI. Check for mistakes.
b.WriteString(", ")
}
fmt.Fprintf(&b, "%v=%v", kv[i], kv[i+1])
}

Copilot AI Apr 2, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

formatKV silently drops the last element when an odd number of key/value items is provided, which can hide diagnostics and make output confusing. Consider handling odd-length input explicitly (e.g. emit the dangling key with a placeholder value or append "").

Suggested change
}
}
if len(kv)%2 == 1 {
if len(kv) > 1 {
b.WriteString(", ")
}
fmt.Fprintf(&b, "%v=%v", kv[len(kv)-1], "<missing>")
}

Copilot uses AI. Check for mistakes.
@moonD4rk
moonD4rk merged commit dbd007f into main Apr 2, 2026
9 checks passed
@moonD4rk
moonD4rk deleted the feat/add-verbose-logging branch April 2, 2026 06:17
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.

feat: add --verbose flag to CLI for diagnostic output

2 participants