From 47a1d93547756bdb5e90c61f31b020d5a09665e6 Mon Sep 17 00:00:00 2001 From: Jon Date: Mon, 26 Feb 2024 13:32:19 +0930 Subject: [PATCH 1/3] feat(docker): add trace output to determine install path for package !15 --- dockerfile | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dockerfile b/dockerfile index d0e923e..e3cd309 100644 --- a/dockerfile +++ b/dockerfile @@ -92,16 +92,18 @@ COPY includes/ / RUN mkdir -p /tmp/collection; \ if [ "$COLLECTION_PACKAGE" != "dev" ]; then \ - echo "specified"; \ + echo "[TRACE] Package Specified"; \ ansible-galaxy collection install --force-with-deps --pre \ $COLLECTION_PACKAGE; \ elif [ "$COLLECTION_PACKAGE" == "dev" ]; then \ + echo "[TRACE] Development Build"; \ git clone \ --depth=1 \ -b $COLLECTION_BRANCH \ https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent.git \ /tmp/collection; \ if [ "${COLLECTION_COMMIT}" != "none" ]; then git switch $COLLECTION_COMMIT; fi; \ + echo "[TRACE] Installing Development Build"; \ ansible-galaxy collection install --force-with-deps --pre \ /tmp/collection/.; \ rm -Rf /tmp/collection; \ From 3b6f2366029770289ed7570c3168be6aea56c559 Mon Sep 17 00:00:00 2001 From: Jon Date: Mon, 26 Feb 2024 14:41:31 +0930 Subject: [PATCH 2/3] feat(docker): update trusted CA certificates on start !15 closes #17 --- dockerfile | 1 + .../collection/phpipam_scan_agent/docker.md | 10 ++++- .../collection/phpipam_scan_agent/index.md | 2 +- .../collection/phpipam_scan_agent/scanner.md | 2 +- .../collection/phpipam_scan_agent/server.md | 2 +- .../projects/itil/runbooks/linux/custom_ca.md | 1 + includes/bin/update-ca | 40 +++++++++++++++++++ .../conf.d/update-ca-certificates.conf | 8 ++++ 8 files changed, 62 insertions(+), 4 deletions(-) create mode 100644 docs/projects/itil/runbooks/linux/custom_ca.md create mode 100755 includes/bin/update-ca create mode 100644 includes/etc/supervisor/conf.d/update-ca-certificates.conf diff --git a/dockerfile b/dockerfile index e3cd309..302c40a 100644 --- a/dockerfile +++ b/dockerfile @@ -109,6 +109,7 @@ RUN mkdir -p /tmp/collection; \ rm -Rf /tmp/collection; \ fi; \ chmod +x /etc/cron.d/*; \ + chmod +x /bin/update-ca; \ chown root:root -R /etc/phpipam; \ chmod 740 -R /etc/phpipam; diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/docker.md b/docs/projects/ansible/collection/phpipam_scan_agent/docker.md index c990645..1c0af49 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/docker.md +++ b/docs/projects/ansible/collection/phpipam_scan_agent/docker.md @@ -22,6 +22,7 @@ docker run \ -p "5000:5000" \ -v "./scan_agent.yaml:/etc/phpipam/scan_agent.yaml" \ -v "./scan_server.yaml:/etc/phpipam/scan_server.yaml" \ + -v "./my-custom-ca.crt:/usr/local/share/ca-certificates/my-custom-ca.crt:ro" --name scan-agent \ nofusscomputing/phpipam-scan-agent:latest; @@ -37,9 +38,16 @@ When viewing the container logs `docker logs `, what you will se 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. +### Custom CA Certificate + +When the container starts or restarts a script runs that updates the containers trusted CA certificates. Details for mounting a/an certificate(s) is detailed below. + + ### Volumes -You will need to configure the scan components: +To configure the components, the following files will need to be mounted within the container: + +- Custom CA certificate at path `/usr/local/share/ca-certificates/`. you can mount a single `crt` file or multiple if you use a sub-directory at this path. - scanner config file at path `/etc/phpipam/scan_agent.yaml`, see [scanner docs](scanner.md#variables) for details. diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/index.md b/docs/projects/ansible/collection/phpipam_scan_agent/index.md index 82bc806..b083e92 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/index.md +++ b/docs/projects/ansible/collection/phpipam_scan_agent/index.md @@ -54,7 +54,7 @@ The following features are available or planned to be implmented: - [Remote Network Scanning](scanner.md#remote-network-scannning) -- [Resolve DNS names](index.md#Resolve-dns-names) +- [Resolve DNS names](index.md#resolve-dns-names) - [Timezone Normalization](server.md#timezone-normalization) diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md b/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md index 7583449..a05911c 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md +++ b/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md @@ -100,7 +100,7 @@ The scanner component has the following workflow: Once the [server component](server.md#remote-network-scannning) 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. +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](docker.md#custom-ca-certificate) is within the [trusted certificates](../../../itil/runbooks/linux/custom_ca.md) of the machine that is running the agent. !!! danger "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. diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/server.md b/docs/projects/ansible/collection/phpipam_scan_agent/server.md index 1c68b86..7c802b9 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/server.md +++ b/docs/projects/ansible/collection/phpipam_scan_agent/server.md @@ -61,7 +61,7 @@ The Server componet has the following workflow: ## 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. +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](docker.md#custom-ca-certificate) to sign the TLS certificate. Just don't forget to add this CA certificate to the [trusted CA certificates](../../../itil/runbooks/linux/custom_ca.md) The [scan](scanner.md#remote-network-scannning) 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. diff --git a/docs/projects/itil/runbooks/linux/custom_ca.md b/docs/projects/itil/runbooks/linux/custom_ca.md new file mode 100644 index 0000000..fb975f5 --- /dev/null +++ b/docs/projects/itil/runbooks/linux/custom_ca.md @@ -0,0 +1 @@ +linked page \ No newline at end of file diff --git a/includes/bin/update-ca b/includes/bin/update-ca new file mode 100755 index 0000000..64487c3 --- /dev/null +++ b/includes/bin/update-ca @@ -0,0 +1,40 @@ +#!/bin/sh + +set -e; + +run_command() { + + command_date=$(date '+%Y-%m-%d %H:%M:%S'); + + echo "${command_date} - info - $1 - $2"; + + $1 + + if [ $? ]; then + + echo "${command_date} - info - $1 - command ran without error. exit=$?"; + + else + + echo "${command_date} - error - ${1} - command had an error. exit=$?"; + + fi + +} + + +while : +do + + run_command "ls -lR /usr/local/share/ca-certificates/" "List custom CA Certificates"; + + + run_command "update-ca-certificates --fresh" "Clear currently trusted CA Certificates"; + + + run_command "update-ca-certificates" "Update trusted CA Certificates"; + + + sleep 9999999999999; + +done; diff --git a/includes/etc/supervisor/conf.d/update-ca-certificates.conf b/includes/etc/supervisor/conf.d/update-ca-certificates.conf new file mode 100644 index 0000000..48de483 --- /dev/null +++ b/includes/etc/supervisor/conf.d/update-ca-certificates.conf @@ -0,0 +1,8 @@ +[program:trusted-ca-update] +startsecs=0 +stopwaitsecs=55 +command=/bin/update-ca +autorestart=true +autostart=true +stdout_logfile=/dev/stdout +stdout_logfile_maxbytes=0 \ No newline at end of file From 7c970d15218a3f1fb3ac4dd2e917a5e74dc2fc9b Mon Sep 17 00:00:00 2001 From: Jon Date: Mon, 26 Feb 2024 16:09:24 +0930 Subject: [PATCH 3/3] docs: fluffing with requirements and more details !15 --- docs/projects/ansible/collection/phpipam_scan_agent/index.md | 2 ++ .../projects/ansible/collection/phpipam_scan_agent/scanner.md | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/index.md b/docs/projects/ansible/collection/phpipam_scan_agent/index.md index b083e92..860909b 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/index.md +++ b/docs/projects/ansible/collection/phpipam_scan_agent/index.md @@ -25,6 +25,8 @@ A phpIPAM scan agent designed for both local and remote network scanning. This A 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. +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 diff --git a/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md b/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md index a05911c..bb2e3cb 100644 --- a/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md +++ b/docs/projects/ansible/collection/phpipam_scan_agent/scanner.md @@ -6,12 +6,12 @@ template: project.html about: https://gitlab.com/nofusscomputing/projects/ansible/collections/phpipam_scan_agent --- -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 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 -After installing the collection and configuring. Running the agent is as simple as running the following command: +Ensure that the `namp` package is installed, install and configure the collection. Running the agent is as simple as running the following command: ``` bash