IP-API

This integration will enrich IP addresses from IP-API with data about the geolocation, as well as a determination of the IP address being associated with a mobile device, hosting or proxy. Revers DNS is also returned. This service is available for free (with a throttle) - or paid.

Data Enrichment & Threat Intelligence · IP-API

Details

IDIP-API
ProviderKloudend Inc
CategoryData Enrichment & Threat Intelligence
From Version6.0.0
Docker Imagedemisto/python3:3.12.8.3296088
Supported ModulesAgentix XSIAM

README

This integration will enrich IP addresses from IP-API with data about the geolocation, as well as a determination of the IP address being associated with a mobile device, hosting or proxy. Revers DNS is also returned.

This service is available for free (with a throttle) - or paid.

This integration was integrated and tested with IP-API

Configure IP-API in Cortex

Parameter Description Required
Use HTTPS to communicate with the API Use of HTTPS requires an API key False
API Key Only required to bypass rate limits and/or use HTTPS False
Fields to return See https://members.ip-api.com/docs/json for details True
Use system proxy settings   False
Trust any certificate (not secure)   False

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

ip


Return IP information

Base Command

ip

Input

Argument Name Description Required
ip List of IPs. Optional

Context Output

Path Type Description
IP-API.continentCode string continentCode
IP-API.zip string zip
IP-API.mobile boolean mobile
IP-API.reverse string reverse
IP-API.countryCode string countryCode
IP-API.org string org
IP-API.isp string isp
IP-API.currentTime string currentTime
IP-API.query string query
IP-API.city string city
IP-API.lon number lon
IP-API.proxy boolean proxy
IP-API.district string district
IP-API.countryCode3 string countryCode3
IP-API.currency string currency
IP-API.callingCode number callingCode
IP-API.as string as
IP-API.status string status
IP-API.offset string offset
IP-API.continent string continent
IP-API.region string region
IP-API.country string country
IP-API.timezone string timezone
IP-API.hosting boolean hosting
IP-API.asname string asname
IP-API.lat number lat
IP-API.regionName string regionName
DBotScore.Indicator The indicator that was tested. String
DBotScore.Score The actual score. Number
DBotScore.Type The type of indicator. String
DBotScore.Vendor The vendor used to calculate the score. String
DBotScore.Reliability Reliability of the source providing the intelligence data. String

Command Example

!ip ip=8.8.8.8

Human Readable Output

Configuration parameters

  • https — Use HTTPS to communicate with the API
  • apikey — API Key
  • fields — Fields to return (required)
  • proxy — Use system proxy settings
  • insecure — Trust any certificate (not secure)
  • integrationReliability — Source Reliability
  • feedExpirationPolicy
  • feedExpirationInterval

Commands (1)

  • ip

    Return IP information

import traceback
from typing import Any

import demistomock as demisto  # noqa: F401
import urllib3
from CommonServerPython import *  # noqa: F401

# Disable insecure warnings
urllib3.disable_warnings()


class Client(BaseClient):
    def get_ip_reputation(self, ip: str) -> dict[str, Any]:
        params = demisto.params()
        if params.get("https"):
            return self._http_request(
                method="GET", url_suffix=ip, params={"key": params.get("apikey"), "fields": params.get("fields")}
            )
        else:
            return self._http_request(method="GET", url_suffix=ip, params={"fields": params.get("fields")})


def test_module(client: Client) -> str:
    try:
        client.get_ip_reputation("8.8.8.8")
    except DemistoException as e:
        if "Forbidden" in str(e):
            return "Authorization Error: make sure API Key is either empty - or correctly set"
        else:
            raise e
    return "ok"


def ip_reputation_command(client: Client, args: dict[str, Any]) -> list[CommandResults]:
    # ip command: Returns IP details for a list of IPs

    ips = argToList(args.get("ip"))
    if len(ips) == 0:
        raise ValueError("IP(s) not specified")

    command_results: list[CommandResults] = []

    ip_data = []
    for ip in ips:
        # documentation of json api - https://ip-api.com/docs/api:json.
        result = client.get_ip_reputation(ip)

        dbot_score = Common.DBotScore(
            indicator=ip, indicator_type=DBotScoreType.IP, score=0, reliability=demisto.params().get("integrationReliability")
        )

        common_ip = Common.IP(
            ip=ip,
            dbot_score=dbot_score,
            geo_country=result.get("country"),
            region=result.get("regionName"),
            geo_longitude=result.get("lon"),
            geo_latitude=result.get("lat"),
            organization_name=result.get("org"),
        )

        command_res = CommandResults(indicator=common_ip)

        command_results.append(command_res)
        ip_data.append(result)

    readable_output = tableToMarkdown("IP-API", ip_data)

    command_results.append(
        CommandResults(readable_output=readable_output, outputs_prefix="IP-API", outputs_key_field="query", outputs=ip_data)
    )
    return command_results


def main() -> None:
    params = demisto.params()
    if params.get("https"):
        base_url = "https://pro.ip-api.com/json/"
    else:
        base_url = "http://ip-api.com/json/"

    verify_certificate = not params.get("insecure", False)
    proxy = params.get("proxy", False)
    demisto.debug(f"Command being called is {demisto.command()}")
    try:
        client = Client(base_url=base_url, verify=verify_certificate, proxy=proxy)

        if demisto.command() == "test-module":
            # This is the call made when pressing the integration Test button.
            result = test_module(client)
            return_results(result)

        elif demisto.command() == "ip":
            return_results(ip_reputation_command(client, demisto.args()))

    # Log exceptions and return errors
    except Exception as e:
        demisto.error(traceback.format_exc())  # print the traceback
        return_error(f"Failed to execute {demisto.command()} command.\nError:\n{e!s}")


if __name__ in ("__main__", "__builtin__", "builtins"):
    main()