sensitivebox 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sensitivebox-0.1.0/LICENSE +21 -0
- sensitivebox-0.1.0/PKG-INFO +424 -0
- sensitivebox-0.1.0/README.md +403 -0
- sensitivebox-0.1.0/pyproject.toml +90 -0
- sensitivebox-0.1.0/pyproject.toml.orig +68 -0
- sensitivebox-0.1.0/src/sensitivebox/__init__.py +10 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/__init__.py +94 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/config.py +85 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/defaults.toml +126 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/engine.py +624 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/events.py +87 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/globs.py +84 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/model.py +215 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/mute.py +55 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/replay.py +99 -0
- sensitivebox-0.1.0/src/sensitivebox/alerts/routing.py +247 -0
- sensitivebox-0.1.0/src/sensitivebox/api/__init__.py +6 -0
- sensitivebox-0.1.0/src/sensitivebox/api/app.py +225 -0
- sensitivebox-0.1.0/src/sensitivebox/api/data.py +109 -0
- sensitivebox-0.1.0/src/sensitivebox/api/host.py +27 -0
- sensitivebox-0.1.0/src/sensitivebox/api/model.py +90 -0
- sensitivebox-0.1.0/src/sensitivebox/api/security.py +89 -0
- sensitivebox-0.1.0/src/sensitivebox/api/server.py +108 -0
- sensitivebox-0.1.0/src/sensitivebox/api/state.py +220 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/archivo-latin-wdth-normal-DY7AcnAa.woff2 +0 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/ibm-plex-mono-medium-BpyVxOr_.woff2 +0 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/index-BH9EydfS.js +10 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/index-RMruxW54.css +1 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/mark-on-dark-CpSxozdM.png +0 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/mark-on-light-DgUAeHTp.png +0 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/assets/mark-raised-Bg5z6PGs.png +0 -0
- sensitivebox-0.1.0/src/sensitivebox/api/static/index.html +14 -0
- sensitivebox-0.1.0/src/sensitivebox/browser.py +106 -0
- sensitivebox-0.1.0/src/sensitivebox/cli.py +467 -0
- sensitivebox-0.1.0/src/sensitivebox/collector.py +319 -0
- sensitivebox-0.1.0/src/sensitivebox/completion.py +117 -0
- sensitivebox-0.1.0/src/sensitivebox/daemon.py +181 -0
- sensitivebox-0.1.0/src/sensitivebox/data/icons/128.png +0 -0
- sensitivebox-0.1.0/src/sensitivebox/data/icons/256.png +0 -0
- sensitivebox-0.1.0/src/sensitivebox/data/icons/512.png +0 -0
- sensitivebox-0.1.0/src/sensitivebox/data/proart-p16.tar.gz +0 -0
- sensitivebox-0.1.0/src/sensitivebox/data/sensitivebox.desktop.in +8 -0
- sensitivebox-0.1.0/src/sensitivebox/data/sensitivebox.service.in +11 -0
- sensitivebox-0.1.0/src/sensitivebox/doctor.py +322 -0
- sensitivebox-0.1.0/src/sensitivebox/fixtures.py +177 -0
- sensitivebox-0.1.0/src/sensitivebox/history.py +298 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/__init__.py +20 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/classify.py +74 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/discovery.py +139 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/ids.py +35 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/model.py +78 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/normalise.py +42 -0
- sensitivebox-0.1.0/src/sensitivebox/hwmon/reader.py +65 -0
- sensitivebox-0.1.0/src/sensitivebox/inspect.py +175 -0
- sensitivebox-0.1.0/src/sensitivebox/live.py +56 -0
- sensitivebox-0.1.0/src/sensitivebox/notify/__init__.py +7 -0
- sensitivebox-0.1.0/src/sensitivebox/notify/base.py +60 -0
- sensitivebox-0.1.0/src/sensitivebox/notify/desktop.py +84 -0
- sensitivebox-0.1.0/src/sensitivebox/notify/log.py +30 -0
- sensitivebox-0.1.0/src/sensitivebox/operations.py +44 -0
- sensitivebox-0.1.0/src/sensitivebox/output.py +76 -0
- sensitivebox-0.1.0/src/sensitivebox/process.py +25 -0
- sensitivebox-0.1.0/src/sensitivebox/py.typed +0 -0
- sensitivebox-0.1.0/src/sensitivebox/redact.py +85 -0
- sensitivebox-0.1.0/src/sensitivebox/report.py +357 -0
- sensitivebox-0.1.0/src/sensitivebox/runtime.py +313 -0
- sensitivebox-0.1.0/src/sensitivebox/sample.py +84 -0
- sensitivebox-0.1.0/src/sensitivebox/service.py +112 -0
- sensitivebox-0.1.0/src/sensitivebox/simulate.py +220 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/__init__.py +83 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/apps.py +135 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/bluez.py +96 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/bluez_watch.py +214 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/changes.py +121 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/cpu.py +152 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/dbus.py +174 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/logind.py +88 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/memory.py +127 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/net.py +128 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/power_profiles.py +116 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/power_supply.py +70 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/psi.py +78 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/report.py +85 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/wifi.py +90 -0
- sensitivebox-0.1.0/src/sensitivebox/sources/wifi_nm.py +269 -0
- sensitivebox-0.1.0/src/sensitivebox/status.py +205 -0
- sensitivebox-0.1.0/src/sensitivebox/store/__init__.py +5 -0
- sensitivebox-0.1.0/src/sensitivebox/store/changes.py +58 -0
- sensitivebox-0.1.0/src/sensitivebox/store/db.py +423 -0
- sensitivebox-0.1.0/src/sensitivebox/store/events.py +337 -0
- sensitivebox-0.1.0/src/sensitivebox/store/mutes.py +58 -0
- sensitivebox-0.1.0/src/sensitivebox/store/quality.py +51 -0
- sensitivebox-0.1.0/src/sensitivebox/store/read.py +40 -0
- sensitivebox-0.1.0/src/sensitivebox/store/schema.py +194 -0
- sensitivebox-0.1.0/src/sensitivebox/store/status.py +105 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sensitive Box contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sensitivebox
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Read-only Linux hwmon sensor daemon with alerting and a neo-skeuomorphic local web UI.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Classifier: Development Status :: 3 - Alpha
|
|
8
|
+
Classifier: Environment :: Console
|
|
9
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
10
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Topic :: System :: Monitoring
|
|
14
|
+
Classifier: Typing :: Typed
|
|
15
|
+
Requires-Dist: dbus-fast>=5.2,<6
|
|
16
|
+
Requires-Dist: msgspec>=0.19,<1
|
|
17
|
+
Requires-Dist: starlette>=1.10.0
|
|
18
|
+
Requires-Dist: uvicorn>=0.54.0
|
|
19
|
+
Requires-Python: >=3.12
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# Sensitive Box
|
|
23
|
+
|
|
24
|
+
A read-only Linux hardware monitor that **alerts you before something overheats**, with memory
|
|
25
|
+
pressure and network activity alongside thermals, fans and power.
|
|
26
|
+
|
|
27
|
+
> **v0.1.0.** The first shareable release: discovery, alerts, the daemon, the command line,
|
|
28
|
+
> and the local dashboard.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
uv tool install sensitivebox
|
|
34
|
+
sbox enable
|
|
35
|
+
sbox open
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`uv tool install sensitivebox` is the PyPI install. The same wheel is attached to the
|
|
39
|
+
[v0.1.0 GitHub release](https://github.com/JonDanMa/sensitivebox/releases/tag/v0.1.0):
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
uv tool install "https://github.com/JonDanMa/sensitivebox/releases/download/v0.1.0/sensitivebox-0.1.0-py3-none-any.whl"
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
End users do not need Node. The release wheel contains the built dashboard.
|
|
46
|
+
|
|
47
|
+
From a checkout, for development:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
uv sync
|
|
51
|
+
uv run sbox --help
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Both `sbox` and `sensitivebox` are installed and accept the same commands.
|
|
55
|
+
|
|
56
|
+
## Web UI
|
|
57
|
+
|
|
58
|
+
The dashboard is at `/`. Alerts (acknowledge, and mute labelled Snooze) are at `/log`. A rule's
|
|
59
|
+
replay is at `/rule/<id>`. Settings, including the remembered theme and rule edits, are at
|
|
60
|
+
`/settings`. Click a reading to open its history. The design system is at `/styleguide`.
|
|
61
|
+
|
|
62
|
+
Build the UI, then run `sbox watch` or `sbox demo heatwave --no-notify` and open
|
|
63
|
+
`http://127.0.0.1:7878/`. Without a build, the server explains how to build it. `pnpm dev` answers
|
|
64
|
+
the API from a scripted machine, including the rule routes the daemon does not have yet.
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
cd ui
|
|
68
|
+
pnpm i
|
|
69
|
+
pnpm dev # http://localhost:5173/ (the styleguide is /styleguide)
|
|
70
|
+
pnpm test # unit tests
|
|
71
|
+
pnpm test:e2e # Playwright snapshots, behaviour and accessibility checks
|
|
72
|
+
pnpm build # writes to src/sensitivebox/api/static (not committed)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Only people working on the UI need Node and pnpm.
|
|
76
|
+
|
|
77
|
+
## Landing page
|
|
78
|
+
|
|
79
|
+
The public landing page lives in `ui/site/`, with its own Vite entry point and a
|
|
80
|
+
canonical URL of `https://sbox.mosys.ai/`. Its build is independent of the local
|
|
81
|
+
dashboard: it neither includes the fixture API nor writes into the Python package.
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
cd ui
|
|
85
|
+
pnpm install --frozen-lockfile
|
|
86
|
+
pnpm site:dev
|
|
87
|
+
pnpm site:check
|
|
88
|
+
pnpm site:build
|
|
89
|
+
pnpm site:budget
|
|
90
|
+
pnpm site:test
|
|
91
|
+
pnpm site:preview
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Development serves `http://127.0.0.1:5174/`; the built preview serves
|
|
95
|
+
`http://127.0.0.1:4174/`. Static output is `ui/site/dist/`. Fonts, icons and dashboard
|
|
96
|
+
captures are served locally. The labelled call-preparation example uses scripted
|
|
97
|
+
browser-only data; it reads no device data, calls no AI service and pauses no real job.
|
|
98
|
+
|
|
99
|
+
The page presents the approved finished-product direction, including the operator's
|
|
100
|
+
own local AI and private SSH connections. It does not change the daemon's current
|
|
101
|
+
capabilities or the installation status documented above. See the landing-page
|
|
102
|
+
decisions in [the bible](docs/BIBLE.md#public-landing-page-decisions-approved-2026-11-13).
|
|
103
|
+
Building or previewing the site does not publish it.
|
|
104
|
+
|
|
105
|
+
The opening fills a normal desktop viewport through the privacy principles, with
|
|
106
|
+
extra height allowed for larger text or short windows. The four principles stay
|
|
107
|
+
on one row: four at desktop widths, two below 1100px, and one below 600px. The
|
|
108
|
+
smaller-screen carousel supports mouse dragging, touch scrolling, arrow keys and
|
|
109
|
+
Home/End, with Space to pause or resume and no visible controls. Both rest for
|
|
110
|
+
three seconds between moves; phones glide for 660ms and tablets for 1.1 seconds.
|
|
111
|
+
It pauses on hover/focus or while offscreen and stays manual under reduced
|
|
112
|
+
motion. Below 800px the mesh is drawn
|
|
113
|
+
once, refreshing only when its size or theme changes. Both mountain backgrounds
|
|
114
|
+
are self-hosted; the light circles use a still, CSS pearlescent finish. The light
|
|
115
|
+
sky is a whitened sunrise gradient in CSS, with softer mesh dots for readability.
|
|
116
|
+
|
|
117
|
+
`pnpm site:test` builds the landing and runs its browser regression checks,
|
|
118
|
+
including 320px layouts, desktop height, carousel behaviour, and accessibility.
|
|
119
|
+
|
|
120
|
+
## Commands
|
|
121
|
+
|
|
122
|
+
| Command | Purpose |
|
|
123
|
+
|---|---|
|
|
124
|
+
| `sbox` | One status report: host, key readings, stored alert states and freshness. |
|
|
125
|
+
| `sbox watch` | Run the daemon in the foreground, with desktop notifications and history. |
|
|
126
|
+
| `sbox demo heatwave` | Run a packaged scenario with popups and in-memory history. |
|
|
127
|
+
| `sbox doctor` | List every sensor, stable ID, group, limits, default rules and unavailable reasons. |
|
|
128
|
+
| `sbox apps` | Show current memory PSI and the top five apps while memory is tight. |
|
|
129
|
+
| `sbox rules` | Show each configured rule's matched signals, state and reason. |
|
|
130
|
+
| `sbox rule cpu-hot` / `sbox rules cpu-hot` | Replay retained input frames through the real engine. |
|
|
131
|
+
| `sbox mute cpu-hot 30m` / `sbox unmute cpu-hot` | Hold or release every notification severity for a rule. |
|
|
132
|
+
| `sbox quiet 22:00-07:00` / `sbox quiet off` | Recurring local quiet hours for every rule; critical still gets through. |
|
|
133
|
+
| `sbox log` / `sbox log -f` | Group incidents, or follow their individual events. |
|
|
134
|
+
| `sbox log --weekly` | Per-rule ISO-week alert quality measurements. |
|
|
135
|
+
| `sbox log --daemon` | Read the user-service journal; combine with `-f` to follow. |
|
|
136
|
+
| `sbox enable` / `sbox disable` | Enable/start or disable/stop the systemd user service now. |
|
|
137
|
+
| `sbox open [log\|settings]` / `sbox open rule cpu-hot` | Launch a loopback dashboard URL in the default browser. |
|
|
138
|
+
| `sbox report [--fixture]` | Export a private diagnostic archive or reusable machine fixture. |
|
|
139
|
+
| `sbox completion bash` | Print a sourceable bash completion script; `zsh` is also supported. |
|
|
140
|
+
|
|
141
|
+
Use `uv run` before these commands when working from the checkout.
|
|
142
|
+
|
|
143
|
+
`run` remains a hidden alias of `watch` for one release, with exactly the same arguments.
|
|
144
|
+
Old simulation flags now explain how to use `demo`. The old `dump` and `install-service` stubs
|
|
145
|
+
have been removed. The dashboard is the next milestone; `open` launches its URL
|
|
146
|
+
without checking for a listener and explains that the page needs the service.
|
|
147
|
+
|
|
148
|
+
## Status and scripting
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
sbox
|
|
152
|
+
sbox --json
|
|
153
|
+
sbox rules --json
|
|
154
|
+
sbox doctor --json
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Readings come from one fresh sample. Alert state comes from the newest stored evaluations;
|
|
158
|
+
a one-shot command never starts a new alert engine or creates/migrates the history database.
|
|
159
|
+
An evaluation is fresh for three times its signal's poll interval plus the store's 5-second
|
|
160
|
+
flush allowance. Missing or stale state shows **Unknown**, with a hint to start `sbox watch`.
|
|
161
|
+
A changed rule configuration requires restarting the daemon before its state is trusted.
|
|
162
|
+
|
|
163
|
+
| Exit code from plain `sbox` | Meaning |
|
|
164
|
+
|---|---|
|
|
165
|
+
| 0 | Alert state is fresh and no warning or critical alert is open. |
|
|
166
|
+
| 1 | A warning is open, or alert state is stale or missing. |
|
|
167
|
+
| 2 | A critical alert is open; this wins over other stale state. |
|
|
168
|
+
| 3 | Operational failure: invocation, configuration, fixture or database error. |
|
|
169
|
+
|
|
170
|
+
Info alerts, Pending, Warming and a fresh Unknown signal do not raise the health code.
|
|
171
|
+
Host uptime comes from `/proc/uptime` and is labelled **host uptime**. Status and heartbeats
|
|
172
|
+
show explicit mute counts and remaining durations when their boot identity is available. Today's
|
|
173
|
+
and this month's stored byte totals remain **unavailable**; unavailable never means zero. Network counters in doctor are explicitly labelled **since boot**.
|
|
174
|
+
|
|
175
|
+
Every command accepts `--json` before or after the command. One-shot results have the shape
|
|
176
|
+
`{"version":1,"kind":"status","data":{...}}`; live commands emit newline-delimited JSON
|
|
177
|
+
(NDJSON), including startup, alert, status and stopped events. In JSON mode, errors and diagnostic
|
|
178
|
+
logs are JSON on stderr; stdout contains no prose. Usage errors return 3, including typos, which
|
|
179
|
+
suggest a command without running the correction. Text output has no colour escapes, so pipes
|
|
180
|
+
and `NO_COLOR` work without special handling.
|
|
181
|
+
|
|
182
|
+
## Foreground monitoring
|
|
183
|
+
|
|
184
|
+
```sh
|
|
185
|
+
sbox watch
|
|
186
|
+
sbox watch --interval 2
|
|
187
|
+
sbox watch --db ./history.db --json
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The daemon polls every second by default, feeds the alert engine, stores history in
|
|
191
|
+
`~/.local/state/sensitivebox/sensitivebox.db` (or `$XDG_STATE_HOME/sensitivebox/sensitivebox.db`),
|
|
192
|
+
and sends desktop notifications. Critical alerts use critical urgency; resolved alerts use low
|
|
193
|
+
urgency. Output retains startup and alert lines, followed by the 30-second heartbeat and one
|
|
194
|
+
status summary line. There is no full-screen redraw. Ctrl-C or SIGTERM stops it cleanly.
|
|
195
|
+
|
|
196
|
+
Memory and network have a 2-second sampling tier, batteries and chargers 5 seconds, and app
|
|
197
|
+
memory at most every 20 seconds while memory is tight. Sleep and shutdown pause evaluation;
|
|
198
|
+
resume warms rules again without closing an open alert or sending a duplicate notification.
|
|
199
|
+
|
|
200
|
+
User rules in `~/.config/sensitivebox/rules.toml` (or `$XDG_CONFIG_HOME/sensitivebox/rules.toml`)
|
|
201
|
+
override shipped defaults by ID. Rule states are shown per matched signal, so one critical
|
|
202
|
+
signal cannot disappear behind a rule summary. An unmatched rule is Unknown.
|
|
203
|
+
|
|
204
|
+
## Local API
|
|
205
|
+
|
|
206
|
+
`watch`, its hidden `run` alias, and `demo` serve the API on **127.0.0.1:7878** inside the same
|
|
207
|
+
asyncio loop that polls and alerts. An occupied port prints **API unavailable** while monitoring
|
|
208
|
+
continues normally; stopping that daemon still returns 0. No external bind is supported.
|
|
209
|
+
|
|
210
|
+
| Route | Response |
|
|
211
|
+
|---|---|
|
|
212
|
+
| `GET /api/sensors` | Timestamp, freshness, grouped readings with labels/units/limits/missing reasons/evaluations, redacted apps, Bluetooth and Wi-Fi status. |
|
|
213
|
+
| `GET /api/host` | Hostname, Ubuntu release, kernel, package version; absent facts are null. |
|
|
214
|
+
| `GET /api/history?id=<signal>&range=1h` | `{t, avg}` raw samples, Unix seconds and null gaps. |
|
|
215
|
+
| `GET /api/history?id=<signal>&range=6h` (or `24h`) | `{t, avg, min, max}` minute buckets, including the partial current minute. |
|
|
216
|
+
| `GET /api/alerts?limit=100` | `{incidents, truncated}`, open and recently closed (24h), newest first; limit 1–10000. |
|
|
217
|
+
| `POST /api/alerts/<incident-id>/ack` | `{}` body; updated incident. Repeat acknowledgement of an open incident succeeds. |
|
|
218
|
+
| `POST /api/alerts/<incident-id>/mute` | `{"duration":"15m","renotify":true}`; updated incident, with its rule muted. |
|
|
219
|
+
| `GET /api/stream` | SSE `snapshot` and `alert` events with increasing IDs. Current snapshot first, then future events. |
|
|
220
|
+
|
|
221
|
+
Sensor reads return 503 until the first poll. Afterward a stale snapshot remains available with
|
|
222
|
+
`fresh:false`. Missing readings stay null; real zero readings stay zero. Minute averages exclude
|
|
223
|
+
missing readings; empty minutes are null. Every history column has the same length. Today's and
|
|
224
|
+
this month's network totals remain unavailable until persistent totals are implemented.
|
|
225
|
+
|
|
226
|
+
Each signal's evaluations carry `rule_id`, lowercase `state`, `when`, resolved threshold `value`,
|
|
227
|
+
effective recovery `clear`, and the rule's `severity` (even when OK). Unavailable thresholds and
|
|
228
|
+
clears are null. The signal's own `value` remains the reading. GET and SSE use the same shape.
|
|
229
|
+
|
|
230
|
+
API JSON has no CLI envelope. Unknown incidents return 404, closed incidents 409. Ack changes no
|
|
231
|
+
evaluation or notification. Mute uses the CLI's duration syntax, including `15m`, `30m`, `1h`,
|
|
232
|
+
and `until-reboot`, with re-notification on expiry enabled by default. Mutations return 200;
|
|
233
|
+
bad JSON or unknown fields return 400 and a non-JSON content type returns 415.
|
|
234
|
+
|
|
235
|
+
For POST, first GET any API route to receive the `sbox_csrf` cookie, then send its value as
|
|
236
|
+
`X-CSRF-Token` with `Content-Type: application/json` and the exact page origin in `Origin`.
|
|
237
|
+
POSTs require a loopback Host, same-origin Origin and the session token. Cross-origin CORS is
|
|
238
|
+
not enabled. API responses are no-store. JSON/SSE/errors redact private text, including app
|
|
239
|
+
names and home paths; stable sensor IDs remain unchanged. Built UI files are served unchanged.
|
|
240
|
+
|
|
241
|
+
Each SSE subscriber has a 64-event queue. Slow clients are disconnected on overflow; reconnecting
|
|
242
|
+
receives the current snapshot, with no replay (even with Last-Event-ID). Fetch chart history from
|
|
243
|
+
`/api/history`. Built files are served directly, missing assets return 404, and client routes
|
|
244
|
+
such as `/styleguide` and `/rule/cpu-hot` receive index.html. API routes never fall back to HTML.
|
|
245
|
+
|
|
246
|
+
Only the writer upgrades older history schemas. New evaluations preserve open-alert severity
|
|
247
|
+
and incident kind, including during missing readings and resume. Legacy evaluations stay
|
|
248
|
+
Unknown until refreshed. The 400-day 15-minute rollups are retained unchanged.
|
|
249
|
+
|
|
250
|
+
## Mutes, history and weekly measurements
|
|
251
|
+
|
|
252
|
+
```sh
|
|
253
|
+
sbox mute cpu-hot 30m
|
|
254
|
+
sbox mute cpu-hot until-reboot --no-renotify
|
|
255
|
+
sbox unmute cpu-hot
|
|
256
|
+
sbox quiet 22:00-07:00 --no-renotify
|
|
257
|
+
sbox quiet off
|
|
258
|
+
sbox log cpu-hot --since yesterday --limit 50
|
|
259
|
+
sbox log --since 2026-11-01T09:00:00+01:00
|
|
260
|
+
sbox log -f --json
|
|
261
|
+
sbox log --weekly
|
|
262
|
+
sbox rule cpu-hot --json
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Mutes live in SQLite and are visible to the running daemon. They survive daemon restarts in the
|
|
266
|
+
same boot. Timed and until-reboot mutes clear on reboot. Expiry and cooldown use monotonic time,
|
|
267
|
+
which stops during suspend. Explicit rule mutes hold all severities. Quiet schedules use local
|
|
268
|
+
civil time, follow timezone/DST changes, and hold info/warning while allowing critical through.
|
|
269
|
+
Comma-separated quiet intervals are supported.
|
|
270
|
+
|
|
271
|
+
Muting changes notification delivery only: alerts still evaluate, appear in history and affect
|
|
272
|
+
health. Automatic release re-notifies a still-open alert unless `--no-renotify` was selected.
|
|
273
|
+
Manual `unmute` and `quiet off` re-notify regardless of that preference. Releases pass through
|
|
274
|
+
cooldown and, when held, wait until cooldown ends while the same alert remains open.
|
|
275
|
+
|
|
276
|
+
One-shot `log` groups incidents newest first, showing severity, rule, firing duration, peak and
|
|
277
|
+
resolved time, with held/delivered reasons on the same line (for example, `muted (quiet hours)`).
|
|
278
|
+
Peaks survive raw-history pruning; older incidents without a recorded peak show `unavailable`.
|
|
279
|
+
For below rules the peak is the lowest reading; missing data never becomes a numeric peak. Its default
|
|
280
|
+
range starts at local midnight yesterday, with Today and Yesterday headings. `--since` also
|
|
281
|
+
accepts durations, ISO dates and timestamps. `--limit` defaults to 100, accepts 1–10000, and
|
|
282
|
+
reports truncation. `-f` appends individual events as NDJSON with `--json`; Ctrl-C stops it.
|
|
283
|
+
`log --daemon` reads only the Sensitive Box user-service journal.
|
|
284
|
+
|
|
285
|
+
Weekly rows record the computation zone and use ISO weeks beginning Monday at local midnight.
|
|
286
|
+
Fires belong to the opening week; active firing minutes split across occupied weeks. Median
|
|
287
|
+
and percent closed under five minutes describe incidents closed that week. Suspend and daemon
|
|
288
|
+
downtime do not count; incomplete durations are flagged. Muted percentage is separate from
|
|
289
|
+
acknowledgement, which stays unavailable until an acknowledgement producer records a fact.
|
|
290
|
+
The alerts page marks a noisy rule and asks whether an alert was useful.
|
|
291
|
+
|
|
292
|
+
Alert events, weekly measurements and change markers are kept for 400 days, preserving older
|
|
293
|
+
facts needed to identify still-open incidents. Kernel, BIOS, package-version and power-profile
|
|
294
|
+
observations begin as baselines. Apt tracking starts at the current readable EOF and records
|
|
295
|
+
new completed upgrades across rotation and restart; older upgrades are not imported.
|
|
296
|
+
|
|
297
|
+
`rules` without an ID lists every configured rule. `rule <id>` and `rules <id>` replay the same
|
|
298
|
+
retained history; bare `rule` errors with a `sbox rules` hint. An unknown ID suggests the nearest
|
|
299
|
+
configured rule without running a correction or the list. Both commands complete rule IDs.
|
|
300
|
+
|
|
301
|
+
Replay includes guards, chip limits, rule edits and sleep
|
|
302
|
+
lifecycle events. One checkpoint at the ring boundary preserves live engine state across pruning;
|
|
303
|
+
daemon-session events reproduce Warming on restart. History readers never create or migrate a
|
|
304
|
+
database. Raw inputs remain one hour and the 400-day 15-minute rollups remain unchanged.
|
|
305
|
+
|
|
306
|
+
## Service and diagnostic archives
|
|
307
|
+
|
|
308
|
+
```sh
|
|
309
|
+
sbox enable
|
|
310
|
+
sbox disable
|
|
311
|
+
sbox open
|
|
312
|
+
sbox open rule cpu-hot
|
|
313
|
+
sbox report --output ./diagnostics.tar.gz
|
|
314
|
+
sbox report --fixture --output ./machine.tar.gz
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Enable writes the user unit under `$XDG_CONFIG_HOME/systemd/user/` and the launcher under
|
|
318
|
+
`$XDG_DATA_HOME/applications/` (using the standard home defaults when unset), then enables and
|
|
319
|
+
starts the service. Disable stops/disables it and leaves both files. Both commands refuse a
|
|
320
|
+
differing existing unit or launcher. Generated commands refer to the installed `sbox` executable;
|
|
321
|
+
install at its intended location before enabling. Subprocesses use argument vectors and bounded
|
|
322
|
+
waits. The default browser opens an app window when its command is recognized as Chromium-based;
|
|
323
|
+
otherwise the platform default opener handles the URL. The API is not served until Prompt 4.
|
|
324
|
+
|
|
325
|
+
Reports are mode-0600 tarballs and refuse to overwrite any existing destination. Both forms strip
|
|
326
|
+
app names by default; `--keep-app-names` permits them. MACs, Wi-Fi network names, Bluetooth device
|
|
327
|
+
names and home paths are stripped. Ownership metadata is cleared. Existing alert titles may
|
|
328
|
+
retain their hostname. Archives include structured diagnostics and bounded operations history
|
|
329
|
+
when a database is selected, never a raw database or journal. Fixture-mode reports also include
|
|
330
|
+
allowlisted `sys/`, `proc/`, `dbus/` inputs with safe relative links, readable by `doctor` after
|
|
331
|
+
extraction. Missing inputs stay unavailable. Collection is bounded to 64 KiB per file, 4096 members
|
|
332
|
+
and 16 MiB of content; omissions are listed in the manifest and budget failures exit 3.
|
|
333
|
+
|
|
334
|
+
The hidden `--root` can collect either report form without host fallback. `enable`, `disable`,
|
|
335
|
+
`open` and `log --daemon` reject it before accessing the host. Fixture mute controls require an
|
|
336
|
+
explicit `--db`; reports include only an explicitly selected database when `--root` is used.
|
|
337
|
+
|
|
338
|
+
## Demos
|
|
339
|
+
|
|
340
|
+
```sh
|
|
341
|
+
sbox demo idle
|
|
342
|
+
sbox demo heatwave
|
|
343
|
+
sbox demo memory-crunch --no-notify
|
|
344
|
+
sbox demo suspend-resume --json
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
A canonical machine fixture ships inside the Python package, so demos work after wheel
|
|
348
|
+
installation outside the checkout. They use the real collector, engine, store and notifiers,
|
|
349
|
+
with scripted readings and shipped default rules, independent of personal overrides.
|
|
350
|
+
|
|
351
|
+
| Scenario | Behavior |
|
|
352
|
+
|---|---|
|
|
353
|
+
| `idle` | Nothing fires. |
|
|
354
|
+
| `heatwave` | CPU 40 → 95 → 84 °C; CPU hot fires at about 65 s and resolves at about 113 s. |
|
|
355
|
+
| `memory-crunch` | Memory stall, pressure, OOM and low-memory alerts, followed by recovery. |
|
|
356
|
+
| `suspend-resume` | Sleep at 55–75 s with CPU hot open; no no-data alert or duplicate notification. |
|
|
357
|
+
|
|
358
|
+
Popups are enabled by default; `--no-notify` disables them. Without a session bus, the scenario
|
|
359
|
+
continues and explains that notifications were not sent. Demo history is always in memory;
|
|
360
|
+
`--db` is rejected. No hardware files are changed.
|
|
361
|
+
|
|
362
|
+
## Doctor and apps
|
|
363
|
+
|
|
364
|
+
Doctor reports unavailable and junk sensors as well as working ones, including ENODATA, bad
|
|
365
|
+
values and dropped junk limits. Stable IDs use `<chip>/<bus id>/<channel>`, never `hwmonN`.
|
|
366
|
+
Its **DEFAULT RULES** column deliberately describes shipped coverage; `rules` instead uses the
|
|
367
|
+
effective defaults plus user overrides. Doctor JSON includes the same diagnostic information
|
|
368
|
+
as text, with structured sensor and source fields.
|
|
369
|
+
|
|
370
|
+
Memory used means **MemTotal − MemAvailable**, never “free”. Pressure is Linux PSI, not usage
|
|
371
|
+
percentage. `apps` reads the current user's cgroup v2 `app.slice`, only above 80% memory used or
|
|
372
|
+
when pressure is high/rising. Healthy memory prints current PSI and says apps were not sampled.
|
|
373
|
+
Missing cgroup support is reported with a reason.
|
|
374
|
+
|
|
375
|
+
All command output, including JSON, errors and live diagnostics, passes through shared
|
|
376
|
+
redaction. MAC addresses, MAC-derived interface names, Wi-Fi network names and Bluetooth device
|
|
377
|
+
names are omitted or masked. Bluetooth devices are described by class and battery level.
|
|
378
|
+
|
|
379
|
+
## Shell completion
|
|
380
|
+
|
|
381
|
+
For bash:
|
|
382
|
+
|
|
383
|
+
```sh
|
|
384
|
+
source <(sbox completion bash)
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
For zsh, after completion initialization:
|
|
388
|
+
|
|
389
|
+
```sh
|
|
390
|
+
autoload -Uz compinit
|
|
391
|
+
compinit
|
|
392
|
+
source <(sbox completion zsh)
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
The script supports both executable names, public commands, scenarios and options. It includes
|
|
396
|
+
configured rule-ID candidates for rule inspection, muting and log filters. Regenerate/re-source it after changing your rules. Hidden `run` and
|
|
397
|
+
test flags are excluded. No `eval` is needed.
|
|
398
|
+
|
|
399
|
+
## Development and fixture roots
|
|
400
|
+
|
|
401
|
+
```sh
|
|
402
|
+
uv sync
|
|
403
|
+
scripts/check.sh
|
|
404
|
+
uv run sbox demo heatwave --no-notify
|
|
405
|
+
uv run sbox doctor --root tests/fixtures/proart-p16
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
The hidden test-only `--root` works before or after a command. Each machine/case contains
|
|
409
|
+
`sys/`, `proc/` and `dbus/`; empty components represent unavailable sources. Readers never fall
|
|
410
|
+
back to host hardware or buses when a root is selected, and fixture mode never connects real
|
|
411
|
+
notification buses. D-Bus replies are JSON snapshots adapted to the normal bus protocol;
|
|
412
|
+
missing replies mean unavailable, malformed JSON is an operational error. There is no fixture
|
|
413
|
+
inheritance. Counter-reset frames remain grouped within their case.
|
|
414
|
+
|
|
415
|
+
Install bash and zsh to run shell completion tests locally. CI installs zsh for the same tests.
|
|
416
|
+
The full check runs locked dependency sync, lint, formatting, strict types and pytest, including
|
|
417
|
+
installed-wheel checks. Tests use fixtures, fake buses and injected clocks, never real hardware.
|
|
418
|
+
|
|
419
|
+
The design and roadmap live in [docs/BIBLE.md](docs/BIBLE.md). See
|
|
420
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
|
|
421
|
+
|
|
422
|
+
## License
|
|
423
|
+
|
|
424
|
+
[MIT](LICENSE)
|