Skip to content

Audit Logs

Audit logs provide a comprehensive record of all actions performed within your Escape organization. Essential for security monitoring, compliance reporting, and incident investigation.

Overview

The audit log tracks:

  • User authentication and access
  • Scan lifecycle events (started, finished, failed)
  • Configuration changes
  • Issue status updates
  • Profile and asset modifications
  • All API interactions

Audit logs are critical for:

  • Compliance: SOC 2, ISO 27001, PCI DSS, HIPAA
  • Security Monitoring: Detect unauthorized access or suspicious activities
  • Incident Response: Investigate security events and track changes
  • Accountability: Track who did what and when

Listing Audit Logs

View organization activity history with flexible filtering.

escape-cli audit list [flags]

Aliases: ls, logs, audits

Filtering Options

Flag Short Description Format
--date-from -f Start date RFC3339 (e.g., 2025-01-01T00:00:00Z)
--date-to -t End date RFC3339
--event-type -e Event type Event type string
--actor -a Filter by actor User ID or email
--search -s Free-text search Any string

Default Time Range: Last 12 hours

Basic Examples

# List recent audit logs (last 12 hours)
escape-cli audit list

# List last 24 hours
escape-cli audit list --date-from $(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)

# List specific date range
escape-cli audit list \
  --date-from 2025-01-01T00:00:00Z \
  --date-to 2025-01-31T23:59:59Z

# List today's logs
escape-cli audit list \
  --date-from $(date -u +%Y-%m-%dT00:00:00Z)

Filtering by Event Type

# Scan events
escape-cli audit list --event-type scan.started
escape-cli audit list --event-type scan.finished
escape-cli audit list --event-type scan.failed

# User authentication events
escape-cli audit list --event-type user.authenticated
escape-cli audit list --event-type user.login

# Configuration changes
escape-cli audit list --event-type profile.updated
escape-cli audit list --event-type asset.created

Filtering by Actor

# Filter by specific user
escape-cli audit list --actor user@example.com

# Filter by user ID
escape-cli audit list --actor 00000000-0000-0000-0000-000000000000

Free-Text Search

# Search across all log fields
escape-cli audit list --search "production"
escape-cli audit list --search "failed"
escape-cli audit list --search "critical"

Output Format

Table Format (Default)

escape-cli audit list

Example Output:

DATE                      ACTION              ACTOR               ACTOR EMAIL           TITLE
2025-10-15T10:30:00Z     scan.started        john-doe            john@example.com      Started scan on Production API
2025-10-15T10:15:00Z     profile.updated     jane-smith          jane@example.com      Updated profile configuration
2025-10-15T10:00:00Z     user.authenticated  admin-user          admin@example.com     User authenticated via API key

JSON Format

escape-cli audit list -o json

Example Output:

[
  {
    "date": "2025-10-15T10:30:00Z",
    "action": "scan.started",
    "actor": "john-doe",
    "actorEmail": "john@example.com",
    "title": "Started scan on Production API",
    "details": {
      "scanId": "00000000-0000-0000-0000-000000000001",
      "profileId": "00000000-0000-0000-0000-000000000002"
    }
  }
]

Common Event Types

Scan Events

Event Type Description
scan.started Scan initiated
scan.finished Scan completed successfully
scan.failed Scan encountered an error
scan.canceled Scan was cancelled
scan.ignored Scan marked as ignored

Profile Events

Event Type Description
profile.created New profile created
profile.updated Profile configuration changed
profile.deleted Profile removed

Asset Events

Event Type Description
asset.created New asset added
asset.updated Asset metadata changed
asset.deleted Asset removed

Issue Events

Event Type Description
issue.created New issue discovered
issue.updated Issue status or properties changed
issue.resolved Issue marked as resolved
issue.reopened Resolved issue found again

User Events

Event Type Description
user.authenticated User logged in
user.created New user account created
user.updated User account modified
user.deleted User account removed

Location Events

Event Type Description
location.created New private location created
location.started Location agent started
location.stopped Location agent stopped
location.updated Location configuration changed

Compliance Reporting

Generate Monthly Report

#!/bin/bash
# Generate compliance report for the month

MONTH="2025-01"
START_DATE="${MONTH}-01T00:00:00Z"
END_DATE="${MONTH}-31T23:59:59Z"

escape-cli audit list \
  --date-from "$START_DATE" \
  --date-to "$END_DATE" \
  -o json > "audit-report-${MONTH}.json"

echo "Audit report generated: audit-report-${MONTH}.json"

# Generate summary
jq 'group_by(.action) | map({action: .[0].action, count: length})' \
  "audit-report-${MONTH}.json" > "audit-summary-${MONTH}.json"

echo "Summary generated: audit-summary-${MONTH}.json"

Generate User Activity Report

#!/bin/bash
# Track all actions by a specific user

USER_EMAIL="user@example.com"
START_DATE="2025-01-01T00:00:00Z"

escape-cli audit list \
  --actor "$USER_EMAIL" \
  --date-from "$START_DATE" \
  -o json > "user-activity-${USER_EMAIL}.json"

# Count actions by type
jq 'group_by(.action) | map({action: .[0].action, count: length})' \
  "user-activity-${USER_EMAIL}.json"

Export for SIEM Integration

#!/bin/bash
# Export audit logs to SIEM (Splunk, ELK, etc.)

# Get last hour of logs
ONE_HOUR_AGO=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)

escape-cli audit list \
  --date-from "$ONE_HOUR_AGO" \
  -o json | \
  jq -c '.[]' | \
  while read -r log; do
    # Send to SIEM endpoint
    curl -X POST https://siem.example.com/api/logs \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SIEM_TOKEN" \
      -d "$log"
  done

Security Monitoring

Monitor Failed Authentication

# Monitor failed login attempts
escape-cli audit list --event-type user.authentication.failed -o json | \
  jq -r '.[] | "\(.date) - \(.actorEmail) - Failed login from \(.details.ipAddress)"'

Track Configuration Changes

# Monitor all configuration changes
escape-cli audit list \
  --date-from $(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ) \
  -o json | \
  jq '.[] | select(.action | contains("updated") or contains("created") or contains("deleted"))'

Alert on Suspicious Activity

#!/bin/bash
# Alert on multiple failed scans

FAILED_SCANS=$(escape-cli audit list \
  --event-type scan.failed \
  --date-from $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) \
  -o json | jq 'length')

if [ "$FAILED_SCANS" -gt 5 ]; then
  echo "ALERT: $FAILED_SCANS failed scans in the last hour"
  # Send alert (email, Slack, PagerDuty, etc.)
fi

Data Analysis

Count Events by Type

escape-cli audit list \
  --date-from 2025-01-01T00:00:00Z \
  -o json | \
  jq 'group_by(.action) | map({action: .[0].action, count: length}) | sort_by(.count) | reverse'

Example Output:

[
  {"action": "scan.finished", "count": 450},
  {"action": "scan.started", "count": 450},
  {"action": "issue.updated", "count": 123},
  {"action": "profile.updated", "count": 45},
  {"action": "user.authenticated", "count": 38}
]

Most Active Users

escape-cli audit list \
  --date-from 2025-01-01T00:00:00Z \
  -o json | \
  jq 'group_by(.actorEmail) | map({user: .[0].actorEmail, actions: length}) | sort_by(.actions) | reverse | .[0:10]'

Activity Timeline

# Get hourly activity distribution
escape-cli audit list \
  --date-from $(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ) \
  -o json | \
  jq -r '.[] | .date' | \
  cut -d'T' -f2 | \
  cut -d':' -f1 | \
  sort | uniq -c | \
  awk '{print $2":00 - " $1 " events"}'

Continuous Monitoring

Real-Time Log Monitoring

#!/bin/bash
# Monitor audit logs in real-time (poll every 30 seconds)

LAST_CHECK=$(date -u +%Y-%m-%dT%H:%M:%SZ)

while true; do
  sleep 30
  NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  NEW_LOGS=$(escape-cli audit list \
    --date-from "$LAST_CHECK" \
    --date-to "$NOW" \
    -o json)

  if [ "$(echo "$NEW_LOGS" | jq 'length')" -gt 0 ]; then
    echo "=== New Activity ==="
    echo "$NEW_LOGS" | jq -r '.[] | "\(.date) [\(.action)] \(.actorEmail) - \(.title)"'
  fi

  LAST_CHECK=$NOW
done

Scheduled Reports

#!/bin/bash
# Daily audit report (run via cron)

DATE=$(date -u -d 'yesterday' +%Y-%m-%d)
REPORT_FILE="audit-daily-${DATE}.json"

escape-cli audit list \
  --date-from "${DATE}T00:00:00Z" \
  --date-to "${DATE}T23:59:59Z" \
  -o json > "$REPORT_FILE"

# Generate summary
TOTAL=$(jq 'length' "$REPORT_FILE")
SCANS=$(jq '[.[] | select(.action | contains("scan"))] | length' "$REPORT_FILE")
ISSUES=$(jq '[.[] | select(.action | contains("issue"))] | length' "$REPORT_FILE")

cat > "daily-summary-${DATE}.txt" <<EOF
Audit Log Summary for $DATE
============================
Total Events: $TOTAL
Scan Events: $SCANS
Issue Events: $ISSUES

Full report: $REPORT_FILE
EOF

# Email or send to monitoring system
cat "daily-summary-${DATE}.txt"

Best Practices

Retention and Archiving

  • Export audit logs regularly for long-term storage
  • Maintain at least 90 days of audit history for compliance
  • Archive logs to secure, immutable storage (S3, Azure Blob)
  • Implement log rotation and cleanup policies

Access Control

  • Restrict audit log access to authorized personnel
  • Use dedicated service accounts for automated log collection
  • Enable multi-factor authentication for audit log access
  • Regularly review who has access to audit logs

Monitoring and Alerting

  • Set up alerts for critical events (failed scans, configuration changes)
  • Monitor for unusual patterns or anomalies
  • Integrate with SIEM systems for centralized monitoring
  • Create dashboards for real-time visibility

Compliance

  • Document audit log review procedures
  • Schedule regular audit log reviews
  • Maintain evidence of log reviews for auditors
  • Ensure audit logs cannot be tampered with

Integration Examples

Splunk Integration

#!/bin/bash
# Send audit logs to Splunk

escape-cli audit list \
  --date-from $(date -u -d '5 minutes ago' +%Y-%m-%dT%H:%M:%SZ) \
  -o json | \
  jq -c '.[]' | \
  while read -r event; do
    curl -k https://splunk.example.com:8088/services/collector/event \
      -H "Authorization: Splunk $SPLUNK_TOKEN" \
      -d "{\"event\": $event, \"sourcetype\": \"escape:audit\"}"
  done

Elasticsearch Integration

#!/bin/bash
# Send audit logs to Elasticsearch

escape-cli audit list \
  --date-from $(date -u -d '5 minutes ago' +%Y-%m-%dT%H:%M:%SZ) \
  -o json | \
  jq -c '.[]' | \
  while read -r event; do
    curl -X POST "http://elasticsearch.example.com:9200/escape-audit/_doc" \
      -H "Content-Type: application/json" \
      -d "$event"
  done

Slack Notifications

#!/bin/bash
# Send critical events to Slack

escape-cli audit list \
  --event-type scan.failed \
  --date-from $(date -u -d '10 minutes ago' +%Y-%m-%dT%H:%M:%SZ) \
  -o json | \
  jq -c '.[]' | \
  while read -r event; do
    MESSAGE=$(echo "$event" | jq -r '"\(.date): \(.title)"')
    curl -X POST "$SLACK_WEBHOOK_URL" \
      -H "Content-Type: application/json" \
      -d "{\"text\": \":warning: Failed Scan Alert\n${MESSAGE}\"}"
  done

Troubleshooting

No Logs Returned

If no audit logs are returned:

  • Check date range (default is last 12 hours)
  • Verify you have permission to view audit logs
  • Ensure the organization has activity in the specified timeframe
  • Try removing filters to see all logs

Incomplete Log Data

If log entries are missing information:

  • Some fields may be null for certain event types
  • Use JSON output to see all available fields
  • Check API permissions for your account

Performance Issues

For large date ranges:

  • Break queries into smaller time chunks
  • Use specific event-type filters when possible
  • Export to JSON and process locally for complex analysis
  • Consider using pagination for very large result sets

Next Steps