1. Project Name & Tagline

NeoTrace

Real-time global cyber threat intelligence and hands-on cybersecurity learning in one platform.

2. Table of Contents

• 1. Project Name & Tagline
• 2. Table of Contents
• 3. Project Overview
• 4. Quick Start
  • 4.1 Requirements
  • 4.2 Installation Steps
• 5. Usage
• 6. Configuration
• 7. Project Structure
• 8. Development
• 9. Deployment
• 10. FAQ
• 11. Contributing
• 12. License

3. Project Overview

Background

Cyber fraud, phishing, ransomware, and social engineering evolve quickly. Teams need understandable threat visibility and practical training tools in the same place.

Main Features

• CesiumJS-powered Global Cyber Threat Intelligence globe:
  • Rotatable, zoomable, tiltable 3D Earth.
  • Dynamic attack flow lines (source -> destination).
  • Severity markers (red = high, yellow = medium, blue = low).
  • 3D regional attack bars (incident counts).
  • Global risk heat layer.
  • Click panel with IPs, threat type, confidence, and timestamp.
• Real-time event updates:
  • WebSocket stream (/ws/events) for local Node runtime.
  • SSE fallback (/api/events/stream) for environments without WebSocket support.
• Threat/news fusion backend:
  • Multi-source ingestion (official feeds, RSS, snapshots).
  • Event normalization, confidence scoring, and export (GeoJSON/CSV).
• Security analysis tools:
  • URL scanner, image forensics, text verifier, phone inspector, WiFi scanner, QR scanner, email analyzer.
• Bilingual UI:
  • English and Traditional Chinese language switching with persistent preference.

Use Cases

• Security operations demos and briefings.
• Threat landscape storytelling for security awareness.
• Interactive cybersecurity training for beginners to intermediate users.
• Lightweight threat intelligence visualization prototype for teams.

Tech Stack

• Frontend: HTML, CSS, JavaScript, Chart.js, Leaflet, CesiumJS
• Backend: Node.js, Express
• Realtime: WebSocket (ws) + Server-Sent Events fallback
• Deployment: Vercel (HTTP/SSE), GitHub CLI workflow support
• Testing: Jest + Supertest

4. Quick Start

4.1 Requirements

• Operating Systems:
  • Windows
  • macOS
  • Linux
• Runtime:
  • Node.js 18+
• Tools:
  • Git
  • npm
  • Vercel CLI (vercel)
  • GitHub CLI (gh)

4.2 Installation Steps

1. Clone the repository.

   git clone https://github.com/Brian-code-123/NeoTrace.git
   cd NeoTrace

2. Install dependencies.

   npm install

3. Configure environment variables.

   cp .env.example .env

   Then set the required keys in .env (see Configuration).

4. Start the project.

   npm start

5. Open the app.

   • Default: http://localhost:3000
   • If port 3000 is busy:

     PORT=3010 node server.js

5. Usage

Basic Usage

• Open the Dashboard to view:
  • Global 3D threat globe
  • News fusion cards
  • Threat trend charts
• Use filters to narrow events by category, confidence, and time window.
• Click markers for event details (source IP, target IP, threat type, time).

Common Commands

npm start
npm run dev
npm test
npm run test:coverage

API Examples

Get normalized events:

curl 'http://localhost:3000/api/events?format=json&minConfidence=60'

Export events as GeoJSON:

curl 'http://localhost:3000/api/events/export?format=geojson' -o events.geojson

Export events as CSV:

curl 'http://localhost:3000/api/events/export?format=csv' -o events.csv

UI Guide

• Language toggle: top-right EN / 中
• View switch: 3D Globe / 2D Map
• Export: Export GeoJSON / Export CSV

6. Configuration

Environment Variables

Create .env in project root:

PORT=3000
NODE_ENV=development
API_KEY=your_internal_api_key
ASI_API_KEY=your_asi_api_key
NUMVERIFY_KEY=your_numverify_key
ALLOWED_ORIGINS=https://your-domain.com,https://another-domain.com

Notes

• API_KEY is used for sensitive endpoints (via X-API-Key).
• ASI_API_KEY enables AI-assisted summaries/stats.
• NUMVERIFY_KEY enables live phone intelligence enrichment.
• ALLOWED_ORIGINS extends CORS allowlist.

Custom Configuration

• Rate limits are set in server.js.
• Security headers and CSP are configured via helmet in server.js.
• Cache TTLs for news/events are defined in server.js constants.

7. Project Structure

NeoTrace/
  public/
    css/
      style.css               # Main styling
    js/
      globe-3d.js             # Cesium 3D globe threat visualization
      dashboard.js            # Dashboard logic, map/news/charts, realtime listeners
      i18n.js                 # Translation dictionary and language switcher
      ...                     # Tool-specific scripts
    index.html                # Main dashboard page
    ...                       # Other feature pages
  test/
    api.smoke.test.js         # API smoke tests
  server.js                   # Express API + event pipeline + realtime streaming
  package.json                # Scripts and dependencies
  vercel.json                 # Vercel routing/runtime config
  README.md                   # Project documentation

8. Development

Code Style

• Use clear, explicit naming.
• Keep functions focused and composable.
• Avoid leaking sensitive values in logs.

Git Commit Convention

Recommended format:

• feat: add Cesium realtime globe flows
• fix: handle websocket fallback on vercel
• docs: rewrite readme structure

Branching Strategy

• main: stable production branch
• dev: integration branch
• feature/*: feature branches

9. Deployment

Staging / Preview (Vercel)

vercel

Production (Vercel)

vercel --prod

Monitor Deployments

Vercel:

vercel ls
vercel inspect <deployment-url>

GitHub:

gh repo view --web
gh run list
gh run view <run-id> --log

Secrets Hygiene (GitHub + Vercel)

Check GitHub repository secrets:

gh secret list

Check Vercel environment variables:

vercel env ls

If a secret is exposed:

1. Revoke and rotate it immediately at provider side.
2. Remove leaked value from code/history and force a clean redeploy.
3. Re-add the new secret via gh secret set or vercel env add.
4. Audit logs and access history.

Docker / Nginx

• Docker and Nginx configs are not included by default in this repository.
• Add them only when self-hosting outside Vercel.

10. FAQ

Q1: WebSocket is not connecting on Vercel. Why?

Vercel serverless functions do not provide long-lived Node WebSocket servers in this setup. NeoTrace automatically falls back to SSE (/api/events/stream) and polling.

Q2: Why no live stats updates?

• Check feed/API network access.
• Verify ASI_API_KEY for AI-enhanced stats.
• Confirm CORS allowlist includes your origin.

Q3: Language switch misses some text.

Ensure the page text uses data-i18n/data-i18n-placeholder and that keys exist in both en and zh in public/js/i18n.js.

Q4: API requests are blocked.

• Confirm X-API-Key for protected endpoints.
• Check rate limiting thresholds in server.js.

11. Contributing

How to Open an Issue

• Use clear reproduction steps.
• Include expected vs actual behavior.
• Attach screenshots/logs when possible.

How to Submit a Pull Request

1. Fork the repo and create feature/* branch.
2. Add focused commits with clear messages.
3. Run tests locally.
4. Submit PR with summary and test evidence.

Code Review Rules

• Security and correctness first.
• Include tests for behavior changes.
• Keep docs updated for public API/UX changes.

12. License

This project is licensed under the MIT License.