Scanner

The Scan Agent Scanner component is intended to scan networks that are assigned to it by the phpIPAM server. It can be installed and ran from any host that is capable of running python. The scan agent only requires that there be nmap installed as this is the package that conducts the network scanning.

Usage

Ensure that the namp package is installed, install and configure the collection. Running the agent is as simple as running the following command:

ansible-playbook nofusscomputing.phpipam_scan_agent.agent

See below for the variable details

phpIPAM API

The scanner component requires API access to phpIPAM. THe API user that is used, must only be given read only access to the API.

Variables

Variables for the scanner are set in a variables file at path /etc/phpipam/scan_agent.yaml. The variables described below, if optional the value specified here is the default value.

nofusscomputing_phpipam_scan_agent:

  api_url:                           # Mandatory, String. url with protocol of the phpIPAM API to connect to.

  http_port: 5000                    # Optional, Integer. http port to connect to the server.
  http_server: http://127.0.0.1      # Optional, Integer. url with protocol of the Scan Server to connect to.
  auth_token:                        # Optional, String. The Scan-Agent server authentication token.

  cache_expire_time: 1800            # Optional, Integer. Time in seconds to expire the phpIPAM cache.
  epoch_time_offset: 0               # optional, int. Value in seconds to offset the time

# phpIPAM Scan Agent Settings
  client_token:                      # Mandatory, String client api token to connect to phpIPAM API
  client_name:                       # Mandatory, String. The scanner name as set in phpIPAM interface
  scanagent_code:                    # Mandatory, String. Scan Agent Code as set in phpIPAM interface

Tip

You can specify environmental variable ANSIBLE_LOG_PATH=/var/log/ansible.log, which will tell the scanner component to log to a file at path /var/log/ansible.log

phpIPAM Interface variable Mapping

These images are of the phpIPAM interface that show in green text the variable name that would be set as detailed above.

phpIPAM API Settings

phpIPAM Scan Agent Settings

Workflow

The scanner component has the following workflow:

Expire cache, if cache expiry has elapsed.
Fetch from the phpIPAM API, the subnets assigned to it. results are cached
Fetch ALL address' from phpIPAM API, that are assosiated with agent subnets. results are cached
For each network:
1. conduct Scan of network.
  Info
  
  The following details are included in the scan report:
  - IP Address
  - MAC Address* Only if the scanner is on the same L2 network (Broadcast Domain)
2. Re-format nmap scan report to format Server component recognizes.
3. upload scan report to configured Server.
workflow complete.

Remote network Scannning

Once the server component has been setup, the client can be installed/used from any network. Even a network that is isolated from the server. Only caveat is that the client can communicate with the server. To ensure that the client can connect to the server set the auth_token to match that of the server.

There is no true confirmation of the servers identity outside of confirming the TLS Certificate is trusted. Due to this fact, you're advised to use your own CA to sign the server components TLS Certificate. By doing this only you can issue a certificate to the server component. All that is required is to ensure that your CA certificate is within the trusted certificates of the machine that is running the agent.

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.

In an attempt to mitigate this, the scanner will fail to communicate with the server if you have set an auth_token and attempt non-TLS communication with the server.

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