# audittrail
**audittrail** is a lightweight, open-source Python library for creating a **tamper-proof audit trail** of API activity. It works as a plug-and-play middleware for FastAPI (and soon Flask/Django), automatically recording each request and cryptographically linking entries to prevent undetected tampering.
---
## Features
### Core Features
- **Tamper-proof logging** — Each log entry is hashed and chained to the previous one.
- **Plug-and-play middleware** — Just import and add it to your FastAPI app.
- **Verifiable ledger** — Easily confirm the integrity of your audit log.
- **Encrypted payloads** — Request/response bodies are encrypted at rest.
- **CLI tools** — Command-line interface for verification, monitoring, and reporting.
- **Lightweight storage** — Uses SQLite backend by default.
### Compliance Features (Optional)
- **Digital signatures** — RSA signatures for non-repudiation.
- **Timestamp authorities** — Cryptographic proof of creation time.
- **WORM protection** — Write-Once-Read-Many immutability.
- **Anomaly detection** — Real-time threat monitoring with configurable alerts.
- **Role-based access** — Viewer, Verifier, and Admin roles with permissions.
- **Compliance reporting** — Professional HTML/JSON reports for auditors.
---
## Installation
```bash
pip install audittrail
```
or from source:
```bash
git clone https://github.com/ethanbonsall/audittrail-py.git
cd audittrail-py
pip install .
```
---
## ⚡ Quick Start (FastAPI Example)
```python
from fastapi import FastAPI
from audittrail import AuditTrailMiddleware, verify_ledger
app = FastAPI()
app.add_middleware(AuditTrailMiddleware, storage_path="audit_log.db")
@app.post("/create")
def create_item(item: dict):
return {"msg": "created", "item": item}
# Verify the integrity of the log manually
print(verify_ledger("audit_log.db"))
```
Every incoming request is logged in `audit_log.db` with a cryptographic hash linking it to the previous entry.
### 🔒 Enhanced Compliance Mode
For production banking and financial applications, enable advanced compliance features:
```python
app.add_middleware(
AuditTrailMiddleware,
storage_path="audit_log.db",
enable_compliance=True # Enables digital signatures, timestamps, and WORM protection
)
```
See [COMPLIANCE_FEATURES.md](COMPLIANCE_FEATURES.md) for full documentation.
---
## Example Log Entry
| ts | method | path | user | status | hash | prev_hash |
|----|---------|------|------|---------|------|------------|
| 2025-10-19T22:01Z | POST | /create | anonymous | 201 | `a8f92d...` | `1cd32a...` |
---
## Verify Ledger Integrity
You can verify the entire log chain to ensure no tampering:
```python
from audittrail import verify_ledger
result = verify_ledger("audit_log.db")
print(result) # {"verified": True, "entries": 128}
```
If any record was altered, the verification will fail and return:
```json
{"verified": false, "error_at": "2025-10-19T21:52:00Z"}
```
---
## Directory Structure
```
audittrail/
├── __init__.py # Main exports
├── middleware.py # FastAPI middleware with compliance features
├── ledger.py # Core ledger logic (hashing, verification)
├── cli.py # Command-line interface (RBAC, compliance tools)
├── auth.py # Role-based access control and authentication
├── signatures.py # Digital signature management (RSA)
├── timestamp.py # Timestamp authority integration
├── worm.py # Write-Once-Read-Many protection
├── anomaly.py # Anomaly detection and alerting
└── compliance_report.py # Compliance report generation
pyproject.toml
README.md
```
---
## CLI Commands
AuditTrail includes a comprehensive command-line interface with role-based access control:
### Authentication
```bash
audittrail login # Login with username/password
audittrail logout # Logout from current session
audittrail whoami # Show current user info
```
### Verification & Monitoring
```bash
audittrail verify <db> # Verify ledger integrity
audittrail verify-enhanced <db> # Enhanced verification with compliance checks
audittrail logs <db> --limit 10 # View recent logs
audittrail logs <db> --decrypt # View with decrypted payloads (admin only)
audittrail search <db> --user <user> # Search logs by user
audittrail stats <db> # Show statistics
audittrail watch <db> # Real-time log monitoring
```
### Compliance Features
```bash
audittrail init-signing # Initialize digital signature keys
audittrail compliance-status # Show compliance features status
audittrail compliance-report <db> # Generate compliance report
audittrail worm-status <db> # Check WORM protection
audittrail anomalies # View detected anomalies
```
### User Management (Admin Only)
```bash
audittrail add-user # Add new user
audittrail list-users # List all users
audittrail remove-user <username> # Remove user
```
See [RBAC_GUIDE.md](RBAC_GUIDE.md) for role-based access control documentation.
---
## Roadmap
### Completed
- [x] Encrypted payload logging
- [x] CLI tool with comprehensive commands
- [x] Digital signatures for non-repudiation
- [x] Timestamp authorities
- [x] WORM (Write-Once-Read-Many) protection
- [x] Anomaly detection and alerting
- [x] Role-based access control
- [x] Compliance reporting (HTML/JSON)
### Planned Features
- [ ] Flask & Django middleware support
- [ ] Custom backends (PostgreSQL, MongoDB, etc.)
- [ ] HSM/KMS integration for production key management
- [ ] External Timestamp Authority (RFC 3161) integration
- [ ] Webhook/email alert notifications
- [ ] Real-time dashboard for log visualization
- [ ] Automated compliance report scheduling
- [ ] Multi-tenant support
---
## Compliance Standards Supported
With compliance features enabled, AuditTrail supports requirements from:
- **SOX (Sarbanes-Oxley)** — Audit trail completeness, data integrity, non-repudiation
- **HIPAA** — Healthcare audit logging, encryption, access controls
- **GDPR** — Data protection, audit trails, breach detection
- **PCI-DSS** — Payment card logging, tamper detection, access controls
- **SOC 2** — Security monitoring, change management, incident response
See [COMPLIANCE_FEATURES.md](COMPLIANCE_FEATURES.md) for detailed compliance documentation.
---
## Documentation
- **[README.md](README.md)** — This file, quick start guide
- **[QUICK_START_COMPLIANCE.md](QUICK_START_COMPLIANCE.md)** — 5-minute compliance setup
- **[COMPLIANCE_FEATURES.md](COMPLIANCE_FEATURES.md)** — Full compliance documentation
- **[RBAC_GUIDE.md](RBAC_GUIDE.md)** — Role-based access control guide
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution guidelines
---
## Contributing
Contributions are welcome! We're especially interested in:
- Flask & Django middleware adapters
- HSM/KMS integration
- External timestamp authority support
- Performance optimizations
- Additional backend adapters
```bash
git checkout -b feature/your-feature
git commit -m "Add your feature"
git push origin feature/your-feature
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
---
## 📄 License
MIT License © 2025 Ethan P. Bonsall
---
## Summary
**AuditTrail** is a production-ready, tamper-proof audit logging library that brings bank-grade security to your API. With optional compliance features including digital signatures, timestamps, WORM protection, and anomaly detection, it's suitable for the most demanding regulatory environments.
**Quick Start:**
```python
from audittrail import AuditTrailMiddleware
app.add_middleware(AuditTrailMiddleware, enable_compliance=True)
```
That's it — your API now has enterprise-grade audit logging! 🎉
Raw data
{
"_id": null,
"home_page": null,
"name": "audittrail",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "audit, logging, compliance, security, tamper-proof, blockchain, WORM, signatures, SOX, HIPAA, PCI-DSS",
"author": null,
"author_email": "\"Ethan P. Bonsall\" <ethan.bonsall.dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/42/b4/aeb9e167458245b1948e268ed46d509bde83976624194486f99e64133c9c/audittrail-1.0.1.tar.gz",
"platform": null,
"description": "# audittrail\n\n**audittrail** is a lightweight, open-source Python library for creating a **tamper-proof audit trail** of API activity. It works as a plug-and-play middleware for FastAPI (and soon Flask/Django), automatically recording each request and cryptographically linking entries to prevent undetected tampering.\n\n---\n\n## Features\n\n### Core Features\n- **Tamper-proof logging** \u2014 Each log entry is hashed and chained to the previous one.\n- **Plug-and-play middleware** \u2014 Just import and add it to your FastAPI app.\n- **Verifiable ledger** \u2014 Easily confirm the integrity of your audit log.\n- **Encrypted payloads** \u2014 Request/response bodies are encrypted at rest.\n- **CLI tools** \u2014 Command-line interface for verification, monitoring, and reporting.\n- **Lightweight storage** \u2014 Uses SQLite backend by default.\n\n### Compliance Features (Optional)\n- **Digital signatures** \u2014 RSA signatures for non-repudiation.\n- **Timestamp authorities** \u2014 Cryptographic proof of creation time.\n- **WORM protection** \u2014 Write-Once-Read-Many immutability.\n- **Anomaly detection** \u2014 Real-time threat monitoring with configurable alerts.\n- **Role-based access** \u2014 Viewer, Verifier, and Admin roles with permissions.\n- **Compliance reporting** \u2014 Professional HTML/JSON reports for auditors.\n\n---\n\n## Installation\n\n```bash\npip install audittrail\n```\n\nor from source:\n\n```bash\ngit clone https://github.com/ethanbonsall/audittrail-py.git\ncd audittrail-py\npip install .\n```\n\n---\n\n## \u26a1 Quick Start (FastAPI Example)\n\n```python\nfrom fastapi import FastAPI\nfrom audittrail import AuditTrailMiddleware, verify_ledger\n\napp = FastAPI()\napp.add_middleware(AuditTrailMiddleware, storage_path=\"audit_log.db\")\n\n@app.post(\"/create\")\ndef create_item(item: dict):\n return {\"msg\": \"created\", \"item\": item}\n\n# Verify the integrity of the log manually\nprint(verify_ledger(\"audit_log.db\"))\n```\n\nEvery incoming request is logged in `audit_log.db` with a cryptographic hash linking it to the previous entry.\n\n### \ud83d\udd12 Enhanced Compliance Mode\n\nFor production banking and financial applications, enable advanced compliance features:\n\n```python\napp.add_middleware(\n AuditTrailMiddleware, \n storage_path=\"audit_log.db\",\n enable_compliance=True # Enables digital signatures, timestamps, and WORM protection\n)\n```\n\nSee [COMPLIANCE_FEATURES.md](COMPLIANCE_FEATURES.md) for full documentation.\n\n---\n\n## Example Log Entry\n\n| ts | method | path | user | status | hash | prev_hash |\n|----|---------|------|------|---------|------|------------|\n| 2025-10-19T22:01Z | POST | /create | anonymous | 201 | `a8f92d...` | `1cd32a...` |\n\n---\n\n## Verify Ledger Integrity\n\nYou can verify the entire log chain to ensure no tampering:\n\n```python\nfrom audittrail import verify_ledger\n\nresult = verify_ledger(\"audit_log.db\")\nprint(result) # {\"verified\": True, \"entries\": 128}\n```\n\nIf any record was altered, the verification will fail and return:\n\n```json\n{\"verified\": false, \"error_at\": \"2025-10-19T21:52:00Z\"}\n```\n\n---\n\n## Directory Structure\n\n```\naudittrail/\n\u251c\u2500\u2500 __init__.py # Main exports\n\u251c\u2500\u2500 middleware.py # FastAPI middleware with compliance features\n\u251c\u2500\u2500 ledger.py # Core ledger logic (hashing, verification)\n\u251c\u2500\u2500 cli.py # Command-line interface (RBAC, compliance tools)\n\u251c\u2500\u2500 auth.py # Role-based access control and authentication\n\u251c\u2500\u2500 signatures.py # Digital signature management (RSA)\n\u251c\u2500\u2500 timestamp.py # Timestamp authority integration\n\u251c\u2500\u2500 worm.py # Write-Once-Read-Many protection\n\u251c\u2500\u2500 anomaly.py # Anomaly detection and alerting\n\u2514\u2500\u2500 compliance_report.py # Compliance report generation\npyproject.toml\nREADME.md\n```\n\n---\n\n## CLI Commands\n\nAuditTrail includes a comprehensive command-line interface with role-based access control:\n\n### Authentication\n```bash\naudittrail login # Login with username/password\naudittrail logout # Logout from current session\naudittrail whoami # Show current user info\n```\n\n### Verification & Monitoring\n```bash\naudittrail verify <db> # Verify ledger integrity\naudittrail verify-enhanced <db> # Enhanced verification with compliance checks\naudittrail logs <db> --limit 10 # View recent logs\naudittrail logs <db> --decrypt # View with decrypted payloads (admin only)\naudittrail search <db> --user <user> # Search logs by user\naudittrail stats <db> # Show statistics\naudittrail watch <db> # Real-time log monitoring\n```\n\n### Compliance Features\n```bash\naudittrail init-signing # Initialize digital signature keys\naudittrail compliance-status # Show compliance features status\naudittrail compliance-report <db> # Generate compliance report\naudittrail worm-status <db> # Check WORM protection\naudittrail anomalies # View detected anomalies\n```\n\n### User Management (Admin Only)\n```bash\naudittrail add-user # Add new user\naudittrail list-users # List all users\naudittrail remove-user <username> # Remove user\n```\n\nSee [RBAC_GUIDE.md](RBAC_GUIDE.md) for role-based access control documentation.\n\n---\n\n## Roadmap\n\n### Completed \n- [x] Encrypted payload logging\n- [x] CLI tool with comprehensive commands\n- [x] Digital signatures for non-repudiation\n- [x] Timestamp authorities\n- [x] WORM (Write-Once-Read-Many) protection\n- [x] Anomaly detection and alerting\n- [x] Role-based access control\n- [x] Compliance reporting (HTML/JSON)\n\n### Planned Features\n- [ ] Flask & Django middleware support\n- [ ] Custom backends (PostgreSQL, MongoDB, etc.)\n- [ ] HSM/KMS integration for production key management\n- [ ] External Timestamp Authority (RFC 3161) integration\n- [ ] Webhook/email alert notifications\n- [ ] Real-time dashboard for log visualization\n- [ ] Automated compliance report scheduling\n- [ ] Multi-tenant support\n\n---\n\n## Compliance Standards Supported\n\nWith compliance features enabled, AuditTrail supports requirements from:\n\n- **SOX (Sarbanes-Oxley)** \u2014 Audit trail completeness, data integrity, non-repudiation\n- **HIPAA** \u2014 Healthcare audit logging, encryption, access controls\n- **GDPR** \u2014 Data protection, audit trails, breach detection\n- **PCI-DSS** \u2014 Payment card logging, tamper detection, access controls\n- **SOC 2** \u2014 Security monitoring, change management, incident response\n\nSee [COMPLIANCE_FEATURES.md](COMPLIANCE_FEATURES.md) for detailed compliance documentation.\n\n---\n\n## Documentation\n\n- **[README.md](README.md)** \u2014 This file, quick start guide\n- **[QUICK_START_COMPLIANCE.md](QUICK_START_COMPLIANCE.md)** \u2014 5-minute compliance setup\n- **[COMPLIANCE_FEATURES.md](COMPLIANCE_FEATURES.md)** \u2014 Full compliance documentation\n- **[RBAC_GUIDE.md](RBAC_GUIDE.md)** \u2014 Role-based access control guide\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** \u2014 Contribution guidelines\n\n---\n\n## Contributing\n\nContributions are welcome! We're especially interested in:\n- Flask & Django middleware adapters\n- HSM/KMS integration\n- External timestamp authority support\n- Performance optimizations\n- Additional backend adapters\n\n```bash\ngit checkout -b feature/your-feature\ngit commit -m \"Add your feature\"\ngit push origin feature/your-feature\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License \u00a9 2025 Ethan P. Bonsall\n\n---\n\n## Summary\n\n**AuditTrail** is a production-ready, tamper-proof audit logging library that brings bank-grade security to your API. With optional compliance features including digital signatures, timestamps, WORM protection, and anomaly detection, it's suitable for the most demanding regulatory environments.\n\n**Quick Start:**\n```python\nfrom audittrail import AuditTrailMiddleware\napp.add_middleware(AuditTrailMiddleware, enable_compliance=True)\n```\n\nThat's it \u2014 your API now has enterprise-grade audit logging! \ud83c\udf89\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Production-ready tamper-proof audit trail library with digital signatures, WORM protection, and compliance reporting for Python web frameworks.",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/ethanbonsall/audittrail-py/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/ethanbonsall/audittrail-py#readme",
"Homepage": "https://github.com/ethanbonsall/audittrail-py",
"Issues": "https://github.com/ethanbonsall/audittrail-py/issues",
"Repository": "https://github.com/ethanbonsall/audittrail-py"
},
"split_keywords": [
"audit",
" logging",
" compliance",
" security",
" tamper-proof",
" blockchain",
" worm",
" signatures",
" sox",
" hipaa",
" pci-dss"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "44dde9d28cac653271d005077bc44b9ae9f887ac32fc9816d02270159d18ee71",
"md5": "bb25afc7f1dc13419603fc24a693fd77",
"sha256": "074899bd40d63cd14f90542ef96c453cc997ce651095eec9de520e578a788a82"
},
"downloads": -1,
"filename": "audittrail-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb25afc7f1dc13419603fc24a693fd77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 34096,
"upload_time": "2025-10-20T20:46:50",
"upload_time_iso_8601": "2025-10-20T20:46:50.821952Z",
"url": "https://files.pythonhosted.org/packages/44/dd/e9d28cac653271d005077bc44b9ae9f887ac32fc9816d02270159d18ee71/audittrail-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "42b4aeb9e167458245b1948e268ed46d509bde83976624194486f99e64133c9c",
"md5": "ec7f9d93d6bf1b2c2e760c79e11b3b57",
"sha256": "7209bc284bce14fc7341d466347d8cd20f86529e131d9b229a057a054de365d7"
},
"downloads": -1,
"filename": "audittrail-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "ec7f9d93d6bf1b2c2e760c79e11b3b57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31048,
"upload_time": "2025-10-20T20:46:51",
"upload_time_iso_8601": "2025-10-20T20:46:51.731256Z",
"url": "https://files.pythonhosted.org/packages/42/b4/aeb9e167458245b1948e268ed46d509bde83976624194486f99e64133c9c/audittrail-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 20:46:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ethanbonsall",
"github_project": "audittrail-py",
"github_not_found": true,
"lcname": "audittrail"
}
JSON
