isMalicious API: Make Your First Reliable IOC Lookup

A successful curl command proves that a server answered once. A reliable IOC integration proves more: it calls the right host, protects the credential, rejects malformed input, distinguishes a verdict from an outage, and leaves enough evidence to investigate later.

The current canonical lookup is GET https://api.ismalicious.com/check?query=<indicator>. It accepts an IP address, domain, URL, or hexadecimal file hash through query, with basic, standard, or full enrichment. This walkthrough uses standard, then adds the controls needed to move from a terminal test into a service, SIEM rule, or SOAR playbook.

Keep the interactive API documentation beside you while implementing. It is the source of truth for the current host, parameters, response examples, and related endpoints.

Start with the canonical contract

Use https://api.ismalicious.com for server-to-server clients. The main web application also exposes dashboard and session routes, but a new IOC client should not depend on a browser session or silently switch hosts. Pin the base URL in configuration and allow only HTTPS.

Send exactly one normalized target in query. Before the request, trim whitespace, reject an empty value, cap its length, and classify it as an IP, domain, URL, or hash. Client-side validation matters because a missing target can still produce a small successful response. A transport-level 200 therefore does not prove that enrichment happened.

Start with enrichment=standard. Treat the response as untrusted input: validate its JSON shape, bound what you store, and avoid following any URL in returned context automatically. The OWASP guidance on unsafe API consumption specifically calls for TLS, timeouts, response validation, and controlled redirects when integrating third-party APIs.

If you want to inspect the request without writing code, use the API playground. It helps separate credential or parameter problems from bugs in your client.

Build the credential safely

Create the key pair in Account Settings. Authentication for this endpoint uses a Base64 representation of apiKey:apiSecret in the X-API-KEY header. Base64 is an encoding, not encryption, so the encoded value is a secret too.

Store the key and secret in a secret manager or protected environment variables. Construct the header in memory at startup, never commit it, never place it in a URL, and never print it during debugging. Give development, staging, and production separate credentials so one leak does not cross environments.

For a controlled shell test:

credential="$(printf '%s' "$ISMALICIOUS_API_KEY:$ISMALICIOUS_API_SECRET" | base64)"

curl --fail-with-body --silent --show-error \
  --get 'https://api.ismalicious.com/check' \
  --data-urlencode 'query=example.com' \
  --data-urlencode 'enrichment=standard' \
  --header "X-API-KEY: $credential"

Run this only in a shell where those variables are already provided securely. Clear command output before sharing a terminal capture. A 401 means the client should stop and surface an authentication problem, not retry the same credential repeatedly.

Make one controlled request in code

A first application call needs an explicit timeout and status handling. This Python example keeps policy out of the transport layer:

import base64
import os
import requests

pair = f"{os.environ['ISMALICIOUS_API_KEY']}:{os.environ['ISMALICIOUS_API_SECRET']}"
credential = base64.b64encode(pair.encode()).decode()

response = requests.get(
    "https://api.ismalicious.com/check",
    params={"query": "example.com", "enrichment": "standard"},
    headers={"X-API-KEY": credential, "Accept": "application/json"},
    timeout=(3, 15),
    allow_redirects=False,
)

if response.status_code == 401:
    raise RuntimeError("isMalicious credential rejected")
if response.status_code == 429:
    raise RuntimeError("isMalicious request rate limited")
response.raise_for_status()

payload = response.json()
if "malicious" not in payload or "apiVersion" not in payload:
    raise RuntimeError("Incomplete IOC response")

Do not assume every enrichment field is always present. Optional providers can fail independently, and different indicator types naturally return different context. Read fields such as riskScore, evidence, and dataTrust defensively. The broader IOC enrichment guide explains how to map that context to analyst decisions without dumping the full payload into every alert.

Treat failures as explicit outcomes

Define a small result model for your application: enriched, rejected, rate_limited, temporarily_unavailable, and invalid_response. Keep these states separate from malicious, suspicious, or safe. If the provider is unavailable, the indicator is unknown, not benign.

Retry only transient failures, normally network errors, 429, and selected 5xx responses. Use exponential backoff with jitter, a strict attempt limit, and the Retry-After header when it is present. Do not retry an authentication failure or malformed local input. Put a circuit breaker around sustained failure so a busy enrichment dependency cannot stall the entire alert queue.

Cache repeated lookups for a bounded period, keyed by normalized indicator and enrichment level. The cache should reduce duplicate work, not conceal staleness. Preserve the enrichment timestamp and require a fresh call for decisions whose risk warrants it. For larger planned sets, use the dedicated bulk-check feature instead of launching an uncontrolled fan-out of single requests.

Log evidence without leaking secrets

Create your own correlation ID before the call and carry it into the ticket or job record. Log the endpoint name, indicator type, status class, elapsed time, attempt number, API version, and whether required response fields passed validation. Record the normalized indicator only when your data policy permits it; hashes, domains, and URLs can still be sensitive investigation data.

Never log the API key, secret, encoded credential, complete request headers, or an unrestricted response body. Store a curated decision record instead: verdict, score when present, freshness, recommended action, provider timestamp, and a hash of the raw payload if you need integrity evidence. This gives responders a useful audit trail while limiting data spread.

Useful operational metrics include success rate, timeout rate, authentication failures, rate-limited calls, latency percentiles, invalid responses, cache hits, and decisions routed to manual review. These measurements reveal integration health. They do not claim that every malicious verdict prevented an incident.

Move from a test to a production workflow

Place the client behind a narrow internal function such as enrich_indicator(target). Normalize inputs before that boundary, validate the response inside it, and apply business policy after it. This separation lets a SIEM integration attach context to alerts while a fraud service or firewall workflow uses a different threshold.

Roll out in three stages:

1. Replay a labeled set of benign, suspicious, malformed, and unavailable cases.
2. Run in shadow mode, where results are logged and attached but cannot change enforcement.
3. Enable one reversible action, such as raising ticket priority, before any automatic blocking.

Compare the shadow decision with analyst outcomes and document overrides. The SIEM enrichment playbook provides a practical downstream pattern, while the API comparison guide helps decide where a second source or specialist sandbox is still needed.

Validate, then extend the integration

Your release gate should exercise a valid credential, a rejected credential, a timeout, a transient server failure, a rate-limited response, malformed JSON, and a successful but incomplete body. Confirm that every path produces a bounded retry decision and a redacted log entry. Test key rotation without restarting unrelated services.

Add a small contract test to continuous integration, but keep it out of untrusted fork builds where secrets can be exposed. The test should call one non-sensitive indicator, assert only the stable fields your adapter needs, and fail clearly when the schema changes. Do not snapshot the complete payload: enrichment context can evolve without breaking your contract. Run a separate synthetic check from production monitoring so you can detect credential expiry, DNS failure, TLS failure, or an unexpected response shape before the first analyst request of the day.

Once the first lookup is stable, connect it to a neighboring workflow through the integrations catalog. Keep the same adapter and evidence model as you add bulk triage, SIEM enrichment, or feed ingestion. The first reliable call is valuable because it establishes a reusable contract: explicit input, protected authentication, validated output, observable failure, and reversible action.