# j-525/mini-project architecture

> Architecture diagram of the GitHub repository j-525/mini-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/j-525/mini-project
- Repository: https://github.com/j-525/mini-project

## Overview

This is a Linux BadUSB/HID keystroke-injection detector. Its runtime starts USB hotplug monitoring alongside keyboard event capture; newly detected keyboard insertion updates shared suspicion state, while keystroke windows feed behavioral risk scoring and then alert/log output. The README additionally documents HID identification and typing-speed/delay/frequency analysis, represented by the input-monitoring and scoring components. The separate shell-history scanner and USB simulator are present but are not invoked by the main runtime. Edges reflect calls or shared state explicitly visible in sampled files; unsampled behavior is not inferred.

Main entry points: [`badusb/keystroke_monitor.py`](https://github.com/j-525/mini-project/blob/main/badusb/keystroke_monitor.py) (Keystroke Monitor), [`badusb/main.py`](https://github.com/j-525/mini-project/blob/main/badusb/main.py) (Runtime Entry), [`badusb/usb_monitory.py`](https://github.com/j-525/mini-project/blob/main/badusb/usb_monitory.py) (USB Hotplug Monitor), [`badusb/risk_engine.py`](https://github.com/j-525/mini-project/blob/main/badusb/risk_engine.py) (Typing Risk Scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Device and Input Monitoring"]
  node_runtime["Runtime Entry<br/>[main.py]"]
  node_usbwatch["USB Hotplug Monitor<br/>[usb_monitory.py]"]
  node_keyboard["Keystroke Monitor"]
end

subgraph group_analysis["Behavior and Risk Analysis"]
  node_scoring["Typing Risk Scoring<br/>[risk_engine.py]"]
  node_thresholds["Risk Thresholds<br/>[config.py]"]
  node_history["Shell History Scanner<br/>[log.py]"]
end

subgraph group_response["Alerting and Logging"]
  node_alert["Alert Output<br/>[alert_engine.py]"]
  node_logger["Alert Logger<br/>[logger.py]"]
end

subgraph group_support["Shared State and Tools"]
  node_shared["Suspicion State<br/>[sus.py]"]
  node_simulator["USB Attack Simulator<br/>[sim.py]"]
end

node_operator(("Operator"))
node_udev["Linux Input Events"]
node_evdev["Keyboard Event Devices"]

node_operator -->|"starts"| node_runtime
node_runtime -->|"starts thread"| node_usbwatch
node_runtime -->|"runs"| node_keyboard
node_usbwatch -->|"monitors"| node_udev
node_usbwatch -->|"sets insertion state"| node_shared
node_keyboard -->|"reads key events"| node_evdev
node_keyboard -->|"reads and resets"| node_shared
node_keyboard -->|"evaluates windows"| node_scoring
node_scoring -->|"uses limits"| node_thresholds
node_scoring -->|"checks suspicion"| node_shared
node_keyboard -->|"logs alerts"| node_logger
node_keyboard -->|"emits alert"| node_alert
node_history -->|"prints findings"| node_operator
node_simulator -->|"monitors devices"| node_udev

click node_runtime "https://github.com/j-525/mini-project/blob/main/badusb/main.py"
click node_usbwatch "https://github.com/j-525/mini-project/blob/main/badusb/usb_monitory.py"
click node_keyboard "https://github.com/j-525/mini-project/blob/main/badusb/keystroke_monitor.py"
click node_shared "https://github.com/j-525/mini-project/blob/main/badusb/sus.py"
click node_scoring "https://github.com/j-525/mini-project/blob/main/badusb/risk_engine.py"
click node_thresholds "https://github.com/j-525/mini-project/blob/main/badusb/config.py"
click node_alert "https://github.com/j-525/mini-project/blob/main/badusb/alert_engine.py"
click node_logger "https://github.com/j-525/mini-project/blob/main/badusb/logger.py"
click node_history "https://github.com/j-525/mini-project/blob/main/badusb/log.py"
click node_simulator "https://github.com/j-525/mini-project/blob/main/badusb/usb/sim.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime,node_usbwatch,node_keyboard toneBlue
class node_scoring,node_thresholds,node_history toneAmber
class node_alert,node_logger toneMint
class node_shared,node_simulator toneRose
class node_operator,node_udev,node_evdev toneIndigo
```

## Components

### Device and Input Monitoring

- [Runtime Entry](https://github.com/j-525/mini-project/blob/main/badusb/main.py): `badusb/main.py`
- [USB Hotplug Monitor](https://github.com/j-525/mini-project/blob/main/badusb/usb_monitory.py): `badusb/usb_monitory.py`
- [Keystroke Monitor](https://github.com/j-525/mini-project/blob/main/badusb/keystroke_monitor.py): `badusb/keystroke_monitor.py`

### Behavior and Risk Analysis

- [Typing Risk Scoring](https://github.com/j-525/mini-project/blob/main/badusb/risk_engine.py): `badusb/risk_engine.py`
- [Risk Thresholds](https://github.com/j-525/mini-project/blob/main/badusb/config.py): `badusb/config.py`
- [Shell History Scanner](https://github.com/j-525/mini-project/blob/main/badusb/log.py): `badusb/log.py`

### Alerting and Logging

- [Alert Output](https://github.com/j-525/mini-project/blob/main/badusb/alert_engine.py): `badusb/alert_engine.py`
- [Alert Logger](https://github.com/j-525/mini-project/blob/main/badusb/logger.py): `badusb/logger.py`

### Shared State and Tools

- [Suspicion State](https://github.com/j-525/mini-project/blob/main/badusb/sus.py): `badusb/sus.py`
- [USB Attack Simulator](https://github.com/j-525/mini-project/blob/main/badusb/usb/sim.py): `badusb/usb/sim.py`

### Other components

- **Operator**
- **Linux Input Events**
- **Keyboard Event Devices**

## Connections

- Operator → Runtime Entry: starts (evidence: `badusb/main.py`)
- Runtime Entry → USB Hotplug Monitor: starts thread (evidence: `badusb/main.py`)
- Runtime Entry → Keystroke Monitor: runs (evidence: `badusb/main.py`)
- USB Hotplug Monitor → Linux Input Events: monitors (evidence: `badusb/usb_monitory.py`)
- USB Hotplug Monitor → Suspicion State: sets insertion state (evidence: `badusb/usb_monitory.py`)
- Keystroke Monitor → Keyboard Event Devices: reads key events (evidence: `badusb/keystroke_monitor.py`)
- Keystroke Monitor → Suspicion State: reads and resets (evidence: `badusb/keystroke_monitor.py`)
- Keystroke Monitor → Typing Risk Scoring: evaluates windows (evidence: `badusb/keystroke_monitor.py`)
- Typing Risk Scoring → Risk Thresholds: uses limits (evidence: `badusb/risk_engine.py`)
- Typing Risk Scoring → Suspicion State: checks suspicion (evidence: `badusb/risk_engine.py`)
- Keystroke Monitor → Alert Logger: logs alerts (evidence: `badusb/keystroke_monitor.py`)
- Keystroke Monitor → Alert Output: emits alert (evidence: `badusb/keystroke_monitor.py`)
- Shell History Scanner → Operator: prints findings (evidence: `badusb/log.py`)
- USB Attack Simulator → Linux Input Events: monitors devices (evidence: `badusb/usb/sim.py`)