Quick Start Guide

Follow these instructions to run the CyberGuard development server on your local environment and configure all active modules.

1. Prerequisites

Before launching, install and verify the following system versions on your local machine:

• Node.js: v18.0 or higher (Required for Express server operations and test execution).
• NPM: v9.0 or higher (Required for handling package dependencies).
• Docker Desktop: Required to run isolated security scanner containers (Nmap, ZAP, etc.).
• MySQL: v8.0 or higher (Required for persistent target records and projects caching).
• Redis: v6.2 or higher (Required for tracking background scanning tasks).

2. Environment Configuration

Create a local environment file by copying the template file:

# Copy environment template
cp .env.example .env

Open .env in your editor and configure the variables:

# Database Connection Setup
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cyberguard_pro
DB_USERNAME=root
DB_PASSWORD=your_secure_db_password

# Redis Cache and Queue Setup
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null

# Threat Intelligence APIs (Retrieve from respective provider portals)
VIRUSTOTAL_API_KEY=vt_token_here
ABUSEIPDB_API_KEY=abuseipdb_token_here
URLSCAN_API_KEY=urlscan_token_here
WHOISXML_API_KEY=whoisxml_token_here

# AI Assistant LLM Provider Keys
OPENROUTER_API_KEY=openrouter_token_here
GROQ_API_KEY=groq_token_here
JWT_SECRET=your_jwt_signing_key_here

3. Dependency Installation & Database Migrations

Install the required packages and seed the default schemas:

# Install node modules
npm install

# Run database migrations and seed default tiers
php artisan migrate --seed

4. Start the Application

Start the local Express development server to clean-route production URLs:

# Start development server
npm run dev

The console will log the local address mappings:

🛡️ CyberGuard — Local Dev Server
   http://127.0.0.1:5513

   Clean URLs active (mirrors Vercel production):
   http://127.0.0.1:5513/dashboard
   http://127.0.0.1:5513/pricing
   http://127.0.0.1:5513/docs
   http://127.0.0.1:5513/project-detail

5. Running the Testing Suite

CyberGuard includes a suite of unit and integration tests driven by Vitest to verify core frontend behaviors and calculators. To execute the tests, run:

# Run all tests in the workspace
npm test

# Run a specific unit test file (e.g. Password Entropy checks)
npx vitest run tests/unit/password-entropy-calculation.test.js

# Run integration tests to check state preservation
npx vitest run tests/unit/cyberguard-hashtools-preservation.test.js

Security Functions Testing Guide

Follow these step-by-step verification plans to test every security tool in the CyberGuard dashboard.

1. Dashboard Visuals & Reporting Tests

Scenario: Metrics Calculation & Gauge Updates

• Setup: Log in with a standard workspace containing target findings.
• Steps:
  1. Navigate to the **Security Dashboard**.
  2. Observe the Global Risk Score gauge and findings count cards.
  3. Add a target in projects and launch a mock scan that discovers critical issues.
• Expected Result: The "Critical Findings" card increments. The Global Risk Score gauge updates its circular path and transitions its color state to red.

Scenario: Audit Report Exporting (PDF & CSV)

• Setup: Ensure the dashboard displays findings under the recent findings table.
• Steps:
  1. Scroll to the recent findings section.
  2. Click the **Export PDF** button. Save the file.
  3. Click the **Export CSV** button. Save the file.
• Expected Result: The PDF generates using jspdf-autotable layout, displaying project metadata and structured tables. The CSV download initiates containing raw columns of target addresses, issue names, severities, and timestamps.

2. Web Auditing Tests

Scenario: SSL/TLS Certificate Check

• Input Target: https://badssl.com (Expired, invalid cert test target)
• Steps:
  1. Input the URL into the target config.
  2. Select the **SSL / TLS Certificate** card and click **Run Analysis**.
• Expected Result: Engine flags certificate expiration warning, identifies cipher suite vulnerabilities, and reports Grade F.

Scenario: URL Phishing ML Classifier

• Input URL: https://g00gle.com/login (Spoofed domain)
• Steps:
  1. Input the domain in the target input field.
  2. Select the **URL Phishing Analyzer** card and click **Run Analysis**.
• Expected Result: The machine-learning module calculates high string entropy, flags typosquatting mismatch indicators, and raises the threat score to High Risk (>90%).

Scenario: DNS Spoofing Integrity Check

• Input Target: https://google.com
• Steps:
  1. Select the **DNS Spoofing Detection** card.
  2. Click **Run Analysis**.
• Expected Result: Queries global authoritative NS records, verifies resolver consistency, confirms DNSSEC signatures match, and returns Safe status.

Scenario: VirusTotal Multi-Engine Scan

• Input Hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (Empty SHA-256 hash)
• Steps:
  1. Scroll down to the VirusTotal Intelligence card.
  2. Paste the hash into the input field and click **Check Hash**.
• Expected Result: The integration query returns details from VT engines, flagging 0 malicious reports.

3. Cryptography & Cipher Suite Tests

Scenario: Multi-Hash Parallel Generator

• Input Text: "CyberGuard"
• Steps:
  1. Navigate to the **Cipher Suite** tab.
  2. Type the string into the input area.
• Expected Result: MD5, SHA-1, SHA-256 (4b7b252bb88cf7...), and SHA-512 values display in parallel. Copying hashes copies the plain text digest strings to the clipboard.

Scenario: Password Entropy Analyzer

• Weak Input: "password123"
• Strong Input: "CGuard_2026_Secure!"
• Steps:
  1. Type both inputs into the analyzer field. Check composition checkboxes.
• Expected Result: The weak input fails composition checks, reports Low Strength, and shows a red progress bar. The strong input activates all checks (Numbers, Special Symbols, Case mix), calculates high entropy (>80 bits), and transitions the bar to green.

Scenario: Smart Hash Identifier

• Input Hash: 8743b52063cd84097a65d1633f5c74f5 (MD5 hash)
• Steps:
  1. Paste the hash into the Unknown Hash field.
• Expected Result: Algorithm automatically detects signature as MD5. Result states reasoning (Length: 32 hex characters, representation format).

Scenario: File Integrity Checks

• Steps:
  1. Drag and drop a local file into the integrity check dropzone.
  2. Observe the calculated SHA-256 hash output.
  3. Paste the matching hash into the expected field. Change a character in the expected field.
• Expected Result: Matching inputs display a green success status ("Hashes Match"). Modified expected inputs flag a red warning alert ("Hash Mismatch").

4. JWT Debugger & Editor Tests

Scenario: Decode and Validate Token

• Steps:
  1. Navigate to the **JWT Debugger** tab.
  2. Paste an encoded token into the Encoded Token area.
• Expected Result: Separates header (orange) and payload (purple). The JSON view displays formatted keys, and the claims tab parses expiration dates and issuer names.

Scenario: Modifying Claims and Re-Signing

• Steps:
  1. Switch mode to **JWT Encoder** or edit the JSON payload inside the decoder box.
  2. Change "role": "user" to "role": "admin".
  3. Enter secret_key in the sign panel and check the Base64 toggle.
• Expected Result: The Encoded JWT output update is triggered, generating a new signed token string containing the escalated admin role claim.

5. AI Assistant & Autopilot Tests

Scenario: Autopilot Command Routing

• Steps:
  1. Navigate to the **AI Assistant** tab.
  2. Enter command: "Switch to JWT Debugger tab" and send it.
• Expected Result: The assistant detects navigation intent, triggers autopilot routing, and changes active dashboard view to the JWT Debugger.

Scenario: Custom API Configuration Save

• Steps:
  1. Click the gear icon to open AI settings.
  2. Select **Groq API** and input a mock api key. Change temperature to 0.9. Click **Save Settings**.
• Expected Result: Settings panel collapses, values are saved locally, and subsequent requests route through the saved configuration parameters.

6. Threat Intelligence Search Tests

Scenario: IP Address Reputation Lookup

• Input Target: 185.220.101.5 (Known Tor exit node)
• Steps:
  1. Navigate to the **Threat Intel** tab.
  2. Enter the IP address in the search box and click **Search**.
• Expected Result: Verdict card displays "MALICIOUS". AbuseIPDB card displays a high abuse confidence score (>90%), logs reporting occurrences, and VT lists malicious node categories.

7. Projects & Scoping Tests

Scenario: Scope Target Configuration

• Steps:
  1. Navigate to the **Projects** tab.
  2. Click **New Project** and input details. Click on the project card.
  3. Click **Add Target**. Select type IP and enter 192.168.1.1. Click **Submit**.
• Expected Result: Target card renders under scoping. Historical table logs record insertion events.