This is a development version, so includes source code with docker images. In future versions, source code will be contained within the images so that you only need the docker files and the images. RE has been primarily tested on Debian Linux and all instructions below assume a Debian environment.
- Prerequisites
- Getting Started
- Back Up/Restore
- Other Functions
- Development Guide
- Help Templates
- Technical Constraints
- Troubleshooting
Docker Engine (v20.10.12+) must be installed to run RE. It is recommended to install the latest version of Docker Engine.
Verify Docker Engine Version
Once docker is successfully installed, run the following command to verify that a compatible version is installed:
> docker versionDocker Compose (v2.2.3+) must be installed to run RE. It is recommended to install the latest version of Docker Compose.
Verify Docker Compose Version
Once docker compose is successfully installed, run the following command to verify that a compatible version is installed:
> docker compose versionPython (v3.8.0+) must be installed to run RE. In some cases, running the most up-to-date version of Python could present issues if the maintainers of this repository have not completed testing with the latest version. RE has been primarily tested using v3.8.0-3.11.2.
Verify Python Version
Once python is successfully installed, run the following command to verify that a compatible version is installed:
> python3 --version> git clone https://github.com/asmtlab/assessment-reporting-engine.git
> cd assessment-reporting-engineA python3 script ptp.py is included to automate various functions, including the set up, backup, restore, and tear down processes. In order to use the ptp.py script and set up RE, the following dependencies must be met (in addition to the prerequisites outlined in the previous section). Note that RE has only been tested with the following dependency versions and may not function correctly with other versions.
Any alternate versions of Node and NPM that may be running on the system where RE is being installed could conflict with RE set up. For that reason, it is recommended to purge any existing versions of Node and NPM if they are not needed. The following command will install Node and NPM:
> curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
> NODE_MAJOR=18
> echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
> apt-get update && apt-get install nodejs -y && apt-get install npm -yReboot system after installation.
Verify node and npm versions by running the following commands:
> node --version
> npm --versionThe following command will install Python3-Django:
> apt install python3-djangoVerify python3-django version by running the following command:
> python3 -m django --versionThe following command should be run from the root of the RE directory and will install TailwindCSS 3 dependencies (requires that a valid version of npm already be installed) - note that this installation is performed when the python3 ptp.py setup command is run.
> npm install -D node/dependencies/tailwindcss-3 --legacy-peer-depsThe following command should be run from the root of the RE directory and will install Vue.js 3 dependencies (requires that a valid version of npm already be installed) - note that this installation is performed when the python3 ptp.py setup command is run.
> npm install -D node/dependencies/components-vue3 --legacy-peer-depsThe following command can be run from the root of the RE directory to install the TailwindCSS 3 and Vue.js 3 dependencies (if this has not already been done manually per the last section):
> python3 ptp.py setupOnce all prerequisites and dependencies are met, an instance of RE can be spun up by running the following command (be sure to specify the correct assessment type with the -r flag):
> python3 ptp.py run -r [FAST/RPT/RVA]The default assessment type of the application is set to RVA in cases where an assessment type is not specified.
The application can be accessed at: https://localhost/ptportal
Superusers can access the admin interface by logging in and selecting their username from the account dropdown menu, then selecting Admin. Alternatively, the admin interface can be accessed at the following URL in development mode: https://localhost/admin
A back up ZIP file can be downloaded through the GUI by logging in and navigating to the Export page. The required Assessment Details fields must already be completed since the password set on that form is what is used to encrypt the ZIP file. Alternatively, the following command can be run to generate a backup ZIP (user will be prompted to enter a password to encrypt the file):
> python3 ptp.py backupIt is assumed that a copy of the assessment-reporting-engine directory (whether its backed up from the previous instance or a new copy) is on the system where RE is being restored. The version of RE must match the version the backup was generated from and the same assessment type from the previous instance must be specified with the -r flag. The following command will restore the RE instance from a backup ZIP file:
> python3 ptp.py restore -r [FAST/RPT/RVA] -b [/path/to/backup.zip]While the initial set up of RE involves internet connectivity, the application can be restored without internet connectivity (this requires the instance of RE being backed up to still be running normally).
This method involves a lot of overhead in terms of large files transferred between systems, so if internet connectivity is available on the system where RE is being restored, it is recommended to follow the Back Up for Online Restore and Restore Online steps:
> python3 ptp.py backup
> docker save prod-web > web.tar
> docker save prod-nginx > nginx.tar
> docker save prod-db > db.tarThe entire assessment-reporting-engine directory, including the web/nginx/db TAR files and the backup ZIP file must be transferred to the new system due to various dependencies and files that were generated with internet connectivity, and which cannot be re-generated in the offline environment. This will fulfill the TailwindCSS and Vue.js requirements, however, the system where RE is being restored must already meet all other prerequisites and dependency requirements.
Requirements:
- All prerequisites and dependency requirements are met on the new system
- Back Up for Offline Restore steps have been completed correctly
- All required files from the offline backup process are on the new system
Once the above requirements are met, the following commands can be run from the root of the transferred RE directory to restore the application:
> docker load < web.tar
> docker load < nginx.tar
> docker load < db.tar
> python3 ptp.py restore -r [FAST/RPT/RVA] -b [/path/to/backup.zip] -c offlineDuring set up, you will automatically be prompted to create a superuser. Once the application is running, users on networked machines can create their accounts with the sign up button on the login screen or an admin user can add accounts through the Admin panel. If additional superusers are needed, the following command can be run (user will be prompted to set a username and password for the new superuser):
> python3 ptp.py suThe password for an existing account can be changed by running the following command (user will be prompted to set a new password for the user):
> python3 ptp.py password -u [username]An account will be locked out after three failed attempts to prevent brute-force password attacks. The attempt count for all accounts can be reset by running the following command:
> python3 ptp.py resetLogs for each container can be viewed by running the following command (be sure to specify the container associated with the logs you wish to view):
> python3 ptp.py logs -c [db/nginx/web]To connect to a shell for a particular container, use the following command (be sure to specify the container associated with the shell you wish to connect to):
> python3 ptp.py shell -c [db/nginx/web]To pause an instance of Reporting Engine, run the following command (be sure to back up the instance first):
> python3 ptp.py pauseTo resume a paused instance of Reporting Engine, run the following command:
> python3 ptp.py resumeTo tear down the application, the following command can be run (note that this will remove all containers and their data - be sure to back up RE before tearing down):
> python3 ptp.py removeOnce all prerequisites and dependencies are met, a development instance of RE can be set up by mounting the code directory as a volume, allowing for live reload of most code changes in the application. A developer instance of RE can be spun up by running the following command:
> python3 ptp.py dev -r [FAST/RPT/RVA]The default assessment type of the application is set to RVA in cases where an assessment type is not specified.
The development instance of the application can be accessed at: http://localhost:8080/ptportal
Superusers can access the admin interface by logging in and selecting their username from the account dropdown menu, then selecting Admin. Alternatively, the admin interface can be accessed at the following URL in development mode: http://localhost:8080/admin
Additional development information coming soon
Help templates are provided as examples of the expected format of CSV files that are uploaded to RE, including sample data:
- emails.csv: CSV format for the emails upload function in the Open Source Information section of Report (RPT)
- domains.csv: CSV format for the domains upload function in the Open Source Information section of Report (RPT)
- payloads.csv: CSV format for the payloads upload function on the Payloads screen
In the current version, collaborating on the same screen as another user is not possible and could lead to overwriting another user's changes or other conflicts. If users are editing and saving separate screens or separate findings, this should not cause any issues. There are some file size and number constraints within the application to prevent poor performance and crashing.
It is recommended to refer to Docker and Django documentation for troubleshooting guidance. This section will be updated at a later time to reflect common issues.