This document explains the core data structures and logic used by the Threat Intelligence API. To start calling the API, see the Get Started guide, and to see all the available methods, see the REST 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 relatedasset 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.