Skip to content

feat(security): implement policy audit trail and decision logging#3191

Open
crivetimihai wants to merge 6 commits intomainfrom
feature/audit-logging-2225
Open

feat(security): implement policy audit trail and decision logging#3191
crivetimihai wants to merge 6 commits intomainfrom
feature/audit-logging-2225

Conversation

@crivetimihai
Copy link
Copy Markdown
Member

Note: This PR was re-created from #2707 due to repository maintenance. Your code and branch are intact. @kcostell06 please verify everything looks good.

📋 Issue

Closes #2225

🎯 Summary

Implements comprehensive policy audit trail and decision logging system for IBM MCP Context Forge, meeting all requirements from issue #2225.

📦 Changes

New Files

  • mcp-servers/audit/ - Core audit logging implementation (5 modules)
  • tests/audit/ - Comprehensive test suite (45+ tests)
  • docs/audit/ - Complete documentation

Features Implemented

  • ✅ Audit record logging with complete context
  • ✅ Database storage (SQLite, PostgreSQL-ready)
  • ✅ SIEM integrations (Splunk HEC, Elasticsearch, Webhook)
  • ✅ REST API for querying (FastAPI)
  • ✅ Query filtering (subject, resource, decision, time range)
  • ✅ Statistics and analytics
  • ✅ Export to CSV/JSON
  • ✅ Compliance framework support
  • ✅ Retention management

✅ User Stories Completed

US-1: Security Analyst - Query Access Decisions

# Query decisions by subject email
GET /audit/decisions?subject_email=user@example.com&decision=deny

US-2: Security Team - Export to SIEM

  • Splunk HEC format with batch processing
  • Elasticsearch bulk API integration
  • Generic webhook support

🧪 Testing

All tests passing ✅

Run basic tests:

python3 tests/audit/test_mcp_audit.py
# Result: 16/16 tests passed

Run comprehensive tests:

pytest tests/audit/test_mcp_audit_comprehensive.py -v
# Result: 45+ tests passed

📚 Documentation

  • Implementation Guide: docs/audit/MCP_AUDIT_IMPLEMENTATION.md
  • Testing Guide: docs/audit/TESTING_GUIDE.md
  • Quick Start: docs/audit/QUICKSTART_TESTING.md
  • Test Summary: docs/audit/TEST_SUMMARY.md

🔗 Related Issues

Kelly Costello and others added 6 commits February 24, 2026 10:05
Signed-off-by: Kelly Costello <kellycostello@Kellys-Air.localdomain>
Integrate policy decision audit logging into the gateway, replacing the
standalone mcp_servers/ implementation. Fixes all six reviewer issues:
SQL injection (allowlist validation), blocking async (sync sessions),
missing auth (require_admin_auth), return type mismatch (always returns
PolicyDecision), print→logging, and the integration gap.

Adds SIEM export service (Splunk HEC, Elasticsearch, webhook) with
batch processing, retry/backoff, and lifecycle management in main.py.
Wires policy logging into RBAC enforcement middleware.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Kelly Costello <kellycostello@Kellys-MacBook-Air.local>
- Fix Alembic migration: rename to hex revision, merge two heads
- Remove duplicate mcp-servers/audit/ standalone implementation
- Add sort_by/sort_order pattern validation on GET endpoint
- Remove unnecessary db.commit() from read-only queries
- Separate health endpoint into unauthenticated router
- Add plugin-auth decision logging in rbac.py
- Honor per-decision audit toggles (log_allowed/log_denied)
- Fix deprecated asyncio.get_event_loop() -> get_running_loop()
- Fix timezone-naive datetime.now() in siem_export_service
- Upgrade audit failure log level to warning
- Clean up docs/audit/ artifacts
- Include health_router in main.py
- Add per-decision toggle and health endpoint tests

Closes #2225

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Kelly Costello <kellycostello@Kellys-MacBook-Air.local>
- Rewrite PolicyDecision ORM model to Mapped[]/mapped_column() style
  matching AuditTrail convention in db.py
- Remove duplicate index=True from columns covered by composite indexes
- Add missing named indexes to migration, make downgrade idempotent
- Extract lazy-cached singleton for policy_decision_service in rbac.py
- Convert f-string logging to %s style in service and router modules
- Add bounded queue with drop-oldest to SIEMBatchProcessor
- Add shutdown no-progress guard to prevent _flush_all hanging
- Add tests for flush_all, shutdown hang prevention, and queue bounds
- Register PolicyDecision on Base.metadata for create_all bootstrap
- Trim TESTING_GUIDE.md to reference actual test paths
- Update copyright years to 2026

Signed-off-by: Jonathan Springer <jps@s390x.com>
- Add SIEM export service tests (39 tests covering all exporters and batch processor)
- Add policy_audit ORM model serialization tests
- Add policy_decision_service tests for SIEM queuing, query filters, and statistics
- Add API error handler tests for 500 responses
- Fix import ordering (isort) and pre-commit formatting
- Merge third Alembic head (w6g7h8i9j0k1) to resolve multiple-heads error
- Exclude untracked ip_control files from coverage

Coverage: 99% (53,217 stmts, 458 missed)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Kelly Costello <kellycostello@Kellys-Air.localdomain>
…1l2 (#2225)

The migration's down_revision was pointing to w6g7h8i9j0k1 (parent of
current head) instead of x7h8i9j0k1l2 (the jwks_uri migration that is
the actual current head on main). This would have created multiple
Alembic heads and broken migrations.

Also adds the x7h8i9j0k1l2 migration file from upstream main so the
revision chain is complete on this branch.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Kelly Costello <kellycostello@Kellys-Air.localdomain>
@crivetimihai crivetimihai added this to the Release 1.0.0-GA milestone Feb 24, 2026
@crivetimihai crivetimihai added enhancement New feature or request COULD P3: Nice-to-have features with minimal impact if left out; included if time permits labels Feb 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

COULD P3: Nice-to-have features with minimal impact if left out; included if time permits enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE][POLICY]: Policy audit trail and decision logging

2 participants