> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socdefenders.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SOC Defenders threat data to Elastic Security

> Configure Elastic Security to ingest IOCs from SOC Defenders using the REST API or TAXII feed. Includes filebeat configuration and EQL detection examples.

Elastic Security stores threat indicators in the `threat.indicator` fields of the Elastic Common Schema (ECS), making them available for correlation rules, timeline investigations, and indicator match rules. You can populate these fields by polling the SOC Defenders REST API with a Python script or custom integration, or — on Pro — by configuring the Threat Intelligence TAXII integration in Elastic Agent to handle polling automatically.

## Option 1: REST API with custom ingest

Use a Python script to poll `GET /api/v1/iocs` on a schedule, map the response fields to ECS, and index the documents into Elasticsearch.

### Poll the API and index to Elasticsearch

The following script fetches IPv4 indicators and indexes them into an Elasticsearch index named `logs-ti.socdefenders-default`. Adjust the `IOC_TYPE` and `INDEX` variables to suit your environment.

```python poll_and_index.py theme={null}
import requests
from datetime import datetime, timezone
from elasticsearch import Elasticsearch

SOC_API_KEY = "YOUR_API_KEY"
SOC_BASE_URL = "https://socdefenders.ai/api/v1/iocs"
ES_HOST = "https://your-elasticsearch-host:9200"
ES_API_KEY = "YOUR_ES_API_KEY"
INDEX = "logs-ti.socdefenders-default"
IOC_TYPE = "ipv4"

es = Elasticsearch(ES_HOST, api_key=ES_API_KEY)

def fetch_iocs(ioc_type: str, limit: int = 1000) -> list:
    resp = requests.get(
        SOC_BASE_URL,
        headers={"Authorization": f"Bearer {SOC_API_KEY}"},
        params={"type": ioc_type, "limit": limit},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json().get("data", [])

def to_ecs(ioc: dict) -> dict:
    return {
        "@timestamp": datetime.now(timezone.utc).isoformat(),
        "event": {"kind": "enrichment", "category": ["threat"], "type": ["indicator"]},
        "threat": {
            "indicator": {
                "type": "ipv4-addr",
                "ip": ioc.get("value"),
                "confidence": ioc.get("confidence"),
                "provider": ioc.get("source", {}).get("feed_name"),
            }
        },
    }

iocs = fetch_iocs(IOC_TYPE)
for ioc in iocs:
    es.index(index=INDEX, document=to_ecs(ioc))

print(f"Indexed {len(iocs)} indicators.")
```

Run this script on a schedule using cron or a task scheduler. For Free tier accounts, a 15-minute interval keeps you within the rate limit. Pro accounts can reduce the interval to 1 minute.

### ECS field mapping

| SOC Defenders field | ECS field                           |
| ------------------- | ----------------------------------- |
| `value` (IP)        | `threat.indicator.ip`               |
| `value` (domain)    | `threat.indicator.url.domain`       |
| `value` (hash)      | `threat.indicator.file.hash.sha256` |
| `confidence`        | `threat.indicator.confidence`       |
| `source.feed_name`  | `threat.indicator.provider`         |
| `type`              | `threat.indicator.type`             |

## Option 2: TAXII via Elastic Agent (Pro)

Elastic Agent includes a **Threat Intelligence** integration that supports TAXII 2.1 feeds. Once configured, Elastic Agent polls the SOC Defenders TAXII server on a schedule and indexes STIX 2.1 objects directly into ECS-mapped fields — no custom code required.

<Note>
  The TAXII integration requires a SOC Defenders Pro subscription.
</Note>

<Steps>
  <Step title="Add the Threat Intelligence integration">
    In Kibana, go to **Fleet → Integrations** and search for **Threat Intelligence**. Select the integration and click **Add Threat Intelligence**.
  </Step>

  <Step title="Configure the TAXII source">
    In the integration settings, choose **TAXII** as the source type and enter the following:

    | Field         | Value                                         |
    | ------------- | --------------------------------------------- |
    | TAXII server  | `https://www.socdefenders.ai/api/taxii2/api/` |
    | Collection ID | `all` (or `ips`, `hashes`, `cves`)            |
    | Username      | `apikey`                                      |
    | Password      | Your SOC Defenders API key                    |
    | Poll interval | `1h`                                          |
  </Step>

  <Step title="Assign to an agent policy">
    Assign the integration to an Elastic Agent policy and deploy. Elastic Agent will begin polling and indexing indicators automatically.
  </Step>

  <Step title="Verify ingestion">
    In Kibana Discover, filter on `event.category: threat` and `event.type: indicator` to confirm indicators are arriving.
  </Step>
</Steps>

## Detection with EQL

Once indicators are indexed, use indicator match rules or the following EQL query to hunt for network connections to known-malicious IPs in your environment.

### Correlate network events with ingested IP indicators

```eql theme={null}
sequence by host.id
  [network where event.category == "network" and network.direction == "egress"]
  [any where event.dataset == "ti.socdefenders" and threat.indicator.type == "ipv4-addr"]
  until [network where event.category == "network" and network.direction == "egress"
         and threat.indicator.ip == destination.ip]
```

For a simpler ad-hoc search using ES|QL:

```esql theme={null}
FROM logs-ti.socdefenders-default
| WHERE threat.indicator.type == "ipv4-addr"
| STATS count = COUNT(*) BY threat.indicator.ip, threat.indicator.confidence
| SORT count DESC
| LIMIT 50
```