Public Guide

Investigate and Integrate Threat Intelligence

Determine whether an IOC affects your environment, review explainable tenant matches, and safely automate enforceable indicators across SIEM, network, DNS, and endpoint controls. Audience: Security engineers, SOC analysts, and network administrators. Typical setup time: 5-10 minutes.

reference

Use this if

Determine whether an IOC affects your environment, review explainable tenant matches, and safely automate enforceable indicators across SIEM, network, DNS, and endpoint controls.

Audience: Security engineers, SOC analysts, and network administratorsTypical time: 5-10 minutes

Before You Begin

  • Create an ingestion API key in Settings → API Keys with at least read access to the Threat Intel blocklist.
  • Confirm your security tooling (WAF, DNS, EDR) has API or file-based ingestion capabilities.
  • Review the indicator types available in your tenant (IP, domain, SHA256) to decide which integrations to deploy first.

Guide walkthrough

1

Step 1

Investigate whether the threat affects you

Use the Query tab for IPs, domains, URLs, emails, SHA256 hashes, CVEs, or sanctioned entities, then pivot from source rationale into tenant evidence.

  • Open `/threat-intel?tab=query` and search a recent record from the intelligence library.
  • Review verdict, severity, confidence, freshness, blocklist eligibility, and source evidence.
  • Inspect matches across SIEM, EASM, and findings, then open the linked finding or alert when one exists.
  • Escalate through the normal incident workflow only after validating impact; context records never create incidents directly.

What success looks like

Escalate through the normal incident workflow only after validating impact; context records never create incidents directly.

2

Step 2

Choose a safe downstream recipe

The Integrations tab shows prerequisites, expected results, and copy-ready examples for Splunk, Sentinel, Elastic, firewalls, AWS WAF, DNS, EDR, REST, and the Python SDK.

  • Start with a detect-only or preview mode when the destination supports it.
  • Use `/api/v1/threat-intel/blocklist/export` only for prevention controls.
  • Use `/api/v1/threat-intel/investigate`, `/records`, and `/matches` for analyst context and correlation.
  • Preserve normal finding lifecycle resolution when intelligence later becomes stale; do not silently close historical evidence.

What success looks like

Preserve normal finding lifecycle resolution when intelligence later becomes stale; do not silently close historical evidence.

3

Step 3

Deploying to AWS WAF

Fetch the IPv4 blocklist and pipe it dynamically into an AWS WAF IPSet to block malicious scanners automatically.

  • Generate a read-only API key with threat_intel:read in Settings → API Keys.
  • Use the Boto3 Python snippet to `requests.get` the `/threat-intel/blocklist/export?indicator_type=ip`.
  • Transform the IPs into `address/32` CIDR notation.
  • Call `waf_client.update_ip_set()` to push the changes live.

What success looks like

Call `waf_client.update_ip_set()` to push the changes live.

4

Step 4

DNS Sinkholing with CoreDNS or Pi-hole

Use a bash script to fetch malicious domains and sinkhole them to prevent internal systems from resolving known malware or C2 infrastructure.

  • Fetch the domain export over the CSV endpoint: `/export?format=csv&indicator_type=domain`.
  • Parse each malicious domain and output `0.0.0.0 [domain]` into a `hosts` file.
  • Reload your DNS daemon (e.g. `pihole restartdns reload`).

What success looks like

Reload your DNS daemon (e.g. `pihole restartdns reload`).

5

Step 5

EDR Hash Ingestion

Export known malicious SHA256 hashes to import directly into your Endpoint Detection and Response platform (like CrowdStrike Falcon) to quarantine malware on execution.

  • Fetch the SHA256 export over the CSV endpoint.
  • Parse the payload to extract the hash and threat name.
  • Transform into the respective API payload format for your EDR.
  • Execute the request to sync the IOCs with your detection policies.

What success looks like

Execute the request to sync the IOCs with your detection policies.

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Run This

aws_waf_update.py
import os
import boto3
import requests

def update_waf_ipset():
    api_key = os.environ.get("BLACKSHIELD_API_KEY")
    waf_client = boto3.client("wafv2", region_name="us-east-1")
    ip_set_id = os.environ.get("WAF_IPSET_ID")
    ip_set_name = os.environ.get("WAF_IPSET_NAME")

    # 1. Fetch latest IP indicators
    url = "https://api.blackshield.chaplau.com/api/v1/threat-intel/blocklist/export?format=txt&indicator_type=ip"
    res = requests.get(url, headers={"X-API-Key": api_key})
    res.raise_for_status()

    addresses = []
    for ip in res.text.strip().split("\n"):
        if ip and not ip.startswith("#"):
            addresses.append(f"{ip}/32" if "/" not in ip else ip)

    # 2. Update the WAF IPSet
    ip_set = waf_client.get_ip_set(Name=ip_set_name, Scope="CLOUDFRONT", Id=ip_set_id)
    lock_token = ip_set["LockToken"]

    waf_client.update_ip_set(
        Name=ip_set_name,
        Scope="CLOUDFRONT",
        Id=ip_set_id,
        Addresses=addresses,
        LockToken=lock_token
    )
    print(f"Updated WAF IPSet {ip_set_name} with {len(addresses)} addresses.")

if __name__ == "__main__":
    update_waf_ipset()
dns_sinkhole.sh
#!/bin/bash
# Generate a CoreDNS/Pi-Hole compatible hosts file from the domain export
export_url="https://api.blackshield.chaplau.com/api/v1/threat-intel/blocklist/export?format=csv&indicator_type=domain"

curl -s -X GET "$export_url" \
  -H "X-API-Key: $BLACKSHIELD_API_KEY" \
  > domains.csv

echo "# Threat Intel Sinkhole" > blocklist.hosts

tail -n +2 domains.csv | while IFS=',' read -r indicator type source severity confidence_score last_seen_at
do
  if [ -n "$indicator" ]; then
    echo "0.0.0.0 $indicator" >> blocklist.hosts
  fi
done
edr_hash_sync.py
import os
import requests

def get_malicious_hashes():
    api_key = os.environ.get("BLACKSHIELD_API_KEY")
    url = "https://api.blackshield.chaplau.com/api/v1/threat-intel/blocklist/export?format=csv&indicator_type=sha256"

    response = requests.get(url, headers={"X-API-Key": api_key})
    response.raise_for_status()

    ioc_payloads = []
    lines = response.text.strip().split("\n")[1:]

    for line in lines:
        if not line:
            continue
        parts = line.split(",")
        sha256 = parts[0]
        source = parts[2] if len(parts) > 2 else "unknown source"

        ioc_payloads.append({
            "type": "sha256",
            "value": sha256,
            "policy": "detect",
            "description": f"BlackShield Threat Intel source: {source}"
        })

    return ioc_payloads

What success looks like

  • Your AWS WAF IPSet reflects the latest blocklist IPs and blocks known-malicious scanners.
  • DNS sinkhole hosts file reloads on schedule and internal clients can no longer resolve blocklisted domains.
  • EDR platform shows newly imported SHA256 IOCs with the correct threat labels from BlackShield.
Investigate and Integrate Threat Intelligence | BlackShield Docs