Advanced Scanning Configurations

New Domotz Metrics article
Time icon

5 MIN

Tag Icon

Tips & Tricks

Tag Icon

HOME PAGE

5 min

By default, Domotz scans all the Network interfaces that it finds on the Operating System it’s installed on, and therefore it scans all the networks these interfaces are connected to.

Table of Contents

Prerequisites

In order to tune/change your scanning configuration, you will need:

  • an Agent/Collector ID
  • the Network Interfaces names
  • a Domotz API key
  • the Domotz API key endpoint
  • a little bit of knowledge on how to use curl and/or PowerShell scripting

Get the Agent/Collector ID

From the the Site Explorer or from Inventory View (Sites section) select the agent and enter the Agent/Collector’s Page. You will find the ID in the web address URL:

Get the Network Interfaces Names

In order to obtain the network Interfaces names along with the network they are scanning please:

1. Go to “Inventory”.
2. Select “Sites”.
3. Select the specific cell in the Network Setup column.
4. Find the names of the Networks and Interfaces in the menu to the right.

Get the Domotz API KEY and the API KEY Endpoint

Please see here on how to generate it in our Help Center Article – Domotz API – Domotz Help Center.

How to Modify Domotz Scanning Properties

As already mentioned, Domotz by default scans all the networks attached to the network interfaces it finds configured on the operating system it runs on. 

In order to modify this behavior, you might consider the following scenarios:
 
1) With the Domotz default scanning enabled, you can: 

  • set interfaces as “denied” to disable scanning on a specific Layer 2 network 
  • exclude specific devices from being monitored using the device blacklist 

2) With the Domotz scanning disabled (it is possible to activate an agent with Domotz scanning disabled at startup), you can: 

  • allow specific interfaces to be scanned 
  • allow IP list to be scanned 
  • allow ranges of IP’s to be scanned 

Modify scanning policies on Domotz default scanning enabled

Using the Interfaces Policy API, you can precisely control which interfaces the agent interacts with. This lets you choose whether to allow or deny scanning on specific interfaces.

To allow only specific interfaces to be scanned, you will need to set the scan policy to “deny” for the interface/s which corresponds to the network/s you would like to exclude from scanning.

Example: you would like to exclude from scanning the network 192.168.13.0/24 which is attached to the eth1 interface

Windows

Open a PowerShell and perform the following command (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACES):

Invoke-RestMethod -Uri "$API_KEY_ENDPOINT/agent/$AGENTID/network/interfaces-policy" -Method PUT -Headers @{ "X-API-Key" = '$API_KEY' } -ContentType "application/json" -Body '{"policy": "deny", "rules": ["$INTERFACES"]}'


The PowerShell method is advised, but you might also use cmd with curl:

curl -X PUT "$API_KEY_ENDPOINT/agent/$AGENTID/network/interfaces-policy" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d "{\"policy\": \"deny\", \"rules\": [\"$INTERFACES\"]}"


This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, denying scanning on interface eth1:

Invoke-RestMethod -Uri "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/interfaces-policy" -Method PUT -Headers @{ "X-API-Key" = 'kjase8928j8jdkjsd921204ksdlkqs' } -ContentType "application/json" -Body '{"policy": "deny", "rules": ["eth1"]}'

Linux

You can open a shell and use curl (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACE):

curl -X PUT $API_KEY_ENDPOINT/agent/$AGENTID/network/interfaces-policy -H 'Accept: application/json' -H 'X-Api-Key: $API_KEY' -d '{"policy": "deny", "rules": ["$INTERFACES"]}' 

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, denying scanning on interface eth1:

curl -X PUT https://api-eu-west-1-cell-1.domotz.com/public-api/v1/2223323/network/interfaces-policy -H 'Accept: application/json' -H 'X-Api-Key: kjase8928j8jdkjsd921204ksdlkqs' -d '{"policy": "deny", "rules": ["eth1"]}' 

Python script

You might also create a Python script which can be useful (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACES):

import requests 
 
url = "$API_KEY_ENDPOINT/v1/agent/$AGENTID/network/interfaces-policy" 
headers = { 
    "X-API-Key": "$API_KEY", 
    "Content-Type": "application/json" 
} 
data = { 
    "policy": "deny", 
    "rules": ["$INTERFACES"] 
} 
 
response = requests.put(url, headers=headers, json=data) 
print(response.text)

multiple interfaces can be listed separated with commas:

“rules”:[ “eth1,eth2,eth3”]

Exclude specific devices from being monitored

To exclude specific devices by ip address you can use the device blacklist feature.

To add devices to the blacklist, you can click on “Device Blacklist” in the Collector’s Device list:


Modify scanning policies if Domotz scanning is disabled

After activating an agent with scanning disabled (using the following PowerShell command):

Invoke-RestMethod -Method Post -Uri "http://${DOMOTZ_AGENT_IP}:3000/api/v1/agent" -Headers @{"x-api-key" = "${X_API_KEY}"} -Body (@{"name" = "${AGENT_NAME}"; "endpoint" = "${DOMOTZ_PUBLIC_ENDPOINT}"; "deny_all_interfaces" = $true} | ConvertTo-Json)

Or utilizing the following curl command:

curl -v  -XPOST -H "x-api-key: ${X_API_KEY}" -d "{\"name\": \"${AGENT_NAME}\", \"endpoint\": \"${DOMOTZ_PUBLIC_ENDPOINT}\", \"deny_all_interfaces\": true}" http://${DOMOTZ_AGENT_IP}:3000/api/v1/agent

Then you can re-write the part allowing a interfaces instead of denying as above.

Allow specific interfaces to be scanned:

To allow specific interfaces to be scanned. You need to set the Agent policy to “allow” for the interface and provide it with rules. 

Example: you would like to allow scanning the network 192.168.13.0/24 which is attached to the eth1 interface


Windows

Open a PowerShell and perform the following command (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACES): 

Invoke-RestMethod -Uri "$API_KEY_ENDPOINT/agent/$AGENTID/network/interfaces-policy" -Method PUT -Headers @{ "X-API-Key" = '$API_KEY' } -ContentType "application/json" -Body '{"policy": "allow", "rules": ["$INTERFACES"]}' 

The PowerShell method is advised, but you might also use cmd with curl:

curl -X PUT "$API_KEY_ENDPOINT/agent/$AGENTID/network/interfaces-policy" -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" -d "{\"policy\": \"allow\", \"rules\": [\"$INTERFACES\"]}" 

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, allowing scanning on interface eth1:

Invoke-RestMethod -Uri "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/interfaces-policy" -Method PUT -Headers @{ "X-API-Key" = 'kjase8928j8jdkjsd921204ksdlkqs' } -ContentType "application/json" -Body '{"policy": "allow", "rules": ["eth1"]}'

Linux

You can open a shell and use curl (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACE):

curl -X PUT $API_KEY_ENDPOINT/agent/$AGENTID/network/interfaces-policy -H 'Accept: application/json' -H 'X-Api-Key: $API_KEY' -d '{"policy": "allow", "rules": ["$INTERFACES"]}'

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, denying scanning on interface eth1:

curl -X PUT https://api-us-east-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/interfaces-policy -H 'Accept: application/json' -H 'X-Api-Key: kjase8928j8jdkjsd921204ksdlkqs' -d '{"policy": "allow", "rules": ["eth1"]}'

Python script

You might also create a Python script which can be useful (remember to replace $API_KEY_ENDPOINT,$AGENTID,$API_KEY,$INTERFACES):

import requests 
 
url = "$API_KEY_ENDPOINT/v1/agent/$AGENTID/network/interfaces-policy" 
headers = { 
    "X-API-Key": "$API_KEY", 
    "Content-Type": "application/json" 
} 
data = { 
    "policy": "allow", 
    "rules": ["$INTERFACES"] 
} 
 
response = requests.put(url, headers=headers, json=data) 
print(response.text)

Allow IP list to be scanned:

To specify a specific set of IP addresses for the agent to scan, you can utilize the Domotz public API endpoint named ‘ip-scan-policy’. This allows you to include IP addresses under ‘forced_ip_addresses’ for scanning, irrespective of the agent’s automatic discovery settings. 

You simply need to include the list of IP addresses under ‘forced_ip_addresses’ and leave ‘forced_ip_ranges’ empty.

Example: you would like to allow scan the IP addresses 10.0.20.100, 10.0.20.101, and 10.0.20.250

Windows

Open a PowerShell and perform the following command (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACES):

Invoke-RestMethod -Uri "$API_KEY_ENDPOINT/agent/$AGENTID/network/ip-scan-policy" -Method PUT -Headers @{ "X-API-Key" = '$API_KEY' } -ContentType "application/json" -Body '{"forced_ip_addresses": ["$INTERFACE1", "$INTERFACE2", "$INTERFACE3"], "forced_ip_ranges": []}'

The PowerShell method is advised, but you might also use cmd with curl:

curl -X PUT "$API_KEY_ENDPOINT/agent/$AGENTID/network/ip-scan-policy" -H "Accept: application/json" -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" -d "{\"forced_ip_addresses\": [\"$INTERFACE1\", \"$INTERFACE2\", \"$INTERFACE3\"], \"forced_ip_ranges\": []}"

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, allowing scanning the IP addresses ‘10.0.20.100’, ‘10.0.20.101’, and ‘10.0.20.250’:

Invoke-RestMethod -Uri "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/ip-scan-policy" -Method PUT -Headers @{ "X-API-Key" = 'kjase8928j8jdkjsd921204ksdlkqs' } -ContentType "application/json" -Body '{"forced_ip_addresses": ["10.0.20.100", "10.0.20.101", "10.0.20.250"], "forced_ip_ranges": []}'

Linux

You can open a shell and use curl (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACE):

curl -X PUT $API_KEY_ENDPOINT/agent/$AGENTID/network/ip-scan-policy -H 'Accept: application/json' -H 'X-Api-Key: $API_KEY' -d '{"forced_ip_addresses": [ "$INTERFACE1", "$INTERFACE2","$INTERFACE3"], "forced_ip_ranges": []}'

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, allowing scanning the IP addresses ‘10.0.20.100’, ‘10.0.20.101’, and ‘10.0.20.250’:

curl -X PUT https://api-eu-west-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/ip-scan-policy -H 'Accept: application/json' -H 'X-Api-Key: kjase8928j8jdkjsd921204ksdlkqs' -d '{"forced_ip_addresses": [ "10.0.20.100", "10.0.20.101","10.0.20.250"], "forced_ip_ranges": []}'

Allow ranges of IP’s to be scanned 

When focusing solely on scanning a specific range of IP addresses, make use of ‘forced_ip_ranges’. Simply define the ‘start’ and ‘end’ points of this range, leaving the ‘forced_ip_addresses’ empty.  

Example: you would like to allow scan the range 192.168.178.1 to 192.168.178.23

Windows

Open a PowerShell and perform the following command (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACES)

Invoke-RestMethod -Uri "$API_KEY_ENDPOINT/agent/$AGENTID/network/ip-scan-policy" -Method PUT -Headers @{ "X-API-Key" = '$API_KEY' } -ContentType "application/json" -Body '{"forced_ip_addresses": [], "forced_ip_ranges": [{"end": "$End_IP", "start": "$Start_IP"}]}'


The PowerShell method is advised, but you might also use cmd with curl:

curl -X PUT "$API_KEY_ENDPOINT/agent/$AGENTID/network/ip-scan-policy" -H "Accept: application/json" -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" -d "{\"forced_ip_addresses\": [], \"forced_ip_ranges\": [{\"end\": \"$End_IP\", \"start\": \"$Start_IP\"}]}"

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, allowing scanning the range 192.168.178.1– 23:

Invoke-RestMethod -Uri "https://api-eu-west-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/ip-scan-policy" -Method PUT -Headers @{ "X-API-Key" = 'kjase8928j8jdkjsd921204ksdlkqs' } -ContentType "application/json" -Body '{"forced_ip_addresses": [], "forced_ip_ranges": [{"end": "192.168.178.23", "start": "192.168.178.1"}]}'

Linux

You can open a shell and use curl (remember to replace $API_KEY_ENDPOINT, $AGENTID, $API_KEY, $INTERFACE):

curl -X PUT $API_KEY_ENDPOINT/agent/$AGENTID/network/ip-scan-policy -H 'Accept: application/json' -H 'X-Api-Key: $API_KEY' -d '{"forced_ip_addresses": [], "forced_ip_ranges": [{"end": "$End_IP", "start": "$Start_IP"}]}'

This is an example for the Europe API Key Endpoint, agent/collectorID 2223323, allowing scanning the range 192.168.178.1 – 23:

curl -X PUT https://api-eu-west-1-cell-1.domotz.com/public-api/v1/agent/2223323/network/ip-scan-policy -H 'Accept: application/json' -H 'X-Api-Key: kjase8928j8jdkjsd921204ksdlkqs' -d '{"forced_ip_addresses": [], "forced_ip_ranges": [{"end": "192.168.178.23", "start": "192.168.178.1"}]}'

Share via Social Networks

Categories

You might also like…

Read more top posts in this category

Want more tips on Network Monitoring?

Ready to get started with Domotz?

  • Powerful
  • Automated
  • Simple
  • Affordable
Start Your Free Trial Contact Sales