Skip to main content

Google Chronicle Backstory API (Legacy) MCP Server

⚠️ LEGACY API: This documentation covers the Backstory API (v2), which is a legacy API with a simpler structure. For new integrations, we recommend using the Chronicle API (v1) which follows Google Cloud API standards with regional endpoints and comprehensive resource management.

Create a powerful Model Context Protocol (MCP) server for Google Chronicle Backstory API in minutes with our AI Gateway. This guide walks you through setting up seamless security operations integration with enterprise-grade security and instant OAuth authentication.

About Google Chronicle Backstory API (v2)​

Google Chronicle Backstory API (v2) is the legacy API for Google Chronicle Security Operations. This API provides a simpler structure without the full Google Cloud resource hierarchy, making it easier to use but with limited features compared to the modern Chronicle API (v1).

Google Chronicle Security Operations is a cloud-native security information and event management (SIEM) platform that provides comprehensive security analytics, threat detection, and investigation capabilities. The Backstory API (v2) enables programmatic access to security data, detection rules, threat intelligence, and investigation workflows using a simplified API structure.

Key Capabilities​

  • Threat Detection: Create and manage custom detection rules using YARA-L
  • Security Data Search: Powerful UDM (Unified Data Model) queries for investigation
  • Threat Intelligence: Manage IOC (Indicators of Compromise) lists and threat feeds
  • Data Ingestion: Ingest security logs and events from multiple sources
  • Role-Based Access Control: Fine-grained permissions for security teams
  • Data Export: Export security data for compliance and reporting
  • Real-time Detection: Automated threat detection and alerting
  • Multi-tenant Support: Customer isolation and data segregation

API Features​

  • Detection Engine API: Create, manage, and run security detection rules
  • Lists API: Manage IOC lists (SHA256, SHA1, MD5, IP addresses, domains, URLs)
  • Search API: Query security data using UDM query language
  • RBAC API: Role and permission management
  • Data Export API: Export security data to Cloud Storage or BigQuery
  • OAuth 2.0: Service account authentication
  • Rate Limiting: Varies by endpoint and customer tier

What You Can Do with Google Chronicle MCP Server​

The MCP server transforms Chronicle Security Operations APIs into a natural language interface, enabling AI agents to:

Threat Detection​

  • Detection Rule Management

    • "Create a detection rule for suspicious PowerShell execution"
    • "Update the data exfiltration detection rule"
    • "List all high-priority detection rules"
    • "Disable detection rule for false positives"

  • Detection Analysis

    • "Show detection results from the last 24 hours"
    • "Analyze detection trends by severity"
    • "Review detection rule performance metrics"
    • "Export detection results for investigation"

Threat Intelligence​

  • IOC Management

    • "Add SHA256 hashes to malware list"
    • "Create a list of suspicious IP addresses"
    • "Update IOC list with new threat indicators"
    • "Search for indicators in all lists"

  • Threat Intelligence Operations

    • "Import threat feeds from external sources"
    • "Export IOC lists for sharing"
    • "Compare IOC lists for duplicates"
    • "Archive old threat indicators"

Security Investigation​

  • Security Data Search

    • "Search for all process launches in the last hour"
    • "Find network connections to suspicious IPs"
    • "Query user login events from last week"
    • "Search for file modifications by specific user"

  • Investigation Workflows

    • "Correlate events across multiple data sources"
    • "Timeline analysis for security incident"
    • "Identify related security events"
    • "Export investigation data for reporting"

Data Management​

  • Data Export

    • "Export security events to Cloud Storage"
    • "Export detection results to BigQuery"
    • "Schedule regular data exports"
    • "Monitor export job status"

  • Data Ingestion

    • "Configure new log source ingestion"
    • "Validate ingested data quality"
    • "Monitor ingestion pipeline health"
    • "Troubleshoot ingestion errors"

Prerequisites​

  • Access to Cequence AI Gateway
  • Google Cloud Console account with Chronicle enabled
  • Chronicle Security Operations subscription
  • Administrative access to create service account credentials
  • Contact with Google Security Operations representative for API access

Step 1: Enable Chronicle API and Create Service Account​

Before setting up the MCP server, you need to enable the Chronicle API and create service account credentials in Google Cloud Console.

1.1 Access Google Cloud Console​

  1. Navigate to Google Cloud Console
  2. Select your project or create a new one
  3. Ensure billing is enabled for your project
  4. Important: Chronicle Security Operations requires a separate subscription and API access approval from Google

1.2 Contact Google Security Operations​

  1. Contact your Google Security Operations representative
  2. Request API access for Chronicle Backstory API (v2)
  3. Obtain approval for service account credentials
  4. Note: Chronicle API access is typically restricted and requires business justification
  5. Important: Consider requesting access to Chronicle API (v1) instead for new integrations

1.3 Enable Chronicle API​

  1. Go to APIs & Services → Library
  2. Search for "Chronicle Security Operations API" or "Chronicle Backstory API"
  3. If available, click Enable
  4. Note: The API may not appear in the library if not yet approved for your organization

1.4 Create Service Account​

  1. Navigate to IAM & Admin → Service Accounts
  2. Click + CREATE SERVICE ACCOUNT
  3. Fill in the service account details:
    • Service account name: "AI Gateway Chronicle Integration"
    • Service account ID: Auto-generated (e.g., ai-gateway-chronicle)
    • Description: "Service account for Chronicle Security Operations API integration"
  4. Click CREATE AND CONTINUE

1.5 Grant Required IAM Roles​

  1. Grant the following roles to the service account:
    • Chronicle API User (if available)
    • Service Account Token Creator
    • Service Account User
  2. Click CONTINUE
  3. Skip optional user access (not needed for service account authentication)
  4. Click DONE

1.6 Create Service Account Key​

  1. Click on the created service account
  2. Go to KEYS tab
  3. Click ADD KEY → Create new key
  4. Select JSON format
  5. Click CREATE
  6. Important: Save the downloaded JSON key file securely
  7. Note the Service Account Email (e.g., ai-gateway-chronicle@project-id.iam.gserviceaccount.com)

1.7 Configure Chronicle API Access​

  1. Contact your Google Security Operations representative
  2. Provide the service account email
  3. Request API access with the following scopes:
    • https://www.googleapis.com/auth/chronicle-backstory
    • https://www.googleapis.com/auth/malachite-ingestion (if using ingestion APIs)
  4. Wait for access approval (may take 1-3 business days)

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find Google Chronicle Backstory API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: https://backstory.googleapis.com
  2. Select endpoints:
    • Detection Engine API endpoints (/v2/detects)
    • Lists API endpoints (/v2/lists)
    • Search API endpoints (/v2/udm/search)
    • RBAC API endpoints (/v2/roles)
    • Data Export API endpoints (/v2/export)
  3. Click Next

Step 6: MCP Server Configuration​

  1. Name: "Google Chronicle Backstory API (Legacy)"
  2. Description: "SIEM and threat detection platform (Backstory API v2)"
  3. Configure production mode
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: OAuth 2.0 with Service Account
  2. Service Account Key: Upload the JSON key file downloaded from Google Cloud Console
  3. Authorization URL: 
    https://accounts.google.com/o/oauth2/v2/auth
  4. Token URL: 
    https://oauth2.googleapis.com/token
  5. Scopes: Configure required scopes (see Available Scopes section below)
  6. Click Next

Available Google Chronicle OAuth Scopes​

Configure the appropriate scopes based on your application needs:

General Access​

  • https://www.googleapis.com/auth/chronicle-backstory
    • Full access to Chronicle Backstory API
    • Read and write detection rules
    • Manage IOC lists
    • Search security data
    • Manage RBAC roles
    • Export security data
    • Recommended for: Full Chronicle integration

Data Ingestion​

  • https://www.googleapis.com/auth/malachite-ingestion
    • Access to Chronicle data ingestion APIs
    • Ingest security logs and events
    • Configure ingestion pipelines
    • Validate ingested data
    • Recommended for: Log ingestion use cases
    • Note: Requires separate approval from Google

For Threat Detection and Investigation:

https://www.googleapis.com/auth/chronicle-backstory

For Full Integration Including Ingestion:

https://www.googleapis.com/auth/chronicle-backstory
https://www.googleapis.com/auth/malachite-ingestion

Required IAM Roles and Permissions​

Service Account Roles​

  • Service Account Token Creator: Allows the service account to create OAuth tokens
  • Service Account User: Allows using the service account for authentication

Chronicle-Specific Permissions​

Chronicle Security Operations uses its own permission model separate from standard Google Cloud IAM:

  1. Detection Engine Permissions:

    • chronicle.detections.create - Create detection rules
    • chronicle.detections.read - View detection rules
    • chronicle.detections.update - Update detection rules
    • chronicle.detections.delete - Delete detection rules

  2. Lists Permissions:

    • chronicle.lists.create - Create IOC lists
    • chronicle.lists.read - View IOC lists
    • chronicle.lists.update - Update IOC lists
    • chronicle.lists.delete - Delete IOC lists

  3. Search Permissions:

    • chronicle.search.execute - Execute UDM queries
    • chronicle.search.export - Export search results

  4. RBAC Permissions:

    • chronicle.rbac.read - View roles and permissions
    • chronicle.rbac.manage - Manage roles (admin only)

  5. Data Export Permissions:

    • chronicle.export.create - Create export jobs
    • chronicle.export.read - View export job status

Note: These permissions are configured within Chronicle Security Operations, not Google Cloud Console. Contact your Chronicle administrator to assign appropriate permissions to your service account.

Step 8: Test Connection​

  1. Click Test Connection
  2. Verify authentication succeeds
  3. Test a sample API call (e.g., list detection rules)
  4. If successful, click Create MCP Server

Using Your Google Chronicle Backstory API MCP Server​

Setup Instructions:

Natural Language Commands​

  • "Create a detection rule for suspicious PowerShell execution"
  • "List all high-priority detection rules"
  • "Add SHA256 hashes to malware list"
  • "Search for all process launches in the last hour"
  • "Export security events to Cloud Storage"
  • "Update IOC list with new threat indicators"
  • "Show detection results from the last 24 hours"
  • "Create a list of suspicious IP addresses"

Common Use Cases​

Security Operations​

  • Detection rule management and monitoring
  • Real-time threat detection and alerting
  • Security data search and investigation
  • IOC list management

Threat Intelligence​

  • Threat indicator management
  • IOC list creation and updates
  • Threat feed integration
  • Indicator sharing

Data Management​

  • Security data export for compliance
  • Log ingestion configuration
  • Data quality validation
  • Historical data analysis

Troubleshooting​

Authentication Errors​

Error: "Permission denied" or "UNAUTHENTICATED"

  • Verify service account key file is correct
  • Ensure service account has been granted Chronicle API access
  • Check that Chronicle API is enabled in your Google Cloud project
  • Verify service account email matches the one approved by Google Security Operations

Error: "API not enabled"

  • Contact Google Security Operations to enable Chronicle API access
  • Chronicle API may require separate subscription activation
  • Verify your organization has Chronicle Security Operations subscription

API Access Issues​

Error: "Access denied" or "FORBIDDEN"

  • Verify service account has appropriate Chronicle permissions
  • Check RBAC roles assigned to service account in Chronicle
  • Ensure required scopes are included in OAuth configuration
  • Contact Chronicle administrator to verify permissions

Error: "Rate limit exceeded"

  • Chronicle API has rate limits that vary by customer tier
  • Implement exponential backoff for retries
  • Consider batching requests where possible
  • Contact Google Support to request rate limit increase if needed

Service Account Setup​

Cannot create service account key

  • Verify you have "Service Account Key Admin" role
  • Ensure service account exists and is accessible
  • Check project permissions

Service account key not working

  • Verify JSON key file is valid
  • Check key hasn't been rotated or deleted
  • Ensure service account hasn't been disabled
  • Regenerate key if necessary

Best Practices​

Security​

  • Secure Key Storage: Store service account keys securely, never commit to version control
  • Key Rotation: Rotate service account keys regularly (every 90 days recommended)
  • Least Privilege: Grant only necessary Chronicle permissions to service account
  • Audit Logging: Enable audit logs for Chronicle API access
  • Network Security: Use VPC Service Controls if available

Performance​

  • Rate Limiting: Implement proper rate limiting and retry logic
  • Caching: Cache detection rules and IOC lists when appropriate
  • Pagination: Use pagination for large result sets
  • Query Optimization: Optimize UDM queries for performance

Monitoring​

  • API Usage: Monitor API usage and costs
  • Error Tracking: Track and alert on authentication failures
  • Performance Metrics: Monitor API response times
  • Quota Management: Track API quota usage

Migration to Chronicle API (v1)​

If you're starting a new integration or planning to migrate:

  • Chronicle API (v1) offers:

    • Regional endpoints for better performance
    • Full Google Cloud resource hierarchy (projects/{project}/locations/{location}/instances/{instance})
    • Comprehensive resource management (instances, data access labels/scopes, reference lists, rules, deployments, retrohunts, watchlists)
    • Standard Google Cloud API patterns
    • Better scalability and multi-tenant support

  • See the Chronicle API (v1) MCP Server Setup Guide for modern integration options.

Additional Resources​

Support​

For issues specific to Chronicle Security Operations:

For AI Gateway integration issues: