Network

This documentation is currently outdated and in the process of being updated. This documentation is provided as a temporary reference to various API endpoints and output. This warning will be at the top of each outdated page. As the documentation is updated, this warning will be removed.

Using RiskSense networks, you can upload and aggregate asset data into a structure that match your own organization’s network (which are based either on IP address or by hostname). You can also mix and match networks, that is creating networks of different types, to accommodate the different type of networks that are might coexist within your organization and the partition scope of testing that individual scanners will perform.

Assets are uniquely identified by the network, so the platform requires you to choose the network before uploading the data. If you upload the same scan file to two different networks, the platform will treat them as separate assets, so it’s important that you arrange the network based on how you scan your network and produce the output scan file.

Creating a Network

Create a network for the designated client.

API Call: POST/client/{clientId}/network

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network

URL Parameters

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can create a network are:

  • Manager
  • Group Manager with Upload Permissions

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
NETWORKNAME Network name. string Y
NETWORKTYPE Network type. string Y Options: IP, HOSTNAME, MIXED.

cURL

cURL Sample create_network Snippet

Copy

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network" \
  -H  "accept: application/json" \
  -H  "x-api-key: <APIKEY>" \
  -H  "Content-Type: application/json" \
  -d "{  \"name\": \"<NETWORKNAME>\",  \"type\": \"<NETWORKTYPE>\"}"

Replace angle bracket parameters with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
NETWORKNAME Network name. string Y
NETWORKTYPE Network type. string Y Options: IP, HOSTNAME.

Response Parameters

Sample Response

Copy

{
  "id": <NETWORKID>,
  "clientId": <CLIENTID>,
  "name": "<NETWORKNAME>",
  "type": "<NETWORKTYPE>",
  "locked": <LOCKED>
}

Name Description Type Additional Information
NETWORKID Network ID number. integer
CLIENTID Client ID number. integer
NETWORKNAME Network name. string
NETWORKTYPE Network type. string
LOCKED Is the network locked? boolean True = Yes, False = No

HTTP Status Codes

Code Description
201 Success

201 Sample Response

Copy

{
  "id": 0,
  "clientId": 0,
  "name": "Sample Network",
  "type": "IP"
  "locked": False
}

Code Description
401 Unauthorized
404 Not Found

Updating a Network

Update a network within the designated client.

API Call: PUT/client/{clientId}/network/{networkId}

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/<NETWORKID>

URL Parameters

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID
NETWORKID Network ID number. Searching for a Network

User Roles

The user roles that can update a network are:

  • Manager
  • Group Manager with Upload Permissions

Python

Python Sample update_network Snippet

Copy

import requests

platform = 'http://platform<PLATFORM>.risksense.com'
client_id = "<CLIENTID>"
api_key = "<APIKEY>"

network_id = <NETWORKID>

name = "<NETWORKNAME>"
network_type = "<NETWORKTYPE>"  # Options are "IP" or "HOSTNAME"

url = platform + "/api/v1/client/" + str(client_id) + "/network/" + str(network_id)

header = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=header, data=json.dumps(body))

Replace angle bracket parameters with your own values.

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
NETWORKID Network ID number. integer Y
NETWORKNAME Network name. string Y
NETWORKTYPE Network type. string Y Options: IP, HOSTNAME.

cURL

cURL Sample update_network Snippet

Copy

curl -X PUT "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/<NETWORKID>" \
  -H  "accept: application/json" \
  -H  "x-api-key: <APIKEY>" \
  -H  "Content-Type: application/json" \
  -d "{  \"name\": \"<NETWORKNAME>\",  \"type\": \"<NETWORKTYPE>\"}"

Make sure to replace the angle bracket parameters here with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
NETWORKID Network ID number. integer Y
NETWORKNAME Network name. string Y
NETWORKTYPE Network type. string Y Options: IP, HOSTNAME.

Response Parameters

Sample Response

Copy

{
  "id": <NETWORKID>,
  "clientId": <CLIENTID>,
  "name": "<NETWORKNAME>",
  "type": "<NETWORKTYPE>",
  "locked": <LOCKED>
}

Name Description Type Additional Information
NETWORKID Network ID number. integer
CLIENTID Client ID number. integer
NETWORKNAME Network name. string
NETWORKTYPE Network type. string
LOCKED Is the network locked? boolean True = Yes, False = No

HTTP Status Codes

Code Description
200 Success

200 Sample Response

Copy

{
  "id": 0,
  "name": "string",
  "type": "IP"
}

Code Description
401 Unauthorized
404 Not Found

Deleting a Network

Delete a network within the designated client.

API Call: DELETE/client/{clientId}/network/{networkId}

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/<NETWORKID>

URL Parameters

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID
NETWORKID Network ID number. Searching for a Network

User Roles

The user role that can delete a network is:

  • Manager

Python

Python Sample delete_network Snippet

Copy

import requests

platform = 'http://platform<PLATFORM>.risksense.com'
client_id = "<CLIENTID>"
api_key = "<APIKEY>"

network_id = <NETWORKID>

url = platform + "/api/v1/client/" + str(client_id) + "/network/" + str(network_id)

header = {
    "x-api-key": api_key,
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=header)

Replace angle bracket parameters with your own values.

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
NETWORKID Network ID number. integer Y Searching for a Network

cURL

cURL Sample delete_network Snippet

Copy

curl -X DELETE "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/<NETWORKID>" \
  -H  "accept: application/json" \
  -H  "x-api-key: <APIKEY>"

Replace angle bracket parameters with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
NETWORKID Network ID number. integer Y Searching for a Network
APIKEY Your API key. string Y Generating an API Token

HTTP Status Codes

Code Description
204 Delete request was processed without errors
401 Unauthorized
404 Not Found

Listing Network Projections and Their Models

List network projections and their models that can be requested from the search endpoint.

API Call: GET/client/{clientId}/network/model

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/model

###URL Parameters###

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can list network projections and their models are:

  • Manager
  • Group Manager
  • User

Python

Python Sample network_projections Snippet

Copy

import requests

platform = 'https://platform<PLATFORM>.risksense.com'
api_key = '<APIKEY>'
client_id = <CLIENTID>

header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}

url = platform + "/api/v1/client/" + str(client_id) + "/network/model"

response = requests.get(url, headers=header)

Replace angle bracket parameters with your own values.

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
APIKEY Your API key. string Y Generating an API Token
CLIENTID Client ID number. integer Y Finding Your Client ID

cURL

cURL Sample network_projections Snippet

Copy

curl -X GET "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/model" \
  -H  "accept: application/json" \
  -H  "x-api-key: <APIKEY>"

Replace angle bracket parameters with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token

Response Parameters

Sample Response

Copy
{
  "subject": "network",
  "projections": [
    {
      "name": "basic",
      "fields": [
        {
          "field": "id",
          "type": "int",
          "nested": []
        },
        {
          "field": "clientId",
          "type": "int",
          "nested": []
        },
        {
          "field": "name",
          "type": "string",
          "nested": []
        },
        {
          "field": "type",
          "type": "string",
          "nested": []
        },
        {
          "field": "hostCount",
          "type": "int",
          "nested": []
        },
        {
          "field": "appCount",
          "type": "int",
          "nested": []
        },
        {
          "field": "dbCount",
          "type": "int",
          "nested": []
        },
        {
          "field": "connectorCount",
          "type": "int",
          "nested": []
        }
      ]
    }
  ]
}
Name Description Type Additional Information
ID Network ID number. integer
CLIENTID Client ID number. integer
NAME Network name. string
TYPE Network type. string Options: IP, hostname
HOSTCOUNT Number of hosts in network. integer
APPCOUNT Number of applications in network. integer
DBCOUNT Number of databases in network. integer
CONNECTORCOUNT Number of connectors in network. integer

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy
{
  "projections": [
    {
      "name": "basic",
      "fields": [
        {
          "field": "id",
          "type": "integer"
        },
        {
          "field": "name",
          "type": "string"
        }
      ]
    }
  ]
}
Code Description
401 Unauthorized
404 Not Found

Listing Filterable Network Fields

Displays the network fields that the search endpoint can filter by.

API Call: GET/client/{clientId}/network/filter

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/filter

URL Parameters

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can list network fields that can be filtered by are:

  • Manager
  • Group Manager
  • User

Python

Python Sample list_networkfields Snippet

Copy

import requests

platform = 'https://platform<PLATFORM.risksense.com'
api_key = '<APIKEY>'
client_id = <CLIENTID>

header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}

url = platform + "/api/v1/client/" + str(client_id) + "/network/filter"

response = requests.get(url, headers=header)

Replace angle bracket parameters with your own values.

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
APIKEY Your API key. string Y Generating an API Token
CLIENTID Client ID number. integer Y Finding Your Client ID

cURL

cURL Sample list_networkfields Snippet

Copy

curl -X GET "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/filter" \
  -H  "accept: application/json" \
  -H  "x-api-key: <APIKEY>" \

Replace angle bracket parameters with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token

Response Parameters

Sample Response

Copy

[
  {
    "name": "Application Count",
    "legacyUid": "app_count",
    "uid": "appCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "int",
    "description": "Filters Network Partitions by app count"
  },
  {
    "name": "Connector Count",
    "legacyUid": "connector_count",
    "uid": "connectorCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "int",
    "description": "Filters Network Partitions by connector count"
  },
  {
    "name": "Database Count",
    "legacyUid": "db_count",
    "uid": "dbCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "int",
    "description": "Filters Network Partitions by database count"
  },
  {
    "name": "Host Count",
    "legacyUid": "host_count",
    "uid": "hostCount",
    "operators": [
      "EXACT",
      "IN",
      "RANGE"
    ],
    "type": "int",
    "description": "Filters Network Partitions by host count"
  },
  {
    "name": "Name",
    "legacyUid": "name",
    "uid": "name",
    "operators": [
      "EXACT",
      "IN",
      "LIKE",
      "WILDCARD"
    ],
    "type": "string",
    "description": "Filters Network Partitions by name"
  },
  {
    "name": "Type",
    "legacyUid": "type",
    "uid": "type",
    "operators": [
      "EXACT",
      "IN"
    ],
    "type": "string",
    "description": "Filters Network Partitions by type."
  }
]

Name Description Type Additional Information
APPLICATIONCOUNT Application count. integer Filter Options: Exact, In, Range
CONNECTORCOUNT Connector count. integer Filter Options: Exact, In, Range
DATABASECOUNT Database count. integer Filter Options: Exact, In, Range
HOSTCOUNT Host count. integer Filter Options: Exact, In, Range
NAME Network name. string Filter Options: Exact, In, Like, Wildcard
TYPE Network type. string Filter Options: Exact, In

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy
[
  {
    "name": "id",
    "uid": "id",
    "operator": [
      "EXACT",
      "IN"
    ],
    "type": "integer",
    "description": "The id"
  }
]
Code Description
401 Unauthorized
404 Not Found

Suggesting Filter Values for Network Filtering

Displays suggested filter values when filtering networks.

API Call: POST/client/{clientId}/network/suggest

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/suggest

URL Parameters

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can view suggested filter values for networks are:

  • Manager
  • Group Manager
  • User

Python

Python Sample filter_networkvalues Snippet

Copy

import json
import requests

platform = 'https://platform<PLATFORM>.risksense.com'
api_key = '<APIKEY>'
client_id = <CLIENTID>

header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}

body = {
    "filters": [
        {
            "field": "<FIELD>",
            "exclusive": <EXCLUSIVE>,
            "operator": "<OPERATOR>",
            "value": "<VALUE>"
        }
    ],
    "filter": {
        "field": "<FIELD>",
        "exclusive": <EXCLUSIVE>,
        "operator": "<OPERATOR>",
        "value": "<VALUE>"
    }
}

url = platform + "/api/v1/client/" + str(client_id) + "/network/suggest"

response = requests.post(url, headers=header, data=json.dumps(body))

Replace angle bracket parameters with your own values.

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
APIKEY Your API key. string Y Generating an API Token
CLIENTID Client ID number. integer Y Finding Your Client ID
FIELD Filter category. string Y
EXCLUSIVE Exclusive. boolean Y Options: True = Exclude values listed in the VALUE field, False = Filter based on VALUE field.
OPERATOR Search operator. string Y Options: EXACT, IN, LIKE, WILDCARD, RANGE, CIDR
VALUE Search value. string Y

cURL

cURL Sample filter_networkvalues Snippet

Copy

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/suggest" \
  -H  "accept: application/json" \
  -H  "x-api-key: <APIKEY>" \
  -H  "Content-Type: application/json" \
  -d "{  \"filters\": [    {      \"field\": \"<FIELD>\",      \"exclusive\": <EXCLUSIVE>,      \"operator\": \"<OPERATOR>\",      \"value\": \"<VALUE>\"    }  ],  \"filter\": {    \"field\": \"<FIELD>\",    \"exclusive\": <EXCLUSIVE>,    \"operator\": \"<OPERATOR>\",    \"value\": \"<VALUE>\"  }}"

Replace angle bracket parameters with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
FIELD Filter category. string Y
EXCLUSIVE Exclusive. boolean Y Options: True = Exclude values listed in the VALUE field, False = Filter based on VALUE field.
OPERATOR Search operator. string Y Options: EXACT, IN, LIKE, WILDCARD, RANGE, CIDR
VALUE Search value. string Y

Response Parameters

Sample Response

Copy
[
  {
    "key": "<KEY>",
    "count": <COUNT>
  }
]

Name Description Type Additional Information
KEY Value for the field requested. string
COUNT Count. integer($int64)

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy
[
  {
    "key": "string",
    "count": 0
  }
]
Code Description
400 Bad Request
401 Unauthorized
404 Not Found

Searching for a Network

Search for a network within the designated client.

API Call: POST/client/{clientId}/network/search

URL: https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/search

URL Parameters

Name Description Additional Information
PLATFORM Platform number. Endpoint URL Structure
CLIENTID Client ID number. Finding Your Client ID

User Roles

The user roles that can search for a network are:

  • Manager
  • Group Manager
  • User

Python

Python Sample search_network Snippet

Copy

import json
import requests

platform = 'https://platform.risksense.com'
api_key = '<INSERT API KEY HERE>'
client_id = <INSERT CLIENT ID HERE>

header = {
    "x-api-key": api_key,
    "content-type": "application/json"
}
body = {
    "filters": [
        {
            "field": "<FIELD>",
            "exclusive": <EXCLUSIVE>,
            "operator": "<OPERATOR>",
            "value": "<VALUE>,<VALUE>"
        }
    ],
    "projection": "<PROJECTION>",
    "sort": [
        {
            "field": "<SORTFIELD>",
            "direction": "<SORTDIRECTION>"
        }
    ],
    "page": <PAGENUMBER>,
    "size": <PAGESIZE>
}​

url = platform + "/api/v1/client/" + str(client_id) + "/network/search"

response = requests.post(url, headers=header, data=json.dumps(body))

Replace angle bracket parameters with your own values.

Python Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
APIKEY Your API key. string Y Generating an API Token
CLIENTID Client ID number. integer Y Finding Your Client ID
FIELD Filter category. string Y
EXCLUSIVE Exclusive. boolean Y Options: True = Exclude values listed in the VALUE field, False = Filter based on VALUE field.
OPERATOR Search operator. string Y Options: EXACT, IN, LIKE, WILDCARD, RANGE, CIDR
VALUE Search value. string Y
PROJECTION Projection type. string Y Options: basic, detailed
SORTFIELD Field to sort. string Y
SORTDIRECTION Sort direction. string Y Options: ASC, DESC
PAGENUMBER Page to view. integer Y First Page: 0
PAGESIZE Page size requested. integer Y Shows how many items to display on the page.

cURL

cURL Sample search_network Snippet

Copy

curl -X POST "https://platform<PLATFORM>.risksense.com/api/v1/client/<CLIENTID>/network/search"
  -H "accept: application/json" \
  -H "x-api-key: <APIKEY>" \
  -H "Content-Type: application/json" \
  -d "{ \"projection\": \"<PROJECTION>\", \"sort\": [ { \"field\": \"<SORTFIELD>\", \"direction\": \"<SORTDIRECTION>\" } ], \"page\": <PAGENUMBER>, \"size\": <PAGESIZE>}"

Replace angle bracket parameters with your own values.

cURL Parameters

Name Description Type Required Additional Information
PLATFORM Platform number. integer Y Endpoint URL Structure
CLIENTID Client ID number. integer Y Finding Your Client ID
APIKEY Your API key. string Y Generating an API Token
PROJECTION Projection type. string Y Options: basic, detailed
SORTFIELD Field to sort. string Y
SORTDIRECTION Sort direction. string Y Options: ASC, DESC
PAGENUMBER Page to view. integer Y First Page: 0
PAGESIZE Page size requested. integer Y Shows how many items to display on the page.

Response Parameters

Sample Response

Copy

{
  "errors": [],
  "page": {
    "size": <PAGESIZE>,
    "totalElements": <TOTALELEMENTS>,
    "totalPages": <TOTALPAGES>,
    "number": <PAGENUMBER>
  },
  "_embedded": {
    "networks": [
      {
        "id": <NETWORKID>,
        "clientId": <CLIENTID>,
        "name": "<NETWORKNAME>",
        "type": "<NETWORKTYPE>",
        "locked": <LOCKED>,
        "hostCount": <HOSTCOUNT>,
        "appCount": <APPCOUNT>,
        "dbCount": <DBCOUNT>,
        "connectorCount": <CONNECTORCOUNT>
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://platform.risksense.com/api/v1/client/<CLIENTID>/network/search?page=<PAGENUMBER>&size=<PAGESIZE>&sort=<SORTFIELD>,<SORTDIRECTION>"
    }
  }
}

Name Description Type Additional Information
PAGESIZE Page size requested. integer Shows how many items to display on the page.
TOTALELEMENTS Total number of items available. integer
TOTALPAGES Total number of pages available. integer
PAGENUMBER Page to view. integer First Page: 0
NETWORKID Network ID number. integer
CLIENTID Client ID number. integer
NETWORKNAME Network name. string
NETWORKTYPE Network type. string Options: IP, HOSTNAME.
LOCKED Is this network locked? boolean Options: True = Yes, False = No
HOSTCOUNT Host count. integer
APPCOUNT Application count. integer
DBCOUNT Database count. integer
CONNECTORCOUNT Connector count. integer
SORTFIELD Field to sort by. string
SORTDIRECTION Sort direction. string Options: ASC, DESC

HTTP Status Codes

Code Description
200 OK

200 Sample Response

Copy
{
  "_embedded": {
    "strings": [
      {}
    ]
  },
  "page": {
    "size": 0,
    "totalElements": 0,
    "totalPages": 0,
    "number": 0
  },
  "errors": [
    {
      "id": "string",
      "errorRefId": "string",
      "code": 0,
      "cause": "string"
    }
  ]
}
Code Description
400 Bad Request
401 Unauthorized
404 Not Found