google-secops-mcp 0.7.0

Google SecOps MCP server

Chronicle SecOps MCP Server

This is an MCP (Model Context Protocol) server for interacting with Google's Chronicle Security Operations suite. MCP Info

Features

Security Tools

• search_security_events(text, project_id=None, customer_id=None, hours_back=24, max_events=100, region=None)

  • Searches for security events in Chronicle using natural language. Translates the natural language query (text) into a UDM query and executes it.

• get_security_alerts(project_id=None, customer_id=None, hours_back=24, max_alerts=10, status_filter='feedback_summary.status != "CLOSED"', region=None)

  • Retrieves security alerts from Chronicle, filtered by time range and status.

• lookup_entity(entity_value, project_id=None, customer_id=None, hours_back=24, region=None)

  • Looks up an entity (IP, domain, hash, etc.) in Chronicle.

• list_security_rules(project_id=None, customer_id=None, region=None)

  • Lists security detection rules from Chronicle.

• search_security_rules(query, project_id=None, customer_id=None, region=None)

  • Searches security detection rules from Chronicle using regex.

• get_detection_rule(rule_id, project_id=None, customer_id=None, region=None)

  • Retrieves complete YARA-L detection rule code and metadata from Chronicle by Rule Id.

• get_ioc_matches(project_id=None, customer_id=None, hours_back=24, max_matches=20, region=None)

  • Retrieves Indicators of Compromise (IoCs) matches from Chronicle within a specified time range.

• get_threat_intel(query, project_id=None, customer_id=None, region=None)

  • Get answers to general security domain questions and specific threat intelligence information using Chronicle's AI capabilities.

• search_udm(query, hours_back=24, max_events=100, project_id=None, customer_id=None, region=None)

  • Searches UDM events directly in Chronicle using raw UDM query syntax. Useful for precise, technical searches when you know the exact UDM field paths.

• export_udm_search_csv(query, fields, hours_back=24, case_insensitive=True, project_id=None, customer_id=None, region=None)

  • Exports UDM search results to CSV format with specified fields for analysis and reporting. Great for exporting security event data for offline analysis.

• find_udm_field_values(query, page_size=None, project_id=None, customer_id=None, region=None)

  • Finds and autocompletes UDM field values in Chronicle SIEM. Helps discover valid field values when building queries without needing to know exact matches.

• create_retrohunt(rule_id, start_time, end_time, project_id=None, customer_id=None, region=None)

  • Creates a retrohunt operation to run a detection rule against historical data for threat hunting. Returns operation details for tracking status.

• get_retrohunt(rule_id, operation_id, project_id=None, customer_id=None, region=None)

  • Retrieves the status and results of a retrohunt operation. Use to monitor progress of long-running threat hunting operations.

• search_rule_alerts(start_time, end_time, max_alerts=10, project_id=None, customer_id=None, region=None)

  • Searches for alerts generated by detection rules across a specified time range. Returns alerts grouped by rule with event samples.

Log Ingestion Tools

• ingest_raw_log(log_type, log_message, project_id=None, customer_id=None, region=None, forwarder_id=None, labels=None, log_entry_time=None, collection_time=None)

  • Ingest raw logs directly into Chronicle SIEM. Supports various formats (JSON, XML, CEF, etc.) and batch ingestion.

• ingest_udm_events(udm_events, project_id=None, customer_id=None, region=None)

  • Ingest events already formatted in Chronicle's Unified Data Model (UDM) format, bypassing the parsing stage.

• get_available_log_types(project_id=None, customer_id=None, region=None, search_term=None)

  • Get available log types supported by Chronicle for ingestion, optionally filtered by search term.

Parser Management Tools

• create_parser(log_type, parser_code, project_id=None, customer_id=None, region=None, validated_on_empty_logs=True)

  • Create a custom parser for a specific log type to transform raw logs into Chronicle's UDM format.

• get_parser(log_type, parser_id, project_id=None, customer_id=None, region=None)

  • Get details of a specific parser including its configuration and metadata.

• activate_parser(log_type, parser_id, project_id=None, customer_id=None, region=None)

  • Activate a parser, making it the active parser for the specified log type.

• deactivate_parser(log_type, parser_id, project_id=None, customer_id=None, region=None)

  • Deactivate a parser, stopping it from processing incoming logs of the specified type.

• run_parser_against_sample_logs(log_type, parser_code, sample_logs, project_id=None, customer_id=None, region=None, parser_extension_code=None, statedump_allowed=False)

  • Test parser configuration against sample log entries to validate parsing logic before deployment.

Data Table Management Tools

• create_data_table(name, description, header, project_id=None, customer_id=None, region=None, rows=None)

  • Create a structured data table that can be referenced in detection rules. Supports multiple column types (STRING, CIDR, INT64, BOOL).

• add_rows_to_data_table(table_name, rows, project_id=None, customer_id=None, region=None)

  • Add new rows to an existing data table, expanding the dataset available for detection rules.

• list_data_table_rows(table_name, project_id=None, customer_id=None, region=None, max_rows=50)

  • List rows in a data table to review contents and verify data integrity.

• delete_data_table_rows(table_name, row_ids, project_id=None, customer_id=None, region=None)

  • Delete specific rows from a data table based on their row IDs.

Reference List Management Tools

• create_reference_list(name, description, entries, project_id=None, customer_id=None, region=None, syntax_type="STRING")

  • Create a reference list containing values that can be referenced in detection rules. Supports STRING, CIDR, and REGEX syntax types.

• get_reference_list(name, project_id=None, customer_id=None, region=None, include_entries=True)

  • Get details and contents of a reference list including metadata and entries.

• update_reference_list(name, project_id=None, customer_id=None, region=None, entries=None, description=None)

  • Update the contents or description of an existing reference list.

Feed Management Tools

• list_feeds(project_id=None, customer_id=None, region=None)

  • Lists all configured feeds in Chronicle, providing details such as feed name, status, log type, and source type.

• get_feed(feed_id, project_id=None, customer_id=None, region=None)

  • Get detailed information about a specific feed by ID, including connection settings, log type, state, and metadata.

• create_feed(display_name, feed_details, project_id=None, customer_id=None, region=None)

  • Creates a new feed configuration for ingesting data into Chronicle. Supports various feed types including HTTP, S3, GCS, and GCP SCC.

• update_feed(feed_id, display_name=None, feed_details=None, project_id=None, customer_id=None, region=None)

  • Modifies the configuration of an existing feed. Can update the display name, connection settings, or other properties.

• enable_feed(feed_id, project_id=None, customer_id=None, region=None)

  • Activates a feed that is currently in the INACTIVE state, allowing it to resume data ingestion.

• disable_feed(feed_id, project_id=None, customer_id=None, region=None)

  • Stops data ingestion for a feed by setting its state to INACTIVE. The feed configuration remains but no new data will be processed.

• delete_feed(feed_id, project_id=None, customer_id=None, region=None)

  • Permanently removes a feed configuration from Chronicle. This action cannot be undone.

• generate_feed_secret(feed_id, project_id=None, customer_id=None, region=None)

  • Creates a new authentication secret for feeds that support authentication (e.g., HTTP feeds with basic auth). This replaces any existing secret.

Curated Rules Management Tools

• list_curated_rules(project_id=None, customer_id=None, region=None, page_size=100, page_token=None, as_list=False)

  • List all curated detection rules available in Chronicle. Retrieves pre-built detection rules provided by Google that cover common security threats and attack patterns.

• get_curated_rule(rule_id, project_id=None, customer_id=None, region=None)

  • Retrieve specific curated rule details by rule ID. Fetches complete definition and metadata for a specific Google-curated detection rule.

• get_curated_rule_by_name(display_name, project_id=None, customer_id=None, region=None)

  • Find curated rule by display name. Searches for a curated rule matching the specified human-readable name.

• search_curated_detections(rule_id, start_time, end_time, project_id=None, customer_id=None, region=None, list_basis=None, alert_state=None, page_size=100, page_token=None)

  • Search detections generated by a specific curated rule within a time range. Useful for investigating threats detected by Google-curated detection content.

• list_curated_rule_sets(project_id=None, customer_id=None, region=None, page_size=100, page_token=None, as_list=False)

  • List all curated rule sets available in Chronicle. Retrieves collections of related curated rules grouped by threat category or data source.

• get_curated_rule_set(rule_set_id, project_id=None, customer_id=None, region=None)

  • Retrieve specific curated rule set details by ID. Provides information about rules included in the set and deployment options.

• list_curated_rule_set_deployments(project_id=None, customer_id=None, region=None, page_size=100, page_token=None, as_list=False)

  • List deployment status of all curated rule sets. Shows enabled status, precision level (broad/precise), and alerting configuration.

• update_curated_rule_set_deployment(category_id, rule_set_id, precision, enabled, alerting, project_id=None, customer_id=None, region=None)

  • Update deployment configuration for a curated rule set. Enables/disables rule sets, configures precision level (broad or precise), and controls alerting settings.

Rule Exclusions Management Tools

• create_rule_exclusion(display_name, refinement_type, query, project_id=None, customer_id=None, region=None)

  • Create a new rule exclusion to filter out false positives or exclude specific events from triggering detections. Rule exclusions use UDM query syntax to define which events should be excluded.

• get_rule_exclusion(exclusion_id, project_id=None, customer_id=None, region=None)

  • Retrieve detailed information about a specific rule exclusion by ID, including display name, query, refinement type, and deployment status.

• list_rule_exclusions(page_size=None, page_token=None, project_id=None, customer_id=None, region=None)

  • List all rule exclusions configured in Chronicle with pagination support for reviewing and managing exclusions.

• patch_rule_exclusion(exclusion_id, display_name=None, query=None, update_mask=None, project_id=None, customer_id=None, region=None)

  • Update an existing rule exclusion's properties including display name and query. Supports partial updates via update_mask.

• update_rule_exclusion_deployment(exclusion_id, enabled, archived, detection_exclusion_application, project_id=None, customer_id=None, region=None)

  • Manage deployment settings for a rule exclusion including enable/disable status, archive status, and which rules or rule sets the exclusion applies to.

• compute_rule_exclusion_activity(exclusion_id, start_time, end_time, project_id=None, customer_id=None, region=None)

  • Calculate activity statistics showing how many events were excluded during a specified time period. Helps measure exclusion effectiveness and impact.

Watchlist Management Tools

• create_watchlist(name, display_name, multiplying_factor, description, project_id=None, customer_id=None, region=None)

  • Creates a new watchlist to track high-risk entities and apply risk score multipliers for prioritizing investigations.

• update_watchlist(watchlist_id, display_name=None, description=None, multiplying_factor=None, entity_population_mechanism=None, watchlist_user_preferences=None, project_id=None, customer_id=None, region=None)

  • Updates an existing watchlist's configuration, risk multiplier, or user preferences like pinning.

• delete_watchlist(watchlist_id, force=False, project_id=None, customer_id=None, region=None)

  • Permanently removes a watchlist from Chronicle. Use with caution as this operation cannot be undone.

• get_watchlist(watchlist_id, project_id=None, customer_id=None, region=None)

  • Retrieves detailed information about a specific watchlist including configuration and entity membership.

• list_watchlists(page_size=None, page_token=None, as_list=False, project_id=None, customer_id=None, region=None)

  • Lists all watchlists in Chronicle with pagination support for reviewing configured watchlists.

Investigation Management Tools

• list_investigations(page_size=50, page_token=None, project_id=None, customer_id=None, region=None)

  • List all investigations in Chronicle instance. Returns investigation status, verdict, and confidence. Supports pagination.

• get_investigation(investigation_id, project_id=None, customer_id=None, region=None)

  • Retrieve specific investigation by ID. Returns detailed investigation information including status and verdict.

• trigger_investigation(alert_id, project_id=None, customer_id=None, region=None)

  • Create new investigation for a specific alert. Returns created investigation details and trigger type.

• fetch_associated_investigations(detection_type, alert_ids=None, case_ids=None, association_limit_per_detection=5, project_id=None, customer_id=None, region=None)

  • Retrieve investigations associated with alerts or cases. Supports filtering by detection type (ALERT or CASE). Returns investigation associations with verdict information.

API Capabilities

The MCP server provides the following capabilities:

1. Search Security Events: Search for security events in Chronicle
2. Get Security Alerts: Retrieve security alerts
3. Lookup Entity: Look up entity information (IP, domain, hash, etc.)
4. List Security Rules: List detection rules
5. Search Security Rules: Searches detection rules using regex
6. Get IoC Matches: Get Indicators of Compromise matches
7. Get Threat Intel: Get AI-powered threat intelligence answers
8. Advanced Security Rules: Create and monitor retrohunts, search rule alerts
9. Log Ingestion: Ingest raw logs and UDM events
10. Parser Management: Create, manage, and test log parsers
11. Data Table Management: Create and manage structured data tables for detection rules
12. Reference List Management: Create and manage reference lists for detection rules
13. Feed Management: Create, update, enable, disable, and delete data feeds
14. Curated Rules Management: Discover, retrieve, and manage Google-curated detection content and rule set deployments
15. Rule Exclusions Management: Create, manage, and monitor rule exclusions to filter false positives and tune detection rules
16. Watchlist Management: Create, update, delete, and list watchlists for entity risk scoring
17. Investigation Management: Manage cases and investigations, trigger investigations, and fetch associated investigations
18. UDM Search & Export: Direct UDM querying, field value autocomplete, and CSV export

Example

See example.py for a complete example of using the MCP server.

Tool Categories and Use Cases

Security Operations Tools

These tools focus on core security operations tasks:

• Event Search & Investigation: Use search_security_events to find security events using natural language queries
• Alert Management: Use get_security_alerts to retrieve and monitor security alerts
• Entity Analysis: Use lookup_entity to investigate IPs, domains, hashes, and other indicators
• Rule Management: Use list_security_rules and search_security_rules to manage detection rules
• Threat Hunting: Use create_retrohunt and get_retrohunt for historical threat hunting with detection rules
• Rule Alerts: Use search_rule_alerts to search and analyze alerts generated by detection rules
• Threat Intelligence: Use get_ioc_matches and get_threat_intel for IOC analysis and AI-powered insights
• Curated Rules Management: Use curated rules management tools to discover, enable, and configure Google-maintained detection content
• Rule Exclusions Management: Use create_rule_exclusion, get_rule_exclusion, list_rule_exclusions, patch_rule_exclusion, update_rule_exclusion_deployment, and compute_rule_exclusion_activity to manage false positive filtering and detection rule tuning
• Watchlist Management: Use create_watchlist, update_watchlist, list_watchlists, get_watchlist, and delete_watchlist to manage entity watchlists with risk score multipliers for prioritizing high-risk entities
• Investigation Management: Use list_investigations, get_investigation, trigger_investigation, and fetch_associated_investigations to manage investigations and cases
• UDM Analysis & Export: Use search_udm, export_udm_search_csv, and find_udm_field_values for direct UDM querying, data export, and field discovery

Data Ingestion & Parsing Tools

These tools help you get data into Chronicle:

• Raw Log Ingestion: Use ingest_raw_log for logs in their original format (JSON, XML, CEF, etc.)
• UDM Event Ingestion: Use ingest_udm_events for pre-formatted security events
• Parser Development: Use the parser management tools to create custom parsers for unique log formats
• Testing: Use run_parser_against_sample_logs to validate parser logic before deployment
• Feed Management: Use feed management tools (list_feeds, create_feed, etc.) to configure and manage data collection sources

Context Data Management Tools

These tools help you maintain reference data for enhanced detections:

• Data Tables: Use for structured data with multiple columns (e.g., asset inventories with criticality ratings)
• Reference Lists: Use for simple lists of values (e.g., IP addresses, domains, usernames)
• Detection Enhancement: Both data tables and reference lists can be referenced in detection rules to make them more dynamic and maintainable

Curated Detection Management Tools

These tools help you leverage Google-curated detection content:

• Discovery: Use list_curated_rules and list_curated_rule_sets to browse available pre-built detection content
• Deployment: Use update_curated_rule_set_deployment to enable rule sets with configurable precision levels (broad/precise)
• Investigation: Use search_curated_detections to analyze threats detected by curated rules
• Configuration: Manage alerting settings and precision tuning for optimal detection coverage

Configuration

MCP Server Configuration

Add the following configuration to your MCP client's settings file:

NOTE: For OSX users, if you used this one-liner to install uv, use the full path to the uv binary for the "command" value below, as uv will not be placed in the system path for Claude to use! For example: /Users/yourusername/.local/bin/uv instead of just uv.

Using uv (Recommended)

{
  "mcpServers": {
    "secops": {
      "command": "uv",
      "args": [
        "--env-file=/path/to/your/env",
        "--directory",
        "/path/to/the/repo/server/secops/secops_mcp",
        "run",
        "server.py"
      ],
      "env": {
        "CHRONICLE_PROJECT_ID": "${CHRONICLE_PROJECT_ID}",
        "CHRONICLE_CUSTOMER_ID": "${CHRONICLE_CUSTOMER_ID}",
        "CHRONICLE_REGION": "${CHRONICLE_REGION}",
        "SECOPS_SA_PATH": "${SECOPS_SA_PATH}"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: The SECOPS_SA_PATH environment variable is optional. If not set, the server will use Application Default Credentials (ADC). Only include this variable if you want to use service account authentication.

Using pip

You can also use pip instead of uv to install and run the MCP server:

{
  "mcpServers": {
    "secops": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "cd /path/to/the/repo/server/secops && pip install -e . && secops_mcp"
      ],
      "env": {
        "CHRONICLE_PROJECT_ID": "${CHRONICLE_PROJECT_ID}",
        "CHRONICLE_CUSTOMER_ID": "${CHRONICLE_CUSTOMER_ID}",
        "CHRONICLE_REGION": "${CHRONICLE_REGION}",
        "SECOPS_SA_PATH": "${SECOPS_SA_PATH}"
      },
      "disabled": false,
      "autoApprove": [
        "get_ioc_matches",
        "search_security_events",
        "get_security_alerts"
      ],
      "alwaysAllow": [
        "get_ioc_matches"
      ]
    }
  }
}

Note: The SECOPS_SA_PATH environment variable is optional. See the Authentication section below for more details.

When to use uv vs pip

• uv: Recommended for most users as it provides faster package installation, better dependency resolution, and supports loading environment variables from a file with the --env-file option.
• pip: Use when you prefer the standard Python package manager or when you need specific environment setup requirements.

Environment Variable Setup

Set up these environment variables in your system:

For macOS/Linux:

export CHRONICLE_PROJECT_ID="your-google-cloud-project-id"
export CHRONICLE_CUSTOMER_ID="your-chronicle-customer-id"
export CHRONICLE_REGION="us"

For Windows PowerShell:

$Env:CHRONICLE_PROJECT_ID = "your-google-cloud-project-id"
$Env:CHRONICLE_CUSTOMER_ID = "your-chronicle-customer-id"
$Env:CHRONICLE_REGION = "us"

The CHRONICLE_REGION can be one of:

• us - United States (default)
• eu - Europe
• asia - Asia-Pacific

Authentication

The MCP server supports two authentication methods:

1. Application Default Credentials (ADC) - Default

The server uses Google Cloud Application Default Credentials by default. Authenticate using:

gcloud auth application-default login

2. Service Account Authentication - Optional

To use a service account instead of ADC, set the SECOPS_SA_PATH environment variable to point to your service account JSON key file:

For macOS/Linux:

export SECOPS_SA_PATH="/path/to/service-account-key.json"

For Windows PowerShell:

$Env:SECOPS_SA_PATH = "C:\path\to\service-account-key.json"

When SECOPS_SA_PATH is set, the server will use the specified service account for authentication. This is useful for automated deployments, CI/CD pipelines, or environments where ADC is not available.

License

Apache 2.0

Development

The project is structured as follows:

• server.py: Main MCP server implementation
• example.py: Example usage of the MCP server