---
title: "System Audit Logs"
description: "Documentation for Audit Logs"
---

## Table of Contents
1. [Overview & Governance Architecture](#1-overview--governance-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Forensic Inspection](#4-visual-interface--forensic-inspection)
5. [Field & Event Reference](#5-field--event-reference)
6. [Audit Logging Pipeline & Middleware Mechanics](#6-audit-logging-pipeline--middleware-mechanics)
7. [Security Hardening & SIEM Integration](#7-security-hardening--siem-integration)
8. [Troubleshooting & Verification Commands](#8-troubleshooting--verification-commands)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Governance Architecture

In **Ring2All SBC**, the **System Audit Logs** module provides immutable, tamper-resistant logging of all administrative actions, configuration changes, user authentications, and system mutations transiting the management plane. Implemented within the `sbc_admin` database subsystem (`public.ui_audit_log`), every administrative interaction is intercepted at the API gateway layer, capturing the authenticated identity, client network socket, HTTP verb, affected resource, and full JSON payload diff.

```
Administrative Operator / API Client           Fastify API Middleware Gateway               PostgreSQL Core Storage
                 │                                           │                                         │
                 │─────── PUT /api/routing/domains/1 ───────>│                                         │
                 │        (Update SIP Domain Config)         ├─── 1. Authenticate Token (JWT)          │
                 │                                           ├─── 2. Authorize Permissions             │
                 │                                           ├─── 3. Execute Database Mutation ───────>│
                 │                                           │                                         │
                 │                                           ├─── 4. Construct Audit Payload           │
                 │                                           │    • Operator: "admin"                  │
                 │                                           │    • Action: "UPDATE"                   │
                 │                                           │    • Resource: "routing/domains"        │
                 │                                           │    • IP: 192.168.11.71                  │
                 │                                           │    • JSON Body & Status Code            │
                 │                                           │                                         │
                 │                                           └─── 5. INSERT INTO ui_audit_log ────────>│
                 │<────── HTTP 200 OK (Mutation Done) ───────│                                         │
```

Unlike basic application log files written to standard output, Ring2All SBC audit logging offers:
1. **Cryptographic & Non-Repudiation Assurance**: Log entries are written to an append-only relational table with strict PostgreSQL role permissions preventing modification or deletion.
2. **Comprehensive Request/Response Context**: Captures not merely high-level event summaries, but full JSON payloads, user-agent signatures, and HTTP response codes.
3. **Automated Credential Masking**: High-entropy secrets, SIP passwords, and cryptographic keys are stripped and sanitized prior to persistence.

---

## 2. Business & Operational Significance

* **Regulatory Compliance & Certifications**: Satisfies rigorous compliance mandates including SOC 2 Type II, ISO 27001, HIPAA, and PCI-DSS by providing a permanent evidentiary trail of all telecom routing changes.
* **Rapid Incident Reconstruction**: Enables engineering teams to determine the exact sequence of events, configuration edits, or credential usage that preceded an operational outage or routing anomaly.
* **Insider Threat Detection**: Immediately alerts security personnel to unauthorized permission escalations, suspicious off-hours logins, or bulk routing deletions.
* **Accountability Across Operations Teams**: Eliminates ambiguity regarding which engineer or automated pipeline modified a specific carrier trunk, dispatcher set, or firewall rule.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **Security & Compliance Officer** | Regulatory Auditing & Threat Hunting | Search and filter all administrative activity; export immutable audit evidence for SOC 2/ISO compliance reviews. |
| **System Administrator** | Change Verification & Rollback Analysis | Verify that applied routing changes correspond to approved change tickets; inspect full JSON request payloads. |
| **Lead Telecom Architect** | Operational Governance | Review administrative modifications across SIP domains, trunk groups, and STIR/SHAKEN certificates. |
| **External Security Auditor** | Independent Control Verification | Review access records, verify authentication success/failure ratios, and confirm tamper-evident protections. |
| **AI Platform Copilot / NOC Diagnostic Agent** | Autonomous Security Auditing & Trail Recording | Search administrative events, correlate operational changes with routing anomalies, verify change ticket compliance, and record audit records for AI actions. |

---

## 4. Visual Interface & Forensic Inspection

The audit log interface combines a high-performance filtering console, a categorized ledger DataGrid, and an interactive JSON detail modal.

### 4.1 System Audit Logs Ledger View
The primary ledger displays historical administrative events chronologically with color-coded action badges, user identities, resource paths, and remote IP addresses.

![System Audit Logs Ledger View](/screenshots/sbc/reports/system/audit-logs/audit-logs-list.png)

### 4.2 Forensic JSON Detail Modal
Clicking the action eye icon on any row opens the detail modal, rendering the full JSON context including the HTTP endpoint, status code, user agent, and payload.

![Audit Log Forensic JSON Detail Modal](/screenshots/sbc/reports/system/audit-logs/audit-logs-detail.png)

---

## 5. Field & Event Reference

### Ledger Columns

| Column | Data Type | Source | Description |
| :--- | :--- | :--- | :--- |
| **Timestamp** | Timestamp | `ui_audit_log.created_at` | Precise UTC timestamp formatted according to the operator's local browser timezone. |
| **User** | String | `ui_audit_log.user` | The administrative username or API service account executing the request (e.g., `admin`). |
| **Action** | Action Badge | `ui_audit_log.action` | Categorized operation type (`CREATE`, `UPDATE`, `DELETE`, `LOGIN`, `LOGOUT`). |
| **Resource** | String | `ui_audit_log.resource` | Target subsystem or API endpoint path (e.g., `auth/login`, `integrations/msteams`). |
| **IP Address** | IPv4 / IPv6 | `ui_audit_log.ip_address` | Remote client socket address establishing the administrative session. |
| **Actions** | Action Icon | — | Opens the JSON detail modal for granular forensic payload inspection. |

### Action Badge Categorization

| Action Badge | Color Coding | Event Types Included |
| :--- | :--- | :--- |
| **CREATE** | Emerald (`bg-emerald-500/15`) | Creation of new SIP domains, endpoints, carriers, trunk accounts, or security policies. |
| **UPDATE** | Blue (`bg-blue-500/15`) | Modification of existing routes, threshold policies, dispatcher sets, or dashboard layouts. |
| **DELETE** | Red (`bg-red-500/15`) | Removal of carriers, routes, certificates, or user accounts. |
| **LOGIN** | Purple (`bg-purple-500/15`) | Successful or failed operator authentication attempts via username/password or SSO. |
| **LOGOUT** | Slate (`bg-slate-500/15`) | Explicit session termination or token revocation events. |

---

## 6. Audit Logging Pipeline & Middleware Mechanics

Every HTTP interaction modifying the SBC state passes through the Fastify `onResponse` logging hook:

```typescript
// Fastify audit logging interceptor
fastify.addHook('onResponse', async (request, reply) => {
  // Only capture mutations and authentication events
  if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(request.method) || request.url.includes('/login')) {
    const user = (request as any).user?.username || 'anonymous';
    const action = deriveAuditAction(request.method, request.url);
    const resource = extractResourcePath(request.url);
    const sanitizedBody = maskSensitiveFields(request.body);

    await db.insertInto('ui_audit_log').values({
      user,
      action,
      resource,
      ip_address: request.ip,
      details: JSON.stringify({
        url: request.url,
        method: request.method,
        statusCode: reply.statusCode,
        body: sanitizedBody,
        userAgent: request.headers['user-agent']
      }),
      created_at: new Date().toISOString()
    }).execute();
  }
});
```

### Sensitive Data Masking Engine
Prior to serialization, the audit middleware traverses all JSON payloads and replaces confidential attributes with `[REDACTED]`:
* `password`, `secret`, `api_key`, `token`
* `sip_auth_password`, `private_key`, `jwt`

---

## 7. Security Hardening & SIEM Integration

To prevent malicious actors from altering or clearing their own tracks after compromising administrative accounts, Ring2All SBC enforces strict database-level immutability:

```sql
-- Enforce Append-Only Immutability on Audit Logs Table
REVOKE UPDATE, DELETE, TRUNCATE ON ui_audit_log FROM sbc_web;
REVOKE UPDATE, DELETE, TRUNCATE ON ui_audit_log FROM kamailio;
GRANT INSERT, SELECT ON ui_audit_log TO sbc_web;

-- Trigger to Prevent Any Administrative Modifications
CREATE OR REPLACE FUNCTION prevent_audit_tampering() 
RETURNS TRIGGER AS $$
BEGIN
    RAISE EXCEPTION 'Audit log records are strictly immutable and cannot be updated or deleted.';
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_protect_audit_logs
BEFORE UPDATE OR DELETE ON ui_audit_log
FOR EACH ROW EXECUTE FUNCTION prevent_audit_tampering();
```

### Syslog & SIEM Streaming
For enterprise deployments requiring centralized Security Information and Event Management (SIEM), audit events can be forwarded in real time via RFC 5424 Syslog to platforms such as **Splunk**, **Elasticsearch**, or **Datadog**.

---

## 8. Troubleshooting & Verification Commands

### Inspecting Recent Audit Logs via CLI
Query the audit database directly to verify event ingestion:

```bash
# Query the latest 10 administrative actions in sbc_admin
psql -U sbc_admin -d sbc_admin -c "
SELECT id, created_at, \"user\", action, resource, ip_address 
FROM ui_audit_log 
ORDER BY id DESC LIMIT 10;"
```

### Auditing Authentication Failures
List all failed login attempts over the past 24 hours:

```bash
psql -U sbc_admin -d sbc_admin -c "
SELECT created_at, \"user\", ip_address, details->>'statusCode' as status 
FROM ui_audit_log 
WHERE resource = 'auth/login' AND details->>'statusCode' != '200' 
ORDER BY created_at DESC;"
```

### Verifying Table Immutability
Confirm that unauthorized deletions are blocked by database triggers:

```bash
# Attempt to delete a test row (should fail with permission error)
psql -U sbc_admin -d sbc_admin -c "DELETE FROM ui_audit_log WHERE id = 1;"
# Output: ERROR: Audit log records are strictly immutable and cannot be updated or deleted.
```

---

## 9. Model Context Protocol (MCP) AI Integration

The System Audit Logs subsystem is natively connected to the Ring2All SBC Model Context Protocol (MCP) server. Autonomous AI agents, compliance scanners, and NOC forensic copilots use these tools to inspect the administrative trail, track configuration mutations, and record audit records for autonomous operations.

### Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `get_sbc_audit_logs` | Forensic Query | `read` | Search administrative audit trail and security event logs filtered by username, resource, action, or date. |
| `log_sbc_audit_event` | Audit Registration | `operational` | Record a tamper-resistant administrative audit log entry documenting configuration actions or AI agent executions. |

---

### Tool Schemas & Payloads

#### 1. `get_sbc_audit_logs`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter by username, resource name, or payload details."
    },
    "action": {
      "type": "string",
      "description": "Filter by action (e.g. 'CREATE', 'UPDATE', 'DELETE', 'RELOAD', 'LOGIN')."
    },
    "resource": {
      "type": "string",
      "description": "Filter by resource type (e.g. 'carrier', 'lcr_route', 'firewall', 'smr', 'routing/domains')."
    },
    "limit": {
      "type": "number",
      "description": "Number of records to return (default: 25, max: 100)."
    }
  }
}
```

##### Output Payload Example
```json
{
  "count": 2,
  "logs": [
    {
      "id": 4821,
      "user": "admin",
      "action": "UPDATE",
      "resource": "routing/carriers",
      "ip_address": "192.168.11.71",
      "details": {
        "carrier_id": 4,
        "name": "Telnyx-Primary",
        "weight": 80,
        "status": "active"
      },
      "created_at": "2026-09-08T15:10:22.000Z"
    },
    {
      "id": 4820,
      "user": "noc_copilot",
      "action": "AI_EXECUTION",
      "resource": "firewall/htable",
      "ip_address": "127.0.0.1",
      "details": {
        "operation": "unban_ip",
        "ip": "198.51.100.22",
        "reason": "Carrier maintenance window completed"
      },
      "created_at": "2026-09-08T15:08:44.000Z"
    }
  ]
}
```

---

#### 2. `log_sbc_audit_event`

##### Input Schema
```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "Action type (e.g. 'CREATE', 'UPDATE', 'DELETE', 'AI_EXECUTION', 'RELOAD')."
    },
    "resource": {
      "type": "string",
      "description": "Resource name or API path (e.g. 'carrier', 'dispatcher', 'smr_rule')."
    },
    "resourceId": {
      "type": "string",
      "description": "Identifier or name of the affected entity."
    },
    "details": {
      "type": "string",
      "description": "Human-readable description or JSON string summarizing the mutation."
    }
  },
  "required": ["action", "resource"]
}
```

##### Output Payload Example
```json
{
  "success": true,
  "audit_id": 4822,
  "action": "AI_EXECUTION",
  "resource": "dispatcher",
  "recorded_at": "2026-09-08T15:35:10.000Z"
}
```

---

### Natural Language AI Prompts

#### English Examples
* *"Show me the last 10 audit log entries where changes were made to carrier routing."*
* *"Who modified the firewall rules or unbanned an IP in the last 2 hours?"*
* *"Log an audit event indicating that the NOC Copilot reloaded the Kamailio dispatcher ring."*

#### Spanish Examples (Español)
* *"Muéstrame las últimas 10 entradas de auditoría donde se modificó el enrutamiento de carriers."*
* *"¿Quién modificó las reglas de firewall o desbloqueó una IP en las últimas 2 horas?"*
* *"Registra un evento de auditoría indicando que el Copilot NOC recargó el anillo de dispatchers de Kamailio."*

---

### Enterprise Safeguards & Access Governance
1. **Append-Only Immutability**: All audit entries are strictly insert-only. No MCP tool exists to update or delete rows from `ui_audit_log`, backed by database-level triggers preventing tampering.
2. **Automated Credential Masking**: Secrets, private keys, passwords, and tokens are stripped before persistence.
3. **Role-Based Execution Isolation**: Reading audit logs is restricted to compliance and administrative roles (`security_auditor`, `sbc_system_admin`, `super_admin`).

---

## 10. Glossary

* **Append-Only Log**: A storage pattern where records can only be created, never altered or removed.
* **Fastify Hook**: Server lifecycle interception point allowing middleware to inspect and log requests and responses.
* **Non-Repudiation**: The assurance that a user or system cannot deny the authenticity of their signature or action.
* **SIEM (Security Information and Event Management)**: Centralized platform for aggregating, analyzing, and alerting on security logs across enterprise infrastructure.
* **SOC 2 Type II**: Security audit framework validating the operational effectiveness of security controls over an extended evaluation period.