This document explains the core data structures and logic used by the Google Threat Intelligence Alerts API. To start calling the API, see the Get Started guide, and to see all the available methods, see the Google Threat Intelligence API Reference.

Organization Profile

The Organization Profile is a structured data object stored within the projects.configurations resource. It encapsulates the entity's characteristics used for threat matching.

A profile typically contains:

Identity: Company name, brands, and key persons.
Assets: Domains, IPs, and tech precences.
Context: Industry, geographic regions, and security considerations.

The system uses the org profile to perform nuanced, context-aware semantic matching beyond keyword search.

Findings vs. Alerts

The API distinguishes between raw detections and actionable incidents using two distinct resources:

Findings

Resource: projects.findings

A Finding is an immutable record of a specific threat detection event. It contains:

Source Data: The raw content (e.g., forum post body, file hash).
Match Metadata: Why it matched, severity, and confidence.
Timestamp: When the event was observed.

Alerts

Resource: projects.alerts

An Alert is a mutable, stateful object that groups one or more Findings. It represents a security incident that requires investigation. Alerts are enriched with:

Aggregated Context: Summary of all related findings.
Status: Triage state (e.g., New, Triaged, Resolved).
Severity: Computed risk score based on the findings and related asset criticality.

Threat Scenarios

Threat Scenarios organizes and groups relevant alerts together, and are the logical definitions that determine detection behavior.

Supported scenarios include:

Data Leakage: Identifying potentially sensitive data on external platforms.
Initial Access Broker (IAB): Detecting potential sale of network access.
Insider Threats: Detecting potential recruitment attempts and insider offerings.