DeltaScan is an advanced port scanning tool designed to detect and report changes in open ports and services over time. It offers scan results manipulation functionalities like export, import, differential check between scans and an interactive shell.
poetry install # globally
# or
poetry build # for current userSet alias in .zshrc or .bashrc to run dscan with sudo
alias ssdo="sudo -E env PATH=\${PATH} "
poetry shell
dscan -h
ssdo dscan -t <IP> -c <config_file> -p <Profile>
#
# or
#
ssdo poetry run dscan -t <IP> -c <config_file> -p <Profile>To reactivate the env shell:
source $(poetry env info --path)/bin/activateFor quick run after changes instead of re-building youcan run
ssdo poetry run python3 main.py -t <IP> -c <config_file> -p <Profile>In the future DeltaScan will be published on pip repository
usage: deltascan [-h] [-o OUTPUT] [-d DIFF_FILES] [--single] [--template TEMPLATE] [-i IMPORT_FILE] [-p PROFILE] [-c CONF_FILE] [-s] [--n-scans N_SCANS] [--n-diffs N_DIFFS] [--from-date FROM_DATE]
[--to-date TO_DATE] [--port-type PORT_TYPE] [-t HOST] [-it] [-db DB_PATH]
{scan,diff,view,import,version}
A package for scanning deltas
positional arguments:
{scan,diff,view,import,version}
the command to run
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
output file
-d DIFF_FILES, --diff-files DIFF_FILES
comma separated files to find their differences (xml)
--single if flag exists, it exports scans as single entries
--template TEMPLATE the html template file to generate .html and .pdf reports
-i IMPORT_FILE, --import IMPORT_FILE
import file (csv, xml). Csv must be generated by deltascan and XML must be generated by nmap
-p PROFILE, --profile PROFILE
select scanning profile that exists in config file or already in database
-c CONF_FILE, --conf-file CONF_FILE
path to configuration file
-v, --verbose verbose output
--n-scans N_SCANS limit of scans databse queries. It is applied in scans view as well as scans diff
--n-diffs N_DIFFS limit of the diff results
--from-date FROM_DATE
date of oldest scan to compare. eg: '2024-05-30 10:00:00' or '2024-05-30'
--to-date TO_DATE date of newest scan to compare. eg: '2024-06-30 10:00:00' or '2024-06-30'
--port-type PORT_TYPE
Type of port status (open,filter,closed,all)
-t HOST, --target HOST
select target host/subnet to scan
-it, --interactive execute action and go in interactive mode
-db DB_PATH, --db-path DB_PATH
set the sqlite database path
For generating pdf reports we use pdfkit library. In order for it to work you need to install wkhtmltopdf.
sudo apt-get install wkhtmltopdfexample_dscan_results_for_html_template.json is the schema of the dict that is stored in the database and exposed to be used inside your custom html template (see core/templates). Hence, these are the Nmap fields that are stored at the moment. More Nmap results are going to be added in future releases.
Run tests
pipenv run pytestThe configuration file contains a list of profiles (profile name and its arguments). Users can add new profiles in the config.yaml.
profiles:
TCP_PORTS_TOP_1000_NO_PING_NO_DNS:
arguments: "-sS -n -Pn -vv --top-ports 1000 --reason --open"
TCP_PORTS_FULL_NO_PING_NO_DNS:
arguments: "-sS -n -Pn -vv -p- --reason --open"
UDP_PORTS_TOP_1000_NO_PING_NO_DNS:
arguments: "-sU -n -Pn -vv --top-ports 1000 --reason --open"Scan hosts or subnets like nmap. Flag -p is the profile selection, where you can select a profile available from the given -c config.yaml or existing in the database. A given profile, given in the config file, is stored in the database and then used from there.
Scanning uses a target host, a configuration file, and a profile.
sudo -E env PATH=${PATH} deltascan scan -c config.yaml -p MY_PROFILE -t 192.168.0.100
sudo -E env PATH=${PATH} deltascan scan -c config.yaml -p MY_PROFILE -t 192.168.0.100/24
sudo -E env PATH=${PATH} deltascan scan -c config.yaml -p MY_PROFILE -t 192.168.0.100 -o export.<csv|pdf|html>
# The -s bool flag exports each scan in a separate file
sudo -E env PATH=${PATH} deltascan scan -c config.yaml -p MY_PROFILE -t 192.168.0.100 -s
# The below command uses a custom template file (it has to be an .html file)
sudo -E env PATH=${PATH} deltascan scan -c config.yaml -p MY_PROFILE -t 192.168.0.100 --template your_template.htmlListing the differences between scans is the next key feature. By providing a host and a profile, you can list all the differences that have occurred for the specific host and profile in the given time period specified by --from-date and --to-date. The scan comparison happens between every consecutive scan pair and is added to the diff list only if at least one added, changed, or removed key is found.
sudo -E env PATH=${PATH} deltascan diff -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" -t 192.168.0.100
sudo -E env PATH=${PATH} deltascan diff -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" -t 192.168.0.100/24
sudo -E env PATH=${PATH} deltascan diff -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" -t 192.168.0.100/24 -o export.<csv|pdf|html>
# The "--n-scans 20 --n-diffs -2" means "from below command mean from the last 20 scans show the latest differences"
sudo -E env PATH=${PATH} deltascan diff -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" --n-scans 20 --n-diffs -2 -t 192.168.0.100
# The below command uses a custom template file (it has to be an .html file)
sudo -E env PATH=${PATH} deltascan diff -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" --n-scans 20 --n-diffs -2 -t 192.168.0.100 --template your_template.htmlDiff raw, nmap, comma separated files and dump them in json file:
sudo -E env PATH=${PATH} deltascan diff --diff-files tcp_services_10.10.10.1.xml,tcp_services_10.10.10.2.xml -o dump.jsonListing scan results is a simple query to the deltascan database. The query takes into account the given parameters (host, profile, --from-date, --to-date, --port-type)
sudo -E env PATH=${PATH} deltascan view -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" -t 192.168.0.100
sudo -E env PATH=${PATH} deltascan view -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" -t 192.168.0.100/24
sudo -E env PATH=${PATH} deltascan view -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" -t 192.168.0.100/24 -o export.<csv|pdf|html>
# The below command brings only the open ports from the defined scans
sudo -E env PATH=${PATH} deltascan view -c config.yaml -p MY_PROFILE --from-date "2024-01-01 10:00:00" --to-date "2024-01-02 10:00:00" --port-type open -t 192.168.0.100
Importing nmap, raw, scan results.
sudo -E env PATH=${PATH} deltascan import -i raw_nmap_results.xmlImporting DeltaScan results from .csv file (probably from another DeltaScan database).
sudo -E env PATH=${PATH} deltascan import -i previous_exports.csvExporting the results of the operation requires just the flag -o or --output with a file name and an extension of pdf, html or csv. The csv results are the only output format (at the moment) that exports the whole, raw scan results and can be used to import the scans in another DeltaScan database.
html: Html reports are generated from the given template. The default templates are in deltascan/core/templates. There are two different template types, one for scan results and one for diff results. Custom templates can be provided using the flag --template <name_of_template_file>. The fields that DeltaScan exposes to be used inside the custom template, are shown in example_dscan_results_for_html_template.json for scan results and example_diff_results_for_html_templayte.json for diff results. To add fields in your custom template, use Jinja syntax.
pdf: Pdf reports are actually the html report converted to pdf, so html details are also applied here.
csv: Csv reports are actually database dumps. Database fields are exported as they are. The main use of a csv export is to use it as an import file to another DeltaScan database or (using a custom parser) to load it to another tool/application.
deltascan>: ? # Display help
Documented commands (type help <topic>):
========================================
clear diff exit imp q report view
conf diff_files help profiles quit scan
Interactive shell:
deltascan>: conf # Display current configuration
output_file: out_file.html
template_file: None
import_file: None
diff_files: None
n_scans: 1
n_diffs: 1
From date [fdate]: None
To date [tdate]: None
verbose: True
host: 0.0.0.0
profile: None
deltascan>: conf verbose=true # Modify configuration value
deltascan>: view # View result based on current configuration parameters
# ... Results ...
deltascan>: diff 1,2 # Difference between previous view results (always use verbose=False to find diff indexes)
deltascan>: imp nmap_dump_file.0.0.0.0.xml # Import nmap dump file
deltascan>: imp nmap_dump_file.0.0.0.0.csv # Import deltascan csv exported file
deltascan>: report # Report last results (must set an output_file before with: conf output_file=filename.(html|pdf|csv))
deltascan>: diff_files d1.xml,d2.xml # Differences between two nmap dump files
deltascan>: profiles # List profiles in database
deltascan>: scan 0.0.0.0 PROFILE # Scan with IP and profileRun mkdocs server:
pipenv run mkdocs serve