Merge pull request #5 from LimberDuck/develop

v0.4.0

Author: damian-krawczyk

.github/workflows/python-package.yml

@@ -0,0 +1,47 @@
+name: Python package
+
+on:
+  push:
+    branches:
+      - develop
+      - master
+  workflow_dispatch:
+
+env:
+  python_package_name: nessus-file-reader
+  folder_package_name: nessus_file_reader
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: [3.7, 3.8, 3.9]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install tools
+        run: |
+          python -m pip install --upgrade pip build
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+      - name: Build package
+        run: python -m build
+
+      - name: Install locally
+        run: |
+          ls
+          ls dist
+          TOOL_CURRENT_VERSION=`sed -e 's/.*__version__ = "\(.*\)".*/\1/' ${{ env.folder_package_name }}/_version.py`
+          pip install dist/${{ env.folder_package_name }}-${TOOL_CURRENT_VERSION}-py3-none-any.whl
+        shell: bash
+      - name: pip show package
+        run: |
+          pip show ${{ env.python_package_name }}

.github/workflows/python-publish.yml

@@ -0,0 +1,36 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

CHANGELOG.md

@@ -5,6 +5,14 @@ This document records all notable changes to [nessus file reader by LimberDuck][
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2022-05-13
+
+### Added
+
+- **commandline interface** - from now on this package will provide you possibility to run `nfr` in commandline. After installation type `nf` or `nfr --help` to find out more.
+- **Tenable.io files support** - initial support to pars nessus files coming from Tenable.io
+
+
 ## [0.3.0] - 2020-07-25
 
 ### Added
@@ -26,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
+[0.4.0]: https://github.com/LimberDuck/nessus-file-reader/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/LimberDuck/nessus-file-reader/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/LimberDuck/nessus-file-reader/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/LimberDuck/nessus-file-reader/releases/tag/v0.1.0

README.md

@@ -0,0 +1,178 @@
+# nessus file reader
+
+**nessus file reader** by LimberDuck (pronounced *ˈlɪm.bɚ dʌk*) is a CLI tool 
+and python module created to quickly parse nessus files containing the results 
+of scans performed by using Nessus by (C) Tenable, Inc. This module will let 
+you get data through functions grouped into categories like file, scan, host 
+and plugin to get specific information from the provided nessus scan files.
+
+[![Latest Release version](https://img.shields.io/github/v/release/LimberDuck/nessus-file-reader?label=Latest%20release)](https://github.com/LimberDuck/nessus-file-reader/releases)
+[![GitHub Release Date](https://img.shields.io/github/release-date/limberduck/nessus-file-reader?label=released&logo=GitHub)](https://github.com/LimberDuck/nessus-file-reader/releases)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/nessus-file-reader?logo=PyPI)](https://pypistats.org/packages/nessus-file-reader)
+
+[![License](https://img.shields.io/github/license/LimberDuck/nessus-file-reader.svg)](https://github.com/LimberDuck/nessus-file-reader/blob/master/LICENSE)
+[![Repo size](https://img.shields.io/github/repo-size/LimberDuck/nessus-file-reader.svg)](https://github.com/LimberDuck/nessus-file-reader)
+[![Code size](https://img.shields.io/github/languages/code-size/LimberDuck/nessus-file-reader.svg)](https://github.com/LimberDuck/nessus-file-reader)
+[![Supported platform](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-lightgrey.svg)](https://github.com/LimberDuck/nessus-file-reader)
+
+## Main features
+
+* read data from nessus files containing results of scans performed by using Nessus by (C) Tenable, Inc.
+* use it in CLI or as python module
+
+> Check code [examples].
+
+
+## Installation
+
+> **Note:**
+> It's advisable to use python virtual environment for below instructions. Read more about python virtual environment in [The Hitchhiker’s Guide to Python!](https://docs.python-guide.org/dev/virtualenvs/)
+> 
+>Read about [virtualenvwrapper in The Hitchhiker’s Guide to Python!](https://docs.python-guide.org/dev/virtualenvs/#virtualenvwrapper): [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io) provides a set of commands which makes working with virtual environments much more pleasant.
+
+
+Install **nessus file reader**
+    
+`pip install nessus-file-reader`
+
+> To upgrade to newer version run:
+> 
+> `pip install -U nessus-file-reader`
+
+
+## Use
+
+### Use in CLI
+
+1. Run **nessus file reader**
+
+   `nfr`
+
+2. Check help for commands
+   
+   `nfr [command] --help` e.g. `nfr file --help`
+
+### Use as python module
+
+1. Import `nessus-file-reader` module.
+   
+```python
+import nessus_file_reader as nfr
+```
+
+2. Use `file` functions to get details about provided file e.g. root, file name, file size.
+   
+```python
+import nessus_file_reader as nfr
+
+nessus_scan_file = './your_nessus_file.nessus'
+root = nfr.file.nessus_scan_file_root_element(nessus_scan_file)
+file_name = nfr.file.nessus_scan_file_name_with_path(nessus_scan_file)
+file_size = nfr.file.nessus_scan_file_size_human(nessus_scan_file)
+print(f'File name: {file_name}')
+print(f'File size: {file_size}')
+```
+
+3. Use `scan` functions to get details about provided scan e.g. report name, number of target/scanned/credentialed hosts, scan time start/end/elapsed and more.
+
+```python
+import nessus_file_reader as nfr
+nessus_scan_file = './your_nessus_file.nessus'
+root = nfr.file.nessus_scan_file_root_element(nessus_scan_file)
+
+report_name = nfr.scan.report_name(root)
+number_of_target_hosts = nfr.scan.number_of_target_hosts(root)
+number_of_scanned_hosts = nfr.scan.number_of_scanned_hosts(root)
+number_of_scanned_hosts_with_credentialed_checks_yes = nfr.scan.number_of_scanned_hosts_with_credentialed_checks_yes(root)
+scan_time_start = nfr.scan.scan_time_start(root)
+scan_time_end = nfr.scan.scan_time_end(root)
+scan_time_elapsed = nfr.scan.scan_time_elapsed(root)
+print(f' Report name: {report_name}')
+print(f' Number of target/scanned/credentialed hosts: {number_of_target_hosts}/{number_of_scanned_hosts}/{number_of_scanned_hosts_with_credentialed_checks_yes}')
+print(f' Scan time START - END (ELAPSED): {scan_time_start} - {scan_time_end} ({scan_time_elapsed})')
+```
+
+4. Use `host` functions to get details about hosts from provided scan e.g. report hosts names, operating system, hosts scan time start/end/elapsed, number of Critical/High/Medium/Low/None findings and more.
+
+```python
+import nessus_file_reader as nfr
+nessus_scan_file = './your_nessus_file.nessus'
+root = nfr.file.nessus_scan_file_root_element(nessus_scan_file)
+
+for report_host in nfr.scan.report_hosts(root):
+   report_host_name = nfr.host.report_host_name(report_host)
+   report_host_os = nfr.host.detected_os(report_host)
+   report_host_scan_time_start = nfr.host.host_time_start(report_host)
+   report_host_scan_time_end = nfr.host.host_time_end(report_host)
+   report_host_scan_time_elapsed = nfr.host.host_time_elapsed(report_host)
+   report_host_critical = nfr.host.number_of_plugins_per_risk_factor(report_host, 'Critical')
+   report_host_high = nfr.host.number_of_plugins_per_risk_factor(report_host, 'High')
+   report_host_medium = nfr.host.number_of_plugins_per_risk_factor(report_host, 'Medium')
+   report_host_low = nfr.host.number_of_plugins_per_risk_factor(report_host, 'Low')
+   report_host_none = nfr.host.number_of_plugins_per_risk_factor(report_host, 'None')
+   print(f'  Report host name: {report_host_name}')
+   print(f'  Report host OS: {report_host_os}')
+   print(f'  Host scan time START - END (ELAPSED): {report_host_scan_time_start} - {report_host_scan_time_end} ({report_host_scan_time_elapsed})')
+   print(f'  Critical/High/Medium/Low/None findings: {report_host_critical}/{report_host_high}/{report_host_medium}/{report_host_low}/{report_host_none}')
+```
+
+5. Use `plugin` functions to get details about plugins reported in provided scan e.g. plugins ID, plugins risk factor, plugins name.
+
+```python
+import nessus_file_reader as nfr
+nessus_scan_file = './your_nessus_file.nessus'
+root = nfr.file.nessus_scan_file_root_element(nessus_scan_file)
+
+for report_host in nfr.scan.report_hosts(root):
+   report_items_per_host = nfr.host.report_items(report_host)
+   for report_item in report_items_per_host:
+      plugin_id = int(nfr.plugin.report_item_value(report_item, 'pluginID'))
+      risk_factor = nfr.plugin.report_item_value(report_item, 'risk_factor')
+      plugin_name = nfr.plugin.report_item_value(report_item, 'pluginName')
+      print('\t', plugin_id, '  \t\t\t', risk_factor, '  \t\t\t', plugin_name)
+```
+
+6. If you want to get output for interesting you plugin e.g. "Nessus Scan Information" use below function
+
+```python
+import nessus_file_reader as nfr
+nessus_scan_file = './your_nessus_file.nessus'
+root = nfr.file.nessus_scan_file_root_element(nessus_scan_file)
+
+for report_host in nfr.scan.report_hosts(root):
+   pido_19506 = nfr.plugin.plugin_output(root, report_host, '19506')
+   print(f'Nessus Scan Information Plugin Output:\n{pido_19506}')
+```
+
+7. If you know that interesting you plugin occurs more than ones for particular host e.g. "Netstat Portscanner (SSH)" use below function
+
+```python
+import nessus_file_reader as nfr
+nessus_scan_file = './your_nessus_file.nessus'
+root = nfr.file.nessus_scan_file_root_element(nessus_scan_file)
+
+for report_host in nfr.scan.report_hosts(root):
+   pidos_14272 = nfr.plugin.plugin_outputs(root, report_host, '14272')
+   print(f'All findings for Netstat Portscanner (SSH): \n{pidos_14272}')
+```
+
+## Meta
+
+### Change log
+
+See [CHANGELOG].
+
+### Licence
+
+GNU GPLv3: [LICENSE].
+
+### Authors
+
+[Damian Krawczyk] created **[nessus file reader]** by [LimberDuck].
+
+[nessus file reader]: https://limberduck.org/en/latest/tools/nessus-file-reader
+[Damian Krawczyk]: https://damiankrawczyk.com
+[LimberDuck]: https://limberduck.org
+[CHANGELOG]: https://github.com/LimberDuck/nessus-file-reader/blob/master/CHANGELOG.md
+[LICENSE]: https://github.com/LimberDuck/nessus-file-reader/blob/master/LICENSE
+[examples]: https://github.com/LimberDuck/nessus-file-reader/tree/master/examples