1. Searching Audit Logs

Searching Audit Logs

This scenario demonstrates how to search and retrieve audit logs from the Circularo system. Audit logs provide a comprehensive record of user activities and system events, essential for security monitoring, compliance, and troubleshooting.

Key features:

Search audit logs using various criteria including user actions, document operations, and time periods
Filter logs by specific users, activities, or targets
Analyze system activity for security and compliance purposes
Retrieve detailed information about specific events and actions

Prerequisites

Before searching audit logs, you need:

A valid authentication token
The "view_logs" permission assigned to your user account
Understanding of the audit log structure and search parameters
Knowledge of the specific events or actions you want to investigate

Understanding Audit Log Structure

Circularo audit logs capture detailed information about each system event:

Actor Information: Who performed the action (user, system, etc.)
Activity Details: What action was performed (login, document creation, signing, etc.)
Target Information: What object was affected (document, user, etc.)
Timestamp: When the action occurred
Contextual Data: Additional details specific to the action type

Audit logs are immutable records that cannot be modified or deleted, ensuring the integrity of your system's activity history.

Step 1 - Search User Activity Logs

This endpoint demonstrates how to search for all activities performed by a specific user. This is useful for user activity monitoring, security investigations, and compliance auditing.

Retrieves a record of all actions performed by the specified user
Includes logins, document operations, and other system interactions
Results are paginated to handle large volumes of audit data
Each log entry contains detailed information about the action performed

Endpoint

CODE

POST /logs/search

Request

JSON

POST /logs/search?token=OrwJUqUAiNAMRFxWoVVVuumcItR0Lk4N9iOasW4BVzgO4QtobgtDkd51MjDLRWxT

Content-Type: application/json

{
  "logsQuery": {
    "query": {
      "filter": [
        {
          "type": "term",  //Filter by actor type (user, system, etc.)
          "field": "actorType",
          "value": "user"
        },
        {
          "type": "term",  //Filter by specific user ID/username
          "field": "actorId",
          "value": "mary.griffin@circularo.com"
        }
      ]
    },
    "from": 0,  //Starting position in the result set (for pagination)
    "size": 100  //Maximum number of results to return
  }
}

Response

JSON

{
  "total": 5772,  //Total number of matching log entries
  "results": [  //Array of log entries for the current page
    {
      "id": "kHopbnoduWazpbBv9CMG",
      "activityTarget": "user",
      "activityType": "logged",
      "actorId": "mary.griffin@circularo.com",
      "actorType": "user",
      "timestamp": "2023-08-15T14:32:18.456Z",
      ...
    },
    ...
  ]
}

The response contains a paginated list of audit log entries for the specified user.

Each log entry includes the action type, target, timestamp, and other contextual information
The total count indicates the overall number of matching log entries
Use the pagination parameters (from, size) to navigate through large result sets

For users with extensive activity history, consider using more specific filters or time ranges to narrow down the results.

Step 2 - Search Document Signing Logs

This endpoint demonstrates how to search for all document signing events in the system. This is particularly useful for tracking document workflow completions, verifying signatures, and maintaining an audit trail for compliance purposes.

Retrieves all instances where documents were signed in the system
Includes information about who signed the document and when
Provides document identifiers for cross-referencing with document storage
Helps verify the completion of document workflows

Endpoint

CODE

POST /logs/search

Request

JSON

POST /logs/search?token=OrwJUqUAiNAMRFxWoVVVuumcItR0Lk4N9iOasW4BVzgO4QtobgtDkd51MjDLRWxT

Content-Type: application/json

{
  "logsQuery": {
    "query": {
      "filter": [
        {
          "type": "term",  //Filter by activity target type (document)
          "field": "activityTarget",
          "value": "document"
        },
        {
          "type": "term",  //Filter by specific activity (signed)
          "field": "activityType",
          "value": "signed"
        }
      ]
    },
    "from": 0,
    "size": 100
  }
}

Response

JSON

{
  "total": 247,
  "results": [
    {
      "id": "7T64lLh8Huii9NiiWMnN",
      "activityTarget": "document",
      "activityType": "signed",
      "actorId": "mary.griffin@circularo.com",
      "actorType": "user",
      "subject": "c31600b7-f66f-4f8b-b958-816f305de0d1",
      "timestamp": "2023-08-15T15:45:22.789Z",
      "document": {
        "documentTitle": "Contract Agreement",
        ...
      },
      ...
    },
    ...
  ]
}

The response contains a list of all document signing events, including details about the signer, document, and timestamp.

Each log entry includes the document ID, signer information, and signing timestamp
Additional document metadata may be included depending on system configuration
The total count indicates how many document signing events match the criteria

Step 3 - Search Logs by Time Range

This endpoint demonstrates how to search for audit logs within a specific time period. Time-based filtering is essential for investigating incidents that occurred during a particular timeframe or for generating periodic activity reports.

Retrieves all system events that occurred within the specified time range
Uses Elasticsearch date math expressions for flexible time specifications
Can be combined with other filters for more precise searches
Useful for periodic reviews, incident investigations, and compliance reporting

The 'now-1M/M' expression used in this example retrieves logs from the past month, rounded to the month boundary. You can use various date math expressions like 'now-1d' (past day) or 'now-1h' (past hour).

Endpoint

CODE

POST /logs/search

Request

JSON

POST /logs/search?token=OrwJUqUAiNAMRFxWoVVVuumcItR0Lk4N9iOasW4BVzgO4QtobgtDkd51MjDLRWxT

Content-Type: application/json

{
  "logsQuery": {
    "query": {
      "filter": [
        {
          "type": "range",  //Range filter for time-based searches
          "field": "timestamp",
          "value": {
            "gte": "now-1M/M"  //Greater than or equal to one month ago
          }
        }
      ]
    },
    "from": 0,
    "size": 100
  }
}

Response

JSON

{
  "total": 75421,
  "results": [
    {
      "id": "4rq7gnslTtvjyyo32Knw",
      "activityTarget": "document",
      "activityType": "created",
      "timestamp": "2023-08-15T16:22:45.123Z",
      ...
    },
    ...
  ]
}

The response contains all system events that occurred within the specified time range, regardless of the actor or activity type.

Results include all types of system activities from the past month
The total count indicates the overall system activity volume in this period
Analyze these logs to identify patterns, anomalies, or security concerns

Audit Log Searching Summary

You have successfully learned how to search and retrieve audit logs from the Circularo system using various criteria.

Key Concepts

Audit Log Structure: Understanding the components of audit logs (actor, activity, target, timestamp)
Search Filters: Using different filter types (term, terms, range) to narrow down results
Pagination: Managing large result sets with from and size parameters
Time-Based Searching: Using date expressions to filter logs by time periods

Common Search Patterns

User Activity Monitoring: Tracking all actions performed by specific users
Document Lifecycle Tracking: Following the complete history of a document
Security Investigations: Examining logs during specific time periods or for specific actions

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT

// Audit log searching example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_TOKEN"; // Must have "view_logs" permission

try {
    // Example 1: Search for all activities by a specific user
    const userActivityResponse = await fetch(`${URL}${API_PATH}/logs/search?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            logsQuery: {
                query: {
                    filter: [
                        {
                            type: "term",
                            field: "actorType",
                            value: "user"
                        },
                        {
                            type: "term",
                            field: "actorId",
                            value: "john.smith@example.com"
                        }
                    ]
                },
                from: 0,
                size: 100
            }
        })
    });
    if (!userActivityResponse.ok) {
        throw new Error(`User activity search failed: ${userActivityResponse.status} ${userActivityResponse.statusText}`);
    }

    const userActivityData = await userActivityResponse.json();
    console.log(`Found ${userActivityData.total} activities for user john.smith@example.com`);

    // Example 2: Search for document signing events
    const signingEventsResponse = await fetch(`${URL}${API_PATH}/logs/search?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            logsQuery: {
                query: {
                    filter: [
                        {
                            type: "term",
                            field: "activityTarget",
                            value: "document"
                        },
                        {
                            type: "term",
                            field: "activityType",
                            value: "signed"
                        },
                    ]
                },
                from: 0,
                size: 100
            }
        })
    });
    if (!signingEventsResponse.ok) {
        throw new Error(`Signing events search failed: ${signingEventsResponse.status} ${signingEventsResponse.statusText}`);
    }

    const signingEventsData = await signingEventsResponse.json();
    console.log(`Found ${signingEventsData.total} document signing events`);

    // Example 3: Search for logs in the past month
    const rangeEventsResponse = await fetch(`${URL}${API_PATH}/logs/search?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            logsQuery: {
                query: {
                    filter: [
                        {
                            type: "range",
                            field: "timestamp",
                            value: {
                                gte: "now-1M/M"
                            }
                        }
                    ]
                },
                from: 0,
                size: 100
            }
        })
    });
    if (!rangeEventsResponse.ok) {
        throw new Error(`Range events search failed: ${rangeEventsResponse.status} ${rangeEventsResponse.statusText}`);
    }

    const rangeEventsData = await rangeEventsResponse.json();
    console.log(`Found ${rangeEventsData.total} events from the past month`);

} catch (error) {
    console.error('Error searching audit logs:', error.message);
}