Deploying the Network Devices Misconfiguration Sensor

Pre-Installation

Set up the Network Sensor Server on Ubuntu or Red Hat (latest LTS or stable versions are preferred). The server must be a dedicated machine and placed in a network location with access to the management interfaces of the organization's network devices.

For environments with disconnected, isolated, or separate networks/data centers, multiple dedicated Network Sensor servers can be deployed - each acting as an independent sensor within its respective segment(s).

The GYTPOL Linux Sensor can also be installed on the same device. The Network Sensor and Linux Sensor are fully compatible and can operate side by side without conflict.

Requirements for Network Management Sensor Server

Ensure the machine meets the following specifications:

Network Device Count	CPU (Cores)	Memory (GB)	Storage (GB)

Network Device Count	CPU (Cores)	Memory (GB)	Storage (GB)
Up to 300 (+ PoV)	2	8	60
301 to 500	4	8	60
501 to 1000	8	8	60

For planned deployments involving more than 1,000 network devices, coordination with your GYTPOL Account Manager is strongly recommended to ensure optimal performance, scaling, and support.

Ensure the following before deploying the Network Sensor:

The server has proper routing access to all relevant network devices.
All devices must be reachable via IPv4 (IPv6 is not supported).
Network device ACLs allow SSH access from the Network Sensor.
Any firewalls between the Sensor and target network devices allow the necessary communication (e.g., TCP port 22 for SSH).

This setup is required to enable the system to monitor and manage network device configurations effectively.

Does the Server need to be a member of the Windows Domain?

No

Ports to open:

Source	Destination	Destination Port	Note

Source	Destination	Destination Port	Note
GYTPOL Network Sensor	GYTPOL SaaS	443	Used for secure communication with the GYTPOL cloud platform.
GYTPOL Network Sensor	Organization’s network devices	22	Default port for SSH access. This value can be customized in the `network_config.json` file.

Download the GYTPOL Network Sensor

The sensor installation package can be downloaded directly from the GYTPOL UI:

Navigate to the System Health screen.
Download the appropriate installer for your platform (Debian or RPM-based).

If the download links appear grayed out, it means the Network Devices license is not enabled in your account.
Please contact your GYTPOL Account Manager to activate the required module.

Install the GYTPOL Network Sensor Package

For Debian-based systems:

sudo dpkg -i <gytpol-sensor-path>

For RPM-based systems:

sudo rpm -ivh <gytpol-sensor-path>

Configure Network Sensor Settings

Configuration files are located at: /opt/gytpol-network-sensor/configs/network_configs

Two template files are provided:

network_config.json.template
secrets.json.template
network_devices.txt.template

Copy and rename them (remove the .template suffix) to enable editing:

sudo cp /opt/gytpol-network-sensor/configs/network_configs/network_config.json.template /opt/gytpol-network-sensor/configs/network_configs/network_config.json
sudo cp /opt/gytpol-network-sensor/configs/network_configs/secrets.json.template /opt/gytpol-network-sensor/configs/network_configs/secrets.json
sudo cp /opt/gytpol-network-sensor/configs/network_configs/network_devices.txt.template /opt/gytpol-network-sensor/configs/network_configs/network_devices.txt

These configuration files define which network devices should be scanned and specify the scanning protocols and credentials.

Configuring `network_devices.txt`

Edit the network_devices.txt file to include the IPv4 addresses of the network devices (whatever vendor) that should be scanned by the Network Sensor.

These addresses should point to the management interfaces of the devices, the ones used for administrative access (e.g., SSH).

Each IP address must be listed on a separate line, for example:

192.168.1.1
192.168.1.2
192.168.1.3

This file acts as the input list that the sensor will use to initiate connections and perform configuration scans.

Configuring `network_config.json`

Edit the network_config.json file to define the connection settings the Network Sensor will use to access the network devices.

The expected JSON structure is as follows:

{
    "protocol": "ssh",
    "port": 22,
    "workers": 3,
    "nms_sources": []
}

For integration with Network Management Systems (NMS) such as Cisco DNA Center (Catalyst Center):

{
    "protocol": "ssh",
    "port": 22,
    "workers": 3,
    "nms_sources": [
        {
            "name": "cisco-dnac-prod",
            "type": "cisco_catalyst_center",
            "address": "https://dnac.example.com",
            "port": 443,
            "enabled": true,
            "insecure": true
        }
    ]
}

Configuring `secrets.json`

Edit the secrets.json file to define device credentials and NMS authentication.

The expected JSON structure is as follows:

{
    "device_auth": {
        "credentials": {
            "admin": ["pass123"]
        },
        "keys": {}
    },
    "nms_auth": {}
}

For multiple password options:

{
    "device_auth": {
        "credentials": {
            "admin": ["pass123", "otherPass"],
            "oper": ["operPass321"]
        },
        "keys": {}
    },
    "nms_auth": {}
}

For NMS integration (Cisco DNA Center / Catalyst Center):

{
    "device_auth": {
        "credentials": {
            "admin": ["pass123"]
        },
        "keys": {}
    },
    "nms_auth": {
        "cisco-dnac-prod": {
            "username": "dnac_user",
            "password": "dnac_password"
        }
    }
}

During the configuration step, the secrets.json.template file was copied to secrets.json. Do not delete the original .template file.

Once the Network Sensor is executed for the first time, secrets.json will be encrypted. Keeping the .template file intact allows for easier modification of the configuration in the future if changes are required.

Configuration File Reference: `network_config.json`

Below is a breakdown of the available fields in the configuration file and how to use them:

Protocol

Defines the protocol used to connect to devices.

Only ssh is currently supported.

Set this value as:

"protocol": "ssh"

Port

Specifies the port used for the selected protocol.

Default is 22 for SSH.

If a different SSH port is configured in the organization, set it accordingly:

"port": 22

Workers

Controls the number of network devices scanned in parallel.

Increasing this value can speed up scans but may increase network and system load.

Adjust this value based on the available system resources (e.g., RAM):

"workers": 3

NMS Sources

Defines Network Management System sources to fetch device IPs from dynamically.

NMS is supported starting Network Sensor 0.5.4

Currently supported NMS platforms:

Cisco DNA Center (DNAC / Catalyst Center) - type: cisco_catalyst_center

Device IPs from NMS sources are combined with IPs from network_devices.txt. If NMS is unreachable, the sensor continues with file-based IPs only.

Leave as an empty array if not using NMS integration:

"nms_sources": []

name (required)

Unique identifier for this NMS source. Must match the corresponding entry in secrets.json.

"name": "cisco-catalyst-center"

type (required)

The NMS platform type. Determines which API client to use.

"type": "cisco_catalyst_center"

address (required)

The URL or IP address of the NMS server. Can include protocol (<https://)> and custom port (:8443). If protocol is omitted, <https://> is assumed.

"address": "catalyst-center.example.com:8443"

enabled (required)

Controls whether this NMS source should be queried during scans. When set to false, the source is skipped entirely (no connection attempt). When set to true, the sensor will fetch device IPs from this source.

Use cases:
• Set to false to temporarily disable an NMS source without removing it
• Set to true to enable an NMS source for production use

Default behavior: If this field is missing, it defaults to false (disabled).

"enabled": true

insecure (optional)

Controls TLS/SSL certificate verification for HTTPS connections. When set to true, the sensor accepts self-signed or invalid certificates. When set to false or omitted, standard certificate verification is performed.

Security considerations:
• Only use in lab/development environments with self-signed certificates
• Production deployments should use valid, CA-signed certificates
• When false, connections fail if certificate is invalid/expired/self-signed

Default behavior: If omitted, defaults to false (verify certificates).

Example: "insecure": true or "insecure": false

Complete NMS Source Example:

 "nms_sources": [
  {
    "name": "cisco-catalyst-center",
    "type": "cisco_catalyst_center",
    "address": "https://10.10.20.10",
    "enabled": true,
    "insecure": true
  }
]

Multiple NMS Sources Example:

"nms_sources": [
  {
    "name": "primary-dnac",
    "type": "cisco_catalyst_center",
    "address": "https://dnac-primary.example.com",
    "enabled": true,
    "insecure": false
  },
  {
    "name": "secondary-dnac",
    "type": "cisco_catalyst_center",
    "address": "https://dnac-secondary.example.com",
    "enabled": false,
    "insecure": false
  }
]

Configuration File Reference: secrets.json

Below is a breakdown of the available fields in the secrets configuration file and how to use them:

Credentials

The credentials defined in secrets.json should have read-only access to the network devices. This means the user must be permitted to run non-intrusive show commands, such as:

show running-config
show version
show interfaces
show ip route

This access is typically granted through a user account with privilege level 1 or higher, depending on the device's configuration. If using AAA (e.g., RADIUS or TACACS+), ensure the user is assigned a read-only role with sufficient privileges to execute these diagnostic commands.

No configuration or write permissions are required.

Example with a single user:

"credentials": {
    "user1": ["Aa12345"]
}

Example with multiple users (the sensor will iterate through the list until a connection succeeds):

"credentials": {
    "user1": ["Aa12345"],
    "user2": ["StrongPassword123", "AnotherStrongPass123"]
}

Keys

SSH private keys for device authentication.

Provide the full path to the key file:

"keys": {
    "ubuntu": ["/path/to/key.pem"]
}

NMS Auth

Authentication credentials for Network Management Systems.

The name must match the name defined in network_config.json NMS sources.

For Cisco DNA Center (Catalyst Center):

"nms_auth": {
    "cisco-dnac-prod": {
        "username": "readonly_user",
        "password": "secure_password"
    }
}

Starting the Network Sensor Service

After installation, the service does not start automatically. This is by design, as it waits for manual configuration of the required files (network_config.json, secrets.json, and network_devices.txt) before launching.

Once the configuration is complete, start the service manually using: sudo systemctl start gytpol-network-sensor

Manual startup is required only once, after initial configuration. On subsequent reboots, the service will start automatically and retain its previous status.

Post-Installation

Where are the scanned devices displayed?

Once the Network Sensor is running and scanning, the discovered network devices will appear in the ‘Network Devices’ section of the GYTPOL UI.

This interface provides visibility into each device's configuration status, compliance posture, and any detected misconfigurations.

When will newly added devices appear in the GYTPOL UI?

The Network Sensor performs a full scan every 24 hours. After adding new IP addresses to the network_devices.txt file, results will be available within 24 hours of the next scheduled scan.
The dashboard graph is also refreshed at a 24-hour interval, so updates to the visualization will follow the same schedule.
If a manual rescan is triggered via “Generic Actions” menu, device data will appear on the “Devices” page within 1 hour after the scan is completed.

How do I check or control the Network Sensor service?

Use the following systemctl commands to manage the GYTPOL Network Sensor service:

Start the service:
sudo systemctl start gytpol-network-sensor
Stop the service:
sudo systemctl stop gytpol-network-sensor
Check the service status:
sudo systemctl status gytpol-network-sensor

These commands allow you to start, stop, or verify the current status of the sensor as needed.

Sample Output (Status):

gytpol-network-sensor.service - Gytpol's Network Sensor
     Loaded: loaded (/usr/lib/systemd/system/gytpol-network-sensor.service; enabled; preset: enabled)
     Active: active (running) since Wed 2025-03-05 13:41:14 IST; 41s ago
   Main PID: 50353 (gytnet)
      Tasks: 11 (limit: 11840)
     Memory: 7.5M (peak: 9.5M)
        CPU: 1.208s
     CGroup: /system.slice/gytpol-network-sensor.service
             └─50353 /opt/gytpol-network-sensor/gytnet
             
Mar 05 13:41:14 ubuntux86 systemd[1]: Started gytpol-network-sensor.service - Gytpol's Network Sensor.

This output confirms that the service is running and provides useful runtime information like memory usage, PID, and start time.

The start and stop commands do not produce output when they succeed. Use the status command to verify the service state.

Installation Path and Logs

Where is the Network Sensor installed?

The default installation path is: /opt/gytpol-network-sensor

Where are the logs located?

Log files are stored in: /opt/gytpol-network-sensor/logs

Each log file corresponds to a specific day and follows the naming format: <year>-<month>-<day>_service.log, for example: 2025-02-26_service.log

These are plain text files and can be viewed using a text editor or directly from the terminal, for example: sudo cat 2025-02-26_service.log

Each log entry is formatted in JSON and includes the log level (info, warning, error), timestamp, message, and possibly internal variable values.

Sample log line:

{"level":"info","msg":"Starting send-reports job","time":"2025-02-26T15:25:31+02:00"}

This information is useful for troubleshooting, verifying service activity, and understanding sensor behavior.

Log Retention Policy

The GYTPOL Network Sensor is currently configured to retain logs for 10 days.

Log files are stored in: /opt/gytpol-network-sensor/logs
Each day may generate one or more log files, depending on sensor activity such as scans, service events, and remediations.
Automatic cleanup is performed: log files older than 10 days are deleted to optimize disk usage and simplify log management.

This behavior can be confirmed on any installed Network Sensor by inspecting the contents of the log directory in /opt/gytpol-network-sensor/log.

Estimated Log Storage Requirements (10-Day Retention):

Number of Network Devices	Required Space for 10 Days Retention

Number of Network Devices	Required Space for 10 Days Retention
40	27.5MB
200	136MB
1000	680MB
3K	2.1GB
10K	6.8GB

These values are approximate and may vary depending on the scanning frequency and the volume of data generated per device.

To estimate the required log storage for your environment, use the following formula:

Estimated Size (in KB) = 68 × 10 × [Number of Network Devices]

Configuration Folder

The Network Sensor’s configuration files are located at: /opt/gytpol-network-sensor/configs

Key Configuration Files:

config.json – Core configuration file for the Sensor (used to connect to the GYTPOL Network Sensor).
metrics.json – Configuration file for sensor metrics and reporting.

These files should not be edited manually.

Upgrade the GYTPOL Network Sensor Package

For Debian-based systems:

sudo dpkg -i <gytpol-sensor-path>

For RPM-based systems:

sudo rpm -Uvh <gytpol-sensor-path>

Use the -Uvh option to upgrade the sensor without removing existing configuration or data.

Uninstalling the GYTPOL Network Sensor

For Debian-Based Systems:

sudo dpkg --remove gytpol-network-sensor

To fully remove the package including logs, archives, and residual files, use:

sudo dpkg --purge gytpol-network-sensor

For RPM-Based Systems:

sudo rpm -e gytpol-network-sensor

Both dpkg and rpm may remove certain configuration files associated with GYTPOL.
Ensure that no critical data is deleted unintentionally. Backup any important files (e.g., configuration, logs, or archives) before proceeding with uninstallation.

(Coming Soon) Discover Subnet: Automatically Identify SSH-Accessible Network Devices

The Discover Subnet feature allows the GYTPOL Network Sensor to automatically scan a subnet for devices with open SSH ports. It updates the device list used for misconfiguration detection, ensuring only reachable devices are targeted.

How It Works

The Network Sensor connects to network devices using SSH.
When the --discover-subnet flag is used, the sensor scans the specified subnet for devices with an open SSH port (as defined in the configuration).
The scan is optimized using multiple parallel workers to complete quickly without affecting network performance.
Discovered devices are automatically added to the network_devices.txt file. Unreachable devices are removed.
A backup of the previous device list and detailed scan results are saved with a timestamp.

The Discover Subnet scan is a manual operation. When run, it updates the network_devices.txt and subnet list used by the GYTPOL Network Sensor. These will be used for all future scans until Discover Subnet is run again and the lists are refreshed.

Usage

Run the following command (supports up to /16 subnets):

sudo /opt/gytpol-network-sensor/gytnet --discover-subnet <subnet>

For example:

sudo /opt/gytpol-network-sensor/gytnet --discover-subnet 192.168.1.0/24

Where Results Are Stored

Updated device list:
/opt/gytpol-network-sensor/configs/network_configs/network_devices.txt
Previous version of device list (backup):
Timestamped file in the same directory
Example: 2025-07-16T10-37-30_network_devices.txt
Scan result log:
Example: 2025-07-16T10-37-30_discover-subnet_192.168.1.0_24.txt

Common Issues and Troubleshooting

Unreachable over network
- Try pinging the IP from the sensor. If it fails, check the device's network connectivity.
SSH port is unaccessible
- Verify firewall rules allow SSH from the sensor’s IP.
- Ensure SSH is configured and running on the device.
- Confirm vty-line and ACL configurations allow access.
SSH works manually, but scan fails
- There may be ACLs blocking the sensor’s IP.
- Device may respond too slowly (scanner times out after 3 seconds per IP).
- You can manually add the device to network_devices.txt.