Server

The Scan Agent Server component is intended to act as the go between for the Scanner component and phpIPAM.

Usage

After installing the collection, running the server is as simple as running the following command:

ansible-rulebook -r nofusscomputing.phpipam_scan_agent.agent_receive

Variables

The variables described below, if optional the value specified here is the default value. The variables are to be set in a variables file at path /etc/phpipam/scan_server.yaml

nofusscomputing_phpipam_scan_server:

  # phpIPAM MariaDB/MySQL Variables
  mysql_host:         # Mandatory, String. IP/DNS of host to connect.
  mysql_port: 3306    # Optional, Integer. port to use for connection.
  mysql_user:         # Mandatory, String. User to authenticate with.
  mysql_password:     # Mandatory, String. Password for the user to connect with.


  # Server Component Variables
  http_port: 5000     # Optional, Integer. The port for the Server component to listen for connections.
  auth_token:         # Optional, String. Token used to authentication Agents.

Workflow

The Server componet has the following workflow:

Receive the Scanner component report.
check if the Scanner Code is in the DB
- if no results found, no further processing occurs
Confirm the subnet scanned is assigned to the scanner
- if no results found, no further processing occurs
Update the phpIPAM MariaDB/MySQL database directly

Remote network Scannning

Remote network scanning is possible with the Scan-Agent. The server must be setup and have connectivity to the phpIPAM MariaDB/MySQL database. Currently the server does not perform secure communication. As such you are strongly encouraged to setup the server component behind a reverse proxy that conducts the TLS termination. It's also recommended that you use your own CA to sign the TLS certificate. Just don't forget to add this CA certificate to the trusted CA certificates

The scan and server component must be setup with the same auth_token. It is this token that provides a means to ensure that what the server is receiving, is from an authorized client.

Security

Failing to secure the server component communication with TLS will allow anyone with direct access to the line of communication to view the auth_token. Anyone who has the auth_token will be able to upload data to the server.

Timezone normalization

As there is no support within phpIPAM for different timezones. The server component when receiving updates from scanners, will convert any time found to UTC (GMT +00:00). This is required so that phpIPAM features that rely on time, function as they should. This setup requires that machine or docker containers for phpIPAM and the MySQL/MariaDB database both have their timezones set to UTC. If you don't wish for any timezone conversion to be done, ensure that where ever all components, including the scan server component, share the same timezone.

About:

This page forms part of our Project phpIPAM Scan Agent.

Page Metadata

Version: ToDo: place files short git commit here
Date Created: 2024-02-20
Date Edited: 2024-02-26

Contribution:

Would You like to contribute to our phpIPAM Scan Agent project? You can assist in the following ways:

Edit This Page If there is a mistake or a way you can improve it.
Add a Page to the Manual if you would like to add an item to our manual
Raise an Issue if there is something about this page you would like to improve, and git is unfamiliar to you.

ToDo: Add the page list of contributors