Obtaining Google Threat Intelligence's unique attributes from the API
To successfully obtain the gti_assessment attribute within the JSON response, the inclusion of the x-tool header in your request is a critical requirement. This header is essential for uniquely identifying your specific tool or service. Without this vital component, the API will be unable to process your request correctly and, consequently, the gti_assessment attribute will not be returned in the JSON payload. Ensure that the x-tool header accurately reflects the identifier of your application or service to guarantee proper API functionality and data retrieval.
The x-tool header
The "x-tool" header is a critical component for authenticating and identifying your requests when interacting with the API. While technically it can be any arbitrary string, adhering to a best practice for its value is highly recommended. To ensure clarity, traceability, and proper attribution, it is advisable to format the "x-tool" value by combining your organizational name with the specific application or system from which the API call originates. This structured approach not only helps in debugging and monitoring API usage but also assists the API provider in understanding the context of incoming requests, potentially leading to better support and service optimization. For instance, an ideal "x-tool" value might look like "YourOrganizationName-YourApplicationName" or "YourOrganizationName/YourProjectIdentifier".
Python script example header
headers = {
"accept": "application/json",
"x-apikey": "***************redacted************************",
"x-tool": "Google-PythonScriptForIndicators"
}
Google Threat Intelligence Objects
- The gti_assessment field is a dictionary. It contains key attributes related to an entity's threat assessment. If a field's value within this dictionary is null, it will not be included in the API response.:
- verdict: A dictionary that provides a classification of the entity's maliciousness. The value property within this dictionary can be one of the following:
- VERDICT_BENIGN: The entity is considered entirely harmless, with no indicators of malicious activity.
- VERDICT_UNDETECTED: No immediate or conclusive evidence of malicious intent has been identified for the entity.
- VERDICT_SUSPICIOUS: Possible malicious activity has been detected, and the entity warrants further investigation and analysis.
- VERDICT_MALICIOUS: There is a high level of confidence that the entity poses a significant threat and is actively involved in malicious activities.
- VERDICT_UNKNOWN: The system was unable to generate a conclusive verdict due to insufficient data or other factors.
- severity: A dictionary describing the potential impact of the detected threat. The value property can include any of these classifications:
- SEVERITY_NONE: This level is assigned to entities that have a non-malicious verdict, indicating no threat impact.
- SEVERITY_LOW: The threat is likely to have a minor impact but still requires monitoring and potential preventative measures.
- SEVERITY_MEDIUM: This indicates a potential threat that warrants immediate attention and a thorough investigation to mitigate risks.
- SEVERITY_HIGH: Immediate action is strongly recommended, as the threat could have a critical and widespread impact on systems or data.
- SEVERITY_UNKNOWN: Insufficient data is available to accurately assess the severity of the threat.
- description: A clear, human-readable string that details the contributing factors and rationale behind the verdict and severity classifications.
- Example: "This indicator is malicious (high severity) with high impact. It is considered widespread, GTI's ML scoring model identified this indicator as malicious, it is associated with a community threat actor, it is associated with a tracked Mandiant campaign and it is contained within a collection provided by the Google Threat Intelligence team, or a trusted partner or security researcher. Analysts should prioritize investigation."
- threat_score: An integer representing the Google Threat Intelligence score, derived from a combination of the Verdict, Severity, and various internal factors. Valid values for this score range from 0 (harmless) to 100 (highly malicious).
- Example: "threat_score": {
- verdict: A dictionary that provides a classification of the entity's maliciousness. The value property within this dictionary can be one of the following:
"value": 95
}
- contributing_factors: A dictionary outlining the specific signals and evidence that led to the verdict and severity classifications. These factors provide transparency into the threat assessment process:
- mandiant_analyst_benign: A boolean value indicating that a Google Threat Intelligence analyst has determined the indicator to be benign, implying it poses no threat.
- “mandiant_analyst_benign”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_analyst_malicious: A boolean value confirming that a Google Threat Intelligence analyst has identified the indicator as malicious.
- “mandiant_analyst_malicious”: true
- “mandiant_analyst_malicious”: false
- If the boolean value is null, the corresponding field will be absent from the API response.
- google_malware_analysis: A boolean value indicating detection by Google Threat Intelligence's advanced malware analysis systems.
- “google_malware_analysis”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- google_botnet_emulation: A boolean value signifying detection through Google Threat Intelligence's botnet analysis and emulation capabilities.
- “google_botnet_emulation”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- google_mobile_malware_analysis: A boolean value indicating detection by Google Threat Intelligence's specialized mobile malware analysis tools.
- “google_mobile_malware_analysis”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- google_malware_similarity: A boolean value reflecting detection based on similarities to known malware identified by Google Threat Intelligence's analysis.
- “google_malware_similarity”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- google_malware_analysis_auto: A boolean value indicating automated detection by Google Threat Intelligence's malware analysis systems.
- “google_malware_analysis_auto”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_association_report: A boolean value indicating that the indicator is associated with a specific Google Threat Intelligence Intelligence Report.
- “mandiant_association_report”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_association_actor: A boolean value indicating an association with a tracked Google Threat Intelligence threat actor.
- “mandiant_association_actor”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_association_malware: A boolean value indicating an association with a tracked Google Threat Intelligence malware family.
- “mandiant_association_malware”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_domain_hijack: A boolean value indicating that the domain was recently identified as malicious by a Google Threat Intelligence analyst.
- “mandiant_domain_hijack”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_osint: A boolean value indicating that the indicator is considered widespread based on open-source intelligence.
- “mandiant_osint”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- safebrowsing_verdict: A string value representing the Google Safebrowsing verdict for the entity.
- "safebrowsing_verdict": "harmless"
- "safebrowsing_verdict": "malicious"
- gavs_detections: An integer representing the number of detections by Google’s robust spam and threat filtering engines.
- "gavs_detections": 2
- If the integer value is null, the corresponding field will be absent from the API response.
- gavs_categories: A list of strings identifying known threat categories associated with the entity.
- “gavs_categories”[ "trojan" ]
- normalised_categories: A list of strings representing standardized known threat categories.
- "normalised_categories": [ "trojan" ]
- If the list is null, the corresponding field will be absent from the API response.
- legitimate_software: A boolean value indicating that the indicator is benign and is associated with a well-known and trusted software distributor, suggesting no threat.
- “legitimate_software” : true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- matched_malicious_yara: A boolean value indicating that the entity matches known YARA rules for malicious activity.
- “matched_malicious_yara”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- malicious_sandbox_verdict: A boolean value indicating detection by sandbox analysis, highlighting suspicious behavior.
- "malicious_sandbox_verdict": true
- "malicious_sandbox_verdict": false
- associated_reference: A boolean value indicating that the entity appears in public sources or external references.
- “associated_reference”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- associated_malware_configuration: A boolean value indicating that the entity contains known malware configurations.
- “associated_malware_configuration”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- associated_actor: A boolean value indicating an association with a community threat actor.
- "associated_actor": true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- high_severity_related_files: A boolean value indicating that related files are marked as malicious with a high severity level.
- “high_severity_related_files”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- medium_severity_related_files: A boolean value indicating that related files are marked as malicious with a medium severity level.
- “medium_severity_related_files”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- low_severity_related_files: A boolean value indicating that related files are marked as malicious with a low severity level.
- “low_severity_related_files”: true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- pervasive_indicator: A boolean value indicating that related files have been observed in Open-Source Intelligence (OSINT) sources, suggesting a wider presence.
- “pervasive_indicator": true
- If the boolean value is false or null, the corresponding field will be absent from the API response.
- mandiant_analyst_benign: A boolean value indicating that a Google Threat Intelligence analyst has determined the indicator to be benign, implying it poses no threat.
- gti_confidence_score: An integer representing the Google Threat Intelligence confidence score for the indicator. This score is derived from a probabilistic model that weights various internal and external signals. It reflects the confidence level in an indicator being malicious (values closer to 100) or benign (values closer to 0). This score serves as a critical additional signal used to determine the gti_assessment.verdict field. The interpretation of this score is as follows:
- Values Above 95: Indicators with scores in this range are considered highly malicious, and analysts should prioritize their investigation due to the high confidence of a threat.
- Values Above 80: Indicators falling into this category are generally considered malicious, warranting significant attention.
- Values Between 60 and 80: Indicators within this range are considered suspicious and require further analysis to confirm or deny malicious intent.
- Values Between 20 and 60: For indicators in this range, there are insufficient signals to definitively classify them as malicious or benign. This is equivalent to an 'undetected' verdict.
- Values Below 20: Indicators with scores in this lower range can typically be considered benign or represent noisy, non-malicious activity.
Conclusion
This document outlines the process for extracting Google Threat Intelligence (GTI) attributes, with a specific focus on the gti_assessment dictionary, directly from an API response. It also provides a detailed explanation of the underlying structure of GTI objects, enabling users to effectively interpret and utilize the threat intelligence data. Understanding this structure is crucial for accurate analysis and integration of GTI into various security operations and platforms
