# Threat List IOCs

**Sync Type: Incremental**

## Overview

The Google Threat Intelligence (GTI) **Threat List IOCs** input collects high-confidence indicators of compromise — files, URLs, domains, and IP addresses — from GTI's curated **Threat Lists**. GTI is the platform that unifies **Mandiant Advantage Threat Intelligence** and **VirusTotal**; if you were previously a Mandiant customer, this is where that intelligence now lives.

Threat Lists are published as **hourly packages**. This input walks those hourly packages forward in time for the threat list you choose, filters each indicator by its **GTI score** (default ≥ 80), and emits every matching IOC as an individual record — ideal for feeding a SIEM or a threat-intelligence upload output (for example, Microsoft Sentinel).

By default the input emits records in **Microsoft Sentinel's upload shape** (`STIX (Sentinel)`), ready to send to Sentinel — GTI does the conversion server-side. Other shapes are available (e.g. **STIX 2.0** for Monad's Microsoft Sentinel Threat Intelligence output); see [Output format](#output-format).

## Prerequisites

### 1. A Google Threat Intelligence subscription
- An active GTI account. Some threat lists require **Enterprise** or **Enterprise Plus** licensing (see [Threat Lists](#threat-lists)).

### 2. A GTI API key
- The input authenticates with a GTI API key sent as the `x-apikey` header.
- For unattended pipelines, use a **service account** API key. Service accounts are created by a GTI **group administrator**, are not tied to an individual.

## API Key Setup

1. **Sign in to Google Threat Intelligence** (or have your group administrator do so).
2. **Retrieve an API key:**
   - *Personal key:* open your profile → **API Key**.
   - *Service account key (recommended for pipelines):* a **group administrator** creates a service account and copies its API key from the GTI admin console.
3. **Confirm the key is entitled** to the threat list(s) you plan to collect (Enterprise / Enterprise Plus lists require the corresponding license).
4. **Store the key securely** and provide it as the input's API Key secret.

## Configuration

### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| Threat List | one-of | Yes | The threat list to collect from. Selecting a list reveals only the IOC Types that list supports. See [Threat Lists](#threat-lists). |
| IOC Types | array | No | Restrict collection to specific entity types for the chosen list. **Leave empty to collect all types the list supports.** Options are filtered to the selected list (e.g. `ransomware` only offers `file`). |
| Minimum GTI Score | int | No | Only collect IOCs whose GTI score is at or above this value (0–100). Defaults to **80**. |
| Output Format | string | No | The shape records are emitted in: **STIX (Sentinel)** (default), **STIX 2.0**, or **JSON** (native GTI). See [Output format](#output-format). |
| Backfill Start Time | string | No | RFC 3339 timestamp to start collecting from. Defaults to the newest available package (collect going forward). Packages are retrievable roughly **2 years** back. |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate. Leave blank to use the connector's default. See [API Rate Limiting](../../guides/rate-limiting). |
| API Key | string (secret) | Yes | GTI API key sent as the `x-apikey` header. |

### Threat Lists

Choose one threat list. The **IOC Types** you can select are constrained to what that list actually publishes.

| Threat List | Supported IOC Types | License |
|-------------|---------------------|---------|
| Ransomware (`ransomware`) | file | All |
| Malicious Network Infrastructure (`malicious-network-infrastructure`) | url, domain, ip_address | All |
| Malware (`malware`) | file, url, domain, ip_address | Enterprise / Enterprise Plus |
| Threat Actor (`threat-actor`) | file, url, domain, ip_address | Enterprise / Enterprise Plus |
| Daily Top Trending (`trending`) | file, url, domain, ip_address | Enterprise / Enterprise Plus |
| Mobile (`mobile`) | file | Enterprise Plus |
| OS X (`osx`) | file | Enterprise Plus |
| Linux (`linux`) | file | Enterprise Plus |
| Internet of Things (`iot`) | file | Enterprise Plus |
| Cryptominers (`cryptominer`) | file, url, domain, ip_address | Enterprise Plus |
| Phishing (`phishing`) | url, domain, ip_address | Enterprise Plus |
| First Stage Delivery Vectors (`first-stage-delivery-vectors`) | file | Enterprise Plus |
| Vulnerability Weaponization (`vulnerability-weaponization`) | file, url, domain, ip_address | Enterprise Plus |
| Infostealers (`infostealer`) | file | Enterprise Plus |

### Output format

The **Output Format** setting controls the shape of each emitted record. GTI performs the conversion server-side, so no transform node is needed.

| Format | What you get | Use it when |
|--------|--------------|-------------|
| **STIX (Sentinel)** (default) | GTI's Microsoft Sentinel upload envelope | Sending indicators to Microsoft Sentinel — the records are already in Sentinel's expected shape. |
| **STIX 2.0** | Standard STIX `indicator` objects | Feeding Monad's **Microsoft Sentinel Threat Intelligence** output, which ingests STIX 2.0/2.1 objects — wire `Threat List IOCs → Microsoft Sentinel Threat Intelligence` with **no transform** in between. |
| **JSON** | The native GTI IOC object (`{ "type": "file", "id": …, "attributes": { … } }`) | Routing elsewhere, or when you want the raw GTI fields to transform yourself. |

## How collection works

- **Hourly packages.** Each threat list is regenerated every hour as an immutable package addressed by an hourly timestamp (`YYYYMMDDhh`, UTC).
- **2-hour availability lag.** A package for hour `T` becomes retrievable at roughly `T + 2h`. The input never requests a package newer than `now − 2h`.
- **Score filtering is server-side.** The GTI score threshold is applied by the API (`gti_score:{n}+`), so only qualifying IOCs are transferred.
- **Incremental by hour.** The input tracks the next hourly package to fetch and advances one hour at a time, so each run collects only packages it hasn't processed yet. With a **Backfill Start Time**, the first run walks every hourly package from that time up to `now − 2h`.
- **Update-aware.** A package includes an IOC when its `last_modification_date` falls in that hour, so an indicator that is later re-scored or enriched re-appears in the package for its update hour — updates are captured without a separate re-scan.

## Sample Record

The example below is a STIX indicator (a `file` indicator), the shape used by both **STIX (Sentinel)** and **STIX 2.0**. With **JSON** format, each record is instead the native GTI IOC object (`{ "type": "file", "id": …, "attributes": { "gti_assessment": …, "last_modification_date": … } }`).

```json
{
  "type": "indicator",
  "spec_version": "2.1",
  "id": "indicator--a2cb5c43-fcc4-9bd2-1a5c-e7ef8bd35cc6",
  "created_by_ref": "identity--1aa11bb7-5ed3-53e6-9a04-34aefffa322f",
  "created": "2026-09-25T18:20:16Z",
  "modified": "2026-09-25T18:20:16Z",
  "name": "001009200d1ed373e53c06edd30e5e5168099e1b295a9c819b8b4ba7f7b76643",
  "confidence": 84,
  "indicator_types": [
    "gti-threat_score-87",
    "gti-severity-medium",
    "gti-verdict-suspicious"
  ],
  "labels": [
    "peexe",
    "trojan"
  ],
  "valid_from": "2026-09-25T18:20:16Z",
  "valid_until": "2026-09-25T18:20:16Z",
  "pattern_type": "stix",
  "pattern": "[file:hashes.'SHA-256' = '001009200d1ed373e53c06edd30e5e5168099e1b295a9c819b8b4ba7f7b76643']",
  "external_references": [
    {
      "source_name": "gti",
      "external_id": "001009200d1ed373e53c06edd30e5e5168099e1b295a9c819b8b4ba7f7b76643"
    }
  ],
  "extensions": {
    "extension-definition--d4ff44e6-a017-5b6d-ac64-3d18ba052642": {
      "verdict": {
        "value": "VERDICT_SUSPICIOUS"
      },
      "threat_score": {
        "value": 94
      },
      "severity": {
        "value": "SEVERITY_HIGH"
      }
    }
  }
}
```

## Troubleshooting

### Common Issues

1. **Authentication Errors (401 / 403)**
   - Confirm the API Key is a valid GTI key sent as `x-apikey`. For a service account, have the group administrator re-copy the key from the admin console.
   - Confirm the key is **entitled** to the selected threat list — Enterprise / Enterprise Plus lists return `403` for accounts without that license.

2. **A Threat List Returns Nothing**
   - Verify licensing for that list, and that the selected **IOC Types** are ones the list publishes (the picker enforces this, but a hand-edited config may not).
   - A high **Minimum GTI Score** narrows results; lower it if you expect more indicators.

3. **Fewer Than Expected IOCs in a Busy Hour**
   - Each hourly package returns at most **4,000 records** and the endpoint has **no pagination beyond that cap**. In an unusually large hour a package can exceed 4,000, in which case the overflow is not retrievable. The connector logs a warning when a package returns exactly the cap. The GTI score filter keeps most packages well under the limit.

4. **No New Records / Empty Syncs**
   - Because of the 2-hour availability lag, the most recent retrievable hour is `now − 2h`. If no new package has been published since the last run, nothing is emitted — this is expected.

5. **Duplicate Records**
   - Delivery is **at least once**. Records are keyed on the stable IOC `id`, so duplicates can be de-duplicated downstream. The connector also suppresses re-emission of records it already delivered when re-processing an interrupted hourly package.

6. **Rate Limiting (429)**
   - The connector backs off and retries automatically. If throttling persists, lower the optional **API Rate Limit**.

## Related Articles

- [Google Threat Intelligence API overview](https://gtidocs.virustotal.com/reference/api-overview)
- [Get an hourly Threat List](https://gtidocs.virustotal.com/reference/get-hourly-threat-list)
- [GTI indicator score](https://gtidocs.virustotal.com/docs/google-threat-intelligence-indicator-score)
- [Mandiant Advantage → GTI API migration guide](https://gtidocs.virustotal.com/docs/mati-api-migration-guide)