feat: add tamper-evident audit trail for workflow execution#277
Open
mvillmow wants to merge 5 commits into
Open
feat: add tamper-evident audit trail for workflow execution#277mvillmow wants to merge 5 commits into
mvillmow wants to merge 5 commits into
Conversation
Implement structured JSONL audit logging with optional SHA-256 hash chain for workflow execution events. Records who, when, what, and outcome for all workflow, agent, team, and task state transitions. Key features: - Dependency-injected AuditSink (not module-global singleton) - Optional hash chain enabled by default when AUDIT_LOG_PATH is set - Hash chain continuity across process restarts (resumes from last record) - Thread-safe sync emit (no silent drops if await missed) - Graceful fallback to NullSink on configuration errors New files: - src/telemachy/audit.py (AuditSink, NullSink, hash chain logic) - tests/test_audit.py (7 contract tests for sink behavior) - docs/audit-log.md (schema, event types, verification guide) Modified files: - config.py: added AUDIT_LOG_PATH and AUDIT_HASH_CHAIN settings - executor.py: inject sink, emit 11 event types at state transitions - cli.py: build sink from settings and inject into executor - .env.example, CLAUDE.md: document new env vars All 56 tests pass. Coverage: 78.89% (exceeds 75% gate). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> Signed-off-by: mvillmow <4211002+mvillmow@users.noreply.github.com>
No core defects, security gaps, safety hazards, or functional bugs identified. Implementation is complete with 56 passing tests (78.89% coverage). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> Signed-off-by: mvillmow <4211002+mvillmow@users.noreply.github.com>
Signed-off-by: mvillmow <4211002+mvillmow@users.noreply.github.com>
Verdict: CLEAN - No core defects identified - No security gaps identified - No safety hazards identified - No functional bugs identified 5 feature expansion ideas rejected as out-of-scope. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> Signed-off-by: mvillmow <4211002+mvillmow@users.noreply.github.com>
GHSA-4xgf-cpjx-pc3j) Signed-off-by: Micah Villmow <4211002+mvillmow@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implement structured JSONL audit logging with optional SHA-256 hash chain for workflow execution events. Records who, when, what, and outcome for all workflow, agent, team, and task state transitions.
Key Features
AuditSink(not module-global singleton) — resolves DIP/Modularity finding from prior reviewAUDIT_LOG_PATHis set — tamper-evidence always on in productionemit()(no silent drops if await forgotten) — resolves POLA findingNullSinkon configuration errors — executor construction never fails due to bad audit pathImplementation
src/telemachy/audit.py,tests/test_audit.py,docs/audit-log.mdconfig.py(addedAUDIT_LOG_PATH,AUDIT_HASH_CHAIN),executor.py(inject sink, 11 emit sites),cli.py(build and inject sink),.env.example,CLAUDE.mdTesting & Quality
AUDIT_LOG_PATH=/tmp/wf.jsonl pixi run python -m telemachy.cli run workflows/example.yaml --dry-runproduces valid JSONL with verified hash chainTest Plan
pixi run pytest tests/test_audit.py -v— verify sink writes structured JSON with chain continuitypixi run pytest tests/test_executor.py::TestAuditTrail -v— verify full workflow emits complete event sequencepixi run pytest --cov=src/telemachy --cov-fail-under=75— verify 75% coverage gateAUDIT_LOG_PATH=/tmp/wf-audit.jsonl pixi run python -m telemachy.cli run workflows/example.yaml --dry-run— verify end-to-end chain integrityCloses #187
🤖 Generated with Claude Code