Skip to main content

Mapping JSON Logs

Quick Demo​

Watch this short video to see how to create mappings from JSON logs:

What are JSON Logs?​

JSON logs are structured log entries that are already in JSON format. These logs are fully parsed and contain organized data fields, making them easier to map to the OCSF schema. Common sources of JSON logs include:

  • Modern application logs
  • API responses
  • Cloud service logs (AWS, Azure, GCP)
  • Security tool outputs
  • SIEM system exports

Creating a Mapping from JSON Logs​

To create a new mapping from JSON logs:

  1. Click the "New Mapping" button from your project dashboard
  2. Select "From JSON Log" from the options presented
New Mapping Options

Working with JSON Logs​

When working with JSON logs, you have two options for input:

  1. Paste JSON Logs: Directly paste your JSON logs into the input area
  2. Upload JSON File: Upload a file containing your JSON logs
JSON Log Input Interface

JSON Log Requirements​

For successful mapping, your JSON logs should:

  • Be properly formatted JSON
  • Contain consistent field names and structures
  • Include all relevant security event information
  • Be in an array format if uploading a file (each element should be a complete log entry)

Generating Mapping Rules​

After inputting your JSON logs, you have two options for creating mapping rules:

Mapping Generation Options
  1. Analyze Logs: Let the AI generate mapping rules automatically
  2. Edit Directly: Create mapping rules manually in the editor

AI-Generated Mappings​

For AI-generated mappings:

  1. Provide clear additional context about your logs
  2. Click "Analyze Logs" to begin the process
  3. The AI will present several OCSF class options that might match your log type
  4. Select the most appropriate class for your logs
OCSF Class Selection
info

The quality of the additional context greatly determines the AI accuracy. Make sure you provide clear and comprehensive explanation or specs about the sample logs. Formatting the context is NOT important.

Editing Mapping Rules​

The mapping editor provides two modes for editing rules:

Visual Mode​

In Visual Mode, you can:

  • Click on fields to edit them through a user-friendly interface
  • See field definitions and documentation
  • Get generation assistance for individual fields

Code Mode​

In Code Mode, you can:

  • Edit the FEEL expression directly in the code editor
  • Have full control over the mapping logic
  • Use advanced expressions and functions
Mapping Rules Editor

Testing Your Mapping​

To verify your mapping:

  1. Go to the "Logs" tab
  2. Add or modify sample logs
  3. View the mapping results
  4. Make adjustments as needed
Mapping Rules Editor Logs Tab

Best Practices for JSON Mapping​

  1. Provide Diverse Samples: Include multiple variations of your SAME TYPE JSON logs to ensure comprehensive mapping
  2. Check Field Consistency: Ensure field names and structures are consistent across all logs
  3. Include Context: When using AI generation, provide clear explanations of your log format
  4. Verify Results: Always review the mapping output for sample logs
  5. Test Before Production: Validate the mapping with a representative sample set

Downloading and Using the Mapping​

Once you've completed your mapping configuration:

  1. Click the "Download Expression" button
  2. The mapping configuration can be directly used with ZephFlow
  3. For implementation guidance, refer to the ZephFlow Cisco ASA to OCSF tutorial

Need Help?​

If you need assistance with JSON mapping:

  1. Check the Templates Guide for pre-configured mappings
  2. Review the Text Mapping Guide for handling unstructured logs
  3. Contact support for assistance with specific log formats