Platform User Guide

1. Platform Overview

The IoT Security Audit Tool by Novexis App is a comprehensive platform for discovering, auditing, and securing Internet of Things (IoT) devices on your network. It combines automated network scanning, CVE vulnerability database lookups, AI-powered analysis, and professional reporting into a single cross-platform solution.

Core Components

AI Model Architecture

The platform uses a dual-AI architecture for resilience:

• Primary Model: DeepSeek AI — handles vulnerability analysis, remediation planning, and configuration recommendations.
• Backup Model: Google Gemini 2.5 — automatically takes over if DeepSeek is unavailable or fails.
• Failover: The AI Agent automatically routes requests to the backup model if the primary call fails. No user intervention required.

2. Installation & System Requirements

System Requirements

Installation Steps

1. Ensure Python 3.11+ is installed: python --version
2. Download or clone the repository:

   git clone https://github.com/JohnWW11/iotsecurityaudittool.git
   cd iotsecurityaudittool

3. Install dependencies:

   pip install -r requirements.txt

4. Initialize the application:

   python src/main.py

Optional Dependencies

3. Getting Started

First Launch

When you launch the application for the first time, you will see the Welcome/Login dialog:

1. Enter your email address (required for license association).
2. Enter a license key (optional — skips to free Starter plan if blank).
3. Click "Start Free Trial" or "Continue with Free Starter Plan".

Recommended First Steps

4. Desktop Application

Main Window Layout

• Left Sidebar: Navigation menu with Dashboard, Device Discovery, Vulnerabilities, Firmware Advisor, Security Quiz, and Settings.
• Top Bar: Current page title and scan status indicator.
• Main Content Area: The active module's interface.
• Status Bar: System status, device count, and current operation feedback.

Sidebar Navigation

5. Device Discovery & Profiling

Running a Network Scan

1. Navigate to Device Discovery tab.
2. Configure the target subnet (e.g., 192.168.1.0/24).
3. Customize port range if needed (default covers 40+ common IoT ports).
4. Select scanning engine: Scapy (pure Python) or Nmap (external).
5. Click "Scan Network".

What Gets Discovered

The scanner identifies for each device:

• IP Address & MAC Address — unique identifiers
• Vendor/Manufacturer — via MAC OUI lookup (250+ known IoT vendors)
• Device Type — classified into 20+ categories (IP Camera, Router, Smart Speaker, Industrial IoT, etc.)
• Open Ports & Services — scanned across common IoT ports
• Operating System — TTL-based OS fingerprinting
• Risk Score — calculated based on open ports, device type, and vulnerabilities (0-10 scale)

Device Detail Panel

Click any device row to view its full profile including CVE assessment, firmware status, threat port descriptions, and remediation tips — all in the right-side detail panel.

6. Vulnerability Detection

CVE Database System

The platform uses a dual-database approach:

• Curated Local Database: 30+ hand-picked critical IoT CVEs (Log4Shell, EternalBlue, Mirai-related, Hikvision/Dahua backdoors, TP-Link command injection, and more). Available on all plans including Starter.
• Live NVD API: Real-time queries to the National Vulnerability Database at services.nvd.nist.gov. Professional and Enterprise plans only.

Running a Vulnerability Assessment

1. Ensure a network scan has been completed (devices must be in the discovery list).
2. Navigate to Vulnerabilities tab.
3. Click "Run Vulnerability Assessment".
4. Review results in the table (CVE ID, Severity, CVSS Score, Description, Remediation).
5. Click "AI Analysis" (Pro/Enterprise) for intelligent prioritization and analysis.

CVSS Severity Scale

7. AI-Powered Analysis

Configuring AI Models

1. Navigate to Settings → API Keys & AI.
2. Enter your DeepSeek API Key (get from platform.deepseek.com).
3. Enter your Google Gemini API Key (get from aistudio.google.com).
4. Click "Save API Keys". Keys are encrypted at rest using Fernet encryption.

AI Capabilities

Failover Behavior

The AI Agent first attempts to use DeepSeek. If the call fails (network error, rate limit, API outage), it automatically retries with Gemini 2.5. Both attempts must fail for the system to report an error.

8. Firmware Management

Checking Firmware Versions

1. Navigate to Firmware Advisor tab.
2. Click "Check Firmware Updates".
3. Review the table showing Current Version vs. Latest Version for each device.
4. Devices with "OUTDATED" status require immediate attention.

Firmware Database Coverage

The tool includes a curated database covering popular IoT vendors:

• IP Cameras: Hikvision, Dahua, Axis
• Networking: Ubiquiti, TP-Link, Netgear, ASUS, D-Link, MikroTik
• Smart Home: Sonos, Philips Hue, Synology, QNAP
• Embedded: Raspberry Pi, ESP32/ESP8266

Generating Configuration Recommendations

Click "Generate Recommendations" to produce a markdown-formatted list of device-type-specific and port-specific security recommendations. Click "AI Configuration Advice" for AI-generated hardening guidance.

9. QR & Barcode Scanning

Supported Barcode Types

The scanner supports QR Code, Code128, Code39, EAN-13, EAN-8, UPC-E, PDF417, Aztec, and Data Matrix formats.

Scanning Methods

1. Live Camera Feed: Click "QR/Barcode Scan" → select "Live Camera" → point at a code.
2. Image Import: Click "QR/Barcode Scan" → select "Import Image" → choose a file.

Parsing Scanned Data

The scanner automatically parses:

• Serial numbers (prefixed with S/N: or SN:)
• URLs (starting with http: or www.)
• Alphanumeric identifiers (used as serial numbers)
• Generic data (stored as raw text)

10. Generating Reports

Report Formats

• HTML Report: Interactive, opens in your default browser. Includes executive summary cards, device inventory table, vulnerability details, and remediation plan.
• PDF Report: Professional document suitable for compliance submission. Generated using reportlab with branded styling.

How to Generate

1. Complete a network scan and vulnerability assessment.
2. From the Dashboard: Click "Generate Report".
3. From the Vulnerability Report: Click "Export Report".

Report Contents

• Executive Summary: Total devices, vulnerabilities by severity, average CVSS, scan duration.
• Device Inventory: IP, MAC, vendor, device type, risk level, open ports for every discovered device.
• Vulnerability Details: CVE ID, CVSS score, description, affected devices, remediation steps.
• Remediation Plan: AI-generated prioritized action items with effort estimates.

11. Web Portal & Account Management

Website Sections

Account Registration & Login

1. Navigate to Sign Up (/signup).
2. Enter your full name and email address.
3. Choose a password (min. 8 characters, include a number).
4. Accept the Terms of Service and Privacy Policy.
5. Click "Create Account" — a verification email is sent to your registered email.
6. After verification, Log In (/login) with your credentials.

Onboarding Flow

Logging Out

Once signed in, a "Log Out" button appears in the navigation bar on all pages. Clicking it:

1. Clears the local session (sessionStorage).
2. Updates the navigation bar to show "Log In" and "Sign Up" again.
3. Redirects to the Home page.

12. Admin Dashboard

Purpose

The Admin Dashboard (/admin) provides Novexis App staff with tools for:

• Account search, filtering, and management
• Subscription status monitoring (active, trial, expired, suspended)
• Troubleshooting — resend activation emails, reset licenses, extend trials, unlock accounts
• System activity log review
• Recent scan monitoring across all users

Admin Authentication

The Admin Dashboard uses two environment variables for secure access:

# .env file — located in the application data directory

ADMIN_API_KEY=admin-secret-api-key-for-dashboard-access
ADMIN_SESSION_SECRET=your-admin-session-secret-here

ADMIN_API_KEY

This key authenticates administrative API requests from the dashboard to the backend. When an admin performs an action (e.g., "Suspend Account", "Extend Trial"), the dashboard includes this key in the request header. The backend validates it against the stored value before processing the action. Generate a strong, unique key — treat it like a root password.

ADMIN_SESSION_SECRET

This secret is used to sign and verify admin session tokens. When an administrator logs into the dashboard, a session token is created and signed with this secret using HMAC. Every subsequent request includes this token, and the backend verifies the signature to confirm the admin is authenticated. Generate a random, high-entropy secret — if compromised, all admin sessions must be invalidated.

How to Configure Admin Access

1. Open the .env file in the application data directory.
2. Set a strong ADMIN_API_KEY — minimum 32 characters, random string:

   ADMIN_API_KEY=xK9mP2vL7nQ4wR8tY1bN6aD3fH5jU0sG

3. Set a strong ADMIN_SESSION_SECRET — minimum 32 characters, random string:

   ADMIN_SESSION_SECRET=cM8wR2tY5nA1bD6fH3jU0sK9mP4vL7qX

4. Restart the application for changes to take effect.

Admin Logout

The Admin Dashboard includes a distinct "Log Out" button in the top navigation. When clicked, it destroys the admin session token and redirects to the login page. Admin sessions automatically expire after 2 hours of inactivity. On logout, the following occurs:

• The signed session cookie/header is cleared
• The admin is redirected to the standard login page
• The activity log records the logout event with a timestamp

13. Mobile Companion App

Availability

The mobile companion app is available to Enterprise plan subscribers only on both iOS and Android platforms. It is built with React Native (Expo) and provides field technician tools for on-site device inventory.

Key Mobile Features

• QR/Barcode Scanning: Native camera scanning of device serial numbers, MAC addresses, and asset tags.
• Desktop Sync: Scanned devices automatically sync to the desktop application over the local network.
• Location Tagging: Assign physical locations to devices as you scan them.
• Offline Mode: Scan history stored locally; syncs when reconnected.
• 3-Tab Interface: Scanner (live camera), History (past scans), Info (app settings).

Mobile Logout

The mobile companion includes a logout function accessible from the Info/Settings tab. This clears the local session and returns the user to the startup screen.

14. Subscription Plans & Billing

Payment Processing

The platform supports payments via Stripe and PayPal. Configure your payment credentials in the .env file:

STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-client-secret
PAYPAL_MODE=live

15. API Key Configuration

Required Keys (for full functionality)

16. Security & Data Privacy

Data Storage

• Scan data: Stored locally in your machine's app data directory in an SQLite database. No scan results are transmitted to Novexis servers.
• API keys: Encrypted at rest using Fernet (AES-128 in CBC mode, PKCS7 padding).
• License data: Encrypted at rest.
• Reports: Generated and stored locally.

What We Never Collect

• Your network scan results or device information
• IP addresses, MAC addresses, or hostnames
• Vulnerability assessment data
• Network topology or configuration
• Firmware versions or serial numbers

Third-Party Data Sharing

When using AI analysis or live CVE lookups, vulnerability-related queries (not raw scan data) may be sent to DeepSeek, Google, or NVD APIs. No device identifiers or network topology data is shared with third parties.

17. Troubleshooting

Common Issues

App crashes on startup

• Verify Python 3.11+ is installed: python --version
• Reinstall dependencies: pip install -r requirements.txt --force-reinstall
• Check the log file: %APPDATA%/.iot-security-audit/logs/app.log

Network scan finds no devices

• Run as Administrator/root for raw socket access.
• Verify the subnet is correct (run ipconfig / ifconfig to check).
• Ensure your firewall allows outbound ARP/ICMP traffic.
• Try switching between Scapy and Nmap scanning engines.

QR scanner not working

• Install OpenCV and pyzbar: pip install opencv-python pyzbar
• On Linux, install libzbar0: sudo apt install libzbar0
• Ensure your webcam is connected and not in use by another application.

AI analysis fails

• Verify your API keys are configured correctly in Settings or .env.
• Check your internet connection.
• Ensure your subscription plan includes AI access (Pro or Enterprise).
• Check the fallback — if DeepSeek fails, Gemini should automatically take over.

Cannot log in to web portal

• Ensure you've verified your email address (check spam folder).
• Use the Forgot Password link on the login page — reset is sent to registered email only.
• Contact support@cs-e-shop.com if issues persist.

License not activating

• Verify the license key format matches your plan tier.
• Ensure the machine ID hasn't changed (license is tied to hardware).
• Contact support for license reset or reissue.

Admin Dashboard access denied

• Ensure ADMIN_API_KEY and ADMIN_SESSION_SECRET are properly set in .env.
• The admin session may have expired — sign in again.
• Verify the keys have not been rotated without updating your session.

Support Channels

Email: support@cs-e-shop.com
Phone: 800-414-1059 (Mon–Fri, 9 AM–6 PM EST)
Web: Contact Form