Skip to content

Audit Logging User Guide

Version: 1.0
Last Updated: 2026-09-12

This guide provides comprehensive information about audit logging, activity monitoring, and security investigation workflows in the Vista Platform.

Table of Contents

  1. Overview
  2. Understanding Event Types
  3. Event Categories
  4. Compliance Tagging System
  5. Activity Log Management
  6. Security Investigation Workflows
  7. Compliance Reporting Workflows
  8. Best Practices

Overview

The audit logging system captures every action performed in the platform, providing: - Complete Audit Trail: Every action logged with full context - Compliance Support: Automatic tagging for compliance frameworks - Security Monitoring: Real-time detection of suspicious activity - Troubleshooting: Detailed logs for debugging issues

What is Logged

Every logged event includes: - Who: User ID, email, and user type (tenant/platform/service) - What: Event type, action, and resource affected - When: Precise timestamp - Where: IP address and user agent - How: Success/failure status and error details - Why: Request ID for tracing through system - Context: Old values, new values, and changed fields

Routine traffic from your sensors and discovery agents (their heartbeats and job polls) is not recorded: it happens every few seconds and would bury the actions people take. What a sensor or agent submits (discoveries, results, inventory) and certificate rotation are still recorded.

Understanding Event Types

Event types are dotted names. Most activity is recorded by the platform's request logger, which names the event {category}.{resource}.{action} from the request: the action is read, create, update or delete, so adding an asset through the API is recorded as asset.assets.create and creating a ticket as compliance.tickets.create. Search for the resource name (assets, tickets, certificates) to find that activity.

Named Event Types

Some actions record an event of their own, with a fixed name, in addition to the request.

Asset Events

  • asset.created: Asset added
  • asset.updated: Asset modified
  • asset.deleted: Asset removed
  • asset.approved: Discovered asset approved in Approvals
  • asset.denied: Discovered asset denied in Approvals
  • asset.bulk_imported: Assets imported in bulk

User Events

  • user.login: Successful sign-in
  • user.login_failed: Failed sign-in
  • user.logout: User signed out
  • user.created: User added
  • user.invited: User invited
  • user.updated: User modified
  • user.deleted: User removed
  • user.password_changed: Password changed
  • user.password_change_failed: Password change attempt failed

Compliance Events

  • ticket.deleted: Ticket deleted. The delete is permanent, so this event carries the ticket's content.

Settings and Integration Events

  • settings.identification.updated: Asset identification settings changed
  • settings.drift.updated: Drift settings changed
  • integration.created: Integration added
  • integration.deleted: Integration removed

Discovery Events

  • discovery.job.created: Discovery job created
  • discovery.job.cancelled: Discovery job cancelled
  • discovery.job.rerun: Discovery job run again
  • discovery.finding.imported: Discovery results imported
  • discovery.cloud_completed: Cloud discovery finished

Event Categories

Every event carries one category. It is matched by the Audit page's search box and by the export endpoint's event_category filter. These are the categories the platform records:

Category Covers
authentication Login, logout, token refresh, API tokens, SSO and OAuth flows
user User lifecycle, roles and permissions, profile and preference changes
tenant Tenant lifecycle and tenant-level health
asset Infrastructure assets, crypto configurations, keys, findings, asset approval
certificate Certificate upload, deletion, chain building, expiry and revocation
discovery Sensors and discovery agents, discovery jobs, device interrogation, PCAP intake
compliance Framework activation, control evaluation, compliance findings, tickets
report CBOM artifacts, comparisons and scopes
config Tenant and platform settings changes
data Data access and export, including access through the MCP server
job Background job lifecycle
system Platform operation: monitoring, notifications, resource tracking, the audit trail itself

Every request the platform serves is recorded under the category of the service that served it — a request to the inventory service is asset, to a discovery service discovery, and so on — with a few resource-level exceptions (certificates are always certificate, tenant lifecycle is always tenant, settings are always config, and sign-in is always authentication). Handlers that record a richer event of their own name the category directly.

Upgrading

Before this categorization existed, every request the platform's request logger recorded (as opposed to a specific handler naming its own event) was filed under system, with an event type of the form system.<service>.<action> — for example system.inventory-service.create instead of asset.assets.create. Rows written before the upgrade are not rewritten — they keep the category and event type they were recorded with. If you have an alert rule or a SIEM filter that matches on event_category = system or on the system.<service>.<action> event-type shape, it will continue to match only the old rows; new activity moves to the categories in the table above and needs a filter written against those instead.

Compliance Tagging System

Events are automatically tagged with relevant compliance frameworks to simplify compliance reporting.

Supported Frameworks

SOC2 (soc2) - User authentication events - Access control changes - System configuration changes - Backup and recovery events - Security monitoring events

ISO 27001 (iso27001) - Information security events - Asset management events - Access control events - Incident management events - Audit trail events

GDPR (gdpr) - Personal data access - Data modification events - Data deletion events - Consent management - Data export events

HIPAA (hipaa) - PHI access events - Security events - Configuration changes - User management - Audit logging

PCI DSS (pci_dss) - Card data access - Security events - Network configuration - Access control - Audit mechanisms

Using Compliance Tags

Filtering by Framework

Compliance tags are not one of the three controls on the Audit page. To pull the events carrying a given tag, use the audit API's compliance_tag filter (see Getting events out) with one of soc2, iso27001, gdpr, hipaa, pci_dss.

Generating Compliance Reports 1. Select framework 2. All tagged events included automatically 3. Generate on demand (running them on a schedule is an Enterprise capability)

Activity Log Management

Viewing Logs

Open Risk & Compliance → Audit Log in the left rail. Reading the trail needs the audit read permission: Tenant Administrator, Security Administrator and Viewer have it by default; Billing Admin and API User do not.

Events are listed newest first, with four columns:

Column What it shows
Actor The member's email, or System for platform-initiated events.
Action What was done. A failed attempt is marked · failed and shown in red.
Target The resource type and id, falling back to the event category.
When How long ago it happened.

Three controls narrow the list:

  • a search box, matching across actor, action, event type, event category, resource type and resource id;
  • an actor selector, built from the actors present in the loaded events;
  • a window — last 24 hours, last 7 days, or last 30 days (the default).

The controls narrow what is already on screen, not what is fetched. The page loads the most recent events and tells you how many of the total it is showing ("Showing the 100 most recent of 4,812 events"). On a busy trail, a 30-day window can therefore show less than 30 days' worth. To reach further back, use the API below.

There is no advanced query builder and no saved queries on this page.

Getting events out

There is no export control on the Audit page in this release. The audit service exposes an export endpoint instead. Open it in a browser tab where you are signed in to Vista Platform, and the download runs under your session:

GET /api/v1/audit-service/activity-logs/export?format=csv
GET /api/v1/audit-service/activity-logs/export?format=json

format accepts csv or json and defaults to json. A tenant user's request is always scoped to their own organization, whatever else is passed.

Personal API tokens do not work here — they are accepted only by the MCP server, and this endpoint answers them with 401. There is no unattended, token-based way to pull the audit trail yet.

The same request accepts filters, which is how you reach further back than the page can show:

Parameter Notes
start_date, end_date RFC 3339 timestamps. The usual way to bound an export.
event_type, event_category, action Repeatable — pass the parameter more than once for several values.
user_id, user_type Narrow to one member, or to human vs. system actors.
resource_type, resource_id Narrow to one kind of resource, or one resource.
compliance_tag Repeatable. soc2, iso27001, gdpr, hipaa, pci_dss.
success true or false — failures only, or successes only.
search Free-text search, as on the page.
requires_attention, impersonation, tag Flagged events only, impersonated actions only, or events carrying a tag.
tenant_id Platform operators only: scope the export to one tenant. Ignored for tenant users.

One request returns at most 10,000 events. Bound long periods with start_date / end_date and pull them in chunks rather than asking for a year at once.

The two formats do not carry the same detail. CSV is a flat fourteen-column table — id, occurred at, tenant id, user id, user type, user email, event type, event category, action, resource type, resource id, success, error message, compliance tags. JSON carries the whole record, including the fields CSV has no column for: changed_fields, old_values, new_values, ip_address and user_agent. If you are investigating what changed rather than what happened, ask for JSON.

Searching Logs

Use the page's search box for a quick look — it matches a substring against the actor, action, event type, event category, resource type and resource id of the events already loaded. Examples:

  • a member's email address
  • an event type such as asset.created
  • a resource id you are tracing

For anything the box cannot express — a precise time window, a compliance tag, a success/failure split, or more history than the page holds — use the export endpoint's filters above.

Security Investigation Workflows

Investigating Failed Logins

Scenario: Multiple failed login attempts detected

  1. Initial Investigation
  2. Open Risk & Compliance → Audit Log
  3. Search for user.login_failed
  4. Narrow the window to the period in question

  5. Look for patterns (same user, time clustering). Source addresses are not a column on the page — pull a JSON export if you need them

  6. Identify Affected Accounts

  7. Note user emails with failures
  8. Check if multiple users affected (broader attack)

  9. Check if single user (credential issue)

  10. Check for Success After Failures

  11. After identifying time window, search for user.login (this also matches user.login_failed, so read the · failed marker)
  12. Check if successful login follows failures

  13. Potential compromise if login succeeds after many failures

  14. Correlate with Other Events

  15. Search for user activity after successful login
  16. Look for unusual actions (bulk deletions, config changes)

  17. Check IP address changes

  18. Take Action

  19. Reset compromised passwords
  20. Enable/require MFA
  21. Block suspicious IP addresses
  22. Create alert rule to prevent future incidents

Investigating Unauthorized Access

Scenario: Suspected unauthorized resource access

  1. Resource Audit Trail
  2. Copy the resource's id from its page
  3. Open Risk & Compliance → Audit Log and search for that id
  4. Review all access and modifications

  5. Note users who accessed resource

  6. User Activity Review

  7. For each suspicious user:
  8. View user activity timeline
  9. Check authentication events

  10. Review all actions in time window

  11. Pattern Analysis

  12. Look for unusual access patterns
  13. Check access times (after hours?)
  14. Review IP addresses (unusual locations?)

  15. Check user agent (automated tools?)

  16. Correlation

  17. Did user access other sensitive resources?
  18. Were changes made after access?

  19. Are compliance tags affected?

  20. Response

  21. Revoke access if unauthorized
  22. Document findings
  23. Update access controls
  24. Create alert rule for similar patterns

Investigating Data Modifications

Scenario: Unexpected data changes detected

  1. Initial Review
  2. Open Risk & Compliance → Audit Log
  3. Search for the resource type, or for updated / deleted

  4. Identify when changes occurred

  5. Change Details

  6. The page shows that something changed, not what changed. For the field detail, take a JSON export bounded to the window you identified
  7. Review changed_fields, and compare old_values with new_values

  8. Check who made changes

  9. Context Gathering

  10. View user activity timeline
  11. Check what led to changes
  12. Review surrounding actions

  13. Check if part of normal workflow

  14. Impact Assessment

  15. What data was affected?
  16. Are compliance requirements impacted?
  17. Do changes violate policies?

  18. Were proper approvals obtained?

  19. Remediation

  20. Revert changes if unauthorized
  21. Contact user if unclear
  22. Update approval workflows
  23. Add safeguards to prevent recurrence

Compliance Reporting Workflows

SOC2 Audit Preparation

  1. Define Scope
  2. Determine audit period (typically 12 months)
  3. Identify relevant event types

  4. List specific compliance requirements

  5. Pull the events

  6. Call the export endpoint with compliance_tag=soc2 and start_date / end_date set to the audit period (see Getting events out)

  7. A twelve-month period will exceed the 10,000-event cap; pull it month by month and keep each response

  8. Evidence Collection

  9. Repeat the export for access-control and authentication events (event_category=authentication)
  10. Collect configuration-change events the same way

  11. Keep the raw responses: they are the evidence, and re-pulling later gives a different window

  12. Analysis

  13. Review for anomalies
  14. Document any incidents
  15. Verify controls functioning

  16. Prepare explanations for auditors

  17. Reporting

  18. Generate the framework report and deliver it to the compliance team
  19. Maintain historical reports — the platform keeps the trail, not your assembled evidence packages

GDPR Compliance Reporting

  1. Data Access Logging
  2. Export with compliance_tag=gdpr, or event_category=data for access and export events specifically

  3. Document access purposes

  4. Data Subject Requests

  5. For everything the platform holds about one member, use Settings → People & Access → Members → Export this member's data — it is built for exactly this request and states inside what it leaves out. See Tenant Admin Guide → People & Access

  6. For that member's activity specifically, export with their user_id

  7. Data Retention

  8. Retention policies apply to the whole platform and are set by your platform operator in the admin console (Security & Trust → Retention)
  9. Agree GDPR-compliant periods (730 days) with your operator
  10. Document retention decisions

  11. Implement automated deletion

  12. Regular Reporting

  13. Take the export monthly — there is no console control that does it for you
  14. Review data access patterns
  15. Monitor for unauthorized access
  16. Report to Data Protection Officer

HIPAA Audit Trail

  1. Required Events
  2. All PHI access events
  3. User authentication
  4. Configuration changes
  5. Security incidents

  6. System access

  7. Retention Requirements

  8. Ask your platform operator for 7-year retention (2555 days); retention is set platform-wide in the admin console (Security & Trust → Retention)
  9. Ensure logs tamper-proof

  10. Maintain backup copies

  11. Audit Trail Review

  12. Filter by hipaa compliance tag
  13. Review monthly
  14. Document review completion

  15. Report exceptions

  16. Incident Response

  17. Create alert rules for suspicious PHI access
  18. Document all security incidents
  19. Generate incident reports
  20. Maintain incident log

Best Practices

Regular Monitoring

Daily - Review the alert inbox under Remediation → Alerts - Check for failed authentication attempts - Monitor critical resource changes

Weekly - Review activity log summary - Check compliance gaps - Analyze access patterns - Update alert rules as needed

Monthly - Generate compliance reports - Confirm the platform's retention policies with your operator - Update notification rules

Alert Configuration

Start Simple - Begin with critical events only - Add rules gradually - Test each rule thoroughly - Adjust cooldown periods based on frequency

Reduce Noise - Set appropriate thresholds - Use cooldown periods effectively - Combine similar alerts - Filter out expected events

Tune Continuously - Review triggered alerts weekly - Disable rules that fire too often - Add rules for new threats - Update actions as team changes

Security Investigation

Be Thorough - Don't stop at first finding - Correlate multiple data points - Check for related activity - Document all findings

Act Quickly - Investigate alerts within 24 hours - Respond to security events immediately - Document response actions - Follow up on remediation

Learn and Improve - Review past incidents - Update alert rules - Improve detection capability - Share lessons learned

Compliance Management

Proactive Approach - Review compliance tags quarterly - Confirm retention policies with your platform operator annually - Take a test export before you need a real one, so you find out about the 10,000-event cap on your own schedule rather than an auditor's - Maintain audit readiness

Documentation - Document all compliance processes - Maintain evidence files - Keep audit reports organized - Version control policies

Automation - Pull the export on a regular cadence — the console has no scheduler for it, and personal API tokens cannot be used to script it - Confirm with your platform operator that retention keeps the trail for the period you will be asked about

Last Updated: 2026-09-16