NVSRCO/README.md

Development of a User-Friendly, Cost-Effective Network Situational Awareness and Vulnerability Scanner for Resource-Constrained Organizations

This project automates network discovery, port scanning, target creation, task management, and report generation using OpenVAS and Python scripts. It also includes a web application for visualizing reports and provides instructions for accessing OpenVAS via the web interface and API.

---

Prerequisites

1. Install Dependencies

Required Software

• Nmap: A network discovery and scanning tool. bash sudo apt install nmap # For Ubuntu/Debian brew install nmap # For MacOS
• Docker: Used to run OpenVAS as a containerized service.
  • Install Docker: Docker Installation Guide
  • Install Docker Compose: bash sudo apt install docker-compose # Ubuntu/Debian brew install docker-compose # MacOS

Python Libraries

Install the required Python libraries:

pip install pandas dash plotly gvm-tools psutil nmap

---

Project Setup

1. Setup OpenVAS with Docker

1. Navigate to the docker directory: bash cd docker
2. Build the OpenVAS Docker container: bash docker compose build
3. Start the OpenVAS container: bash docker compose up -d
4. Wait 30 minutes for OpenVAS to complete its database setup and updates.

Accessing OpenVAS

Web Interface

1. Open a browser and go to https://localhost:9392 (or replace localhost with your server’s IP address).
2. Log in using the default credentials:
   • Username: admin
   • Password: admin (or the password you set during installation).

Using the OpenVAS API

1. The OpenVAS API listens on port 9390 (default).
2. Use tools like gvm-cli or Python’s gvm-tools library to interact with the API.

Scripts Workflow

Run the scripts in the following order:

Step 1: Network Discovery

Run networkdiscovery.py to identify active hosts on the network:

sudo python networkdiscovery.py

This script:

• Uses Nmap to discover active hosts in your local network.
• Generates a CSV file named active_hosts.csv containing the discovered hosts.

---

Step 2: Port Scanning

Run portscanner.py to scan open ports on the discovered hosts:

sudo python portscanner.py

This script:

• Reads the active_hosts.csv file.
• Scans the specified ports for each host.
• Outputs results in ports.csv.

---

Step 3: Create Targets in OpenVAS

Run createtargets.py to create OpenVAS targets for each active host:

python createtargets.py

This script:

• Reads the active_hosts.csv file.
• Creates targets in OpenVAS for each discovered host.
• Outputs target IDs in target_id.csv.

---

Step 4: Create Tasks in OpenVAS

Run taskmaker.py to create OpenVAS tasks for each target:

python taskmaker.py

This script:

• Reads target_id.csv.
• Creates OpenVAS tasks using the “Full and Fast” scan configuration.
• Outputs task IDs in task_id.csv.

---

Step 5: Start Tasks in OpenVAS

Run starttask.py to start all the created OpenVAS tasks:

python starttask.py

This script:

• Reads task_id.csv.
• Starts each task in OpenVAS.

---

Step 6: Generate Reports

Run getreports.py to check task statuses and generate reports:

python getreports.py

This script:

• Checks the status of each task in task_id.csv.
• If a task is completed, generates a CSV report for the task.
• Combines all reports into a single consolidated file: consolidated_reports.csv.

---

Step 7: Launch the Web Application

Run webapp.py to launch the web interface for visualizing reports:

python webapp.py

This script:

• Starts a Dash web application.
• Access the web application at http://127.0.0.1:8050 or replace 127.0.0.1 with your server’s IP address.
• Visualize, filter, and analyze vulnerability data interactively.

---

File Outputs

Generated Files

1. active_hosts.csv:

   • Hosts discovered by networkdiscovery.py.
   • Format: csv IP,Discovery Timestamp 192.168.0.1,2024-11-20 15:16:09

2. ports.csv:

   • Open ports discovered by portscanner.py.
   • Format: csv IP,Port,Service 192.168.0.1,80,HTTP

3. target_id.csv:

   • Target IDs created by createtargets.py.
   • Format: csv IP,Target ID 192.168.0.1,abc123

4. task_id.csv:

   • Task IDs created by taskmaker.py.
   • Format: csv Target ID,Task ID abc123,task001

5. task_reports.csv:

   • Reports generated by getreports.py.
   • Format: csv Task ID,Report File task001,report_task001.csv

6. consolidated_reports.csv:

   • Combined report generated by getreports.py.
   • Format: csv Task ID,Host,Port,Vulnerability,Severity task001,192.168.0.1,80,Example Vulnerability,High

---

Usage Notes

• The OpenVAS database setup might take up to 30 minutes after starting the Docker container.
• Ensure task_id.csv exists before running starttask.py.
• The getreports.py script might take time to execute, depending on the number of tasks and their completion status.

---

Troubleshooting

Docker Issues

• If OpenVAS doesn’t start correctly, check Docker logs: bash docker logs <container_name>

OpenVAS Login Issues

• Ensure OpenVAS is running and accessible on port 9392.

Network Discovery Errors

• Ensure you have the necessary permissions to run Nmap with sudo.

---