Ciberseguridad (Local) - WiFi / LAN / Audit / Forensics / Sniffer

Local-first defensive security platform for Blue Team workflows, incident support, and network diagnostics.

Core capabilities:

• Windows WiFi scanner via netsh wlan (SSID, signal, channel, auth, encryption, BSSIDs).
• Legal WiFi password lookup: shows only locally saved profile keys (when Windows policy allows).
• Host inventory (computer/user + local webcams connected to the PC).
• LAN IP camera discovery (ONVIF + defensive port sweep).
• Defensive audit modules (URL/WiFi/LAN) and passive Red Team console (no exploitation).
• Blue Team console with risk scoring, prioritization, and remediation guidance.
• Forensic console with evidence collection, chain of custody hashes, IOCs, timeline, hypotheses, and SOC playbook.
• Cross-platform defensive sniffer (diag-agent, Go + pcap/Npcap): flows, alerts, baseline/beaconing, drill-down, export + hash (no payload by default).

Security note: this project is defensive-only. No payloads, exploits, or offensive attack automation are included.

Architecture

flowchart LR
  UI["Frontend (Vite, multipage UI)\nindex/audit/redteam/blueteam/forensic/sniffer/tracker"]
  API["Backend API (Node.js)\nserver/index.mjs"]
  PS["PowerShell tools (Windows)\nWiFi/LAN/Cameras/Audits"]
  AG["diag-agent (Go)\nFlows/Alerts/Exports"]
  DPI["DPI helpers (optional)\nPyShark/TShark"]
  CASES["cases/\nforensic, baselines, tracker, imports"]

  UI -->|/api| API
  API --> PS
  API -->|proxy| AG
  API --> DPI
  API <--> CASES
  AG <--> CASES

Loading

Repository Structure

• frontend/: Vite multipage UI.
• server/index.mjs: Node backend API + SSE + orchestration.
• tools/: PowerShell/Python scripts for WiFi/LAN/audit/camera tasks.
• diag-agent/: Go local sniffer agent.
• cases/: local storage for forensic artifacts, baselines, tracker state, and imported PCAPs.
• scripts/: dev/build launchers.
• SNIFFER_FORENSIC.md: sniffer-specific forensic and operational details.

Requirements

Recommended on Windows:

• Windows 10/11 (for netsh wlan features).
• Node.js 18+ (tested on modern Node, including v22).
• PowerShell (pwsh preferred, Windows PowerShell supported).

For Sniffer (optional):

• Go 1.22+.
• Windows: Npcap installed (WinPcap-compatible mode recommended).
• Linux/macOS: libpcap and proper capture permissions/capabilities.

For DPI (optional):

• Python 3 in PATH (or set PYTHON env var).
• tshark in PATH.
• pyshark (pip install pyshark).

Installation

npm install

Development

Run backend + Vite + diag-agent (if Go is available):

npm run dev

Mobile geolocation-friendly mode (LAN + HTTPS):

npm run dev:https

Public HTTPS mode for phone access (recommended when local cert trust is difficult):

# Example with an existing public HTTPS tunnel URL
$env:TRACKER_PUBLIC_BASE="https://your-public-domain.example"
npm run dev

Open:

• Home: http://127.0.0.1:5173/
• Audits: http://127.0.0.1:5173/audit.html
• Red Team (passive): http://127.0.0.1:5173/redteam.html
• Blue Team: http://127.0.0.1:5173/blueteam.html
• Forensics: http://127.0.0.1:5173/forensic.html
• Sniffer: http://127.0.0.1:5173/sniffer.html
• Tracker (consent-based): http://127.0.0.1:5173/tracker.html

Note:

• In npm run dev, backend starts at the first free port from 8000.
• Vite starts at the first free port from 5173 when using the project scripts.

Production-like Local Run

Build frontend into server/public:

npm run build

Start backend serving static frontend:

npm run start

Docker

This repository now includes Docker support for reproducible local setup.

Quick start:

npm run docker:build
npm run docker:up

Open:

• App/API: http://127.0.0.1:8000

With sniffer agent profile:

npm run docker:up:sniffer

Stop:

npm run docker:down

Important limitation:

• WiFi/LAN modules based on Windows host tools (netsh + PowerShell) are host-dependent.
• In a Linux container, those Windows-specific endpoints will not provide full functionality.
• For full Windows WiFi key/profile/audit behavior, run the project natively on Windows (npm run dev).

NPM Scripts

• npm run dev: backend + frontend + diag-agent (if available).
• npm run dev:server: backend only.
• npm run dev:web: frontend only.
• npm run dev:https: LAN + HTTPS dev mode (recommended for phone geolocation testing).
• npm run dev:agent: diag-agent only.
• npm run build: multipage build to server/public.
• npm run start: backend serving built frontend.
• npm run verify: backend syntax check + build.
• npm run docker:build: build Docker images.
• npm run docker:up: start Docker app service.
• npm run docker:up:sniffer: start app + diag-agent profile.
• npm run docker:down: stop Docker services.
• npm run docker:logs: tail Docker logs.

Feature Overview

1) WiFi Scanner (Windows)

• Uses netsh wlan show networks mode=bssid.
• Exposes SSID, signal %, channel, auth, encryption, and per-BSSID metadata.
• UI sorts by signal descending and supports SSID filtering.
• Live updates via SSE (/api/stream) and force scan (/api/scan?fresh=1).

CLI examples:

.\tools\wifi-scan2.ps1 -AsJson
.\tools\wifi-scan2.ps1 -IncludeBssid
.\tools\wifi-scan2.ps1 -Watch -IntervalSec 3

2) WiFi Password Lookup (Saved Profiles Only)

• Per-SSID Key action in UI.
• Reads local saved profile data only.
• Returns explanatory errors when Windows policy blocks key extraction.

CLI:

.\tools\wifi-password.ps1 -Ssid "MyWifi" -AsJson

3) Host Inventory

• Computer/domain/user information.
• Local webcams connected to the machine (USB/integrated).

4) LAN IP Camera Discovery

• ONVIF probing + defensive port sweep.
• API: /api/cameras?fresh=1&mode=onvif|sweep|both&cidr=...

5) Defensive Audits (URL/WiFi/LAN)

• URL: headers, redirects, DNS/TLS, cookies, CORS checks, common endpoint checks.
• WiFi: WEP/TKIP/WPA/WPA2/WPA3 posture; WPS/PMF if reported by OS/driver; SSID/BSSID consistency and congestion heuristics.
• LAN: passive discovery + optional controlled sweep.

6) Red Team Console (Passive/Defensive)

• Recon-focused checks for authorized targets.
• No exploitation, no brute-force.
• Consolidated report endpoint: /api/redteam/report.

7) Blue Team Console

• One-click consolidated evaluation across modules.
• Risk score + severity distribution.
• MITRE ATT&CK defensive mapping (heuristic).
• JSON export and IOC-focused workflows.

8) Forensics + SOC Playbook

• Case metadata and legal authorization gate.
• Evidence acquisition with per-block SHA-256.
• IOC extraction and timeline correlation.
• Structured hypotheses and validation steps.
• SOC playbook generation and tracking.

9) Sniffer (diag-agent)

• Default mode: metadata-only flows (5-tuple, bytes/packets/timestamps).
• Alerts: new destinations, baseline deviations, beaconing heuristics.
• Host drill-down and export with integrity hash.
• pcap_limited mode available only under authorized scope and strict limits.

10) Offline PCAP Metadata Import

• Analyze existing .pcap/.pcapng files without payload extraction.
• Best-effort DNS qname / TLS SNI metadata.
• Safe-path guardrails (default under cases/import/).

API Highlights

Base: http://127.0.0.1:<PORT>/api

Core:

• GET /api/ping
• GET /api/health
• GET /api/scan
• GET /api/stream
• GET /api/password?ssid=...
• GET /api/system
• GET /api/cameras

Audit/Red Team:

• GET /api/audit/url?url=...&deep=0|1[&allow_public=1]
• GET /api/audit/wifi
• GET /api/audit/lan[?cidr=...&sweep=1]
• GET /api/redteam/wifi
• GET /api/redteam/lan
• GET /api/redteam/web
• GET /api/redteam/report

Sniffer/Forensics/Advanced:

• GET /api/sniffer/*
• POST /api/pcap/analyze
• GET /api/dpi/tshark/health
• POST /api/dpi/tshark/analyze
• GET /api/dpi/health
• POST /api/dpi/start
• POST /api/dpi/stop
• GET /api/dpi/events
• GET /api/ids/*
• POST /api/ids/*
• GET /api/ti/*
• POST /api/ti/*

Environment Variables

Backend (server/index.mjs):

• PORT (default 8000)
• BIND_HOST (default 127.0.0.1)
• SCAN_INTERVAL_MS, SCAN_TIMEOUT_MS
• LAN_TIMEOUT_MS, LAN_RT_TIMEOUT_MS, WIFI_RT_TIMEOUT_MS, CAM_TIMEOUT_MS
• DIAG_AGENT_BASE (default http://127.0.0.1:8787)
• ALLOW_PUBLIC_URL_AUDIT=1 (if explicitly authorized)
• ALLOW_PUBLIC_GEOIP=1 (if explicitly authorized)
• ALLOW_PUBLIC_THREAT_INTEL=1 (if explicitly authorized)

Dev (scripts/dev.mjs):

• VITE_PORT (default 5173)
• VITE_HOST (default follows bind host)
• VITE_SCHEME (auto-set by dev script: http or https)
• VITE_HTTPS=1 (enable HTTPS in Vite)
• VITE_HTTPS_KEY / VITE_HTTPS_CERT (optional custom cert files for trusted local HTTPS)
• LAN=1 (bind 0.0.0.0 for phone/LAN testing)
• TRACKER_PUBLIC_BASE (optional public HTTPS base URL used by Tracker link generation)
• RUN_AGENT=0 (skip auto-start of diag-agent)

Example:

$env:LAN=1
$env:SCAN_INTERVAL_MS=3000
$env:RUN_AGENT=1
npm run dev

Troubleshooting

/api/audit/wifi returns 500

• Ensure you are running the latest code (PowerShell 5.1 compatibility fixes included).
• Verify backend is alive: GET /api/ping.
• Restart all Node processes and run npm run dev again.

WiFi key is not shown

• The SSID must exist as a locally saved profile.
• Windows policy/permissions may block Key Content; backend returns the reason.

Sniffer capture disabled (wpcap.dll error)

• Install Npcap on Windows (WinPcap compatibility recommended).

Phone cannot open LAN URL

• Run dev with LAN=1.
• Confirm Vite is listening on 0.0.0.0 and use the same subnet IP.
• Check Windows firewall rules for Node/Vite.

Phone location is always empty (Loc: --)

• Open track.html and check the geolocation status line.
• If it says insecure HTTP, run npm run dev:https.
• For strict mobile browsers, use a trusted certificate:
  1. Install mkcert on your PC.
  2. Generate cert for your LAN IP.
  3. Set VITE_HTTPS_KEY and VITE_HTTPS_CERT.
  4. Restart dev.
• Alternative: use a public HTTPS tunnel and set:
  • TRACKER_PUBLIC_BASE=https://your-tunnel-domain
  • then regenerate tracker links.

Privacy and Scope

• Metadata-first by default; no payload capture in normal flow mode.
• Authorization checks and scope allowlist are required for sensitive operations.
• WiFi password feature does not crack networks; it reads only locally saved profiles.
• Use only on systems and networks where you have explicit authorization.

Contributing

This repository is now public and open to contributions.

If you are a developer interested in defensive security tooling, we welcome your help:

• Improve detection quality and explainability.
• Strengthen reliability/performance across Windows/macOS/Linux.
• Expand tests, docs, and safe-by-default UX.

Please open an issue or submit a pull request with:

1. Problem statement and scope.
2. Proposed approach.
3. Validation steps and impact notes.

Thanks for helping make this project more useful for both SOC teams and personal/home defensive use cases.

Contributors Wanted

We are actively looking for contributors across:

• Frontend UX/UI and accessibility.
• Node.js backend reliability and API hardening.
• Go (diag-agent) network telemetry and performance.
• PowerShell parsers (Windows locale compatibility).
• Security analytics (Blue Team detections, scoring quality).
• Documentation, onboarding, and examples.

If you want to contribute:

1. Read CONTRIBUTING.md.
2. Pick a task from docs/issue-seed-backlog.md.
3. Open a PR and mention if it is your first contribution.

Contribution labels used in this project:

• good first issue
• help wanted
• documentation
• backend
• frontend
• security

Project Governance Files

• License: LICENSE
• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog (auto via Release Please): CHANGELOG.md
• Architecture: docs/architecture.md
• Roadmap: docs/ROADMAP.md
• Troubleshooting: docs/troubleshooting.md
• Docker guide: docs/docker.md
• Seed contributor issues: docs/issue-seed-backlog.md
• Outreach copy kit: docs/contributor-outreach.md