--- title: "Audit Logs Module Documentation" description: "Documentation for Audit Logs" --- ## Table of Contents 1. [Navigation & Access](#navigation--access) 2. [Screenshots & Visual Interface](#screenshots--visual-interface) 3. [Module Overview (Technical)](#1-module-overview-technical) 4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness) 5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator) 6. [Log Fields Reference](#4-log-fields-reference) 7. [Common Scenarios & Examples](#5-common-scenarios--examples) 8. [Limitations & Important Notes](#6-limitations--important-notes) 9. [Troubleshooting Tips](#7-troubleshooting-tips) 10. [Glossary](#8-glossary) 11. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration) --- ## Navigation & Access To access the System Audit Logs module: 1. Log in to the Ring2All Web Portal (`https:///login`). 2. In the left navigation sidebar, expand **Reports**. 3. Under **System Reports**, click **Audit Logs** (`/reports/system/audit-logs`). 4. Filter historical system activities by user, event type (CREATE, UPDATE, DELETE, AUTH), module category, or date window. --- ## Screenshots & Visual Interface ### System Audit Logs Repository Granular platform event trail displaying timestamps, acting usernames, source IP addresses, targeted resource entities, action event types, and execution outcome statuses. ![Audit Logs Table](/screenshots/reports/system/audit-logs-list.png) --- ## 1. Module Overview (Technical) ### What Are Audit Logs? Audit Logs is a **security and compliance module** that records all administrative actions performed in the system. It tracks who did what, when, from where, and provides a complete audit trail for regulatory compliance and security monitoring. ### Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Audit Logs Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Admin Performs Action │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Any Module (Extensions, Users, Gateways, etc.) │ │ │ │ │ │ │ │ User clicks [Save] / [Delete] / [Create] │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ API Call with User Context │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Backend Middleware │ │ │ │ │ │ │ │ Log entry created: │ │ │ │ ├─ Action: CREATE / UPDATE / DELETE / LOGIN / etc. │ │ │ │ ├─ Resource: extension / user / gateway / etc. │ │ │ │ ├─ Resource ID: 123 │ │ │ │ ├─ User: admin@example.com │ │ │ │ ├─ IP Address: 192.168.1.100 │ │ │ │ ├─ User Agent: Chrome/120.0 │ │ │ │ └─ Metadata: JSON (old/new values) │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ public.audit_logs │ │ │ │ │ │ │ │ id | action | resource | user | ip | timestamp | meta │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ Display in Viewer │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Audit Logs Page │ │ │ │ │ │ │ │ [Filters: Date | Action | Resource | User] │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ │ │Time │Action │Resource│User │IP │...│ │ │ │ │ ├──────────┼───────┼────────┼────────┼────────────┼───┤ │ │ │ │ │10:30:45 │UPDATE │extens │admin │192.168.1.10│...│ │ │ │ │ │10:25:12 │CREATE │user │admin │192.168.1.10│...│ │ │ │ │ │10:20:00 │DELETE │gateway │admin │192.168.1.15│...│ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Module Overview (Commercial/Business) ### Business Value Audit Logs provides **complete accountability**: | Without Audit Logs | With Audit Logs | |--------------------|-----------------| | Unknown who changed | Full accountability | | No change history | Complete trail | | Compliance gaps | Regulatory compliance | | Security blind spots | Activity visibility | ### Use Cases 1. **Security Monitoring** - Track administrator activity - Identify suspicious actions 2. **Compliance** - SOC 2 requirements - HIPAA audit trail - PCI DSS logging 3. **Troubleshooting** - "Who changed this?" - Configuration change history 4. **Investigation** - Security incident response - Forensic analysis ### Feature Highlights | Feature | Benefit | |---------|---------| | **Action Tracking** | What was done | | **User Identification** | Who did it | | **IP Logging** | Where from | | **Timestamp** | When it happened | | **Metadata** | What changed | | **Search/Filter** | Find specific events | --- ## 3. Module Overview (End User/Administrator) ### What Can You Do? - View all system activity - Filter by date range - Filter by action type - Filter by resource - Filter by user - Search across logs - Export for compliance ### Audit Logs Interface ``` ┌─────────────────────────────────────────────────────────────────┐ │ Audit Logs │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ View and analyze system audit logs and user activity │ │ │ │ Filters: │ │ ├─ Range: [Today ▼] [01/16/2026] to [01/16/2026] │ │ ├─ Actions: [All Actions ▼] (CREATE, UPDATE, DELETE...) │ │ ├─ Resource: [ ] │ │ ├─ User: [All Users ▼] │ │ └─ [🔄 Refresh] [Clear Filters] │ │ │ │ 🔍 [Search by action, resource, or user... ] │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │Timestamp │Action │Resource │Res ID│User │IP Address │ │ │ ├─────────────┼───────┼──────────┼──────┼──────┼───────────┤ │ │ │01/16 10:30 │UPDATE │extension │ 123 │admin │192.168.1.1│ │ │ │01/16 10:28 │CREATE │user │ 456 │admin │192.168.1.1│ │ │ │01/16 10:25 │DELETE │gateway │ 789 │super │10.0.0.5 │ │ │ │01/16 10:20 │LOGIN │session │ - │admin │192.168.1.1│ │ │ │01/16 10:15 │UPDATE │queue │ 101 │admin │192.168.1.1│ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ Showing 1-25 of 1,234 records │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Quick Tips > [!TIP] > **Quick Ranges**: Use Today, 7 Days, 15 Days, 30 Days for fast filtering. > [!TIP] > **Multi-Action Filter**: Select multiple action types to filter. > [!NOTE] > **Metadata**: Click row to view full metadata with old/new values. --- ## 4. Log Fields Reference ### Display Columns | Column | Description | |--------|-------------| | **ID** | Unique log entry ID | | **Timestamp** | When action occurred | | **Action** | Type of action | | **Resource** | What was affected | | **Resource ID** | Specific item ID | | **User** | Who performed action | | **IP Address** | Source IP | | **User Agent** | Browser/client info | | **Metadata** | Additional details | ### Common Actions | Action | Description | |--------|-------------| | **CREATE** | New record created | | **UPDATE** | Record modified | | **DELETE** | Record removed | | **LOGIN** | User logged in | | **LOGOUT** | User logged out | | **EXPORT** | Data exported | | **IMPORT** | Data imported | ### Common Resources | Resource | Description | |----------|-------------| | **extension** | SIP extension | | **user** | System user | | **gateway** | SIP gateway | | **queue** | Call queue | | **ivr** | IVR menu | | **route** | Inbound/outbound route | | **domain** | Tenant domain | | **session** | Login session | --- ## 5. Common Scenarios & Examples ### Scenario 1: Who Changed Extension 1001? 1. Filter Resource by "extension" 2. Search for resource ID or number 3. View action history 4. Check metadata for changes ### Scenario 2: Security Investigation 1. Filter by specific user 2. Set date range for incident window 3. Review all actions 4. Export for report ### Scenario 3: Login Audit 1. Filter Action by "LOGIN" 2. Review login times and IPs 3. Identify unusual patterns 4. Check for failed logins ### Scenario 4: Compliance Report 1. Set date range for reporting period 2. Apply relevant filters 3. Export full log 4. Submit for audit --- ## 6. Limitations & Important Notes ### Technical Notes > [!NOTE] > **Automatic Logging**: All admin actions are logged automatically. > [!NOTE] > **Read-Only**: Audit logs cannot be modified or deleted. > [!WARNING] > **Storage**: Long retention periods increase storage needs. ### Retention | Setting | Description | |---------|-------------| | **Default Retention** | Configured per system | | **Compliance Needs** | May require 1-7 years | ### Best Practices 1. **Regular Review**: Check logs weekly for anomalies 2. **Export Archives**: Export and archive regularly 3. **Monitor Logins**: Watch for unusual login patterns 4. **Track Deletions**: Review all DELETE actions 5. **IP Awareness**: Know your admin IPs --- ## 7. Troubleshooting Tips ### Common Issues | Symptom | Possible Cause | Solution | |---------|---------------|----------| | No logs | Too restrictive filter | Clear filters | | Missing action | Not logged | Check if action type is logged | | Slow loading | Large date range | Reduce date range | | User not found | User deleted | Search by user ID | | No metadata | Not captured | Some actions have limited metadata | ### Diagnostic SQL **Recent audit entries:** ```sql SELECT timestamp, action, resource, resource_id, user_email, ip_address FROM public.audit_logs ORDER BY timestamp DESC LIMIT 50; ``` **Actions by user:** ```sql SELECT action, COUNT(*) as count FROM public.audit_logs WHERE user_email = 'admin@example.com' AND timestamp >= NOW() - INTERVAL '24 hours' GROUP BY action ORDER BY count DESC; ``` --- ## 8. Glossary | Term | Definition | |------|------------| | **Audit Log** | Record of system activity | | **Action** | Type of operation performed | | **Resource** | Type of object affected | | **Metadata** | Additional change details | | **User Agent** | Browser/client identification | | **Audit Trail** | Complete history of actions | --- ## 9. Model Context Protocol (MCP) AI Integration The Ring2All Platform Copilot connects directly with the dedicated audit database (`ss_logs.audit_logs`) via the Model Context Protocol (MCP). Security officers, compliance auditors, and system administrators can investigate configuration history, verify administrative actions, and review tenant activities through conversational natural language prompts. ### Exposed MCP Tools | Tool Name | Operation | Primary Parameters | Description | |:---|:---|:---|:---| | `query_audit_logs` | Audit Event Search | `action` (string, optional), `resource` (string, optional), `search` (string, optional), `limit` (number, default: 25) | Queries system audit logs, displaying action type, affected resource, acting user or administrator, IP address, and metadata. | | `get_audit_log_summary` | Administrative Audit Overview | None | Computes a 7-day breakdown of recent administrative operations, top modified resources, and most active administrators. | ### Operational Safeguards & Security Compliance - **Tenant Isolation**: Audit queries strictly isolate records by `tenant_id` (`WHERE tenant_id = :tenant_id`). Tenant administrators cannot inspect events generated by other tenant organizations. - **Immutable Log Store**: The audit trail in `ss_logs.audit_logs` is strictly append-only. Copilot and external API clients cannot delete, overwrite, or redact recorded audit entries. - **Credential Privacy**: Sensitive data (SIP passwords, hashed user credentials, API keys) are masked or stripped from metadata before storage and cannot be viewed via MCP tools. ### Example MCP Payloads #### 1. Checking Recent Audit Events for Extensions (`query_audit_logs`) ```json { "resource": "sip_extensions", "limit": 10 } ``` *Response:* ```json { "success": true, "data": { "total": 2, "auditLogs": [ { "id": "c92841ea-8821-4f11-9a20-dcba81710a91", "action": "UPDATE", "resource": "sip_extensions", "resourceId": "1002", "user": "Carlos Mendez (admin)", "ipAddress": "190.212.45.18", "details": { "field": "effective_caller_id_name", "old": "Support", "new": "Tech Support Lead" }, "timestamp": "2026-09-08T09:15:30.000Z" }, { "id": "a11945cb-1192-4f22-881b-ccdf91829f01", "action": "CREATE", "resource": "sip_extensions", "resourceId": "1005", "user": "Carlos Mendez (admin)", "ipAddress": "190.212.45.18", "details": { "extension": "1005", "name": "Maria Lopez" }, "timestamp": "2026-09-07T16:20:10.000Z" } ] } } ``` #### 2. Generating Audit Activity Summary (`get_audit_log_summary`) ```json {} ``` ### Copilot Natural Language Prompts - *"Who modified extension 1002 this morning?"* - *"Show me all configuration changes made in the PBX over the last 24 hours."* - *"What are the top 5 most active administrators this week?"* - *"Were any inbound routes deleted or disabled during the weekend?"* --- *Documentation last updated: January 2026*