Google SecOps Entities Integration Guide

Overview

The Google SecOps Entities integration allows your NINA workflows to connect with the Google SecOps security intelligence platform for entity and IOC management, watchlist administration, threat intelligence enrichment, reference data management, and UDM ontology customisation. This integration enables automated security operations, threat hunting, and enrichment pipelines directly from your automation platform.

Capabilities

This integration provides access to 18 resources with 99 operations covering:

• Entities: Get entity details, import entity data, modify risk scores, and query risk score history
• Entity Blocklists: Create, delete, get, list, and update entity blocklists
• Entity Risk Scores: Query risk scores for one or more entities
• IOC Associations: Get, batch-get, and fetch related IOC associations
• IOCs: Get, batch-get, find, fetch related, manage IOC state, search curated detections, and find first/last seen timestamps
• Threat Collections: Get, list, and fetch entity metadata, IOC match metadata, and related collections
• Unique Entities: Get, list, update, add notes, download, and fetch full entity profiles
• Watchlists: Create, delete, get, list, update watchlists, and list their member entities
• Watchlist Entities: Add, batch-add, batch-remove, and remove individual entities from watchlists
• Enrichment Agent: Execute enrichment actions, fetch available actions, and fetch alert context data
• Enrichment Controls: Create, delete, disable, get, and list enrichment controls
• Calculated Field Definitions: Full lifecycle management of calculated fields including dependency validation
• Custom Lists: Create, delete, batch-delete, get, list, update, export, and import custom lists
• Property Schema Definitions: Create, delete, get, list, and update custom property schemas
• Reference Lists: Create, get, list, and update YARA-L reference lists
• Ontology Records: Delete, get, list, update, export, import, get family, and get statistics
• Ontology Mapping Rules: Delete, get, list, update, fetch all, save, and test UDM mapping rules
• Ontology Visual Families: Create, delete, get, list, update, export, and import visual families

Credential Configuration

Before using the Google SecOps Entities integration in your workflows, you need to configure credentials for authentication.

Authentication Method

Google SecOps uses Google Service Account authentication. You provide a full service account JSON key, and the integration automatically handles OAuth2 token acquisition and refresh using the cloud-platform scope. No redirect URLs or user interaction are required.

Field	Description	Required
Service Account JSON	Full Google service account JSON key (paste the entire JSON content)	Yes
Region	Google SecOps API region prefix used to construct the base URL	Yes
Project	GCP project ID where the Google SecOps instance lives	Yes
Location	GCP location of the Google SecOps instance (must match provisioning)	Yes
Instance	Google SecOps instance UUID	Yes

How It Works

1. You provide the service account JSON when creating a credential
2. The integration parses the JSON and derives an OAuth2 JWT token automatically
3. Tokens are refreshed automatically when they expire (no manual intervention needed)
4. All API calls are made to https://{region}-chronicle.googleapis.com

Google SecOps API Regions

Select the region that matches your Google SecOps instance:

Region value	Description	Base URL
us	United States	https://us-chronicle.googleapis.com
eu	Europe	https://eu-chronicle.googleapis.com
asia-southeast1	Singapore	https://asia-southeast1-chronicle.googleapis.com
asia-south1	India	https://asia-south1-chronicle.googleapis.com
northamerica-northeast2	Canada	https://northamerica-northeast2-chronicle.googleapis.com
me-west1	Middle East	https://me-west1-chronicle.googleapis.com

How to Obtain a Service Account Key

1. Log in to the Google Cloud Console
2. Navigate to IAM & Admin > Service Accounts
3. Select an existing service account or click Create Service Account
4. Configure the service account:
   • Name: A descriptive name (e.g., "nina-chronicle-entities")
   • Description: Purpose of this service account
5. Click Create and Continue
6. Grant the required IAM roles (see Required IAM Roles below)
7. Click Done
8. Click the service account name to open its details
9. Navigate to the Keys tab
10. Click Add Key > Create new key
11. Select JSON format and click Create
12. Save the downloaded JSON file securely — this is your serviceAccountJson value

Important: The JSON key file is only downloadable once. If you lose it, you must delete the key and create a new one. Never commit this file to source control.

Required IAM Roles

The service account must be granted Google SecOps-specific roles in the GCP project. The roles you need depend on the operations you plan to use:

Google SecOps Role	GCP Role ID	Required For
Google SecOps API Viewer	roles/chronicle.viewer	All read-only operations (get, list, batchGet, fetchRelated, fetchFull, etc.)
Google SecOps API Editor	roles/chronicle.editor	Create, update, and delete operations on entities, watchlists, custom lists, reference lists, enrichment controls, and property schemas
Google SecOps SOAR Admin	roles/chronicle.admin	Ontology management, enrichment agent execution, calculated field definitions, entity risk score modification

Minimum recommended configuration for read-only NINA workflows: Google SecOps API Viewer

Minimum recommended configuration for full automation workflows: Google SecOps API Editor

Minimum required for ontology and enrichment management: Google SecOps SOAR Admin

To grant a role:

1. Go to IAM & Admin > IAM in the GCP Console
2. Click Grant Access
3. Enter the service account email (e.g., [email protected])
4. Select the appropriate Google SecOps role
5. Click Save

Finding Your Credential Values

Field	Where to find it
serviceAccountJson	The JSON file downloaded from GCP Console (Service Accounts → Keys → Create)
region	Google SecOps Console → Settings → Instance details → Region (e.g., eu, us)
project	GCP Console → Project selector → Project ID (e.g., my-project-123, not the project name or number)
location	Google SecOps Console → Settings → Instance details → Location (e.g., eu, us, europe-west2)
instance	Google SecOps Console → Settings → Instance details → Instance ID (UUID format, e.g., fca7f167-b9d1-43b1-9d03-0257d31dcb63)

Note: The region and location values are often the same (e.g., both eu) but can differ. The region sets the API base URL; the location is part of the resource path.

Creating a Google SecOps Entities Credential in NINA

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Integration Service: Select "Google SecOps Entities"
   • Service Account JSON: Paste the entire contents of your service account JSON key file
   • Region: Select your Google SecOps instance region (e.g., eu)
   • Project: Enter your GCP project ID (e.g., my-project-123)
   • Location: Enter the Google SecOps instance location (e.g., eu)
   • Instance: Enter the Google SecOps instance UUID
4. Click Test Connection to verify the credentials work
5. Click Save to store the credential securely

Note: All Google SecOps integrations (Entities, Cases, Events, Detections, Integrations, etc.) share the same five credential fields. You only need to create one credential set to use across all Google SecOps modules.

Supported Resources

Resource	Description	Operations
Entities	Core entity management and risk score operations	4
Entity Blocklists	Manage entity blocklists	5
Entity Risk Scores	Query entity risk scores	1
IOC Associations	Read IOC association graph	3
IOCs	Full IOC management including state and detection search	8
Threat Collections	Read threat intelligence collections	5
Unique Entities	Manage unique entity profiles with notes and downloads	6
Watchlists	Manage watchlists and list their members	6
Watchlist Entities	Manage entity membership in watchlists	4
Enrichment Agent	Execute and manage enrichment actions	3
Enrichment Controls	Manage enrichment control rules	5
Calculated Field Definitions	Manage calculated field definitions	8
Custom Lists	Manage custom lists with import/export	8
Property Schema Definitions	Manage custom property schemas	5
Reference Lists	Manage YARA-L reference lists	4
Ontology Records	Manage UDM ontology records	8
Ontology Mapping Rules	Manage UDM mapping rules	7
Ontology Visual Families	Manage UDM visual families	7

Resource Details

Entities

Core entity management. Retrieve entity details, import entity data, and manage entity risk scores.

Operations

Operation	Name	Description
get	Get Entity	Get entity details by resource name or entity identifier
import	Import Entity Data	Import entity data into Google SecOps
modifyEntityRiskScore	Modify Entity Risk Score	Modify the risk score of an entity (v1alpha)
queryEntityRiskScoreModifications	Query Entity Risk Score Modifications	Query the history of risk score modifications for an entity (v1alpha)

Get Entity

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity (e.g., projects/my-project/locations/eu/instances/<uuid>/entities/<id>).

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entities/abc123"
}

Import Entity Data

Parameters:

Name	Type	Required	Description
entities	array	Yes	List of entity objects to import. Each object follows the Google SecOps Entity schema.

Example:

{
  "entities": [{}]
}

Modify Entity Risk Score

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity.
riskScore	number	Yes	New risk score value for the entity (0–100).
reason	string	No	Reason for modifying the risk score.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entities/abc123",
  "riskScore": 85,
  "reason": "Confirmed malicious activity detected"
}

Query Entity Risk Score Modifications

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entities/abc123",
  "pageSize": 10
}

---

Entity Blocklists

Manage entity blocklists that can be used to flag groups of entities.

Operations

Operation	Name	Description
create	Create Entity Blocklist	Create a new entity blocklist
delete	Delete Entity Blocklist	Delete an entity blocklist by resource name
get	Get Entity Blocklist	Retrieve a specific entity blocklist
list	List Entity Blocklists	List all entity blocklists
patch	Update Entity Blocklist	Update an existing entity blocklist

Create Entity Blocklist

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the blocklist.
description	string	No	Description of the blocklist.
entityType	string	No	Type of entities in this blocklist (e.g., DOMAIN, IP, FILE_HASH).

Example:

{
  "displayName": "Malicious Domains",
  "description": "Domains identified as C2 infrastructure",
  "entityType": "DOMAIN"
}

Delete Entity Blocklist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity blocklist to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entitiesBlocklists/blocklist-id"
}

Get Entity Blocklist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity blocklist.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entitiesBlocklists/blocklist-id"
}

List Entity Blocklists

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression to narrow results.

Example:

{
  "pageSize": 50,
  "filter": "displayName=\"Malicious Domains\""
}

Update Entity Blocklist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity blocklist.
displayName	string	No	Updated display name.
description	string	No	Updated description.
updateMask	string	No	Comma-separated list of fields to update (e.g., displayName,description).

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entitiesBlocklists/blocklist-id",
  "description": "Updated: confirmed C2 infrastructure",
  "updateMask": "description"
}

---

Entity Risk Scores

Query risk scores for one or more entities in batch (v1alpha only).

Operations

Operation	Name	Description
query	Query Entity Risk Scores	Query risk scores for one or more entities

Query Entity Risk Scores

Parameters:

Name	Type	Required	Description
entities	array	Yes	List of entity resource names or identifiers to query.
timeRange	object	No	Optional time range for the risk score query (e.g., {"startTime": "...", "endTime": "..."}).

Example:

{
  "entities": [
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entities/abc123"
  ],
  "timeRange": {
    "startTime": "2025-01-01T00:00:00Z",
    "endTime": "2025-07-01T00:00:00Z"
  }
}

---

IOC Associations

Read-only access to IOC association graph nodes.

Operations

Operation	Name	Description
get	Get IOC Association	Get a specific IOC association by resource name
batchGet	Batch Get IOC Associations	Batch retrieve multiple IOC associations
fetchRelated	Fetch Related IOC Associations	Fetch IOC associations related to a given entity or IOC

Get IOC Association

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the IOC association.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocAssociations/assoc-id"
}

Batch Get IOC Associations

Parameters:

Name	Type	Required	Description
names	array	Yes	List of IOC association resource names to retrieve.

Example:

{
  "names": [
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocAssociations/assoc-id-1",
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocAssociations/assoc-id-2"
  ]
}

Fetch Related IOC Associations

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity or IOC to find associations for.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id",
  "pageSize": 25
}

---

IOCs

Full Indicator of Compromise lifecycle management.

Operations

Operation	Name	Description
get	Get IOC	Get IOC details by resource name
batchGet	Batch Get IOCs	Batch retrieve multiple IOCs
fetchRelated	Fetch Related IOCs	Fetch IOCs related to a given entity or IOC
find	Find IOCs by Value	Find IOCs by their indicator value
findFirstAndLastSeen	Find First and Last Seen	Find first and last seen timestamps for an IOC (v1alpha)
getIocState	Get IOC State	Get the current state of an IOC — active or suppressed (v1alpha)
updateIocState	Update IOC State	Suppress or activate an IOC (v1alpha)
searchCuratedDetectionsForIoc	Search Curated Detections for IOC	Search curated detections associated with a specific IOC (v1alpha)

Get IOC

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the IOC.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id"
}

Batch Get IOCs

Parameters:

Name	Type	Required	Description
names	array	Yes	List of IOC resource names to retrieve.

Example:

{
  "names": [
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id-1",
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id-2"
  ]
}

Fetch Related IOCs

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the entity or IOC.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/entities/entity-id",
  "pageSize": 20
}

Find IOCs by Value

Parameters:

Name	Type	Required	Description
indicatorValue	string	Yes	The IOC indicator value to search for (e.g., an IP address, domain, or file hash).
indicatorType	string	No	Type of indicator — e.g., DOMAIN, IP_ADDRESS, FILE_HASH, URL.

Example:

{
  "indicatorValue": "evil.example.com",
  "indicatorType": "DOMAIN"
}

Find First and Last Seen

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the IOC.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id"
}

Get IOC State

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the IOC.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id"
}

Update IOC State

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the IOC.
state	string	Yes	New state for the IOC — ACTIVE or SUPPRESSED.
reason	string	No	Reason for the state change.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id",
  "state": "SUPPRESSED",
  "reason": "False positive — internal IP range"
}

Search Curated Detections for IOC

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the IOC.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/iocs/ioc-id",
  "pageSize": 10
}

---

Threat Collections

Read threat intelligence collections provided by Google.

Operations

Operation	Name	Description
get	Get Threat Collection	Retrieve a specific threat collection
list	List Threat Collections	List all available threat collections
fetchEntityMetadata	Fetch Entity Metadata from Threat Collection	Fetch metadata for an entity from a threat collection
fetchIocMatchMetadata	Fetch IOC Match Metadata	Fetch metadata for IOC matches within a threat collection
fetchRelated	Fetch Related Threat Collections	Fetch threat collections related to a given entity or IOC

Get Threat Collection

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the threat collection.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/threatCollections/collection-id"
}

List Threat Collections

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression.

Example:

{
  "pageSize": 20
}

Fetch Entity Metadata from Threat Collection

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the threat collection.
entityName	string	No	Name or identifier of the entity to look up within the collection.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/threatCollections/collection-id",
  "entityName": "evil.example.com"
}

Fetch IOC Match Metadata

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the threat collection.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/threatCollections/collection-id",
  "pageSize": 50
}

Fetch Related Threat Collections

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the threat collection or entity.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/threatCollections/collection-id",
  "pageSize": 10
}

---

Unique Entities

Manage the enriched unique entity profiles stored in Google SecOps.

Operations

Operation	Name	Description
get	Get Unique Entity	Retrieve a specific unique entity
list	List Unique Entities	List unique entities in the Google SecOps instance
patch	Update Unique Entity	Update metadata for a unique entity
addNote	Add Note to Unique Entity	Add an analyst note to a unique entity
download	Download Unique Entity Data	Download data for a unique entity as an export
fetchFull	Fetch Full Unique Entity Profile	Fetch the full enriched profile for a unique entity

Get Unique Entity

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the unique entity.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id"
}

List Unique Entities

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression.

Example:

{
  "pageSize": 50,
  "filter": "entityType=\"DOMAIN\""
}

Update Unique Entity

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the unique entity.
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id",
  "updateMask": "labels"
}

Add Note to Unique Entity

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the unique entity.
content	string	Yes	Note content to add.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id",
  "content": "Confirmed C2 server — do not unblock without SOC approval"
}

Download Unique Entity Data

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the unique entity.
format	string	No	Export format — e.g., JSON, CSV.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id",
  "format": "JSON"
}

Fetch Full Unique Entity Profile

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the unique entity.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id"
}

---

Watchlists

Manage watchlists and their entity membership.

Operations

Operation	Name	Description
create	Create Watchlist	Create a new watchlist
delete	Delete Watchlist	Delete a watchlist by resource name
get	Get Watchlist	Retrieve a specific watchlist
list	List Watchlists	List all watchlists
patch	Update Watchlist	Update an existing watchlist
listEntities	List Entities on Watchlist	List all entities that are members of a watchlist (v1alpha)

Create Watchlist

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the watchlist.
description	string	No	Description of the watchlist.
multipleEntityTypes	bool	No	Whether the watchlist supports multiple entity types.

Example:

{
  "displayName": "High Risk Users",
  "description": "Users under active investigation",
  "multipleEntityTypes": false
}

Delete Watchlist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the watchlist to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id"
}

Get Watchlist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the watchlist.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id"
}

List Watchlists

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression.

Example:

{
  "pageSize": 20
}

Update Watchlist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the watchlist.
displayName	string	No	Updated display name.
description	string	No	Updated description.
updateMask	string	No	Comma-separated list of fields to update (e.g., displayName,description).

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id",
  "description": "Updated: insider threat tracking",
  "updateMask": "description"
}

List Entities on Watchlist

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the watchlist.
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id",
  "pageSize": 100
}

---

Watchlist Entities

Manage entity membership in watchlists (v1alpha only).

Operations

Operation	Name	Description
add	Add Entity to Watchlist	Add a single entity to a watchlist
batchAdd	Batch Add Entities to Watchlist	Add multiple entities to a watchlist in a single request
batchRemove	Batch Remove Entities from Watchlist	Remove multiple entities from a watchlist in a single request
remove	Remove Entity from Watchlist	Remove a single entity from a watchlist

Add Entity to Watchlist

Parameters:

Name	Type	Required	Description
parent	string	Yes	Resource name of the watchlist.
entity	string	Yes	Resource name of the entity to add.

Example:

{
  "parent": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id",
  "entity": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id"
}

Batch Add Entities to Watchlist

Parameters:

Name	Type	Required	Description
parent	string	Yes	Resource name of the watchlist.
entities	array	Yes	List of entity resource names to add.

Example:

{
  "parent": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id",
  "entities": [
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id-1",
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id-2"
  ]
}

Batch Remove Entities from Watchlist

Parameters:

Name	Type	Required	Description
parent	string	Yes	Resource name of the watchlist.
entities	array	Yes	List of entity resource names to remove.

Example:

{
  "parent": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id",
  "entities": [
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id-1"
  ]
}

Remove Entity from Watchlist

Parameters:

Name	Type	Required	Description
parent	string	Yes	Resource name of the watchlist.
entity	string	Yes	Resource name of the entity to remove.

Example:

{
  "parent": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/watchlists/watchlist-id",
  "entity": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/uniqueEntities/entity-id"
}

---

Enrichment Agent

Interact with the enrichment agent to execute actions and retrieve alert context (v1alpha only).

Operations

Operation	Name	Description
executeActions	Execute Enrichment Actions	Execute one or more enrichment actions via the enrichment agent
fetchActions	Fetch Available Enrichment Actions	Fetch the list of available enrichment actions
fetchAlertData	Fetch Alert Data for Enrichment	Fetch alert data to use as context for enrichment

Execute Enrichment Actions

Parameters:

Name	Type	Required	Description
actions	array	Yes	List of enrichment action names to execute.
context	object	No	Context data for the enrichment actions (e.g., alert details, entity info).

Example:

{
  "actions": ["VirusTotal_IP_Lookup", "Shodan_Host_Info"],
  "context": {
    "ipAddress": "1.2.3.4"
  }
}

Fetch Available Enrichment Actions

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "pageSize": 50
}

Fetch Alert Data for Enrichment

Parameters:

Name	Type	Required	Description
alertName	string	Yes	Resource name of the alert to fetch context data for.

Example:

{
  "alertName": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/alerts/alert-id"
}

---

Enrichment Controls

Manage enrichment control rules that govern automated enrichment behaviour.

Operations

Operation	Name	Description
create	Create Enrichment Control	Create a new enrichment control
delete	Delete Enrichment Control	Delete an enrichment control (v1alpha)
disable	Disable Enrichment Control	Disable an enrichment control without deleting it
get	Get Enrichment Control	Retrieve a specific enrichment control
list	List Enrichment Controls	List all enrichment controls

Create Enrichment Control

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the enrichment control.
description	string	No	Description of the enrichment control.
config	object	No	Enrichment control configuration object.

Example:

{
  "displayName": "Block Enrichment for Internal IPs",
  "description": "Prevents enrichment of RFC1918 addresses",
  "config": {}
}

Delete Enrichment Control

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the enrichment control to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/enrichmentControls/control-id"
}

Disable Enrichment Control

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the enrichment control to disable.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/enrichmentControls/control-id"
}

Get Enrichment Control

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the enrichment control.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/enrichmentControls/control-id"
}

List Enrichment Controls

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression.

Example:

{
  "pageSize": 20
}

---

Calculated Field Definitions

Manage calculated field definitions that derive new values from existing entity properties (v1alpha only).

Operations

Operation	Name	Description
create	Create Calculated Field Definition	Create a new calculated field definition
delete	Delete Calculated Field Definition	Delete a calculated field definition
get	Get Calculated Field Definition	Retrieve a specific calculated field definition
list	List Calculated Field Definitions	List all calculated field definitions
patch	Update Calculated Field Definition	Update an existing calculated field definition
fetchAvailableTargetFields	Fetch Available Target Fields	Fetch available target fields for calculated field definitions
fetchDynamicOptions	Fetch Dynamic Options	Fetch dynamic options for a calculated field definition
validateDependency	Validate Field Dependency	Validate a calculated field dependency before saving

Create Calculated Field Definition

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the field definition.
description	string	No	Description of the field definition.
expression	string	Yes	Expression for the calculated field (Google SecOps expression language).

Example:

{
  "displayName": "Risk Category",
  "description": "Derived risk category from score",
  "expression": "riskScore > 70 ? 'HIGH' : riskScore > 40 ? 'MEDIUM' : 'LOW'"
}

Delete Calculated Field Definition

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the field definition to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/calculatedFieldDefinitions/field-id"
}

Get Calculated Field Definition

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the calculated field definition.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/calculatedFieldDefinitions/field-id"
}

List Calculated Field Definitions

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "pageSize": 25
}

Update Calculated Field Definition

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the field definition.
expression	string	No	Updated expression for the calculated field.
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/calculatedFieldDefinitions/field-id",
  "expression": "riskScore > 80 ? 'CRITICAL' : riskScore > 50 ? 'HIGH' : 'LOW'",
  "updateMask": "expression"
}

Fetch Available Target Fields

Parameters:

Name	Type	Required	Description
filter	string	No	Filter expression to narrow the results.

Example:

{
  "filter": "type=\"STRING\""
}

Fetch Dynamic Options

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the calculated field definition.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/calculatedFieldDefinitions/field-id"
}

Validate Field Dependency

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the calculated field definition to validate.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/calculatedFieldDefinitions/field-id"
}

---

Custom Lists

Manage custom lists used for UI-driven entity grouping and filtering.

Operations

Operation	Name	Description
create	Create Custom List	Create a new custom list
delete	Delete Custom List	Delete a custom list by resource name
batchDelete	Batch Delete Custom Lists	Delete multiple custom lists in a single request
get	Get Custom List	Retrieve a specific custom list
list	List Custom Lists	List all custom lists
patch	Update Custom List	Update an existing custom list
export	Export Custom List	Export a custom list as a downloadable file
import	Import Custom List	Import entries into a custom list from a file

Create Custom List

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the custom list.
description	string	No	Description of the custom list.
entries	array	No	Initial list entries (array of strings).

Example:

{
  "displayName": "VIP Users",
  "description": "Executives and privileged users",
  "entries": ["[email protected]", "[email protected]"]
}

Delete Custom List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the custom list to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id"
}

Batch Delete Custom Lists

Parameters:

Name	Type	Required	Description
names	array	Yes	List of custom list resource names to delete.

Example:

{
  "names": [
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id-1",
    "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id-2"
  ]
}

Get Custom List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the custom list.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id"
}

List Custom Lists

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression.

Example:

{
  "pageSize": 50
}

Update Custom List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the custom list.
entries	array	No	Updated list entries (replaces existing entries).
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id",
  "entries": ["[email protected]", "[email protected]", "[email protected]"],
  "updateMask": "entries"
}

Export Custom List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the custom list to export.
format	string	No	Export format — e.g., JSON, CSV.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id",
  "format": "CSV"
}

Import Custom List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the custom list.
data	string	Yes	Base64-encoded file content to import.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/customLists/list-id",
  "data": "YWxpY2VAY29ycC5jb20KYm9iQGNvcnAuY29t"
}

---

Property Schema Definitions

Manage custom property schemas that extend Google SecOps's entity model.

Operations

Operation	Name	Description
create	Create Property Schema Definition	Create a new property schema definition
delete	Delete Property Schema Definition	Delete a property schema definition
get	Get Property Schema Definition	Retrieve a specific property schema definition
list	List Property Schema Definitions	List all property schema definitions
patch	Update Property Schema Definition	Update an existing property schema definition

Create Property Schema Definition

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the property schema.
description	string	No	Description of the property schema.
propertyType	string	No	Data type — e.g., STRING, NUMBER, BOOL, TIMESTAMP.

Example:

{
  "displayName": "Business Unit",
  "description": "The business unit this entity belongs to",
  "propertyType": "STRING"
}

Delete Property Schema Definition

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the property schema definition to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/propertySchemaDefinitions/schema-id"
}

Get Property Schema Definition

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the property schema definition.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/propertySchemaDefinitions/schema-id"
}

List Property Schema Definitions

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "pageSize": 30
}

Update Property Schema Definition

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the property schema definition.
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/propertySchemaDefinitions/schema-id",
  "updateMask": "description"
}

---

Reference Lists

Manage reference lists that can be referenced directly inside YARA-L detection rules.

Operations

Operation	Name	Description
create	Create Reference List	Create a new reference list for use in YARA-L detection rules
get	Get Reference List	Retrieve a specific reference list
list	List Reference Lists	List all reference lists
patch	Update Reference List	Update an existing reference list

Create Reference List

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the reference list.
description	string	No	Description of the reference list and its purpose.
lines	array	No	Initial list of string entries.
syntaxType	string	No	Syntax type for list entries — PLAIN_TEXT_STRING, CIDR, or REGEX.

Example:

{
  "displayName": "Allowlisted Domains",
  "description": "Known-safe domains to exclude from detection rules",
  "lines": ["google.com", "microsoft.com", "corp.example.com"],
  "syntaxType": "PLAIN_TEXT_STRING"
}

Get Reference List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the reference list.
view	string	No	View type — REFERENCE_LIST_VIEW_UNSPECIFIED, BASIC, or FULL. Use FULL to include all entries.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/referenceLists/list-id",
  "view": "FULL"
}

List Reference Lists

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
view	string	No	View type — REFERENCE_LIST_VIEW_UNSPECIFIED, BASIC, or FULL.

Example:

{
  "pageSize": 50,
  "view": "BASIC"
}

Update Reference List

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the reference list.
lines	array	No	Updated list of string entries (replaces existing).
description	string	No	Updated description.
updateMask	string	No	Comma-separated list of fields to update (e.g., lines,description).

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/referenceLists/list-id",
  "lines": ["google.com", "microsoft.com", "corp.example.com", "new-safe-domain.com"],
  "updateMask": "lines"
}

---

Ontology Records

Manage UDM (Unified Data Model) ontology records (v1alpha only).

Operations

Operation	Name	Description
delete	Delete Ontology Record	Delete an ontology record
get	Get Ontology Record	Retrieve a specific ontology record
list	List Ontology Records	List ontology records
patch	Update Ontology Record	Update an existing ontology record
export	Export Ontology Records	Export ontology records as a package
family	Get Ontology Family	Retrieve the ontology family for a given record
import	Import Ontology Records	Import ontology records from a package
statistics	Get Ontology Statistics	Get usage statistics for ontology records

Delete Ontology Record

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the ontology record to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/record-id"
}

Get Ontology Record

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the ontology record.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/record-id"
}

List Ontology Records

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.
filter	string	No	Filter expression.

Example:

{
  "pageSize": 50
}

Update Ontology Record

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the ontology record.
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/record-id",
  "updateMask": "description"
}

Export Ontology Records

Parameters:

Name	Type	Required	Description
filter	string	No	Filter expression to select which records to export.

Example:

{
  "filter": "type=\"CUSTOM\""
}

Get Ontology Family

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the ontology record.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/record-id"
}

Import Ontology Records

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded ontology package to import.

Example:

{
  "data": "<base64-encoded-ontology-package>"
}

Get Ontology Statistics

Parameters:

Name	Type	Required	Description
filter	string	No	Filter expression.

Example:

{
  "filter": ""
}

---

Ontology Mapping Rules

Manage UDM mapping rules that transform raw log fields into UDM fields (v1alpha only).

Operations

Operation	Name	Description
delete	Delete Mapping Rule	Delete a UDM ontology mapping rule
get	Get Mapping Rule	Retrieve a specific ontology mapping rule
list	List Mapping Rules	List all ontology mapping rules
patch	Update Mapping Rule	Update an existing ontology mapping rule
fetchAll	Fetch All Mapping Rules	Fetch all mapping rules without pagination
save	Save Mapping Rules	Save one or more ontology mapping rules
test	Test Mapping Rule	Test a mapping rule against sample data

Delete Mapping Rule

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the mapping rule to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/mappingRules/rule-id"
}

Get Mapping Rule

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the mapping rule.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/mappingRules/rule-id"
}

List Mapping Rules

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "pageSize": 50
}

Update Mapping Rule

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the mapping rule.
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/mappingRules/rule-id",
  "updateMask": "expression"
}

Fetch All Mapping Rules

Parameters:

Name	Type	Required	Description
filter	string	No	Filter expression to narrow results.

Example:

{
  "filter": ""
}

Save Mapping Rules

Parameters:

Name	Type	Required	Description
rules	array	Yes	List of mapping rule objects to save.

Example:

{
  "rules": [{}]
}

Test Mapping Rule

Parameters:

Name	Type	Required	Description
name	string	No	Resource name of an existing mapping rule to test.
rule	object	No	Inline mapping rule definition to test (use instead of name).
sampleData	object	No	Sample raw log data to test the rule against.

Example:

{
  "rule": {},
  "sampleData": {
    "src_ip": "1.2.3.4",
    "dst_port": "443"
  }
}

---

Ontology Visual Families

Manage UDM visual families used to group and display entity relationships in the Google SecOps UI.

Operations

Operation	Name	Description
create	Create Visual Family	Create a new UDM ontology visual family
delete	Delete Visual Family	Delete a UDM ontology visual family
get	Get Visual Family	Retrieve a specific ontology visual family
list	List Visual Families	List all ontology visual families
patch	Update Visual Family	Update an existing ontology visual family
export	Export Visual Families	Export ontology visual families as a package
import	Import Visual Families	Import ontology visual families from a package

Create Visual Family

Parameters:

Name	Type	Required	Description
displayName	string	Yes	Display name for the visual family.
description	string	No	Description of the visual family.

Example:

{
  "displayName": "Network Assets",
  "description": "Visual grouping for network-related entities"
}

Delete Visual Family

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the visual family to delete.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/visualFamilies/family-id"
}

Get Visual Family

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the visual family.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/visualFamilies/family-id"
}

List Visual Families

Parameters:

Name	Type	Required	Description
pageSize	number	No	Maximum number of results to return.
pageToken	string	No	Pagination token from a previous response.

Example:

{
  "pageSize": 20
}

Update Visual Family

Parameters:

Name	Type	Required	Description
name	string	Yes	Resource name of the visual family.
updateMask	string	No	Comma-separated list of fields to update.

Example:

{
  "name": "projects/my-project/locations/eu/instances/fca7f167-b9d1-43b1-9d03-0257d31dcb63/ontologyRecords/visualFamilies/family-id",
  "updateMask": "description"
}

Export Visual Families

Parameters:

Name	Type	Required	Description
filter	string	No	Filter expression to select which visual families to export.

Example:

{
  "filter": ""
}

Import Visual Families

Parameters:

Name	Type	Required	Description
data	string	Yes	Base64-encoded visual families package to import.

Example:

{
  "data": "<base64-encoded-visual-families-package>"
}

---

Best Practices

1. Use referenceLists.list or referenceLists.get to test connectivity. These are cheap read-only v1 calls available to any service account with Google SecOps API Viewer. Use them to verify credentials before running more complex workflows.

2. Implement pagination for all list operations. Pass the nextPageToken from each response as pageToken in the next call. Stop when nextPageToken is absent or empty.

3. Do not send pageSize to ontologyMappingRules.list or enrichmentAgent.fetchActions. These endpoints return INVALID_ARGUMENT when pageSize is included. Omit the parameter entirely for these two operations.

4. Back up before bulk-importing or patching reference lists and ontology records. Use export operations before applying changes to avoid data loss.

5. Use updateMask on all PATCH operations. Always specify only the fields you intend to change. Omitting updateMask may result in unintended field overwrites.

6. Confirm IOC state before calling updateIocState. Use getIocState first to verify the current state. Suppressing a true positive can cause missed detections and the change is logged in the audit trail.

7. Use batchAdd and batchRemove for bulk watchlist updates. Calling add and remove individually at scale is rate-limit-inefficient; batch operations are significantly faster.

8. Prefer v1 endpoints for production workflows. Operations on v1alpha are subject to breaking changes. Where both versions exist, v1 is the stable choice. Reserve v1alpha-only operations (e.g., modifyEntityRiskScore, watchlistEntities, enrichment agent) for workflows that explicitly require them.

9. Handle rate limits with the built-in retry logic. The connector retries up to 3 times with exponential back-off on HTTP 429 responses, honouring the Retry-After header when present. Avoid hammering list endpoints in tight loops.

10. Store the service account JSON key securely. Never log it, embed it in code, or commit it to source control. Use NINA's credential management for encrypted storage. Rotate keys regularly using GCP Console → Service Accounts → Keys.

Troubleshooting

Issue	Possible Cause	Solution
serviceAccountJson is required	Missing credential field	Paste the full service account JSON content into the field
failed to parse service account JSON	Corrupt JSON or wrong key type (e.g., an API key was pasted instead of a service account JSON)	Download a fresh JSON key from GCP Console (IAM → Service Accounts → Keys)
401 Unauthenticated	Token expired or service account deleted	Re-export a fresh service account JSON key from GCP Console
403 Permission Denied	Service account lacks required Google SecOps IAM role	Grant Google SecOps API Viewer, Google SecOps API Editor, or Google SecOps SOAR Admin as needed
404 Not Found	Wrong project, location, or instance value in credentials, or the resource does not exist	Verify all five credential fields in Google SecOps Console → Settings → Instance details
UnsupportedApiVersion on entitiesBlocklists.list	This Google SecOps instance tier does not support v1 for this endpoint	This is an instance-tier constraint; the connector handles it gracefully in tests via skipOnInvalidArgument
INVALID_ARGUMENT: Cannot bind query parameter 'pageSize'	pageSize was sent to an endpoint that does not accept it (ontologyMappingRules.list, enrichmentAgent.fetchActions)	Remove pageSize from the call; these endpoints do not support pagination via this parameter
429 Too Many Requests	Rate limit exceeded	The connector retries automatically. If persistent, reduce call frequency in your NINA workflow
404 on ontologyMappingRules.fetchAll or ontologyVisualFamilies.list	Ontology features not enabled on this instance tier	Contact Google SecOps support to enable advanced ontology management
Connection timeout	Wrong region value or network issue	Verify the region matches your Google SecOps instance's provisioned region exactly
Empty list results	No data exists yet, or filter is too restrictive	Remove filter parameters and retry; use the Google SecOps console to confirm data exists

Support

For issues with this integration, please contact support with:

• The resource and operation you were attempting (e.g., watchlists.list)
• The complete error message received
• The parameters used (excluding sensitive credential data)
• Your Google SecOps region and instance ID

For Google SecOps API documentation, visit: Google SecOps API Reference

Updated: 2026-07-08