phpIPAM Scan Agent

A phpIPAM scan agent designed for both local and remote network scanning. This Ansible Collection contains all of the componets required to launch a scan agent that will report back to the phpIPAM server. This collection is also built into it's own docker container and is available on Docker Hub.

This collection has been broken down into two components, a server and a scanner. The scanner as the name implies will scan the networks assigned to it by phpIPAM and on completing a scan of a subnet, will post the results to the Server component which will process the results, and update the phpIPAM MySQL/MariaDB database directly.

This agent has been created to solve a few shortcomings of the official scan-agent. Ansible was chosen as the tool for the creation of the scan-agent. This was done as it lowers the bar of entry to modifying and development. This as well as that Ansible is a mature automation system that has many modules. The latter offers a wide range of integrating different systems. The scanner component is just an ansible playbook, whilst the server is an ansilbe rulebook which is based upon Event Driven Ansible (EDA).

Installation

This collection is available on Ansible Galaxy and can be installed with ansible-galaxy collection install nofusscomputing.phpipam_scan_agent. When installing all of the required dependencies are installed.

Prefer to use our docker image? It's available on Docker Hub docker pull nofusscomputing/phpipam-scan-agent:latest.

There is no timezone support within phpIPAM. Due to this it's recommended that you setup phpIPAM, the database and the scanner component to use UTC (GMT +00:00) timezone or that all components be setup to use the same timezone.

Features

The following features are available or planned to be implmented:

Discover new hosts
ToDo Execute scan from remote host
ToDo Hosts check
ToDo Host Self-Update
MAC Address updating*

Info

It's only possible to obtain a MAC Address if the scanner is on the same L2 network (Broadcast Domain). Within the docs you will find the different methods available to achieve this.
Remote Network Scanning
Resolve DNS names
Timezone Normalization

phpIPAM Features

This section describes the phpIPAM settings and what they each do for the scanner/server component. Regardless of any setting detailed below, unless otherwise specified. If the scan agent is not assigned to the subnet, the subnet will not be scanned.

Discover new hosts

Location Subnet -> Discover new hosts

When this setting is enabled, the scanner will scan the entire subnet that has been assigned to it. Every host that is found is updated in phpIPAM.

Note

the work in Hosts check, will adjust this behaviour to only add hosts that dont exist.

Location Subnet -> Discover new hosts [Last discovery time]

This is displayed within the subnet interface next to the Discover new hosts field. Whenever a scan report is received by the server this filed is updated to reflect the last scan time.

Resolve DNS names

Location Subnet -> Resolve DNS names

When this setting is enabled, DNS resolution for the hostname for any IP found will be conducted. If you have setup nameservers (Administration -> Nameservers) and assigned them to the subnet, they will be used for name resolution. If no nameservers are configured for the subnet, the host's nameservers where the scanner is running from will be used. BY default within phpIPAM, DNS Resolution is turned off for a subnet and as such the scanner will not resolve IP address DNS names.

Info

The FQDN for an IP that is retured is not used as the hostname. Only the first octet. i.e. if the reverse DNS lookup returns a FQDN of my_hostname.domainname.tld, the hostname for the IP address will be set to my_hostname

Scan Agent

Location Administration -> Scan agents [Last access]

This is displayed within the Scan Agent table in column Last access. When ever the scanner checks in, the time of the checkin is used to update the field.

Location Subnet -> Scan agent [Last Check]

This is displayed within the subnet interface next to Scan agent field. When ever the scanner checks in, the time of the checkin is used to update the field.

Development Notes

Contributions to this project are welcome. Below you will find some useful commands for use during development.

# To build the container. ensure the changes are commited and push to you feature branch
docker build . --tag scan-agent:dev --build-arg  COLLECTION_BRANCH=<your feature branch name> --build-arg COLLECTION_COMMIT=$(git log -n1 --format=format:"%H")


# Launch your build container
docker run \
    -d \
    -v "./scan_agent.yaml:/etc/phpipam/scan_agent.yaml" \
    -v "./scan_server.yaml:/etc/phpipam/scan_server.yaml" \
    -e "ANSIBLE_LOG_PATH=/var/log/ansible.log" \
    -p "5000:5000" \
    --name scan-agent \
    scan-agent:dev;

# remove launched dev container
docker rm --force scan-agent

Our docker build file has been designed so that during development it will pull from the repository branch as specified to find the collection to install. if you fail to specify your feature branch, the collection will not install the work you have been doing.

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