How ganiket25201001/hid-v2 works
1. Application shape and runtime
HID Shield is a PySide6 desktop security console, not a web service. The app starts from main.py and runs as a single local GUI process with a persistence layer backed by SQLite (hid_shield.db). Most behavior is event-driven rather than request/response.
2. Top-level orchestration
The repository is organized around a central event bus (core/event_bus.py) that decouples device monitoring, analysis, security decisions, and UI updates. This is the main integration boundary: core modules emit events, and UI / policy / storage modules subscribe to them.
3. Device and OS-facing boundary
USB/HID activity is handled in core/usb_monitor.py, with supporting device metadata logic in core/device_info.py and enforcement-related logic in core/port_lockdown.py. This is the OS-adjacent layer where physical device changes enter the system. The README makes clear the app is simulation-first, so real enforcement is intentionally limited unless stronger OS integration/admin privileges are available.
4. Analysis pipeline
Suspicious files or device payloads flow into the sandbox subsystem under sandbox/. The pipeline is split into file_scanner.py, entropy_analyzer.py, pe_analyzer.py, and sandbox_manager.py, indicating layered inspection: file enumeration, heuristics, entropy-based checks, and executable-specific analysis. This subsystem produces structured findings that feed downstream threat scoring.
5. Threat classification layer
The ML package under ml/ converts analysis outputs into deterministic threat judgments. feature_extractor.py defines the feature contract, while classifier.py is the public entry point and mock_classifier.py provides the current stable demo backend. Architecturally, this is a swappable inference boundary: the README explicitly notes future replacement with a real model while preserving the same feature vector interface.
6. Security policy and access control
The security/ package is the decision layer that turns analysis results into allow/block/approve actions. policy_engine.py encodes thresholds and rules, access_controller.py applies those decisions, whitelist_manager.py handles trusted hardware serials, and auth_manager.py / session_manager.py control operator authentication and session lifetime. This layer sits between detection/analysis and any user-visible or enforcement action.
7. Persistence and audit trail
Database access is isolated under database/ with db.py, models.py, and repository.py. The likely data model supports event logs, scan results, alerts, sessions, and whitelist records, which are then surfaced in the UI and reports. The presence of SQLite WAL files suggests local audit-grade persistence with concurrent read/write support.
8. Operator workflow and UI composition
The ui/ package is a multi-screen analyst console: dashboard, USB detection, threat analysis, decision panel, logs, and settings. main_window.py is the shell, while dashboard.py, usb_detection.py, threat_analysis.py, decision_panel.py, logs_screen.py, and settings_screen.py are the major views. The UI is built from reusable widgets under ui/widgets/ for risk gauges, file trees, tables, badges, and animated presentation elements.
9. Reporting and forensic output
reports/pdf_exporter.py turns stored incident data into PDF reports. This is a separate output boundary from the live UI, using persisted events and analysis results to generate offline forensic artifacts for review or sharing.
10. Configuration and runtime controls
config.yaml is the main operational configuration source, covering policy thresholds, default actions, notification behavior, logging, and session controls. .env.example suggests environment-based secrets or local overrides are also supported. The UI settings screen likely edits a subset of these runtime controls.
11. Static assets and presentation layer
Visual styling is centralized in ui/styles/ with QSS and theme code, while fonts live under assets/fonts/. This matters architecturally because the app has a branded analyst-console presentation layer, but these assets do not affect core security flow.
12. Testing and smoke validation
The repository includes UI and monitor test scripts (test_ui.py, test_dashboard.py, test_monitor.py) that appear to exercise the main event flow, UI rendering, and USB-monitor simulation. These are useful for understanding expected subsystem integration: detection → analysis → decision → logging/reporting.
13. Main end-to-end data flow
The primary flow is: USB/HID event enters via the monitor, the event bus distributes it, the sandbox and ML layers generate risk signals, the policy engine and access controller decide what to do, the result is persisted in SQLite, and the UI updates live while also supporting logs and PDF export. Authentication and whitelisting gate operator actions across that flow.
Main entry points: main_window.py Main window · event_bus.py Event bus · repository.py Repository · sandbox_manager.py Sandbox
Components 30
Runtime
Local desktop application entry and configuration
Core
Event bus and USB/HID boundary
- Event bus · Central decoupling layer for system events
core/event_bus.py - USB monitor · Detects HID and USB activity entering the system
core/usb_monitor.py - Device info · Normalizes device identity and attributes
core/device_info.py - Port lockdown · OS-adjacent control for restricting ports or devices
core/port_lockdown.py
Analysis
Sandbox and threat scoring pipeline
- Sandbox · Coordinates file and payload inspection stages
sandbox/sandbox_manager.py - File scan · Enumerates and inspects candidate files or payloads
sandbox/file_scanner.py - Entropy · Heuristic signal for packed or suspicious content
sandbox/entropy_analyzer.py - PE analyzer · Executable-specific inspection for Windows payloads
sandbox/pe_analyzer.py - Features · Transforms analysis outputs into model features
ml/feature_extractor.py - Classifier · Public threat scoring entry point
ml/classifier.py - Mock model · Current stable classifier implementation
ml/mock_classifier.py
Security
Policy, auth, and access control
- Policy engine · Converts threat signals into allow or block decisions
security/policy_engine.py - Access control · Applies policy decisions to device or operator actions
security/access_controller.py - Whitelist · Tracks trusted hardware serials and allowed devices
security/whitelist_manager.py - Auth · Operator authentication boundary
security/auth_manager.py - Session · Manages authenticated operator session lifetime
security/session_manager.py
Data
SQLite persistence and audit storage
- SQLite DB · Local audit and state store
database/db.py - Models · Database entities for events, scans, alerts, and sessions
database/models.py - Repository · Persistence gateway used by app services
database/repository.py
UI
Operator console and major screens
- Main window · Desktop application shell that hosts the analyst console
ui/main_window.py - Dashboard · Overview screen for current system and threat status
ui/dashboard.py - USB view · Live device detection and monitoring screen
ui/usb_detection.py - Analysis view · Presents sandbox and classifier results
ui/threat_analysis.py - Decision panel · Operator controls for allow, block, and approval actions
ui/decision_panel.py - Logs · Audit trail and event history view
ui/logs_screen.py - Settings · Runtime and policy configuration UI
ui/settings_screen.py - Shared widgets · Reusable UI controls for risk, tables, trees, and effects
ui/widgets
Output
Offline reporting and exports
- PDF export · Generates offline incident reports from persisted data
reports/pdf_exporter.py
Connections 40
- App start → Config: loads · Reads runtime thresholds and defaults
- App start → Event bus: initializes · Creates the central event coordination layer
- App start → USB monitor: starts · Launches device monitoring in the desktop process
- App start → Main window: opens · Starts the operator console
- USB monitor → Device info: enriches · Attaches device metadata to incoming events
- USB monitor → Event bus: publishes · Emits HID and USB events
- Event bus → Sandbox: dispatches · Routes suspicious payloads to inspection
- Sandbox → File scan: runs · Enumerates files and payloads
- Sandbox → Entropy: runs · Adds heuristic risk signals
- Sandbox → PE analyzer: runs · Performs executable inspection
- Sandbox → Features: produces · Builds model-ready feature vectors
- Features → Classifier: feeds · Supplies normalized features for inference
- Classifier → Mock model: backs · Current backend implementation
- Classifier → Policy engine: scores · Outputs threat judgments used by policy
- Policy engine → Access control: decides · Converts scores into actionable decisions
- Whitelist → Policy engine: informs · Trusted devices reduce or bypass risk
- Auth → Session: creates · Authenticated operators receive sessions
- Session → Access control: gates · Restricts privileged actions to active sessions
- Access control → Port lockdown: enforces · Applies device or port restrictions when possible
- Policy engine → Repository: records · Persists decisions and supporting evidence
- Event bus → Repository: logs · Writes operational events and alerts
- Repository → SQLite DB: stores · Uses local SQLite persistence
- SQLite DB → Models: maps · Backs records with structured entities
- Main window → Dashboard: hosts · Primary overview screen
- Main window → USB view: hosts · Device monitoring screen
- Main window → Analysis view: hosts · Threat inspection screen
- Main window → Decision panel: hosts · Operator action screen
- Main window → Logs: hosts · Audit history screen
- Main window → Settings: hosts · Configuration screen
- Dashboard → Event bus: subscribes · Displays live system state from events
- USB view → Event bus: subscribes · Shows device activity updates
- Analysis view → Repository: reads · Loads scan and score history
- Logs → Repository: reads · Queries audit records
- Decision panel → Access control: drives · Invokes approve or block actions
- Settings → Config: edits · Adjusts runtime policy and UI settings
- PDF export → Repository: reads · Pulls persisted incidents and scans
- PDF export → SQLite DB: exports · Supports offline forensic reporting
- Shared widgets → Dashboard: supports · Shared visual controls used across screens
- Shared widgets → Analysis view: supports · Shared visual controls used across screens
- Shared widgets → Logs: supports · Shared visual controls used across screens