ansible-collections/phpipam_scan_agent
2
0
Fork 0
Code Issues 10 Pull Requests Actions Projects Releases 7 Wiki Activity

docs: further work on completing

Browse Source 
!1
This commit is contained in:
Jon Lockwood
2024-02-21 15:25:25 +09:30
parent 52b576be80
commit 565eba3d0d
4 changed files with 135 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/projects/ansible/collection/phpipam_scan_agent/docker.md
View File

@ -8,6 +8,8 @@ about: https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_s
The Scan Agent Docker container has the Ansible collection installed which when launched will by default, start a Scan Server and scanner. The components running inside the container can be customised to suit different use cases.
The Container has been setup to use supervisord, with the server and cron setup as the two available services. Due to the simplicity of supervisord, the container does have a healthcheck, that on failure means one or both of the services have failed.
## Usage
@ -26,11 +28,28 @@ docker run \
-e "SCANNER_CODE=<your value here>" \
-p "5000:5000" \
--name scan-agent \
scan-agent:dev;
scan-agent:latest;
```
Variables must still be set for the running container, please review the [Scanner](scanner.md) or [Server](server.md) documentation as appropriate.
### Logs
when viewing the container logs `docker logs <container name>`, what you will see is the Server component logs. This is by design. If however you are also running the scanner component, as is the default. To view those logs you will need to ensure that when launching the container that you specify environmental variable `ANSIBLE_LOG_PATH=/var/log/ansible.log`. This tells the scanner component to log to file at path `/var/log/ansible.log`.
When viewing the container logs `docker logs <container name>`, what you will see is the Server component logs. This is by design. If however you are also running the scanner component, as is the default. To view those logs you will need to ensure that when launching the container that you specify environmental variable `ANSIBLE_LOG_PATH=/var/log/ansible.log`. This tells the scanner component to log to file at path `/var/log/ansible.log`.
During the build of the container environmental variable `ANSIBLE_FORCE_COLOR='true'` is set, this enables the playbooks to be in colour when viewing the container logs. If this is not desired, set the variable to `ANSIBLE_FORCE_COLOR='false'` when launching the container.
### Volumes
There are no volumes for this container.
If you wish to customize the cronjob for the scan component within the container, mount a new cron file to path `/etc/cron.d/scanner`. The default cron file is as follows:
``` yaml title="/etc/cron.d/scanner" linenums="1"
--8<-- "includes/etc/cron.d/scanner"
```

39
docs/projects/ansible/collection/phpipam_scan_agent/index.md
View File

@ -21,22 +21,24 @@ about: https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_s
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](https://hub.docker.com/r/nofusscomputing/phpipam-scan-agent).
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 collection has been broken down into two components, a [server](server.md) and a [scanner](scanner.md). 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.
## 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`.
Prefer to use our [docker](docker.md) image? It's available on Docker Hub `docker pull nofusscomputing/phpipam-scan-agent:latest`.
## Features
Currenty this collection has the following features:
The following features are available or planned to be implmented:
- Discover new hosts
- [**ToDo** Execute scan from remote host](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/7)
- [**ToDo** Hosts check](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/3)
- [**ToDo** Host Self-Update](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/2)
@ -50,3 +52,34 @@ Currenty this collection has the following features:
- [**ToDo** Resolve DNS names](https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent/-/issues/4)
## Development Notes
Contributions to this project are welcome. Below you will find some useful commands for use during development.
``` bash
# 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 \
-e "API_URL=<your value here>" \
-e "MYSQL_HOST=<your value here>" \
-e "MYSQL_USER=<your value here>" \
-e "MYSQL_PASSWORD=<your value here>" \
-e "SCANNER_TOKEN=<your value here>" \
-e "SCANNER_NAME=<your value here>" \
-e "SCANNER_CODE=<your value here>" \
-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.

33
docs/projects/ansible/collection/phpipam_scan_agent/scanner.md
View File

@ -22,6 +22,7 @@ ansible-playbook nofusscomputing.phpipam_scan_agent.agent \
--extra-vars "scanagent_code=<your value here>"
```
_See below for the variable details_
@ -30,6 +31,7 @@ _See below for the variable details_
The variables described below, if optional the value specified here is the default value. Any variable that can be set via environmental variables have the variable name enclosed in `[]`
``` yaml
client_token: "" # Mandatory, String client api token to connect to phpIPAM API [SCANNER_TOKEN]
client_name: "" # Mandatory, String. The scanner name as set in phpIPAM interface [SCANNER_NAME]
scanagent_code: "" # Mandatory, String. Scan Agent Code as set in phpIPAM interface [SCANNER_CODE]
@ -46,3 +48,34 @@ nfc_c_cache_expire_time: 1800 # Optional, Integer. Time in seconds to e
nfc_c_epoch_time_offset: 0 # optional, int. Value in seconds to offset the time
```
!!! 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`
## Workflow
The scanner component has the following workflow:
1. Expire cache, if cache expiry has elapsed.
1. Fetch from the phpIPAM API, the subnets assigned to it. _results are cached_
1. Fetch ALL address' from phpIPAM API, that are assosiated with agent subnets. _results are cached_
1. 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)_
1. Re-format nmap scan report to format Server component recognizes.
1. upload scan report to configured Server.
1. workflow complete.

45
docs/projects/ansible/collection/phpipam_scan_agent/server.md
View File

@ -8,4 +8,49 @@ about: https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_s
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:
``` bash
ansible-rulebook -r nofusscomputing.phpipam_scan_agent.agent_receive
```
### Variables
The variables described below, if optional the value specified here is the default value. All variables that are used by the server component are environmental variables that must be set before execution.
``` bash
# 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.
```
# Workflow
The Server componet has the following workflow:
1. Receive the Scanner component report.
1. check if the Scanner Code is in the DB
- _if no results found, no further processing occurs_
1. Confirm the subnet scanned is assigned to the scanner
- _if no results found, no further processing occurs_
1. Update the phpIPAM MariaDB/MySQL database directly