Follow

Reputation API

This API is served from the NormShield Cloud and it targets only allowed customers, therefore, not intended for NormShield On-Premise versions.

NormShield Cloud harvests hundreds of thousands of IPs/domains from reputation and blacklists sources daily. In order customers to query this data house for their public IP addresses, NormShield provides easy to use reputation API.

Note: In order to use the API, the source IP address must be first registered in the allowed IP addresses list that NormShield maintains. Please contact info@normshield.com for your requests.

There are two ways of querying the IP/Domain reputation database.

First query method is to use simple HTTP GET

https://api.normshield.com/reputation/query?ips=10.0.2.3,10.0.2.4

https://api.normshield.com/reputation/query?domains=google.com,test.com

The parameter named ips contains comma delimited one or more IP addresses. The parameter named domains contains comma delimited one or more domain names. Maximum total of 50 IP addresses and domain names can be queried in a single GET request. This query looks up for the last 7 days of Reputation IP/Domain database by default. If you want to query earlier entries, day parameter should be added including the number of recent days to query. The maximum day parameter value that can be used is 90. Here's another HTTP GET example to query the Reputation database for a 14 days window;

https://api.normshield.com/reputation/query?ips=10.0.2.3,10.0.2.4&day=14

The second query method is to use HTTP POST

Use POST method instead of GET in order to provide more secrecy and conforming bettern to URL length limits such as;

POST /reputation/query HTTP/1.1
Host: api.normshield.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

ips=10.0.2.3,10.0.2.4

The parameter named ips contains comma delimited one or more IP addresses. The parameter named domains contains comma delimited one or more domain names. Maximum total of 500 IP addresses and domain names can be queried in a single POST request. This query looks up for the last 7 days of Reputation IP/Domain database by default. If you want to query earlier entries, day parameter should be added including the number of recent days to query. The maximum day parameter value that can be used is 90. Here's another HTTP POST example to query the Reputation database for a 14 days window;

POST /reputation/query HTTP/1.1
Host: api.normshield.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

ips=10.0.2.3,10.0.2.4&day=14

The Response

The response is a JSON object, with general structure of;

 

{
  "Success": true,             // the overall query result
  "Elapsed": 23,             // milliseconds to process the query
  "Errors": [],                   // any string list of errors
  "Output": {
    "DailyLimit": 100,        // daily limit applied to your source IP address
    "RemainingLimit": 94,  // remaining daily limit (single GET or POST request)
    "ResultList": [                   // list of results of the IP addresses sent by using GET or POST requests
      {
        "QueryAsset": "10.0.2.3",     // the queried IP address
        "Found": true,        // true if found in the IP Reputation database
        "Reasons": [          // a list of objects denoting date, asset, reason (malware, phishing, proxy) and source url, usually this is a single object
          {"Date" : "yyyy-MM-dd", "Finding" : "...", "Reason" : "...", "Url":"..."}
        ]
      }
    ]
  }
 }

A JSON Response Example

{
  "Success": true,
  "Elapsed": 653,
  "Errors": [],
  "Output": {
    "DailyLimit": 100,
    "RemainingLimit": 94,
    "ResultList": [
      {
        "QueryAsset": "10.0.2.3",
        "Found": true,
        "Reasons": [
          {
            "Date": "2016-09-19",
            "Finding": "10.0.2.3",
            "Reason": "Malware",
            "Url": "https://raw.githubusercontent.com/gosas/sds-ipsets/master/aige_anonymous.netset"
          }
        ]
      },
      {
        "QueryAsset": "10.0.2.4",
        "Found": true,
        "Reasons": [
          {
            "Date": "2016-09-19",
            "Finding": "10.0.2.4",
            "Reason": "Proxy",
            "Url": "https://raw.githubusercontent.com/ehoal/sd-ipsets/master/prosxyrss_a0d.ipset"
          },
          {
            "Date": "2016-09-19",
            "Finding": "10.0.2.4",
            "Reason": "Malware",
            "Url": "https://raw.githubusercontent.com/ehaol/sdd-ipsets/master/fol_amssous.netset"
          }
        ]
      }
    ]
  }
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk