# awsomeangel56/mini-project architecture

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

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

## Overview

Bad USB Attack Detection System is a Linux behavior-based detector. Its runtime starts USB insertion monitoring alongside keyboard event capture; insertion state feeds the keyboard monitor, which evaluates typing windows and emits logged and audible/printed alerts when risk crosses a threshold. The README also describes HID identification and behavior analysis; these appear in the sampled monitor and risk engine. The separate shell-history watcher and safe simulator are present but are not wired into the main runtime. Edges reflect shown calls or shared state; external library/device connections are documented or evident from sampled imports and calls.

Main entry points: [`badusb/keystroke_monitor.py`](https://github.com/awsomeangel56/mini-project/blob/main/badusb/keystroke_monitor.py) (Keyboard Event Capture), [`badusb/usb_monitory.py`](https://github.com/awsomeangel56/mini-project/blob/main/badusb/usb_monitory.py) (USB Event Monitor), [`badusb/risk_engine.py`](https://github.com/awsomeangel56/mini-project/blob/main/badusb/risk_engine.py) (Typing Risk Scoring), [`badusb/sus.py`](https://github.com/awsomeangel56/mini-project/blob/main/badusb/sus.py) (Insertion state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Detection Runtime"]
  node_usb["USB Event Monitor<br/>[usb_monitory.py]"]
  node_keyboard["Keyboard Event Capture"]
  node_susstate["Insertion state<br/>[sus.py]"]
end

subgraph group_analysis["Behavior Analysis"]
  node_risk["Typing Risk Scoring<br/>[risk_engine.py]"]
  node_config["Detection Thresholds<br/>[config.py]"]
end

subgraph group_response["Alerting"]
  node_alerts["Alert Output<br/>[alert_engine.py]"]
  node_logger["Alert Log<br/>[logger.py]"]
end

subgraph group_extras["Standalone Tools"]
  node_history["Shell History Watcher<br/>[log.py]"]
  node_simulator["Safe USB Simulator<br/>[sim.py]"]
end

node_operator(("Operator"))
node_udev["Linux input devices"]
node_evdev["Keyboard devices"]
node_ydotool["ydotool"]

node_operator -->|"starts via"| node_keyboard
node_operator -->|"starts via"| node_usb
node_usb -->|"monitors events"| node_udev
node_usb -->|"sets insertion state"| node_susstate
node_keyboard -->|"reads key events"| node_evdev
node_keyboard -->|"reads and resets"| node_susstate
node_keyboard -->|"evaluates windows"| node_risk
node_risk -->|"reads thresholds"| node_config
node_risk -->|"reads suspicion"| node_susstate
node_keyboard -->|"reads window limits"| node_config
node_keyboard -->|"emits alert"| node_alerts
node_keyboard -->|"logs alert"| node_logger
node_alerts -->|"prints warning"| node_operator
node_history -->|"prints findings"| node_operator
node_simulator -->|"monitors events"| node_udev
node_simulator -->|"types payloads"| node_ydotool

click node_usb "https://github.com/awsomeangel56/mini-project/blob/main/badusb/usb_monitory.py"
click node_keyboard "https://github.com/awsomeangel56/mini-project/blob/main/badusb/keystroke_monitor.py"
click node_susstate "https://github.com/awsomeangel56/mini-project/blob/main/badusb/sus.py"
click node_risk "https://github.com/awsomeangel56/mini-project/blob/main/badusb/risk_engine.py"
click node_config "https://github.com/awsomeangel56/mini-project/blob/main/badusb/config.py"
click node_alerts "https://github.com/awsomeangel56/mini-project/blob/main/badusb/alert_engine.py"
click node_logger "https://github.com/awsomeangel56/mini-project/blob/main/badusb/logger.py"
click node_history "https://github.com/awsomeangel56/mini-project/blob/main/badusb/log.py"
click node_simulator "https://github.com/awsomeangel56/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_usb,node_keyboard,node_susstate toneBlue
class node_risk,node_config toneAmber
class node_alerts,node_logger toneMint
class node_history,node_simulator toneRose
class node_operator,node_udev,node_evdev,node_ydotool toneIndigo
```

## Components

### Detection Runtime

- [USB Event Monitor](https://github.com/awsomeangel56/mini-project/blob/main/badusb/usb_monitory.py): `badusb/usb_monitory.py`
- [Keyboard Event Capture](https://github.com/awsomeangel56/mini-project/blob/main/badusb/keystroke_monitor.py): `badusb/keystroke_monitor.py`
- [Insertion state](https://github.com/awsomeangel56/mini-project/blob/main/badusb/sus.py): `badusb/sus.py`

### Behavior Analysis

- [Typing Risk Scoring](https://github.com/awsomeangel56/mini-project/blob/main/badusb/risk_engine.py): `badusb/risk_engine.py`
- [Detection Thresholds](https://github.com/awsomeangel56/mini-project/blob/main/badusb/config.py): `badusb/config.py`

### Alerting

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

### Standalone Tools

- [Shell History Watcher](https://github.com/awsomeangel56/mini-project/blob/main/badusb/log.py): `badusb/log.py`
- [Safe USB Simulator](https://github.com/awsomeangel56/mini-project/blob/main/badusb/usb/sim.py): `badusb/usb/sim.py`

### Other components

- **Operator**
- **Linux input devices**
- **Keyboard devices**
- **ydotool**

## Connections

- Operator → Keyboard Event Capture: starts via
- Operator → USB Event Monitor: starts via
- USB Event Monitor → Linux input devices: monitors events (evidence: `badusb/usb_monitory.py`)
- USB Event Monitor → Insertion state: sets insertion state (evidence: `badusb/usb_monitory.py`)
- Keyboard Event Capture → Keyboard devices: reads key events (evidence: `badusb/keystroke_monitor.py`)
- Keyboard Event Capture → Insertion state: reads and resets (evidence: `badusb/keystroke_monitor.py`)
- Keyboard Event Capture → Typing Risk Scoring: evaluates windows (evidence: `badusb/keystroke_monitor.py`)
- Typing Risk Scoring → Detection Thresholds: reads thresholds (evidence: `badusb/risk_engine.py`)
- Typing Risk Scoring → Insertion state: reads suspicion (evidence: `badusb/risk_engine.py`)
- Keyboard Event Capture → Detection Thresholds: reads window limits (evidence: `badusb/keystroke_monitor.py`)
- Keyboard Event Capture → Alert Output: emits alert (evidence: `badusb/keystroke_monitor.py`)
- Keyboard Event Capture → Alert Log: logs alert (evidence: `badusb/keystroke_monitor.py`)
- Alert Output → Operator: prints warning (evidence: `badusb/alert_engine.py`)
- Shell History Watcher → Operator: prints findings (evidence: `badusb/log.py`)
- Safe USB Simulator → Linux input devices: monitors events (evidence: `badusb/usb/sim.py`)
- Safe USB Simulator → ydotool: types payloads (evidence: `badusb/usb/sim.py`)