plugin audit log - nself-org/cli GitHub Wiki

Plugin: audit-log

Append-only audit log for security-relevant events. Captures auth activity, privilege changes, secret access, and plugin install/uninstall. Queryable from Admin with filters by event type, actor, severity, and time range.

Security-Always-Free: This plugin has no license requirement. Audit logging is a core security feature available to all nSelf users at no cost.

Install

nself plugin install audit-log
nself build
nself start

Schema: np_auditlog_events

Column Type Description
id TEXT (PK) Unique event ID (UUID)
source_account_id TEXT DEFAULT 'primary' Multi-app isolation — which app in this nSelf deploy generated the event
actor_user_id TEXT User who performed the action (null for system events)
actor_type TEXT user, system, plugin, api_key
event_type TEXT Dot-notation event identifier, e.g. auth.login.success, plugin.install
resource_type TEXT What was acted on: user, secret, plugin, table, etc.
resource_id TEXT ID of the affected resource
ip_address TEXT Client IP at time of event
user_agent TEXT HTTP User-Agent header
metadata JSONB Structured event-specific data
severity TEXT info, warn, error, critical
created_at TIMESTAMPTZ Event timestamp (partitioned by this column)

The table is partitioned by RANGE (created_at) for scalable long-term retention.

Append-only enforcement

RLS policies block UPDATE and DELETE on np_auditlog_events. Events are immutable once written. This is enforced at the database level — not just the application layer.

HTTP API

All endpoints require the X-Plugin-Secret header (set to PLUGIN_INTERNAL_SECRET).

Method Path Description
GET /health Health check — returns {"status":"ok"}
POST /events Write one or more audit events
GET /events Query events with filters
GET /events/{id} Fetch a single event by ID
GET /events/export Export events as JSON or CSV
GET /admin/events Admin query — also accepts HASURA_GRAPHQL_ADMIN_SECRET header

POST /events — write an event

curl -X POST http://127.0.0.1:3308/events \
  -H "X-Plugin-Secret: $PLUGIN_INTERNAL_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "auth.login.success",
    "actor_user_id": "user-abc",
    "actor_type": "user",
    "resource_type": "session",
    "resource_id": "session-xyz",
    "severity": "info",
    "ip_address": "192.168.1.100",
    "metadata": {"mfa_used": true}
  }'

GET /events — query with filters

Query param Description
event_type Filter by event type (exact or prefix)
actor_user_id Filter by actor
actor_type Filter by actor type
severity Filter by severity level
resource_type Filter by resource type
resource_id Filter by resource ID
from Start of time range (ISO 8601)
to End of time range (ISO 8601)
limit Max results (default 100, max 1000)
cursor Pagination cursor from previous response
source_account_id Filter by app (multi-app deployments) 
# Get all auth events from the last 24 hours
curl "http://127.0.0.1:3308/events?event_type=auth&from=2026-05-16T00:00:00Z" \
  -H "X-Plugin-Secret: $PLUGIN_INTERNAL_SECRET"

GET /events/export — bulk export

# Export as CSV
curl "http://127.0.0.1:3308/events/export?format=csv&from=2026-05-01T00:00:00Z" \
  -H "X-Plugin-Secret: $PLUGIN_INTERNAL_SECRET" \
  -o audit-may-2026.csv

# Export as JSON
curl "http://127.0.0.1:3308/events/export?format=json&severity=critical" \
  -H "X-Plugin-Secret: $PLUGIN_INTERNAL_SECRET"

Configuration

Env var Required Description
DATABASE_URL Yes PostgreSQL connection string
PORT No Plugin port (default: 3308)
HASURA_GRAPHQL_ADMIN_SECRET No Enables the /admin/events endpoint for Hasura-level admin queries
PLUGIN_INTERNAL_SECRET No Shared secret for X-Plugin-Secret header authentication

Common event types

Event type Triggered by
auth.login.success Successful login
auth.login.failure Failed login attempt
auth.logout User logout
auth.mfa.enabled MFA turned on
auth.mfa.disabled MFA turned off
auth.password.changed Password change
plugin.install Plugin installed
plugin.uninstall Plugin removed
secret.accessed Vault secret read
secret.rotated Vault secret rotated
privilege.granted Role/permission added
privilege.revoked Role/permission removed

Querying from Admin

The nSelf Admin UI (localhost:3021) includes an Audit Log viewer under Security. You can filter by event type, actor, severity, and date range without writing SQL.

For custom queries, connect directly to Postgres:

SELECT event_type, actor_user_id, severity, created_at, metadata
FROM np_auditlog_events
WHERE event_type LIKE 'auth%'
  AND created_at > NOW() - INTERVAL '7 days'
ORDER BY created_at DESC
LIMIT 100;

Security notes

  • Port 3308 binds to 127.0.0.1 — never exposed externally.
  • Events are immutable at the database level (RLS blocks UPDATE/DELETE).
  • No license required — audit logging is free for all nSelf users (Security-Always-Free).
  • nself doctor --deep includes check PERM-RLS-01 to verify append-only RLS is active.

See also