Audit Logs

Monitor and track security events in real-time

Overview

TruSec automatically logs all security-relevant events in your application. Audit logs provide a complete, immutable record of who did what, when, and from where.

Log Structure

Every audit log entry contains:

{
  "id": "log_abc123def456",
  "timestamp": "2024-01-15T14:30:00.000Z",
  "event": "user.login",
  "actor": {
    "id": "user_123",
    "email": "[e-mail]",
    "type": "user"
  },
  "target": {
    "id": "session_789",
    "type": "session"
  },
  "context": {
    "ip": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "location": {
      "city": "San Francisco",
      "country": "US"
    }
  },
  "result": "success",
  "traceId": "trace_xyz789"
}

Querying Logs

Basic Query

Retrieve recent logs:

const logs = await trusec.logs.list({
  limit: 100,
  order: 'desc',
});

Filtered Query

Filter logs by event type, actor, or time range:

const logs = await trusec.logs.list({
  events: ['user.login', 'user.logout'],
  actor: 'user_123',
  from: '2024-01-01T00:00:00Z',
  to: '2024-01-31T23:59:59Z',
  result: 'failure',
});

Search Query

Full-text search across log entries:

const logs = await trusec.logs.search({
  query: 'password reset',
  from: '2024-01-01T00:00:00Z',
});

Event Types

Authentication

Event	Description
user.login	User logged in
user.logout	User logged out
user.login.failed	Failed login attempt
session.created	New session created
session.revoked	Session revoked
mfa.enabled	MFA enabled for user
mfa.verified	MFA code verified

Authorization

Event	Description
policy.evaluated	Policy was evaluated
access.granted	Access was granted
access.denied	Access was denied
role.assigned	Role assigned to user
role.removed	Role removed from user

Management

Event	Description
user.created	New user created
user.updated	User profile updated
user.deleted	User deleted
policy.created	New policy created
policy.updated	Policy updated
policy.deleted	Policy deleted
apikey.created	API key created
apikey.revoked	API key revoked

Real-time Streaming

Subscribe to log events in real-time using webhooks or our streaming API:

Webhooks

await trusec.webhooks.create({
  url: 'https://yourapp.com/webhooks/trusec',
  events: ['user.login.failed', 'access.denied'],
  secret: 'whsec_your_webhook_secret',
});

Streaming API

const stream = trusec.logs.stream({
  events: ['*'], // All events
});

stream.on('log', (log) => {
  console.log('New event:', log.event);
  
  if (log.event === 'user.login.failed') {
    alertSecurityTeam(log);
  }
});

Log Retention

Log retention periods vary by plan. Enterprise plans include unlimited retention.

Plan	Retention
Free	7 days
Pro	90 days
Enterprise	Unlimited

Exporting Logs

Export logs for compliance or analysis:

const export = await trusec.logs.export({
  from: '2024-01-01T00:00:00Z',
  to: '2024-01-31T23:59:59Z',
  format: 'json', // or 'csv'
});

// Download the export
const downloadUrl = export.downloadUrl;

Compliance

TruSec audit logs help you meet compliance requirements:

SOC 2

Complete audit trail for all access and changes

GDPR

Track data access and processing activities

HIPAA

Monitor access to protected health information

PCI DSS

Log all access to cardholder data

Alerting

Set up alerts for critical security events:

await trusec.alerts.create({
  name: 'Suspicious Login Activity',
  condition: {
    event: 'user.login.failed',
    threshold: 5,
    window: '5m',
  },
  actions: [
    {
      type: 'email',
      to: '[e-mail]',
    },
    {
      type: 'slack',
      channel: '#security-alerts',
    },
  ],
});