Sending Your First Security Event

Once you've installed the LiteSOC SDK, it's time to start tracking security events. This guide covers the fundamentals of event tracking and shows you how to send your first event.

Understanding Security Events

LiteSOC uses a standardized event schema to track security-relevant activities. Each event contains:

• event: The event type (e.g., auth.login.success)
• actor: Information about the user performing the action
• target (optional): The resource being acted upon
• metadata (optional): Additional context about the event

Event Types

LiteSOC supports 26 standard event types across 5 categories:

Basic Event Structure

Here's the anatomy of a security event:

interface SecurityEvent {
  event: string;           // Required: event type
  actor: {
    id: string;            // Required: unique user identifier
    email?: string;        // Optional: user's email
    name?: string;         // Optional: user's display name
  };
  target?: {
    id: string;            // Resource identifier
    type: string;          // Resource type (e.g., 'document', 'user')
    name?: string;         // Resource name
  };
  metadata?: Record<string, unknown>;  // Additional context
}

Example: Tracking a Login Event

Let's track a successful login in your authentication handler:

import litesoc from './litesoc';
import { getClientIp } from './utils';

async function handleLogin(email: string, password: string, req: Request) {
  // Your authentication logic
  const user = await authenticateUser(email, password);
  
  if (user) {
    // Track successful login
    await litesoc.track({
      event: 'auth.login.success',
      actor: {
        id: user.id,
        email: user.email,
        name: user.name,
      },
      metadata: {
        ip_address: getClientIp(req),
        user_agent: req.headers.get('user-agent'),
        method: 'password',
      },
    });
    
    return { success: true, user };
  } else {
    // Track failed login attempt
    await litesoc.track({
      event: 'auth.login.failure',
      actor: {
        id: 'unknown',
        email: email, // Log the attempted email
      },
      metadata: {
        ip_address: getClientIp(req),
        user_agent: req.headers.get('user-agent'),
        reason: 'invalid_credentials',
      },
    });
    
    return { success: false, error: 'Invalid credentials' };
  }
}

Example: Tracking Data Access

Track when users access sensitive data:

async function downloadReport(userId: string, reportId: string) {
  const report = await getReport(reportId);
  
  await litesoc.track({
    event: 'data.export.requested',
    actor: {
      id: userId,
    },
    target: {
      id: reportId,
      type: 'report',
      name: report.title,
    },
    metadata: {
      format: 'pdf',
      size_bytes: report.size,
    },
  });
  
  return report;
}

Example: Tracking Permission Changes

Monitor administrative actions:

async function changeUserRole(adminId: string, targetUserId: string, newRole: string) {
  const previousRole = await getUserRole(targetUserId);
  
  await updateUserRole(targetUserId, newRole);
  
  await litesoc.track({
    event: 'admin.role.changed',
    actor: {
      id: adminId,
    },
    target: {
      id: targetUserId,
      type: 'user',
    },
    metadata: {
      previous_role: previousRole,
      new_role: newRole,
    },
  });
}

Automatic IP Intelligence

When you include an ip_address in your metadata, LiteSOC automatically:

• ✅ Resolves geolocation (country, city, coordinates)
• ✅ Detects VPN, Tor, and proxy usage
• ✅ Identifies datacenter IPs
• ✅ Calculates threat scores
• ✅ Triggers impossible travel detection

Best Practices

1. Always include actor.id: This enables user behavior analysis
2. Use consistent event types: Stick to the 26 standard events
3. Include IP when available: Enables geolocation and threat detection
4. Don't log sensitive data: Never include passwords, tokens, or PII in metadata
5. Handle errors gracefully: Wrap tracking calls in try-catch

// Good practice: non-blocking tracking
try {
  await litesoc.track(event);
} catch (error) {
  // Log but don't fail the main operation
  logger.warn('Failed to track security event', { error });
}

View Your Events

After sending events, view them in your LiteSOC Dashboard:

1. Go to Events in the sidebar
2. You'll see your events appear in real-time
3. Click any event to see the full details, including enriched IP intelligence

Next Steps

• Understanding detection alerts
• Setting up Slack notifications
• Connecting to n8n

Need help? Contact our support team or check our API documentation.