How fariddevu/netsentinel works
1. Repository shape
- This is a three-runtime system: a desktop client in Angular + Electron, a Spring Boot API backend in Java 21, and a Rust sandbox service that runs security tools inside Kali Linux on WSL2.
- The architecture is intentionally split so the UI stays local-first, the backend owns state and analysis, and the sandbox is the only component that can invoke external scanning tools.
2. Desktop application boundary
- The frontend/ folder contains the user-facing app.
- Angular implements the screens for scan setup, dashboard, assets, results, history, comparison, tutorial, credits, and agent chat.
- Electron is the desktop shell: it bridges the renderer to the backend, likely handles startup/bootstrap, and packages the app for Windows distribution.
3. Backend boundary and responsibilities
- The backend/ folder is the central coordinator.
- It exposes a local REST API on port 8080, validates requests, starts and tracks scans, persists results, performs analysis, exports reports, serves dashboard/history data, and mediates access to the sandbox.
- The backend is organized in the standard Spring layers: controller for HTTP, service for business logic, repository for persistence, entity for database models, dto for API payloads, and config/exception for cross-cutting concerns.
4. Scan execution flow
- A scan begins from the frontend through Electron to the backend endpoint POST /api/scan/start.
- The backend creates a ScanJob, validates the target/profile, then calls the Rust sandbox using an authenticated request.
- The sandbox runs tools such as Nmap, Gobuster, and Nikto inside Kali/WSL2, returns raw findings, and the backend parses and stores the results.
- The frontend polls scan status and later fetches full results, logs, or exports.
5. Sandbox boundary
- The sandbox/ service is a separate Rust process using Axum/Tokio.
- Its job is deliberately narrow: validate commands and targets, authenticate backend requests with a token/header, and execute only approved tool invocations.
- This is the trust boundary that isolates the dangerous part of the system from the backend and desktop UI.
6. Analysis and normalization pipeline
- Once raw scanner output returns, backend services like NmapParserService, NiktoParserService, and GobusterParserService normalize it into domain objects.
- AnalysisService then performs deterministic security analysis, calculates a risk score, and generates plain-language remediation guidance in Spanish.
- This means the product’s “diagnosis” is not just a view of raw tool output; it is a second-stage interpretation layer.
7. Persistence model
- The backend persists scan state and findings in PostgreSQL, with schema managed by Flyway migrations under backend/src/main/resources/db/migration.
- Core entities include scan jobs, network hosts, ports, CVE entries, web findings, and finding status records.
- Repositories provide database access for scan history, asset inventory, CVE lookup, and user-updated finding states.
8. CVE correlation and asset inventory
- NvdService connects detected services/versions to the NVD/NIST CVE source so findings can be enriched with known vulnerabilities.
- NetworkService and AssetService shape discovered hosts and ports into the asset inventory and dashboard views.
- This is the main data enrichment path: scan output becomes structured assets plus vulnerability context.
9. Exports, history, and comparison
- ExportService and ScanCompareService support report generation and scan-to-scan comparison.
- The backend includes a Thymeleaf-style report template at templates/report.html, which likely feeds PDF generation alongside JSON and CSV exports.
- History and comparison endpoints depend on the persisted scan graph, not on live sandbox execution.
10. Dashboard and user-facing workflow
- The dashboard view is a summary layer built from backend aggregates, not a separate data source.
- The frontend pages for results, assets, history, and comparison are all consumers of the same scan datastore and analysis pipeline.
- The user journey is: install once, start a scan, wait for completion, review risk and findings, then export or compare.
11. Agent subsystem
- The project also includes an optional Claude-based agent exposed at /api/agent/chat.
- This is separate from the deterministic scanner: it acts as a conversational orchestrator that can drive tools, inspect results, and guide the user via SSE streaming.
- Architecturally, it is an auxiliary control plane on top of the scan system, not the primary source of truth.
12. Operational concerns and cross-cutting config
- SecurityConfig, TraceIdFilter, AsyncConfig, and the custom health indicator show that the backend is designed for local orchestration, tracing, async processing, and health checks of backend/db/sandbox dependencies.
- application-risks.yml and RiskCatalogProperties indicate configurable scoring or recommendation rules.
- Errors are normalized through GlobalExceptionHandler into API-friendly responses.
13. Tests and delivery
- The repo is designed to be built and tested as three components: backend Maven tests, sandbox Cargo tests, and frontend Angular tests.
- GitHub Actions (.github/workflows/ci.yml) runs the full suite, reinforcing the modular boundaries between UI, API, and sandbox.
- Packaging targets Windows desktop distribution via Electron/NSIS, with WSL2/Kali installed as part of the guided setup.
Main entry points: scan.service.ts Scan service · app.routes.ts App routes · main.rs Sandbox API · ScanService.java Scan engine
Components 30
Desktop client
Angular UI packaged with Electron for local-first desktop use.
- Electron shell · Desktop process that boots the app and mediates local runtime startup.
frontend/electron/main.ts - Preload bridge · Secure IPC boundary between Angular renderer and Electron.
frontend/electron/preload.ts - App routes · Top-level Angular navigation across scan, results, history, compare, and agent views.
frontend/src/app/app.routes.ts - Scan setup · Entry point for configuring and starting a scan.
frontend/src/app/pages/scan/scan.ts - Dashboard · Summary view built from backend aggregates.
frontend/src/app/pages/dashboard/dashboard.ts - Results · Detailed findings and scan output review.
frontend/src/app/pages/results/results.ts - Assets · Inventory view for discovered hosts and ports.
frontend/src/app/pages/assets/assets.ts - History · Past scan list and status timeline.
frontend/src/app/pages/history/history.ts - Compare · Scan-to-scan comparison view.
frontend/src/app/pages/compare/compare.ts - Agent chat · Conversational control surface for the assistant workflow.
frontend/src/app/pages/agent/agent.ts - Scan service · Frontend HTTP client used to start scans and poll status/results.
frontend/src/app/services/scan.service.ts
API backend
Spring Boot service that owns scans, analysis, persistence, and exports.
- Spring boot · Application bootstrap and assembly root.
backend/src/main/java/com/netsentinel/NetSentinelApplication.java - Scan API · REST endpoints for scan lifecycle and status.
backend/src/main/java/com/netsentinel/controller/ScanController.java - Scan engine · Validates targets, creates jobs, calls the sandbox, and tracks execution.
backend/src/main/java/com/netsentinel/service/ScanService.java - Sandbox client · Authenticated backend integration to the Rust sandbox.
backend/src/main/java/com/netsentinel/service/SandboxService.java - Analysis · Normalizes findings, computes risk, and generates remediation guidance.
backend/src/main/java/com/netsentinel/service/AnalysisService.java - Parsers · Tool-specific parsers for Nmap, Nikto, and Gobuster output.
backend/src/main/java/com/netsentinel/service/NmapParserService.java - CVE enrichment · Maps detected services and versions to NVD-backed vulnerability data.
backend/src/main/java/com/netsentinel/service/NvdService.java - Asset inventory · Shapes discovered hosts and ports into the inventory model.
backend/src/main/java/com/netsentinel/service/NetworkService.java - Dashboard data · Builds dashboard and history summaries from persisted scan state.
backend/src/main/java/com/netsentinel/service/DashboardService.java - Scan compare · Compares scans using persisted results and analysis artifacts.
backend/src/main/java/com/netsentinel/service/ScanCompareService.java - Export reports · Generates JSON, CSV, and template-based reports.
backend/src/main/java/com/netsentinel/service/ExportService.java - Scan jobs · Persisted scan state and lifecycle record.
backend/src/main/java/com/netsentinel/entity/ScanJob.java - Scan repo · Database access for scan jobs and history.
backend/src/main/java/com/netsentinel/repository/ScanJobRepository.java - Report template · HTML report template used for export generation.
backend/src/main/resources/templates/report.html
Sandbox service
Rust service that runs approved security tools inside Kali on WSL2.
- Sandbox API · Axum/Tokio service that exposes the narrow tool-execution boundary.
sandbox/src/main.rs - Command guard · Validates targets and approved tool commands.
sandbox/src/validator.rs - Tool runner · Runs approved scanner invocations inside the sandbox.
sandbox/src/executor.rs - Sandbox models · Shared request and response types for sandbox execution.
sandbox/src/models.rs
Delivery
Build, packaging, and CI automation.
- CI pipeline · Cross-component build and test workflow.
.github/workflows/ci.yml
Connections 38
- Electron shell → Preload bridge: IPC · Renderer access is mediated through the preload bridge.
- App routes → Scan setup: navigates · Routes surface the scan setup experience.
- App routes → Dashboard: navigates · Routes surface dashboard views.
- App routes → Results: navigates · Routes surface result review.
- App routes → Assets: navigates · Routes surface asset inventory.
- App routes → History: navigates · Routes surface scan history.
- App routes → Compare: navigates · Routes surface scan comparison.
- App routes → Agent chat: navigates · Routes surface the assistant chat.
- Scan setup → Scan service: starts scan · UI delegates scan initiation to the HTTP client.
- Dashboard → Scan service: loads summary · Dashboard consumes aggregated backend data.
- Results → Scan service: fetches results · Results view reads scan details and status.
- Assets → Scan service: loads assets · Asset inventory is fetched from backend APIs.
- History → Scan service: loads history · History view reads persisted scan records.
- Compare → Scan service: compares scans · Comparison view uses backend diff endpoints.
- Agent chat → Scan service: chat tools · Agent UI communicates with the backend assistant endpoint.
- Scan service → Preload bridge: http via shell · Desktop client traffic is initiated from the packaged app boundary.
- Electron shell → Scan API: local API · Electron app talks to the backend REST service on localhost.
- Spring boot → Scan API: hosts · Application bootstrap wires the HTTP controllers.
- Scan API → Scan engine: delegates · Scan controller forwards lifecycle actions to the scan engine.
- Scan engine → Sandbox client: invokes · Backend hands approved execution to the sandbox boundary.
- Scan engine → Scan jobs: creates job · Scan execution begins with persisted job state.
- Scan engine → Parsers: normalizes output · Raw tool output is parsed into domain findings.
- Parsers → Analysis: feeds findings · Normalized output is analyzed for risk and remediation.
- Analysis → CVE enrichment: correlates CVEs · Analysis is enriched with vulnerability intelligence.
- Analysis → Asset inventory: updates inventory · Detected hosts and ports become asset inventory.
- Asset inventory → Dashboard data: summarizes · Inventory and scan data feed dashboard aggregates.
- Dashboard data → Dashboard: serves · Backend summary data powers the dashboard UI.
- Analysis → Export reports: exports · Analysis results are rendered into downloadable reports.
- Export reports → Report template: renders · Template-based report generation uses the HTML template.
- Scan compare → History: uses history · Comparison relies on persisted scan history.
- Scan repo → Scan jobs: persists · Repository stores scan job state.
- Sandbox API → Command guard: guards · Sandbox requests are checked before execution.
- Sandbox API → Tool runner: dispatches · Validated requests are executed by the runner.
- Sandbox API → Sandbox models: serializes · Request and response models define the sandbox API.
- Sandbox client → Sandbox API: authenticated call · Backend invokes the sandbox over a narrow trusted interface.
- CI pipeline → Spring boot: tests · Workflow builds and tests the backend.
- CI pipeline → Sandbox API: tests · Workflow builds and tests the Rust sandbox.
- CI pipeline → Scan service: tests · Workflow runs frontend validation and tests.