Skip to main content

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.

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.
poll_and_index.py
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 fieldECS field
value (IP)threat.indicator.ip
value (domain)threat.indicator.url.domain
value (hash)threat.indicator.file.hash.sha256
confidencethreat.indicator.confidence
source.feed_namethreat.indicator.provider
typethreat.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.
The TAXII integration requires a SOC Defenders Pro subscription.
1

Add the Threat Intelligence integration

In Kibana, go to Fleet → Integrations and search for Threat Intelligence. Select the integration and click Add Threat Intelligence.
2

Configure the TAXII source

In the integration settings, choose TAXII as the source type and enter the following:
FieldValue
TAXII serverhttps://www.socdefenders.ai/api/taxii2/api/
Collection IDall (or ips, hashes, cves)
Usernameapikey
PasswordYour SOC Defenders API key
Poll interval1h
3

Assign to an agent policy

Assign the integration to an Elastic Agent policy and deploy. Elastic Agent will begin polling and indexing indicators automatically.
4

Verify ingestion

In Kibana Discover, filter on event.category: threat and event.type: indicator to confirm indicators are arriving.

​
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

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: 
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