Audit Logs

Overview

NetStacks Controller maintains a comprehensive audit log that records every significant action performed on the platform. Every login attempt, user change, device configuration push, credential access, role modification, and settings update is captured with full attribution — who did it, when, from which IP address, and what exactly changed.

Audit logs serve three primary purposes:

• Security monitoring — Detect unauthorized access attempts, privilege escalation, and suspicious activity patterns across the platform.
• Compliance — Meet regulatory requirements (SOX, PCI-DSS, SOC 2, HIPAA) with tamper-resistant records of all administrative and operational actions.
• Troubleshooting — Trace the sequence of events leading to a problem, such as identifying who changed a device configuration that caused a network outage.

How It Works

Event Schema

Each audit log entry is stored in PostgreSQL with the following fields:

Event Types

Events follow a resource.action naming convention. The following event types are recorded throughout the platform:

Pagination and Filtering

The audit log API supports server-side pagination with configurable page size (1–100 entries per page). Filters can be applied for event type, actor ID, and date range (from/to). The API returns total count and total pages for navigation.

Event Type Discovery

The /api/admin/audit/event-types endpoint returns all distinct event types that have been recorded, making it easy to populate filter dropdowns in the UI without hardcoding the list.

Step-by-Step Guide

Viewing Recent Events

1. Navigate to Admin → Audit Logs.
2. The default view shows the most recent events sorted by timestamp (newest first).
3. Each entry shows the event type, actor (username or email), timestamp, and IP address.
4. Click an entry to expand the details panel, which shows the full JSON payload with all event-specific data.

Filtering and Searching

1. Use the Event Type dropdown to filter by category (e.g., show only auth.login_failed events to investigate failed login attempts).
2. Use the User filter to show events from a specific actor.
3. Set the Date Range to narrow results to a specific time window (e.g., last 24 hours, last 7 days, or a custom range).
4. Combine filters to answer specific questions like “Show all credential access events by user jsmith in the last 48 hours.”

Exporting Audit Logs

1. Apply the desired filters to narrow the dataset.
2. Click Export and select the format:
   • CSV — For spreadsheet analysis in Excel or Google Sheets.
   • JSON — For programmatic processing or SIEM import.
3. The export includes all events matching the current filters, not just the visible page.

Configuring SIEM Export

1. Navigate to Admin → Settings → Integrations → SIEM.
2. Select the export format:
   • Syslog (RFC 5424) — Standard syslog format for most SIEM platforms.
   • CEF (Common Event Format) — For ArcSight, QRadar, and similar.
   • JSON — Structured JSON over HTTPS webhook for Splunk, Elastic, or custom collectors.
3. Enter the destination:
   • Syslog: syslog://siem.dc1.example.net:514 (UDP) or syslog+tls://siem.dc1.example.net:6514 (TLS)
   • Webhook: https://siem.dc1.example.net/api/events
4. Set the export schedule (real-time streaming or batched at intervals).
5. Click Test Connection to verify the SIEM endpoint is reachable and accepting events.
6. Click Enable to start forwarding audit events.

Code Examples

Audit log endpoints are under /api/admin/audit. All operations require the admin.audit permission.

Query Audit Logs with Filters

curl "https://netstacks.dc1.example.net/api/admin/audit?event_type=auth.login_failed&from_date=2025-03-01T00:00:00Z&to_date=2025-03-15T23:59:59Z&limit=50&page=1" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "data": [
    {
      "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
      "event_type": "auth.login_failed",
      "actor_id": null,
      "actor_email": null,
      "resource_type": null,
      "resource_id": null,
      "details": {
        "username": "admin",
        "reason": "invalid_password",
        "auth_source": "local"
      },
      "ip_address": "10.0.1.50",
      "created_at": "2025-03-15T14:30:22Z"
    },
    {
      "id": "f2a3b4c5-d6e7-8901-bcde-f23456789012",
      "event_type": "auth.login_failed",
      "actor_id": null,
      "actor_email": null,
      "resource_type": null,
      "resource_id": null,
      "details": {
        "username": "jsmith",
        "reason": "ldap_bind_failed",
        "auth_source": "ldap"
      },
      "ip_address": "192.168.10.25",
      "created_at": "2025-03-14T09:15:44Z"
    }
  ],
  "total": 23,
  "page": 1,
  "limit": 50,
  "total_pages": 1
}

List Available Event Types

curl https://netstacks.dc1.example.net/api/admin/audit/event-types \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  "auth.login",
  "auth.login_failed",
  "auth.logout",
  "auth.password_changed",
  "certificate.issued",
  "credential.accessed",
  "credential.created",
  "credential.password_viewed",
  "device.config.push",
  "device.created",
  "device.updated",
  "role.created",
  "role.updated",
  "settings.updated",
  "stack.deployed",
  "user.created",
  "user.deleted",
  "user.role_assigned",
  "user.role_removed",
  "user.roles_updated",
  "user.updated"
]

Filter by User (Actor ID)

# Find all actions by a specific user
curl "https://netstacks.dc1.example.net/api/admin/audit?actor_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=25" \
  -H "Authorization: Bearer $TOKEN"

Audit Log Entry: Device Configuration Push

{
  "id": "a3b4c5d6-e7f8-9012-cdef-345678901234",
  "event_type": "device.config.push",
  "actor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "actor_email": "jsmith@dc1.example.net",
  "resource_type": "device",
  "resource_id": "core-rtr-01.dc1.example.net",
  "details": {
    "device_name": "core-rtr-01.dc1.example.net",
    "device_ip": "10.0.0.1",
    "template": "bgp-neighbor-config",
    "stack": "dc1-core-routing",
    "result": "success",
    "changes_applied": 12
  },
  "ip_address": "10.0.1.50",
  "created_at": "2025-03-15T14:30:00Z"
}

SIEM Syslog Format Example

<134>1 2025-03-15T14:30:00Z netstacks.dc1.example.net netstacks - audit [action="device.config.push" user="jsmith" device="core-rtr-01.dc1.example.net" result="success" ip="10.0.1.50"]

SIEM CEF Format Example

CEF:0|NetStacks|Controller|1.0|device.config.push|Configuration Push|3|src=10.0.1.50 suser=jsmith dst=10.0.0.1 dhost=core-rtr-01.dc1.example.net outcome=success msg=BGP neighbor config applied

Questions & Answers

What events are captured in the audit log?

Every significant action is logged, including: authentication events (login, logout, failed attempts, password changes), user management (create, update, delete, role assignments), device operations (create, update, delete, config push), credential access (creation, usage, password viewing), role management (create, update, delete), settings changes, stack deployments, MOP executions and approvals, and SSH certificate issuance. Each event includes the actor, timestamp, IP address, and structured details specific to the action.

How long are audit logs retained?

By default, audit logs are retained indefinitely in the PostgreSQL database. For high-volume deployments, you can configure a retention policy to automatically archive or delete logs older than a specified period (e.g., 90 days, 1 year). Compliance requirements (SOX, PCI-DSS) typically mandate a minimum retention of 1–7 years. Configure retention in Admin → Settings.

Can I export audit logs to a SIEM?

Yes. NetStacks supports SIEM integration through syslog (RFC 5424), CEF (Common Event Format), and JSON webhook export. Configure the export destination and format in Admin → Settings → Integrations → SIEM. You can choose real-time streaming or batched export at configurable intervals. Supported destinations include syslog servers, Splunk HEC, Elastic, and custom HTTPS endpoints.

How do I find who changed a device configuration?

Filter the audit log by event type device.config.push and optionally by the device name or IP in the details. Each config push event includes the actor (who pushed the config), the template and stack used, the number of changes applied, and whether the push succeeded or failed. Via the API, query with?event_type=device.config.push and inspect the detailsJSON for the device identifier.

Does the audit log capture API access?

Yes. All authenticated API operations that modify data are logged as audit events. Read-only API calls (listing devices, viewing settings) are not logged individually to avoid excessive log volume, but authentication events (token issuance, refresh, failed attempts) are always captured. The ip_address field records the client IP for every event.

Can I see credential access history?

Yes. When a credential is used to connect to a device, a credential.accessedevent is logged. When a user reveals a credential password in the UI, acredential.password_viewed event is logged. Filter by these event types to audit who accessed which credentials and when.

Troubleshooting

Audit Logs Growing Too Large

• Configure a retention policy in Admin → Settings to archive or delete logs older than your compliance requirement.
• Set up SIEM export to offload logs to a dedicated log management platform (Splunk, Elastic, Loki) and reduce database storage pressure.
• Consider PostgreSQL table partitioning by date for large audit log tables to improve query performance.

SIEM Export Not Sending

• Check network connectivity from the Controller to the SIEM endpoint: nc -zv siem.dc1.example.net 514
• Verify authentication credentials for webhook-based exports (API keys, tokens).
• For TLS syslog, ensure the SIEM server's certificate is trusted by the Controller.
• Check Controller logs for SIEM-related error messages (connection refused, timeout, authentication failure).
• Use the Test Connection button in the SIEM configuration to verify the endpoint.

Missing Audit Events

• Verify you have the admin.audit permission. Without it, the API returns 403 and no events are visible.
• Check the date range filter — a narrow range may exclude the events you are looking for.
• Verify the event type filter is not excluding the events. Clear all filters to see the full log.
• Some operations log events asynchronously (non-blocking). In rare cases, events may appear with a slight delay.

Search Returns No Results

• Widen the date range to ensure you are not filtering out events by time.
• Clear all filters and verify events exist in the log at all.
• Check the event type spelling — use the /api/admin/audit/event-types endpoint to get the exact list of event types recorded in your system.
• For actor-based searches, use the actor UUID, not the username. Get the UUID from Admin → Users.

Related Features

• User Management — User actions (creation, updates, deletions, role changes) are all captured in the audit log.
• Roles & Permissions — Role changes (creation, permission updates, deletions) generate audit events.
• Authentication (LDAP/OIDC) — Authentication events (login, logout, failures) are key audit log entries.
• System Settings — Settings changes and SIEM export configuration are managed through settings.
• API Authentication — API token events (issuance, refresh, revocation) appear in the audit log.