IP 360 API

API v1 Introduction

Welcome to the Ensign API documentation.

The Ensign API allows you to access STIX 2.0 resources in a simple, programmatic way while using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information.

All of the data visualization and information that you are familiar with in the Ensign IP360 portal is also available through the API endpoints, allowing you to retrieve complex data that your situation requires.

The API documentation will start with a general overview about the design and capabilities that has been implemented, followed by information about the various specific endpoints.

API Libraries

Official libraries for the Ensign Infosecurity API are available in english language only.

Base URL

https://ip-360-api.ensigninfosecurity.com

cedric_loy@ensigninfosecurity.com

Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI.

Requests must be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

HTTP methods

Method	Usage
GET	For simple retrieval of information on the various endpoints, you should use the GET method. The information you request will be returned to you as a JSON object. The attributes defined by the JSON object can be used to form additional requests. Any request using the GET method is read-only and will not affect any of the objects you are querying.
DELETE	To destroy a resource and remove it from your account and environment, the DELETE method should be used. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found. This idempotency means that you do not have to check for a resource's availability prior to issuing a delete command, the final state will be the same regardless of its existence.
PUT	To update the information about a resource in your account, the PUT method is available. Like the DELETE Method, the PUT method is idempotent. It sets the state of the target using the provided values, regardless of their current values. Requests using the PUT method do not need to check the current attributes of the object.
POST	To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.

HTTP status codes

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently

HTTP statue code summary

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on Ensign IP360 API end. (These are rare.)

Authentication

In order to interact with the Ensign API, your application must authenticate with our server.

The Ensign API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account in full or in read-only mode. Do note that the OAuth token is valid for 24 hours only and you will need to retrieve it again after every expiration.

In order to retrieve a valid OAuth token, you need to authenticate with our server via your ACCOUNT EMAIL and API KEY from visiting the API section of the Ensign IP360 portal for your account.

Because of this, it is absolutely essential that you keep your OAuth Token secure as it functions as a complete authentication request.

How to authenticate with OAuth

For every endpoint request, you need to include the OAuth Token in your Bearer Authorization Header within every request. This is the only method of authenticating because it completes the authorization request in the header portion, away from the actual request.

Authentication examples

Retrieve OAuth Token via API key using POST

curl -X POST 'http://ip-360-api.ensigninfosecurity.com/api/v1/auth/login' --form 'email="$ACCOUNT_EMAIL"' --form 'api_key="$API_KEY"'

OAuth output

{
  "message": "Authentication successful!",
  "authorization_token": "aaaabbbbccccddddeeee"
}

Authenticate with a Bearer Authorization Header

curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" "https://ip-360-api.ensigninfosecurity.com/api/v1/communication_activities?$params"

Parameters

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &.

Tools like curl can create the appropriate URI when given parameters and values; this can also be done using the -F flag and then passing the key and value as an argument. The argument should take the form of a quoted string with the attribute being set to a value with an equal sign.

Common Query String Parameters

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input	Yes
statistic_month_duration	Retrieve complied data of 1/3/6 months from the start of the statistic_date	No
is_malicious	Retrieve by malicious type	No
statistic_date	Retrieve data based on statistic_date Default: (Today's Date - 1.month_duration).beginning_of_month Format: YYYY-MM-DD	No
page	Retrieve by page no. Must use in conjunction with per_page	No
per_page	Retrieve with the number of items you would like per page.	No

Examples & Outputs

Sample Meta Object

{
  "meta": {
    "total_pages": 17,
    "current_page_count": 10,
    "total_count": 170,
    "prev_page": 2,
    "next_page": 3
  }
}

Links & Pagination

The links object is returned as part of the response body when pagination is required. By default, 50 objects are returned per page. If the response contains 50 objects or fewer, no prev or next links object will be returned. If the response contains more than 50 objects, the first 50 will be returned along with the links object.

You can request a different pagination limit or force pagination by appending ?per_page= to the request with the number of items you would like per page. For instance, to show only two results per page, you could add ?per_page=2 to the end of your query. The maximum number of results per page is 50.

The links object contains a pages object. The pages object, in turn, contains keys indicating the relationship of additional pages. The values of these are the URLs of the associated pages. The keys will be one of the following:

self: The URI of the current page of results.
prev: The URI of the previous sequential page of results.
next: The URI of the next sequential page of results.
The pages object will only include the links that make sense. So for the first page of results, no first or prev links will ever be set. This convention holds true in other situations where a link would not make sense.

Examples & Outputs

Sample Links Object

{
  "links": {
    "self": "ip-360-api.ensigninfosecurity.com/api/v1/intel/communication_activities?per_page=10&page=2",
    "next": "ip-360-api.ensigninfosecurity.com/api/v1/intel/communication_activities?per_page=10&page=3",
    "prev": "ip-360-api.ensigninfosecurity.com/api/v1/intel/communication_activities?per_page=10&page=1"
  }
}

Rate Limit

The number of requests that can be made through the API is currently limited to 60 per minute per ip address.

The rate limiting information is contained within the response headers of each request. The relevant headers are:

RateLimit-Limit: The number of requests that can be made per minute.
RateLimit-Remaining: The number of requests that remain before you hit your request limit. See the information below for how the request limits expire.
RateLimit-Reset: This represents the time when the oldest request will expire. The value is given in Unix epoch time. See below for more information about how request limits expire.

As long as the RateLimit-Remaining count is above zero, you will be able to make additional requests.

Each customer is only allow to make a no of api calls per min in order to ensure quality of the network. The requests for that min are all counted and deducted from your RateLimit-Remaining and that value will be restted at the end of the min.

If the RateLimit-Remaining reaches zero, subsequent requests will receive a 429 error code until the request reset has been reached. You can see the format of the response in the examples.

Examples & Outputs

Sample Normal Rate Limit Headers

. . .
RateLimit-Limit: 60
RateLimit-Remaining: 39
RateLimit-Reset: 1301428752
. . .

Sample Rate Exceeded Response

{
  "title": "too_many_requests",
  "status": 429,
  "details": "API Rate limit exceeded."
}

Monthly Plan Limit

The number of distinct IP requests that each customer can be made per month is dependent on the plan that the customer is subscribe to.

The monthly limiting information is contained within the response headers of each request. The relevant headers are:

MonthlyRate-Limit: The number of distinct IP requests that can be made per month.
MonthlyRate-Remaining: The number of distinct IP requests that remain before you hit your request limit.
MonthlyRate-Reset: This represents the date when the MonthlyRate-Remaining will reset to the original count. The value is given in ISO 8601 yyyy-mm-dd format.

As long as the MonthlyRate-Remaining count is above zero, you will be able to make additional requests.

Every month, each customer is given a fixed no of api calls which they are allowed to make based on their plan. Every api calls will be totaled and deducted from their MonthlyRate-Remaining and that limit will be resetted at the end of the month.

If the MonthlyLimit-Remaining reaches zero, subsequent requests will receive a 429 error code until the request reset has been reached. You can see the format of the response in the examples.

Examples & Outputs

Sample Normal Monthly Limit Headers

. . .
MonthlyLimit-Limit: 50000
MonthlyLimit-Remaining: 31872
MonthlyLimit-Reset: 2019-07-17
. . .

Sample Monthly Exceeded Response

{
  "title": "too_many_requests",
  "status": 429,
  "details": "Monthly Usage limit exceeded.",
  "monthlyRate_limit": 50000,
  "monthlyRate_reset": "2019-07-17"
}

Communication Activities

Provide Daily stats computed for each IP addresses

statistic_type: 0

Provides the total daily number of distinct IP communicated

statistic_type: 1

Provides the total daily number of communication made/total number of events

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/communication_activities?per_page=1&page=1&ip_address=123.123.123.123&is_malicious=true&statistic_date=2018-12-01' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "3041197502",
      "type": "communication_activity",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-12-31",
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count": 2
          },
          {
            "statistic_type": 1,
            "statistic_count": 24
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 30,
    "total_count": 1,
    "prev_page": "",
    "next_page": 2
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/communication_activities?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-12-01&is_malicious=true",
    "next": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/communication_activities&format=json&ip_address=123.123.123.123&is_malicious=true&page=2&per_page=1&statistic_date=2018-12-01",
    "prev": ""
  }
}

Sectoral Summaries

Provides monthly stats for sectoral summaries.

Stats are computed & roll up into 1/3/6 months
statistic_type: 0

Provides the total number of distinct IP communicated in each sectors for the past 1/3/6 months
Provides distribution (percentage) of distinct IP communicated across the diff sectors for the past 1/3/6 months

statistic_type: 1

Provides the total number of communications made/total number of events in each sectors for the past 1/3/6 months
Provides distribution (percentage) of the number of communications made/total number of events across the diff sectors for the past 1/3/6 months

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/sectoral_summaries?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "12",
      "type": "sectoral_summary",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-11-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count_details": [
              {
                "sector_name": "INFOCOMM",
                "statistic_count": 9,
                "statistic_pct": 100.0
              }
            ]
          },
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "sector_name": "INFOCOMM",
                "statistic_count": 179,
                "statistic_pct": 100.0
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 2,
    "current_page_count": 1,
    "total_count": 2,
    "prev_page": "",
    "next_page": 2
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/sectoral_summaries?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1",
    "next": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/sectoral_summaries&format=json&ip_address=123.123.123.123&is_malicious=true&month_duration=1&page=2&per_page=1&statistic_date=2018-01-01",
    "prev": ""
  }
}

Top Threat Types

Provides monthly stats for sectoral summaries. Top Threat Types will always have a true malicious flag.

Stats are computed & roll up into 1/3/6 months
Computation are performed based on Alerts Data.
IPs in this table comprises ONLY those from Alerts, and not general Network Traffic. This imply that the IP is either a malicious IP or a Victim/Target.
An IP in this table WILL NOT be one, that is not involved in a cyber killchain.
is_malicious = TRUE AND statistic_type: 0

For each threat types (attack vector) used by the malicious IP, provide the total number of distinct communicants (Victim) IP for the past 1/3/6 months
For each threat types (attack vector) used by the malicious IP, provides the distribution (percentage) of distinct communicants (Victim) IP across the diff threat type of the malicious IP for the past 1/3/6 months

is_malicious = TRUE AND statistic_type: 1

For each threat types (attack vector) used by the malicious IP, provide the total number of total number of communications made/total number of events for the past 1/3/6 months
For each threat types (attack vector) used by the malicious IP, provides the distribution (percentage) of the number of communications made/total number of events across the diff threat type of the malicious IP for the past 1/3/6 months

is_malicious = FALSE AND statistic_type: 0

IP = Victim/Target
For each threat types (attack vector) that the IP is compromised/Infected, provide the total number of distinct communicants (Malicious) IP for the past 1/3/6 months
For each threat types (attack vector) that the IP is compromised/Infected, provides the distribution (percentage) of distinct communicants (Malicious) IP across the diff threat type of the victim IP for the past 1/3/6 months

is_malicious = FALSE AND statistic_type: 1

IP = Victim/Target
For each threat types (attack vector) that the IP is compromised/Infected, provide the total number of total number of communications made/total number of events with malicious IPs for the past 1/3/6 months
For each threat types (attack vector) that the IP is compromised/Infected, provides the distribution (percentage) of the number of communications made/total number of events with malicious across the diff threat type of the malicious IP for the past 1/3/6 months

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_threat_types?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=false&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "7",
      "type": "top_threat_type",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-11-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count_details": [
              {
                "threat_rank": 1,
                "threat_type_name": "PORTSCAN_HSCAN",
                "statistic_count": 1,
                "statistic_pct": 100.0
              }
            ]
          },
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "threat_rank": 1,
                "threat_type_name": "PORTSCAN_HSCAN",
                "statistic_count": 1,
                "statistic_pct": 100.0
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_count": 1,
    "prev_page": "",
    "next_page": ""
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_threat_types?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1",
    "next": "",
    "prev": ""
  }
}

Top Communicant IPs (DEPRECATED)

Provides monthly stats for top communicant ips. The communicant ips could be source or destination actor.

Stats are computed & roll up into 1/3/6 months
statistic_type: 0

Provide the top X distinct IP communicated for the past 1/3/6 months

statistic_type: 1

Provide the top X communicants by the total number of communications made/total number of events for the past 1/3/6 months

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_communicant_ips?per_page=10&page=1&ip_address=123.123.123.123&is_malicious=true&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "123456",
      "type": "top_communicant_ip",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-11-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "ip_rank": 1,
                "communicant_ip": "222.222.222.222",
                "statistic_count": 2,
                "statistic_pct": 100.0
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_count": 1,
    "prev_page": "",
    "next_page": ""
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_communicant_ips?per_page=10&page=1&ip_address=123.123.123.123&is_malicious=true&month_duration=1",
    "next": "",
    "prev": ""
  }
}

Top Targeted Ports

Provides monthly stats for top targeted ports.

Stats are computed & roll up into 1/3/6 months
Stats computed are based on its communicants (Destination Port of the netflow). e.g: Ports used by its communicants
statistic_type: 0

For each Ports used by its communicants, provide the total number of distinct communicants IP using the Port for the past 1/3/6 months
For each Ports used by its communicants, provides the distribution (percentage) of distinct communicants IP across the diff Ports for the past 1/3/6 months
Ports used by its communicants are ranked and sorted in asc rank

statistic_type: 1

For each Ports used by its communicants, provide the total number of communications made/total number of events WITH these communicants for the past 1/3/6 months
For each Ports used by its communicants, provides distribution (percentage) of the number of communications made/total number of events WITH the communicants across the diff Ports for the past 1/3/6 months
Ports used by its communicants are ranked and sorted in asc rank

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_targeted_ports?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "11",
      "type": "top_targeted_port",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-11-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count_details": [
              {
                "port_rank": 1,
                "port": 443,
                "statistic_count": 2,
                "statistic_pct": 66.67
              },
              {
                "port_rank": 2,
                "port": 20443,
                "statistic_count": 1,
                "statistic_pct": 33.33
              }
            ]
          },
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "port_rank": 1,
                "port": 443,
                "statistic_count": 139,
                "statistic_pct": 95.21
              },
              {
                "port_rank": 2,
                "port": 20443,
                "statistic_count": 7,
                "statistic_pct": 4.79
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 2,
    "total_count": 1,
    "prev_page": "",
    "next_page": 2
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_targeted_ports?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1",
    "next": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_targeted_ports&format=json&ip_address=123.123.123.123&is_malicious=true&month_duration=1&page=2&per_page=1&statistic_date=2018-01-01",
    "prev": ""
  }
}

Top Operating Systems

Provides monthly stats for top operating systems.

Stats are computed & roll up into 1/3/6 months
Stats computed are based on its communicants. e.g: OS used by its communicants
statistic_type: 0

For each OS type used by its communicants, provide the total number of distinct communicants IP using the OS for the past 1/3/6 months
For each OS type used by its communicants, provides the distribution (percentage) of distinct communicants IP across the diff OS type for the past 1/3/6 months
OS type used by its communicants are ranked and sorted in asc rank

statistic_type: 1

For each OS type used by its communicants, provide the total number of communications made/total number of events WITH these communicants for the past 1/3/6 months
For each OS type used by its communicants, provides distribution (percentage) of the number of communications made/total number of events WITH the communicants across the diff OS for the past 1/3/6 months
OS type used by its communicants are ranked and sorted in asc rank

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_operating_systems?per_page=1&page=1&ip_address=123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "111222333",
      "type": "top_operating_system",
      "attributes": {
        "ip_address": "123.123.123",
        "statistic_date": "2018-11-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count_details": [
              {
                "os_rank": 1,
                "os_name": "ANDROID",
                "statistic_count": 1,
                "statistic_pct": 20.0
              },
              {
                "os_rank": 2,
                "os_name": "IPAD",
                "statistic_count": 1,
                "statistic_pct": 20.0
              },
              {
                "os_rank": 3,
                "os_name": "IPHONE",
                "statistic_count": 1,
                "statistic_pct": 20.0
              }
            ]
          },
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "os_rank": 1,
                "os_name": "ANDROID",
                "statistic_count": 2,
                "statistic_pct": 20.0
              },
              {
                "os_rank": 2,
                "os_name": "IPAD",
                "statistic_count": 2,
                "statistic_pct": 20.0
              },
              {
                "os_rank": 3,
                "os_name": "IPHONE",
                "statistic_count": 2,
                "statistic_pct": 20.0
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_count": 1,
    "prev_page": "",
    "next_page": ""
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_operating_systems?per_page=1&page=1&ip_address=123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1",
    "next": "",
    "prev": ""
  }
}

Top Web Browsers

Provides monthly stats for top web browsers.

Stats are computed & roll up into 1/3/6 months
Stats computed are based on its communicants. e.g: Browser used by its communicants????
statistic_type: 0

For each browser type used by its communicants, provide the total number of distinct communicants IP using the browser for the past 1/3/6 months
For each browser type used by its communicants, provides the distribution (percentage) of distinct communicants IP across the diff browser type for the past 1/3/6 months
Browser type used by its communicants are ranked and sorted in asc rank

statistic_type: 1

For each browser type used by its communicants, provide the total number of communications made/total number of events WITH these communicants for the past 1/3/6 months
For each browser type used by its communicants, provides distribution (percentage) of the number of communications made/total number of events WITH the communicants across the diff browser for the past 1/3/6 months
Browser type used by its communicants are ranked and sorted in asc rank

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_web_browsers?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "829912",
      "type": "top_web_browser",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-11-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count_details": [
              {
                "web_browser_rank": 1,
                "web_browser_name": "CHROME",
                "statistic_count": 2,
                "statistic_pct": 16.67
              },
              {
                "web_browser_rank": 2,
                "web_browser_name": "CHROMEMOBILE",
                "statistic_count": 2,
                "statistic_pct": 16.67
              },
              {
                "web_browser_rank": 3,
                "web_browser_name": "FIREFOX",
                "statistic_count": 2,
                "statistic_pct": 16.67
              }
            ]
          },
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "web_browser_rank": 1,
                "web_browser_name": "CHROME",
                "statistic_count": 2,
                "statistic_pct": 16.67
              },
              {
                "web_browser_rank": 2,
                "web_browser_name": "CHROMEMOBILE",
                "statistic_count": 2,
                "statistic_pct": 16.67
              },
              {
                "web_browser_rank": 3,
                "web_browser_name": "FIREFOX",
                "statistic_count": 2,
                "statistic_pct": 16.67
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 2,
    "total_count": 1,
    "prev_page": "",
    "next_page": 2
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_web_browsers?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true&month_duration=1",
    "next": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_web_browsers&format=json&ip_address=123.123.123.123&is_malicious=true&month_duration=1&page=2&per_page=1&statistic_date=2018-01-01",
    "prev": ""
  }
}

Sectoral Communication Activities

Provides monthly stats for sectoral communication activities.

Daily stats computed for each IP addresses & Threat Types
statistic_type: 0

Provides the total daily number of distinct IP communicated in each sectors

statistic_type: 1

Provides the total daily number of communication made/total number of events in each sectors

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/sectoral_communication_activities?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
is_malicious	Indication whether the asset is malicious	Boolean
statistic_details	statistic_type: { 1: provides the distribution (percentage) of distinct communicants }	JSON

Sample Response

{
  "data": [
    {
      "id": "123123123",
      "type": "sectoral_communication_activity",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2018-06-30",
        "is_malicious": true,
        "statistic_details": [
          {
            "statistic_type": 0,
            "statistic_count_details": [
              {
                "sector_name": "INFOCOMM",
                "statistic_count": 3
              }
            ]
          },
          {
            "statistic_type": 1,
            "statistic_count_details": [
              {
                "sector_name": "INFOCOMM",
                "statistic_count": 40
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "total_pages": 212,
    "total_count": 1,
    "prev_page": "",
    "next_page": 2
  },
  "links": {
    "self": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/sectoral_communication_activities?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=true",
    "next": "https://ip-360-api.ensigninfosecurity.com/api/v1/intel/sectoral_communication_activities&format=json&ip_address=123.123.123.123&is_malicious=true&page=2&per_page=1&statistic_date=2018-01-01",
    "prev": ""
  }
}

Associated Domains

Retrieve Domain information by IP Address. Domain information might change every month for the same ip address.

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
is_malicious	Retrieve by malicious type `true or false`	No
statistic_date	Retrieve data based on statistic_date `YYYY-MM-DD`	No
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1`	Yes
page	Retrieve by page no. Must use in conjunction with per_page `1`	No
per_page	Retrieve with the number of items you would like per page. `10`	No

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/intel/top_threat_types?per_page=1&page=1&ip_address=123.123.123.123&statistic_date=2018-01-01&is_malicious=false&month_duration=1' -H 'Authorization: Bearer $OAUTH_TOKEN'

Output Field Info

Param	Description	Type
id	Unique Identifier of the record	Bigint
type	Record type	String
Attributes
ip_address	IP Address of interest	String
statistic_date	Crawled date	DateString
statistic_month_duration	Complied data of 1/3/6 months since the statistic_date	Integer
is_malicious	Indication whether the asset is malicious	Boolean
domain	Name of the domain	String
domain_last_seen	Date that the domain was last seen for this ip address	String

Sample Response

{
  "data": [
    {
      "id": "2",
      "type": "associated_domain",
      "attributes": {
        "ip_address": "123.123.123.123",
        "statistic_date": "2019-04-01",
        "statistic_month_duration": 1,
        "is_malicious": true,
        "domain": "https://www.malicious-domain.com",
        "domain_last_seen": "2018-02-12T08:34:19.009Z"
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "current_page_count": 1,
    "total_count": 1,
    "prev_page": "",
    "next_page": ""
  },
  "links": {
    "self": "http://ip-360-api.ensigninfosecurity.com/api/v1/intel/associated_domains?ip_address=123.123.123.123&statistic_month_duration=1",
    "next": "",
    "prev": ""
  }
}

STIX 2.0 Introduction

Structured Threat Information Expression (STIX™) is a language and serialization format used to exchange cyber threat intelligence (CTI).

STIX enables organizations to share CTI with one another in a consistent and machine readable manner, allowing security communities to better understand what computer-based attacks they are most likely to see and to anticipate and/or respond to those attacks faster and more effectively.

STIX is designed to improve many different capabilities, such as collaborative threat analysis, automated threat exchange, automated detection and response, and more.

STIX Domain Objects (SDOs)

STIX Objects categorize each piece of information with specific attributes to be populated. Chaining multiple objects together through relationships allow for easy or complex representations of CTI.

Below is a list of objects that is currently available through our platform. For more details and visual representations of additional STIX objects can be found here.

Name	Description
Marking Definition	The marking-definition object represents a specific marking. Data markings typically represent handling or sharing requirements for data, and are applied in the object_marking_refs and granular_markings properties on STIX Objects, which reference a list of IDs for marking-definition objects. Two marking definition types are defined in this specification: TLP, to capture TLP markings, and Statement, to capture text marking statements. In addition, it is expected that the FIRST Information Exchange Policy (IEP) will be included in a future version once a machine-usable specification for it has been defined.
Identity	Identities can represent actual individuals, organizations, or groups (e.g., Ensign Infosecurity Pte Ltd) as well as classes of individuals, organizations, or groups (e.g., the finance sector). The Identity SDO can capture basic identifying information, contact information, and the sectors that the Identity belongs to. Identity is used in STIX to represent, among other things, targets of attacks, information sources, object creators, and threat actor identities.
Observed Data	Observed Data conveys information that was observed on systems and networks using the Cyber Observable specification. For example, Observed Data can capture the observation of an IP address, a network connection, a file, or a registry key. Observed Data is not an intelligence assertion, it is simply information: this file was seen, without any context for what it means.
Indicator	Indicators contain a pattern that can be used to detect suspicious or malicious cyber activity. For example, an Indicator may be used to represent a set of malicious domains and use the STIX Patterning Language (STIX™ Version 2.0. Part 5: STIX Patterning) to specify these domains.

IP Bundles

The endpoints stated here allows you to retrieve ONLY malicious network information related to an IP address. Ip address in the src_ref json block refers the ip_address being queried, it means that the src_ref ip address could either be a source or destination.

This data service will only return past 1,3,6 month of data. We would advise to consume the endpoint every month if there is intention to keep the historical data over a period of time.

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes
statistic_month_duration	Retrieve complied data of 1/3/6 months since the statistic_date `1, 2 or 6`	Yes

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/threat_intel/stix/ip_bundles/search?ip_address=$ip_address&statistic_month_duration=$statistic_month_duration' -H 'Authorization: Bearer $OAUTH_TOKEN'

Sample Response

{
  "id": "bundle--0effdcbb-42d3-4e36-a9c3-5245d18e34b8",
  "objects": [
    {
      "type": "marking-definition",
      "id": "marking-definition--71abadfb-ddff-4dcd-8fb6-08a8c7eb9e6d",
      "created": "2019-02-26T03:30:37.796Z",
      "modified": "2019-02-26T03:30:37.796Z",
      "definition_type": "statement",
      "definition": {
        "statement": "Copyright 2019, Ensign InfoSecurity"
      }
    },
    {
      "type": "marking-definition",
      "id": "marking-definition--980086a4-d068-4387-a0de-2261491a8a8b",
      "created": "2019-02-26T03:31:15.343Z",
      "modified": "2019-04-11T09:17:42.579Z",
      "definition_type": "tlp",
      "definition": {
        "tlp": "white"
      }
    },
    {
      "type": "identity",
      "id": "identity--81531763-6564-470c-b100-c9e64fb746ac",
      "created": "2019-02-25T08:44:27.800Z",
      "modified": "2019-02-27T02:17:31.189Z",
      "name": "Ensign Infosecurity Pte Ltd",
      "identity_class": "organization",
      "description": "Ensign Infosecurity Pte Ltd"
    },
    {
      "type": "observed-data",
      "id": "observed-data--1006804a-65aa-4d09-ab06-922bb7732ff5",
      "created_by_ref": "identity--81531763-6564-470c-b100-c9e64fb746ac",
      "object_marking_refs": [
        "marking-definition--71abadfb-ddff-4dcd-8fb6-08a8c7eb9e6d",
        "marking-definition--980086a4-d068-4387-a0de-2261491a8a8b"
      ],
      "created": "2019-04-12T08:37:07.121Z",
      "modified": "2019-04-12T08:37:07.121Z",
      "first_observed": "2019-03-01T00:00:00.000Z",
      "last_observed": "2019-03-31T00:00:00.000Z",
      "number_observed": 47,
      "objects": {
        "0": {
          "type": "ipv4-addr",
          "value": "123.123.123.123"
        },
        "1": {
          "type": "ipv4-addr",
          "value": "103.14.185.12"
        },
        "2": {
          "type": "network-traffic",
          "src_ref": "0",
          "dst_ref": "1",
          "protocols": [
            "ipv4"
          ]
        },
        "3": {
          "type": "domain-name",
          "value": "https://www.yahoo.com",
          "resolves_to_refs": [
            "0"
          ]
        }
      }
    },
    {
      "type": "indicator",
      "id": "indicator--80396c57-4a26-42ee-b826-6a155d7a4149",
      "created": "2019-04-12T08:37:07.173Z",
      "created_by_ref": "identity--81531763-6564-470c-b100-c9e64fb746ac",
      "modified": "2019-04-12T08:37:07.173Z",
      "name": "H. PORTSCAN",
      "description": "iType: PORTSCAN_HSCAN;",
      "labels": [
        "malicious-activity",
        "target-sector-MANUFACTURING"
      ],
      "object_marking_refs": [
        "marking-definition--71abadfb-ddff-4dcd-8fb6-08a8c7eb9e6d",
        "marking-definition--980086a4-d068-4387-a0de-2261491a8a8b"
      ],
      "pattern": "[ipv4-addr:value = '123.123.123.123']",
      "valid_from": "2019-03-01T00:00:00.000Z",
      "external_references": [
        "http://ensigninfosecurity.com/ip/11819331110"
      ]
    }
  ],
  "spec_version": "2.0",
  "type": "bundle"
}

Geo Endpoints

The endpoints stated here allows you to retrieve geolocation information pertaining a specific IP address.

In order to interact with Geo endpoints, you need to retrieve the OAuth Token and include it as the Bearer Token for every request.

IP Lookup

Retrieve country details by IP address.

GET Param Fields

Param	Description	Mandatory
ip_address	IP Address of interest. Retrieve insights based on this input `123.123.123.123`	Yes

Endpoint Examples & Outputs

Sample Request

curl -X GET 'https://ip-360-api.ensigninfosecurity.com/api/v1/geo/lookup?ip_address=$ip_address' -H 'Authorization: Bearer $OAUTH_TOKEN'

Sample Response

{
  "country_name": "Singapore",
  "iso_code": "SG",
  "latitude": 1.2931,
  "longitude": 103.8558
}