FalconSentinel

Threat Intelligence API

The API offers a detailed security evaluation, highlighting potential risks and delivering threat intelligence. It's an essential tool for augmenting your current security setup with our expert insights. With functionality mirroring our Lookup service, it seamlessly integrates into your security platform.

Subscription plans

The API offers four subscription plans: Core, Professional, Ultimate, and Enterprise. The output fields vary between these plans, with more fields being added from Core to Ultimate.

Additionally, the subscription plans differ in the number of requests allowed per day and minute. For a complete feature comparison of the plans, please refer to the pricing page.

The API response object

The following API response model describes all output fields across all subscription plans. To find out which fields are available in specific subscription plans, please refer to the sections below relevant to each subscription.

Attributes

  • Name
    firstSeen
    Type
    nullable
    timestamp
    Description

    UNIX timestamp of the first detected threat activity from the IP address. This field has value only when the verdict field's value is Threat; otherwise, it is null.

  • Name
    lastSeen
    Type
    nullable
    timestamp
    Description

    UNIX timestamp of the last detected threat activity from the IP address. This field has value only when the verdict field's value is Threat; otherwise, it is null.

  • Name
    verdict
    Type
    string
    Description

    Classification of the IoC's associated threat type.

    Possible values:

    • Threat – Substantial evidence indicates that this IP should be regarded as a threat. Advised Action: Conduct a thorough investigation of the activities linked to this IP and consider implementing restrictions on its traffic.
    • Benign – This IP address poses no threat and is linked to a known service performing legitimate scans/crawls. Advised action: None needed. The benignInfrastructure object contains the name, description, and references to the relevant benign service.
    • Suspicious – Multiple signals have been detected that suggest this IP is suspicious, yet there is no definitive proof to categorize it as a threat. Advised Action: Manually inspect the activities associated with this IP to assess potential risks.
    • Unknown – We haven't received any signals indicating that this IP poses a threat. Advised Action: Manually analyze the existing intelligence to determine its classification.
  • Name
    threatScore
    Type
    integer
    Description

    Numerical score indicating the threat level of the IoC, ranging from 0 to 100. A score of 0 means the IP address poses no threat, while a score of 100 indicates high confidence in classifying it as a threat. This field has a positive value only when the verdict field's value is Threat or Suspicious; otherwise, it is 0.

  • Name
    threatTypes
    Type
    nullable
    string[]
    Description

    A list of threat types associated with the IoC. This field contains items only when the verdict field's value is Threat; otherwise, it is null.

    Possible values:

    • null – There are no threat types associated with this host.
    • Attack – Malicious activity detected from the host.
    • C2 – The host is a known botnet's "Command and Control" server.
    • Malware – The host is related to malicious software distribution.
    • Phishing – The host is involved in phishing activity.
    • Spam – The host is engaged in sending spam.
    • Suspicious – Host activity hasn't been confirmed as malicious, but it remains suspicious. For example, it could involve a host scraping websites or sending a large number of ICMP queries.
  • Name
    location
    Type
    object
    Description

    Geolocation of the IP address. Is omitted if data is unavailable.

    • Name
      location.country
      Type
      string
      Description

      Country name.

    • Name
      location.region
      Type
      string
      Description

      Region name.

    • Name
      location.city
      Type
      string
      Description

      City name.

  • Name
    publicVPN
    Type
    object
    Description

    Determines whether the IP address belongs to a public VPN and retrieves its name if applicable.

    • Name
      publicVPN.detected
      Type
      boolean
      Description

      Indicates whether the IP address belongs to a public VPN.

    • Name
      publicVPN.name
      Type
      string
      Description

      Name of the public VPN. Is omitted if data is unavailable.

  • Name
    torExitNode
    Type
    boolean
    Description

    Indicates whether the IP address is a TOR exit node.

  • Name
    ptr
    Type
    object
    Description

    Retrieves the PTR record for the IP address and the result of the reverse match check. Is omitted if data is unavailable.

    • Name
      ptr.value
      Type
      nullable
      string
      Description

      PTR record value. If the IP address does not have a PTR record, null.

    • Name
      ptr.reverseMatch
      Type
      boolean
      Description

      Indicates whether the A/AAAA record of the domain in the PTR record matches the original IP address.

  • Name
    knownIP
    Type
    object
    Description

    Information on IP addresses linked to known internet services that are not anticipated to perform infrastructure scans or crawls. Is omitted if data is unavailable.

    Examples: GitHub, GitLab, AWS CloudFront.

    • Name
      knownIP.name
      Type
      string
      Description

      The name of the service associated with the IP address.

    • Name
      knownIP.description
      Type
      string
      Description

      Description of the service, if applicable.

    • Name
      knownIP.references
      Type
      string[]
      Description

      A list of links to resources that support the relationship between the IP address and the service, or provide additional context.

  • Name
    benignInfrastructure
    Type
    object[]
    Description

    Details about IP addresses associated with known internet services expected to conduct legitimate infrastructure scans or crawls. This field is available only when the verdict field's value is Benign. Is omitted if data is unavailable.

    Examples: Apple Bot, Facebook Bot, Google Bot.

    • Name
      benignInfrastructure.name
      Type
      string
      Description

      The name of the service associated with the IP address.

    • Name
      benignInfrastructure.description
      Type
      string
      Description

      Description of the service, if applicable.

    • Name
      benignInfrastructure.references
      Type
      string[]
      Description

      A list of links to resources that support the relationship between the IP address and the service, or provide additional context.

  • Name
    as
    Type
    object
    Description

    Autonomous System (AS) object. Is omitted if data is unavailable.

    • Name
      as.asn
      Type
      integer
      Description

      Autonomous System's number.

    • Name
      as.name
      Type
      string
      Description

      Autonomous System's name.

    • Name
      as.domain
      Type
      string
      Description

      Autonomous System's website URL.

  • Name
    netblock
    Type
    object
    Description

    WHOIS information for the IP Netblock associated with the IP address.

    • Name
      netblock.threatScore
      Type
      integer
      Description

      A numerical score representing the threat level of the Netblock, ranging from 0 to 100. A score of 0 indicates no threat, while a score of 100 indicates high confidence that all IPs within the Netblock are classified as threats.

    • Name
      netblock.source
      Type
      string
      Description

      Organization responsible for the management and allocation of the IP address range.

    • Name
      netblock.netname
      Type
      string
      Description

      Name of the IP range.

    • Name
      netblock.modified
      Type
      string
      Description

      Date and time of the last modification to the range, as provided by the registry. Format: '2012-02-24T09:44:34-05:00'.

    • Name
      netblock.inetnum
      Type
      string
      Description

      The range of IP addresses within the netblock. Example: '192.168.1.0 - 192.168.1.255'.

    • Name
      netblock.organization
      Type
      object
      Description

      Organization that registered the range. Is omitted if data is unavailable.

      • Name
        netblock.organization.id
        Type
        string
        Description

        ID of the organization.

      • Name
        netblock.organization.name
        Type
        string
        Description

        Name of the organization.

      • Name
        netblock.organization.email
        Type
        string
        Description

        Contact email of the organization.

      • Name
        netblock.organization.phone
        Type
        string
        Description

        Contact phone of the organization.

      • Name
        netblock.organization.address
        Type
        string[]
        Description

        Address of the organization.

    • Name
      netblock.adminContact
      Type
      object
      Description

      Administrative contact information. Is omitted if data is unavailable.

      • Name
        netblock.adminContact.id
        Type
        string
        Description

        ID of the contact.

      • Name
        netblock.adminContact.role
        Type
        string
        Description

        Role of the contact.

      • Name
        netblock.adminContact.email
        Type
        string
        Description

        Email of the contact.

      • Name
        netblock.adminContact.phone
        Type
        string
        Description

        Phone number of the contact.

      • Name
        netblock.adminContact.address
        Type
        string[]
        Description

        Address of the contact.

    • Name
      netblock.techContact
      Type
      object
      Description

      Technical contact information. This field follows the same structure as the adminContact object. Is omitted if data is unavailable.

    • Name
      netblock.abuseContact
      Type
      object
      Description

      Abuse contact information. This field follows the same structure as the adminContact object. Is omitted if data is unavailable.

The API response JSON object

{
    "firstSeen": 1678320000,
    "lastSeen": 1722902400,
    "verdict": "Threat",
    "threatScore": 75,
    "threatTypes": [
        "Malware",
        "Attack"
    ],
    "location": {
        "country": "United States of America",
        "region": "California",
        "city": "Pleasanton"
    },
    "publicVPN": {
        "detected": true,
        "name": "NordVPN"
    },
    "torExitNode": false,
    "ptr": {
        "value": "scan-51a.shadserver.org.",
        "reverseMatch": true
    },
    "knownIP": {
        "name": "Detectify",
        "description": "Detectify is a web security service that scans websites for vulnerabilities and security issues. It helps website owners identify and fix security weaknesses to protect their websites from cyber threats and attacks.",
        "references": [
            "https://support.detectify.com/support/solutions/articles/48001049001-how-do-i-allow-detectify-to-scan-my-assets-"
        ]
    },
    "benignInfrastructure": [
        {
            "name": "Reserved IP Address",
            "description": "Reserved IP addresses are set aside for special purposes and should not be used on the public internet. These addresses are not routable and are intended for use in private networks, documentation, and other specific scenarios",
            "references": [
                "https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml"
            ]
        }
    ],
    "as": {
        "asn": 6939,
        "name": "Hurricane Electric",
        "domain": "http://he.net"
    },
    "netblock": {
        "threatScore": 31,
        "source": "arin",
        "netname": "HURRICANE-4",
        "modified": "2012-02-24T09:44:34-05:00",
        "inetnum": "64.62.128.0 - 64.62.255.255",
        "organization": {
            "id": "HURC",
            "name": "Hurricane Electric LLC",
            "email": "",
            "phone": "",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "adminContact": {
            "id": "ZH17-ARIN",
            "role": "Hurricane Electric",
            "email": "hostmaster@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "techContact": {
            "id": "ZH17-ARIN",
            "role": "Hurricane Electric",
            "email": "hostmaster@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "abuseContact": {
            "id": "ABUSE1036-ARIN",
            "role": "Abuse Department",
            "email": "abuse@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        }
    }
}

Authentication

To authenticate with the API, include your personal API key in the request using the required apiKey query parameter. Once your subscription payment is confirmed, you will receive an email containing your API key.

"Core" API

Input parameters

  • Name
    apiKey
    Type
    string
    Required
    Required
    Description

    Your personal API key.

  • Name
    ip
    Type
    string
    Required
    Required
    Description

    IPv4 or IPv6 address to look up.

Request limits

The request rate limits vary by subscription plan. The "Core" API allows for a maximum of 1 requests per minute and 100 requests per day. If you exceed these limits, the API will return a 429 HTTP error code.

Output fields

The output fields vary between subscription plans. The "Core" API allows the following output fields:

  • firstSeen
  • lastSeen
  • verdict
  • threatScore
  • threatTypes

For field descriptions, please refer to the API response object section of the documentation.

Request

GET
https://api.falconsentinel.com/v2/core
curl --location 'https://api.falconsentinel.com/v2/core?apiKey=...&ip=101.132.168.206'

Sample response

{
    "firstSeen": 1678320000,
    "lastSeen": 1722902400,
    "verdict": "Threat",
    "threatScore": 75,
    "threatTypes": [
        "Malware",
        "Attack"
    ]
}

"Professional" API

Input parameters

  • Name
    apiKey
    Type
    string
    Required
    Required
    Description

    Your personal API key.

  • Name
    ip
    Type
    string
    Required
    Required
    Description

    IPv4 or IPv6 address to look up.

  • Name
    realTimeData
    Type
    integer
    Description

    Retrieve real-time data instead of potentially cached data. These requests take longer to process.

    Accepted values: 0 or 1

    Default value: 0

Request limits

The request rate limits vary by subscription plan. The "Professional" API allows for a maximum of 5 requests per minute and 500 requests per day. If you exceed these limits, the API will return a 429 HTTP error code.

Output fields

The output fields vary between subscription plans. The "Professional" API allows the following output fields:

  • firstSeen
  • lastSeen
  • verdict
  • threatScore
  • threatTypes
  • location
  • publicVPN
  • torExitNode
  • ptr
  • knownIP
  • benignInfrastructure

For field descriptions, please refer to the API response object section of the documentation.

Request

GET
https://api.falconsentinel.com/v2/pro
curl --location 'https://api.falconsentinel.com/v2/pro?apiKey=...&ip=101.132.168.206'

Sample response

{
    "firstSeen": 1678320000,
    "lastSeen": 1722902400,
    "verdict": "Threat",
    "threatScore": 75,
    "threatTypes": [
        "Malware",
        "Attack"
    ],
    "location": {
        "country": "United States of America",
        "region": "California",
        "city": "Pleasanton"
    },
    "publicVPN": {
        "detected": true,
        "name": "NordVPN"
    },
    "torExitNode": false,
    "ptr": {
        "value": "scan-51a.shadserver.org.",
        "reverseMatch": true
    },
    "knownIP": {
        "name": "Detectify",
        "description": "Detectify is a web security service that scans websites for vulnerabilities and security issues. It helps website owners identify and fix security weaknesses to protect their websites from cyber threats and attacks.",
        "references": [
            "https://support.detectify.com/support/solutions/articles/48001049001-how-do-i-allow-detectify-to-scan-my-assets-"
        ]
    },
    "benignInfrastructure": [
        {
            "name": "Reserved IP Address",
            "description": "Reserved IP addresses are set aside for special purposes and should not be used on the public internet. These addresses are not routable and are intended for use in private networks, documentation, and other specific scenarios",
            "references": [
            "https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml"
            ]
        }
    ],
}

"Ultimate" API

Input parameters

  • Name
    apiKey
    Type
    string
    Required
    Required
    Description

    Your personal API key.

  • Name
    ip
    Type
    string
    Required
    Required
    Description

    IPv4 or IPv6 address to look up.

  • Name
    realTimeData
    Type
    integer
    Description

    Retrieve real-time data instead of potentially cached data. These requests take longer to process.

    Accepted values: 0 or 1

    Default value: 0

Request limits

The request rate limits vary by subscription plan. The "Ultimate" API allows for a maximum of 60 requests per minute and 2,500 requests per day. If you exceed these limits, the API will return a 429 HTTP error code.

Output fields

The output fields vary between subscription plans. The "Ultimate" API allows the following output fields:

  • firstSeen
  • lastSeen
  • verdict
  • threatScore
  • threatTypes
  • location
  • publicVPN
  • torExitNode
  • ptr
  • knownIP
  • benignInfrastructure
  • as
  • netblock

For field descriptions, please refer to the API response object section of the documentation.

Request

GET
https://api.falconsentinel.com/v2/ultimate
curl --location 'https://api.falconsentinel.com/v2/ultimate?apiKey=...&ip=101.132.168.206'

Sample response

{
    "firstSeen": 1678320000,
    "lastSeen": 1722902400,
    "verdict": "Threat",
    "threatScore": 75,
    "threatTypes": [
        "Malware",
        "Attack"
    ],
    "location": {
        "country": "United States of America",
        "region": "California",
        "city": "Pleasanton"
    },
    "publicVPN": {
        "detected": true,
        "name": "NordVPN"
    },
    "torExitNode": false,
    "ptr": {
        "value": "scan-51a.shadserver.org.",
        "reverseMatch": true
    },
    "knownIP": {
        "name": "Detectify",
        "description": "Detectify is a web security service that scans websites for vulnerabilities and security issues. It helps website owners identify and fix security weaknesses to protect their websites from cyber threats and attacks.",
        "references": [
            "https://support.detectify.com/support/solutions/articles/48001049001-how-do-i-allow-detectify-to-scan-my-assets-"
        ]
    },
    "benignInfrastructure": [
        {
            "name": "Reserved IP Address",
            "description": "Reserved IP addresses are set aside for special purposes and should not be used on the public internet. These addresses are not routable and are intended for use in private networks, documentation, and other specific scenarios",
            "references": [
                "https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml"
            ]
        }
    ],
    "as": {
        "asn": 6939,
        "name": "Hurricane Electric",
        "domain": "http://he.net"
    },
    "netblock": {
        "threatScore": 31,
        "source": "arin",
        "netname": "HURRICANE-4",
        "modified": "2012-02-24T09:44:34-05:00",
        "inetnum": "64.62.128.0 - 64.62.255.255",
        "organization": {
            "id": "HURC",
            "name": "Hurricane Electric LLC",
            "email": "",
            "phone": "",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "adminContact": {
            "id": "ZH17-ARIN",
            "role": "Hurricane Electric",
            "email": "hostmaster@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "abuseContact": {
            "id": "ABUSE1036-ARIN",
            "role": "Abuse Department",
            "email": "abuse@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        }
    }
}

"Enterprise" API

Input parameters

  • Name
    apiKey
    Type
    string
    Required
    Required
    Description

    Your personal API key.

  • Name
    ip
    Type
    string
    Required
    Required
    Description

    IPv4 or IPv6 address to look up.

  • Name
    realTimeData
    Type
    integer
    Description

    Retrieve real-time data instead of potentially cached data. These requests take longer to process.

    Accepted values: 0 or 1

    Default value: 0

Request limits

Custom request limits are available for the Enterprise API. Please refer to the pricing page for more information.

Request

GET
https://api.falconsentinel.com/v2/enterprise
curl --location 'https://api.falconsentinel.com/v2/enterprise?apiKey=...&ip=101.132.168.206'

Sample response

{
    "firstSeen": 1678320000,
    "lastSeen": 1722902400,
    "verdict": "Threat",
    "threatScore": 75,
    "threatTypes": [
        "Malware",
        "Attack"
    ],
    "location": {
        "country": "United States of America",
        "region": "California",
        "city": "Pleasanton"
    },
    "publicVPN": {
        "detected": true,
        "name": "NordVPN"
    },
    "torExitNode": false,
    "ptr": {
        "value": "scan-51a.shadserver.org.",
        "reverseMatch": true
    },
    "knownIP": {
        "name": "Detectify",
        "description": "Detectify is a web security service that scans websites for vulnerabilities and security issues. It helps website owners identify and fix security weaknesses to protect their websites from cyber threats and attacks.",
        "references": [
            "https://support.detectify.com/support/solutions/articles/48001049001-how-do-i-allow-detectify-to-scan-my-assets-"
        ]
    },
    "benignInfrastructure": [
        {
            "name": "Reserved IP Address",
            "description": "Reserved IP addresses are set aside for special purposes and should not be used on the public internet. These addresses are not routable and are intended for use in private networks, documentation, and other specific scenarios",
            "references": [
                "https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml"
            ]
        }
    ],
    "as": {
        "asn": 6939,
        "name": "Hurricane Electric",
        "domain": "http://he.net"
    },
    "netblock": {
        "threatScore": 31,
        "source": "arin",
        "netname": "HURRICANE-4",
        "modified": "2012-02-24T09:44:34-05:00",
        "inetnum": "64.62.128.0 - 64.62.255.255",
        "organization": {
            "id": "HURC",
            "name": "Hurricane Electric LLC",
            "email": "",
            "phone": "",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "adminContact": {
            "id": "ZH17-ARIN",
            "role": "Hurricane Electric",
            "email": "hostmaster@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        },
        "abuseContact": {
            "id": "ABUSE1036-ARIN",
            "role": "Abuse Department",
            "email": "abuse@he.net",
            "phone": "+1-510-580-4100",
            "address": [
                "760 Mission Court",
                "Fremont",
                "CA",
                "94539",
                "United States"
            ]
        }
    }
}

Errors

You can determine if your request was successful by checking the status code in the API response. Since 99% of reported errors are user errors, please review your code thoroughly before reaching out to support. Now, let's explore the status codes and error types you might encounter.

Status codes

  • Name
    2xx
    Description

    Successful response.

  • Name
    400
    Description

    Invalid input parameters.

  • Name
    401
    Description

    Unauthorized. Verify your API key or check your subscription limits.

  • Name
    429
    Description

    Too many requests. Try your call again later.

  • Name
    5xx
    Description

    Server error. Please try your call again later or contact support."