Skip to main content

Audit Logs

Comprehensive activity logging for security, compliance, and debugging.

What's Logged​

Every significant action is recorded:

CategoryExamples
AuthenticationLogin, logout, MFA events, failed attempts
AuthorizationPermission changes, role updates
AgentsCreate, update, delete, execute
ConversationsStart, message, end, delete
UsersInvite, update, remove
TeamsCreate, update, membership changes
IntegrationsConnect, disconnect, tool execution
API KeysCreate, rotate, revoke
SettingsConfiguration changes

Viewing Audit Logs​

Via Dashboard​

  1. Go to Security → Audit Logs
  2. Filter by user, action, date range
  3. Export to CSV/JSON

Via API​

const logs = await client.audit.list({
  // Filters
  userId: 'user-123',
  action: 'agent.create',
  severity: 'warning',
  resourceType: 'agent',
  resourceId: 'agent-456',

  // Date range
  startDate: '2024-01-01',
  endDate: '2024-01-31',

  // Search
  search: 'delete',

  // Pagination
  limit: 100,
  offset: 0
});

for (const log of logs.data) {
  console.log({
    id: log.id,
    action: log.action,
    severity: log.severity,
    userId: log.userId,
    resourceType: log.resourceType,
    resourceId: log.resourceId,
    description: log.description,
    metadata: log.metadata,
    ipAddress: log.ipAddress,
    userAgent: log.userAgent,
    timestamp: log.timestamp
  });
}

Log Entry Structure​

interface AuditLogEntry {
  id: string;
  tenantId: string;

  // Who
  userId: string;
  userName?: string;
  ipAddress: string;
  userAgent: string;

  // What
  action: string;
  severity: 'info' | 'warning' | 'critical';
  resourceType: string;
  resourceId: string;
  description: string;

  // Details
  metadata: Record<string, any>;

  // When
  timestamp: string;
}

Action Types​

Authentication Actions​

ActionDescription
auth.loginUser logged in
auth.logoutUser logged out
auth.login_failedFailed login attempt
auth.mfa_enabledMFA was enabled
auth.mfa_verifiedMFA code verified
auth.password_changedPassword was changed
auth.password_resetPassword reset requested
auth.session_revokedSession was terminated

Agent Actions​

ActionDescription
agent.createAgent created
agent.updateAgent configuration changed
agent.deleteAgent deleted
agent.chatChat message sent to agent
agent.tool_executedAgent executed a tool

User Actions​

ActionDescription
user.inviteUser invited
user.joinedUser accepted invite
user.updateUser profile updated
user.role_changedUser role changed
user.deleteUser deleted

Team Actions​

ActionDescription
team.createTeam created
team.updateTeam settings changed
team.deleteTeam deleted
team.member_addedMember added to team
team.member_removedMember removed from team

Integration Actions​

ActionDescription
integration.connectedIntegration connected
integration.disconnectedIntegration revoked
integration.tool_executedIntegration tool called
integration.refreshOAuth token refreshed

API Key Actions​

ActionDescription
api_key.createdAPI key created
api_key.rotatedAPI key rotated
api_key.revokedAPI key revoked

Severity Levels​

LevelDescriptionExamples
infoNormal operationsLogin, create agent
warningPotentially concerningFailed login, permission denied
criticalSecurity-relevantUser deleted, bulk operation

Filter by Severity​

// Get only security-relevant events
const criticalLogs = await client.audit.list({
  severity: 'critical'
});

// Get warnings and above
const warningsAndCritical = await client.audit.list({
  severity: ['warning', 'critical']
});

Search and Filter​

By User​

const userLogs = await client.audit.list({
  userId: 'user-123'
});

By Action​

// Single action
const createLogs = await client.audit.list({
  action: 'agent.create'
});

// Multiple actions
const modifyLogs = await client.audit.list({
  action: ['agent.update', 'agent.delete']
});

// Pattern matching
const allAgentLogs = await client.audit.list({
  action: 'agent.*'
});

By Resource​

const agentLogs = await client.audit.list({
  resourceType: 'agent',
  resourceId: 'agent-123'
});

By Time Range​

const recentLogs = await client.audit.list({
  startDate: '2024-01-15T00:00:00Z',
  endDate: '2024-01-15T23:59:59Z'
});

Full-Text Search​

const searchResults = await client.audit.list({
  search: 'production agent delete'
});

Statistics​

Get aggregated audit data:

const stats = await client.audit.getStats({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

console.log({
  totalEvents: stats.total,
  bySeverity: stats.bySeverity,
  byAction: stats.byAction,
  topUsers: stats.topUsers,
  failedLogins: stats.failedLogins
});

Security Alerts​

Configure alerts for suspicious activity:

await client.audit.createAlert({
  name: 'Multiple Failed Logins',
  condition: {
    action: 'auth.login_failed',
    threshold: 5,
    window: '5m' // 5 failed logins in 5 minutes
  },
  notify: ['security@company.com'],
  severity: 'high'
});

await client.audit.createAlert({
  name: 'Bulk Delete',
  condition: {
    action: '*.delete',
    threshold: 10,
    window: '1h'
  },
  notify: ['admin@company.com']
});

List Alerts​

const alerts = await client.audit.listAlerts();

for (const alert of alerts.data) {
  console.log({
    name: alert.name,
    triggered: alert.triggeredCount,
    lastTriggered: alert.lastTriggeredAt
  });
}

SIEM Integration​

Export logs to your security information and event management system:

Webhook Export​

await client.audit.configureSiemExport({
  type: 'webhook',
  url: 'https://siem.company.com/ingest',
  headers: {
    'Authorization': 'Bearer ${secrets.SIEM_TOKEN}'
  },
  format: 'json', // json, cef, leef
  filters: {
    severity: ['warning', 'critical'],
    actions: ['auth.*', '*.delete']
  },
  realtime: true
});

S3 Export​

await client.audit.configureSiemExport({
  type: 's3',
  bucket: 'company-audit-logs',
  prefix: 'deeployd/',
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY,
    secretAccessKey: process.env.AWS_SECRET_KEY
  },
  format: 'json',
  schedule: 'hourly'
});

Supported SIEM Platforms​

PlatformFormatMethod
SplunkJSON/CEFWebhook/S3
DatadogJSONWebhook
ElasticJSONWebhook
Azure SentinelCEFWebhook
IBM QRadarLEEFWebhook

Log Formats​

JSON (Default)​

{
  "id": "log-123",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "severity": "warning",
  "action": "auth.login_failed",
  "userId": "user-456",
  "userName": "john@company.com",
  "ipAddress": "203.0.113.50",
  "userAgent": "Mozilla/5.0...",
  "resourceType": "auth",
  "description": "Failed login attempt",
  "metadata": {
    "reason": "invalid_password",
    "attemptCount": 3
  }
}

CEF (Common Event Format)​

CEF:0|Deeployd|Platform|1.0|auth.login_failed|Failed login attempt|5|src=203.0.113.50 suser=john@company.com cs1=invalid_password

LEEF (Log Event Extended Format)​

LEEF:2.0|Deeployd|Platform|1.0|auth.login_failed|src=203.0.113.50	usrName=john@company.com	reason=invalid_password

Retention​

Log retention varies by plan:

PlanRetention
Starter7 days
Pro30 days
Business90 days
EnterpriseCustom (up to 7 years)

Configure Retention​

// Enterprise only
await client.audit.setRetention({
  defaultRetention: '365d',
  criticalRetention: '7y', // Keep critical logs longer
  archiveAfter: '90d',
  archiveDestination: 's3://audit-archive/'
});

Export Logs​

CSV Export​

const csv = await client.audit.export({
  format: 'csv',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  columns: ['timestamp', 'action', 'userId', 'description']
});

JSON Export​

const json = await client.audit.export({
  format: 'json',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Best Practices​

1. Regular Reviews​

Schedule regular audit log reviews:

// Weekly security review
const weeklyReview = await client.audit.list({
  severity: ['warning', 'critical'],
  startDate: weekAgo(),
  endDate: now()
});

2. Set Up Alerts​

Don't just log—alert on suspicious patterns:

// Alert on unusual patterns
await client.audit.createAlert({
  name: 'After-Hours Admin Activity',
  condition: {
    action: 'admin.*',
    timeWindow: {
      exclude: '09:00-18:00',
      timezone: 'America/New_York'
    }
  }
});

3. Integrate with SIEM​

For enterprise, send logs to your security team:

await client.audit.configureSiemExport({
  type: 'webhook',
  url: 'https://siem.company.com/ingest',
  realtime: true
});

4. Archive for Compliance​

Keep logs for compliance requirements:

await client.audit.setRetention({
  criticalRetention: '7y' // SOX, HIPAA requirements
});

Next: Explore the Store for pre-built agent templates.