|
| 1 | +--- |
| 2 | +name: 'sourceloop-audit-service' |
| 3 | +displayName: 'SourceLoop Audit Service' |
| 4 | +description: 'Track and record user actions with audit logging - inserts, updates, deletes with S3 archival and CSV export capabilities' |
| 5 | +keywords: |
| 6 | + [ |
| 7 | + 'audit', |
| 8 | + 'logging', |
| 9 | + 'audit-trail', |
| 10 | + 'compliance', |
| 11 | + 'tracking', |
| 12 | + 'sourceloop', |
| 13 | + 's3-archival', |
| 14 | + ] |
| 15 | +author: 'SourceFuse' |
| 16 | +--- |
| 17 | + |
| 18 | +# SourceLoop Audit Service |
| 19 | + |
| 20 | +## Overview |
| 21 | + |
| 22 | +A LoopBack 4 microservice for audit logging that tracks and records user actions including inserts, updates, and deletes. Supports S3 archival for long-term storage and CSV export capabilities. |
| 23 | + |
| 24 | +**Key capabilities:** |
| 25 | + |
| 26 | +- **Action Tracking**: Record inserts, updates, and deletes across services |
| 27 | +- **S3 Archival**: Archive audit logs to AWS S3 for compliance |
| 28 | +- **CSV Export**: Export audit data as CSV via ExcelJS |
| 29 | +- **Repository Mixin**: Drop-in audit logging for any repository |
| 30 | +- **Multi-source Retrieval**: Query from both database and archive |
| 31 | + |
| 32 | +## Available MCP Servers |
| 33 | + |
| 34 | +### sourceloop-cli |
| 35 | + |
| 36 | +**Package:** `@sourceloop/cli` |
| 37 | +**Connection:** Local stdio via npx |
| 38 | + |
| 39 | +Use the `microservice` tool with `--baseOnService --baseService=audit-service` to scaffold a new audit service instance. |
| 40 | + |
| 41 | +## Installation |
| 42 | + |
| 43 | +```typescript |
| 44 | +import {AuditServiceComponent} from '@sourceloop/audit-service'; |
| 45 | +import {BootMixin} from '@loopback/boot'; |
| 46 | +import {ApplicationConfig} from '@loopback/core'; |
| 47 | +import {RestApplication} from '@loopback/rest'; |
| 48 | + |
| 49 | +export class MyApplication extends BootMixin(RestApplication) { |
| 50 | + constructor(options: ApplicationConfig = {}) { |
| 51 | + super(options); |
| 52 | + |
| 53 | + // Validate required environment variables |
| 54 | + this.validateAuditEnv(); |
| 55 | + |
| 56 | + try { |
| 57 | + this.component(AuditServiceComponent); |
| 58 | + console.log('✅ Audit service loaded successfully'); |
| 59 | + } catch (error) { |
| 60 | + console.error('❌ Failed to initialize audit service:', error.message); |
| 61 | + throw error; |
| 62 | + } |
| 63 | + } |
| 64 | + |
| 65 | + private validateAuditEnv() { |
| 66 | + const required = ['DB_HOST', 'DB_PORT', 'DB_DATABASE']; |
| 67 | + const missing = required.filter(env => !process.env[env]); |
| 68 | + if (missing.length > 0) { |
| 69 | + throw new Error( |
| 70 | + `Missing required environment variables: ${missing.join(', ')}`, |
| 71 | + ); |
| 72 | + } |
| 73 | + |
| 74 | + // Validate S3 config if archival is enabled |
| 75 | + if (process.env.ENABLE_ARCHIVAL === 'true') { |
| 76 | + const s3Required = [ |
| 77 | + 'AWS_ACCESS_KEY_ID', |
| 78 | + 'AWS_SECRET_ACCESS_KEY', |
| 79 | + 'S3_BUCKET_NAME', |
| 80 | + ]; |
| 81 | + const s3Missing = s3Required.filter(env => !process.env[env]); |
| 82 | + if (s3Missing.length > 0) { |
| 83 | + throw new Error( |
| 84 | + `S3 archival enabled but missing: ${s3Missing.join(', ')}`, |
| 85 | + ); |
| 86 | + } |
| 87 | + } |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +## Key Models |
| 93 | + |
| 94 | +- **AuditLog** - Core audit log entry with action, actor, timestamp, before/after data |
| 95 | +- **CustomFilter** - Custom query filters for audit retrieval |
| 96 | +- **MappingLog** - Entity mapping audit records |
| 97 | +- **Job** - Background archival job tracking |
| 98 | + |
| 99 | +## Key Controllers |
| 100 | + |
| 101 | +- **AuditController** - CRUD operations for audit logs, export, archival |
| 102 | + |
| 103 | +## Common Workflows |
| 104 | + |
| 105 | +### Workflow 1: Setup Audit Service |
| 106 | + |
| 107 | +```bash |
| 108 | +npx @sourceloop/cli microservice my-audit \ |
| 109 | + --baseOnService \ |
| 110 | + --baseService=audit-service \ |
| 111 | + --datasourceName=auditdb \ |
| 112 | + --datasourceType=postgresql \ |
| 113 | + --includeMigrations |
| 114 | +``` |
| 115 | + |
| 116 | +### Workflow 2: Add Audit Logging to a Repository |
| 117 | + |
| 118 | +Use the audit mixin from `@sourceloop/audit-log`: |
| 119 | + |
| 120 | +```typescript |
| 121 | +import {AuditRepositoryMixin} from '@sourceloop/audit-log'; |
| 122 | + |
| 123 | +export class MyEntityRepository extends AuditRepositoryMixin< |
| 124 | + MyEntity, |
| 125 | + typeof MyEntity.prototype.id, |
| 126 | + MyEntityRelations |
| 127 | +>(DefaultCrudRepository) { |
| 128 | + constructor(@inject('datasources.db') dataSource: DataSource) { |
| 129 | + super(MyEntity, dataSource); |
| 130 | + } |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Best Practices |
| 135 | + |
| 136 | +### Do: |
| 137 | + |
| 138 | +- Archive old audit logs to S3 for cost-effective long-term storage |
| 139 | +- Use the repository mixin for automatic audit logging |
| 140 | +- Index audit logs by actor, action type, and timestamp |
| 141 | +- Configure retention policies for compliance requirements |
| 142 | + |
| 143 | +### Don't: |
| 144 | + |
| 145 | +- Store sensitive data (passwords, tokens) in audit log details |
| 146 | +- Skip audit logging for delete operations |
| 147 | +- Query large audit datasets without filters - use pagination |
| 148 | + |
| 149 | +## Database |
| 150 | + |
| 151 | +Requires PostgreSQL. Run migrations: |
| 152 | + |
| 153 | +```bash |
| 154 | +npx db-migrate up --config database.json --migrations-dir migrations |
| 155 | +``` |
| 156 | + |
| 157 | +## Dependencies |
| 158 | + |
| 159 | +- `@sourceloop/core` |
| 160 | +- `@sourceloop/audit-log` |
| 161 | +- `exceljs` (CSV export) |
| 162 | +- `csvtojson` |
0 commit comments