Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/Rvs006/edq/blob/main/README.md) - [CLAUDE.md](https://github.com/Rvs006/edq/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/Rvs006/edq/blob/main/CONTRIBUTING.md) - [INSTALL.md](https://github.com/Rvs006/edq/blob/main/INSTALL.md) - [SECURITY.md](https://github.com/Rvs006/edq/blob/main/SECURITY.md) - [DEPLOY.md](https://github.com/Rvs006/edq/blob/main/DEPLOY.md) - [frontend/src/pages/LandingPage.tsx](https://github.com/Rvs006/edq/blob/main/frontend/src/pages/LandingPage.tsx)

# Introduction to EDQ EDQ (Electracom Device Qualifier) is a local-first qualification platform designed for security testing and acceptance of smart building IP devices, such as cameras, controllers, and sensors. The system replaces fragmented manual processes and spreadsheet-based reporting with a unified workflow that includes device discovery, automated security profiling, and guided manual inspections. Sources: [README.md:3-9](), [frontend/src/pages/LandingPage.tsx:11-40]() ## System Architecture EDQ is structured as a three-service containerized stack, orchestrated via Docker Compose. It is designed to run entirely offline on a local workstation or within a private network. ### Core Services - **Frontend**: A React 19 Single Page Application (SPA) served by Nginx. It acts as the primary user interface and proxies API and WebSocket requests to the backend. - **Backend**: A FastAPI-based asynchronous Python server (Python 3.12) that handles business logic, database interactions via SQLAlchemy, and background task scheduling. - **Tools Sidecar**: A dedicated Linux-based container housing network security utilities. The backend communicates with this sidecar via an internal HTTP API to execute automated probes. Sources: [CLAUDE.md:10-18](), [README.md:39-50]() ### Architectural Overview Diagram The following diagram illustrates the relationship between the core services and persistent storage volumes. ```mermaid flowchart TD User([User Browser]) <-->|HTTP/WS| Frontend[Frontend - Nginx/React] Frontend <-->|Proxy /api| Backend[Backend - FastAPI] Backend <-->|HTTP| Tools[Tools Sidecar - Network Probes] subgraph Storage [Persistent Volumes] DB[(edq-data - SQLite)] Uploads[(edq-uploads)] Reports[(edq-reports)] end Backend <--> DB Backend <--> Uploads Backend <--> Reports ``` Sources: [README.md:42-55](), [CLAUDE.md:12-18]() ## Core Capabilities and Workflow EDQ automates 43 universal checks, categorized into 29 automated probes and 14 guided manual findings. The system follows a linear progression from discovery to report generation. ### Key Features | Feature | Description | | --- | --- | | **Device Discovery** | Subnet scanning (nmap-based) to detect IP, MAC, vendor, and open ports. | | **Auto-Profiling** | Fingerprint rules that classify devices and tailor specific test applicability. | | **Test Execution** | Automated checks using tools like `testssl.sh`, `hydra`, and `nikto` alongside manual UI reviews. | | **Review Queue** | Workflow for reviewers to approve outcomes or apply justified overrides. | | **Reporting** | Generation of Excel, Word, or PDF deliverables mapped to client templates. | Sources: [README.md:11-37](), [frontend/src/pages/LandingPage.tsx:11-40]() ### Data Flow: Qualification Run This sequence diagram shows the interaction between the user, backend, and tools sidecar during a security scan. ```mermaid sequenceDiagram participant U as Engineer (UI) participant B as Backend API participant T as Tools Sidecar participant DB as Database U->>B: POST /api/test-runs/ (Start) B->>DB: Initialize Run State B->>T: POST /scan (Execute Probes) activate T Note over T: nmap, testssl, nikto, etc. T-->>B: Scan Results (JSON) deactivate T B->>DB: Store Results & Update Status B-->>U: WebSocket: Run Update (Progress) ``` Sources: [CLAUDE.md:21-25](), [scripts/verify-app.sh:78-95](), [README.md:25-27]() ## Security and Identity Model The platform implements a multi-role RBAC (Role-Based Access Control) model with a local-first security approach. ### User Roles - **Admin**: Manages system governance, users, authorized networks, and audit logs. - **Engineer**: Performs device discovery, runs tests, and completes manual checks. - **Reviewer**: Validates test outcomes and applies overrides. Sources: [README.md:17-21](), [SECURITY.md:20-25]() ### Security Controls - **Authentication**: JWT access tokens stored in `httpOnly` cookies with 30-day refresh token rotation. - **CSRF Protection**: Enforced via `X-CSRF-Token` headers on all mutating API requests. - **Network Boundaries**: Subnet scanning is strictly blocked until an administrator defines "Authorized Networks" within the application settings. - **Secrets**: Managed via a root `.env` file; setup scripts automatically generate unique cryptographic keys (`JWT_SECRET`, `TOOLS_API_KEY`) for local installs. Sources: [CLAUDE.md:21-25](), [SECURITY.md:5-15](), [INSTALL.md:73-80]() ## Development and Operations EDQ supports two primary execution modes: the standard Docker stack and a local development mode for frontend/backend engineers. ### Environment Configuration The system relies on a single source of truth: the root `.env` file. Key configuration variables include: - `DEBUG`: Enables interactive API documentation at `/docs` when true. - `COOKIE_SECURE`: Must be `false` for local `http://localhost` development. - `TOOLS_SIDECAR_URL`: Points the backend to the network probe container. Sources: [CLAUDE.md:65-72](), [INSTALL.md:104-108](), [LOCAL_DEVELOPMENT.md:30-36]() ### Operational Lifecycle The following lifecycle diagram represents the standard deployment and update flow for engineers. ```mermaid flowchart TD Start[Clone Repo] --> Setup[Run setup.sh / setup.bat] Setup --> Conf{Check .env} Conf -->|Default| Up[docker compose up -d] Up --> Health[Verify via scripts/verify-app.sh] Health --> Admin[Login as admin & Authorize Subnets] Admin --> Work[Qualification Workflow] Work --> Update[Run update.sh / update.bat] Update --> Up ``` Sources: [INSTALL.md:28-60](), [ENGINEER_UPDATES.md:12-25]() ## Conclusion EDQ provides a standardized environment for smart building device qualification. By containerizing complex network security tools and providing a guided workflow for manual checks, it ensures consistent security baselines across various IP-connected hardware. The architecture emphasizes local control, security, and automated reporting to support engineering teams in enterprise environments.