SecureScan Hub 🛡️

SecureScan Hub is a centralized, web-based Security Operations Center (SOC) dashboard and backend orchestration platform. It provides a single interface for running static application security testing (SonarQube, Semgrep, Trivy FS), container audits (Trivy Image), dynamic web application scanning (OWASP ZAP, Nikto, Nuclei), and supplementary heuristic checks.

---

🌟 Key Features

• Centralized Orchestration: Trigger multi-tool security audits against source code directories, web application URLs, and container images from a unified interface.
• Scanner Adapter Architecture: Isolated runners supporting Native Windows CLI, Docker Run (ephemeral containers), and Docker Exec (existing running DevSecOps containers).
• Transparent Capability Detection: Real security tools are prioritized. If a native binary or container is missing, its status is explicitly marked as Tool Unavailable (Not Installed) rather than silently masked.
• Unified Finding Normalizer: Converts heterogeneous raw scanner outputs (JSON, SARIF, XML) into a standard schema containing Tool, Severity, Rule ID, CVE ID, CWE, OWASP Top 10 category, evidence code snippets, and step-by-step remediation advice.
• Structured Report Directory: Automatically creates timestamped folders with isolated scanner subdirectories alongside metadata.json and scan-summary.json:

  SecurityScans/
  └── Scan_YYYY-MM-DD_HHMMSS/
      ├── metadata.json
      ├── scan-summary.json
      ├── SonarQube/
      ├── Semgrep/
      ├── Trivy-FS/
      ├── Trivy-Image/
      ├── OWASP-ZAP/
      ├── Nikto/
      ├── Nuclei/
      └── Basic-Heuristic/
  

• Real-time Console Stream: Streaming Server-Sent Events (SSE) log terminal tracking active scanner execution step-by-step.
• Security Hardened: Built-in SSRF protections against cloud metadata IP endpoints (169.254.169.254) and path traversal sanitization.
• Interactive Finding Inspector: Click any vulnerability row in the findings table to open a detailed drawer modal with code line snippets, evidence, and a one-click Copy Fix Code button.

---

🏗️ System Architecture & Execution Logic

   [User Configuration]
     ├── Target Directory Path
     ├── Target Web Application URL
     └── Container Image Tag
               │
               ▼
   [Capability Check]  ────────► (Checks Native CLI & Docker Containers)
               │
               ▼
   [Execution Policy] ────────► (Auto / Native CLI / Docker Exec / Docker Run)
               │
               ▼
   [Scanner Adapter Matrix]
     ├── SemgrepAdapter        (SAST)
     ├── TrivyAdapter          (FS & Image CVEs + SBOM)
     ├── NucleiAdapter         (DAST Templates)
     ├── NiktoAdapter          (Web Server Audit)
     ├── ZapAdapter            (OWASP ZAP Baseline)
     ├── SonarAdapter          (SonarQube Server / CLI)
     └── HeuristicAdapter      (Supplementary Secret & Header Rules)
               │
               ▼
   [Normalizer Engine] ───────► Unified Finding Schema (CVE, CWE, OWASP)
               │
               ▼
   [Report Store]     ───────► D:\SecurityScans\Scan_YYYY-MM-DD_HHMMSS\
               │
               ▼
   [SOC Dashboard]    ───────► Interactive Metrics, Filters & Finding Inspector

---

⚡ Quick Start

Prerequisites

• Node.js: v18.0.0 or higher
• npm: v9.0.0 or higher
• (Optional) Native security CLI binaries (semgrep, trivy, nuclei, nikto, zap, sonar-scanner) or Docker Desktop.

1. Clone & Install Dependencies

git clone https://github.com/Nurfish06/SecureScan-Hub.git
cd "SecureScan Hub"
npm install

2. Configure Environment (Optional)

Copy .env.example to .env to configure custom report output directories, backend ports, or custom Docker container names:

cp .env.example .env

3. Run Development Environment

npm run dev

• Frontend Dashboard: http://localhost:5173
• Backend API Server: http://localhost:5000

---

⚙️ Environment Configuration (.env)

Variable	Default Value	Description
PORT	5000	Express API server listening port
SCANS_OUTPUT_DIR	D:\SecurityScans	Base directory for generated scan report folders
SONAR_CONTAINER_NAME	devsecops-sonarqube	Existing Docker container name for SonarQube
SONAR_URL	http://localhost:9000	SonarQube server endpoint
SEMGREP_CONTAINER_NAME	devsecops-semgrep	Existing Docker container name for Semgrep
ZAP_CONTAINER_NAME	devsecops-zap	Existing Docker container name for OWASP ZAP
ZAP_PORT	8090	OWASP ZAP proxy port
NUCLEI_CONTAINER_NAME	devsecops-nuclei	Existing Docker container name for Nuclei
TRIVY_CONTAINER_NAME	devsecops-trivy	Existing Docker container name for Trivy

---

📖 Customization & Custom Container Setup

If you run security tools in custom Docker containers (e.g. devsecops-sonarqube, devsecops-zap, devsecops-semgrep) or have different binary names, refer to the detailed DEPLOYMENT.md guide.

---

📡 REST API Reference

GET /api/health

Checks server status.

{
  "status": "ONLINE",
  "timestamp": "2026-08-15T15:00:00.000Z",
  "system": "SecureScan Hub Orchestrator"
}

GET /api/system/capabilities

Returns system PATH and Docker capability matrix for all security tools.

POST /api/scans/start

Triggers a new multi-tool security scan.

{
  "targetPath": "D:\\Projects\\MyApp",
  "targetUrl": "http://localhost:3000",
  "targetImage": "nginx:alpine",
  "executionMode": "Auto",
  "selectedTools": ["semgrep", "trivy-fs", "nuclei", "basic-heuristic"]
}

GET /api/scans/stream/:jobId

Server-Sent Events (SSE) live progress and streaming console log output.

---

📄 License

Distributed under the MIT License. See LICENSE for details.