Metadata-Version: 2.4
Name: google-secops-mcp
Version: 0.6.0
Summary: Google SecOps MCP server
Author-email: Google SecOps Team <chronicle@google.com>
Project-URL: Homepage, https://github.com/google/mcp-security
Project-URL: Documentation, https://github.com/google/mcp-security/tree/main/server/secops#readme
Project-URL: Repository, https://github.com/google/mcp-security/tree/main/server/secops
Project-URL: Issues, https://github.com/google/mcp-security/issues
Keywords: google,security,chronicle,secops,mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: secops>=0.35.1
Requires-Dist: google-auth>=2.48.0
Requires-Dist: google-auth-httplib2>=0.3.0
Requires-Dist: google-api-python-client>=2.190.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"

# Chronicle SecOps MCP Server

This is an MCP (Model Context Protocol) server for interacting with Google's
Chronicle Security Operations suite.
[MCP Info](https://modelcontextprotocol.io/introduction)

## 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.

### 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. **Watchlist Management**: Create, update, delete, and list watchlists for entity risk scoring
16. **Investigation Management**: Manage cases and investigations, trigger investigations, and fetch associated investigations
17. **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
- **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](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer) 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)

```json
{
  "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:

```json
{
  "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:**
```bash
export CHRONICLE_PROJECT_ID="your-google-cloud-project-id"
export CHRONICLE_CUSTOMER_ID="your-chronicle-customer-id"
export CHRONICLE_REGION="us"
```

**For Windows PowerShell:**
```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:

```bash
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:**
```bash
export SECOPS_SA_PATH="/path/to/service-account-key.json"
```

**For Windows PowerShell:**
```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 
