host-guard 0.3.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.
Files changed (52) hide show
  1. host_guard-0.3.0/LICENSE +21 -0
  2. host_guard-0.3.0/MANIFEST.in +4 -0
  3. host_guard-0.3.0/PKG-INFO +62 -0
  4. host_guard-0.3.0/README.md +246 -0
  5. host_guard-0.3.0/VERSION +1 -0
  6. host_guard-0.3.0/docs/PYPI.md +39 -0
  7. host_guard-0.3.0/pyproject.toml +56 -0
  8. host_guard-0.3.0/setup.cfg +4 -0
  9. host_guard-0.3.0/src/host_guard/__init__.py +2 -0
  10. host_guard-0.3.0/src/host_guard/manager.py +960 -0
  11. host_guard-0.3.0/src/host_guard/payload/LICENSE +21 -0
  12. host_guard-0.3.0/src/host_guard/payload/VERSION +1 -0
  13. host_guard-0.3.0/src/host_guard/payload/examples/profiles/bare-metal-mariadb.conf +12 -0
  14. host_guard-0.3.0/src/host_guard/payload/examples/profiles/compose-postgres.conf +18 -0
  15. host_guard-0.3.0/src/host_guard/payload/examples/profiles/edgeshell.conf +18 -0
  16. host_guard-0.3.0/src/host_guard/payload/examples/profiles/plain-vps.conf +14 -0
  17. host_guard-0.3.0/src/host_guard/payload/guard/README.md +21 -0
  18. host_guard-0.3.0/src/host_guard/payload/guard/conf/52host-guard-unattended +11 -0
  19. host_guard-0.3.0/src/host_guard/payload/guard/conf/base-hardening.sh +153 -0
  20. host_guard-0.3.0/src/host_guard/payload/guard/conf/firewall.sh +8 -0
  21. host_guard-0.3.0/src/host_guard/payload/guard/conf/sysctl-hardening.conf +20 -0
  22. host_guard-0.3.0/src/host_guard/payload/guard/hostguard.py +1932 -0
  23. host_guard-0.3.0/src/host_guard/payload/guard/install.sh +246 -0
  24. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-backup.service +9 -0
  25. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-backup.timer +10 -0
  26. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-boot.service +12 -0
  27. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-feeds.service +9 -0
  28. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-feeds.timer +11 -0
  29. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-firewall.service +12 -0
  30. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-health.service +9 -0
  31. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-health.timer +10 -0
  32. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-patch-window.service +9 -0
  33. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-patch-window.timer +9 -0
  34. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-report.service +9 -0
  35. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-report.timer +9 -0
  36. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-restore-test.service +9 -0
  37. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-restore-test.timer +9 -0
  38. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-scan.service +9 -0
  39. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-scan.timer +10 -0
  40. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-watch.service +9 -0
  41. host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-watch.timer +10 -0
  42. host_guard-0.3.0/src/host_guard/payload/panel/hgpanel.py +533 -0
  43. host_guard-0.3.0/src/host_guard/payload/panel/install.sh +44 -0
  44. host_guard-0.3.0/src/host_guard/payload/panel/systemd/host-guard-export.service +7 -0
  45. host_guard-0.3.0/src/host_guard/payload/panel/systemd/host-guard-export.timer +10 -0
  46. host_guard-0.3.0/src/host_guard/payload/panel/systemd/host-guard-panel.service +43 -0
  47. host_guard-0.3.0/src/host_guard.egg-info/PKG-INFO +62 -0
  48. host_guard-0.3.0/src/host_guard.egg-info/SOURCES.txt +50 -0
  49. host_guard-0.3.0/src/host_guard.egg-info/dependency_links.txt +1 -0
  50. host_guard-0.3.0/src/host_guard.egg-info/entry_points.txt +2 -0
  51. host_guard-0.3.0/src/host_guard.egg-info/top_level.txt +1 -0
  52. host_guard-0.3.0/tests/test_manager.py +331 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Prince Kumar
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,4 @@
1
+ include VERSION LICENSE docs/PYPI.md
2
+ graft src/host_guard/payload
3
+ prune src/host_guard/payload/guard/tests
4
+ prune src/host_guard/payload/panel/tests
@@ -0,0 +1,62 @@
1
+ Metadata-Version: 2.4
2
+ Name: host-guard
3
+ Version: 0.3.0
4
+ Summary: Hardening, monitoring, encrypted backups with restore tests and mail alerts for one Linux server, with versioned installs and manifest-based rollback.
5
+ Author: Prince Kumar
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/855princekumar/host-guard
8
+ Project-URL: Changelog, https://github.com/855princekumar/host-guard/blob/main/CHANGELOG.md
9
+ Keywords: security,hardening,monitoring,backup,fail2ban,server,vps,ec2
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: System Administrators
13
+ Classifier: Operating System :: POSIX :: Linux
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Security
16
+ Classifier: Topic :: System :: Systems Administration
17
+ Classifier: Topic :: System :: Monitoring
18
+ Classifier: Topic :: System :: Archiving :: Backup
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Dynamic: license-file
23
+
24
+ # host-guard
25
+
26
+ Hardening, monitoring, encrypted backups with restore tests, and mail alerts for one
27
+ Linux server (Ubuntu 22.04 to 26.04, Debian 12 and 13): a cloud instance, a VPS or
28
+ bare metal. Python standard library and systemd timers, nothing else to run.
29
+
30
+ This package is the installer. It installs host-guard on the server, records every
31
+ file it changes, and can roll back or remove it again.
32
+
33
+ ## Install
34
+
35
+ System Python refuses `pip install` on current Ubuntu and Debian (PEP 668), so use pipx:
36
+
37
+ ```bash
38
+ sudo apt install -y pipx
39
+ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install host-guard
40
+ sudo host-guard install --mail-to you@example.com --profile examples/profiles/plain-vps.conf
41
+ ```
42
+
43
+ The installer asks for the Gmail app password that sends the mail (not shown as you type).
44
+
45
+ ## Upgrade, roll back, remove
46
+
47
+ ```bash
48
+ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx upgrade host-guard
49
+ sudo host-guard upgrade # uses the options given at install
50
+ sudo host-guard rollback # undo the last install, exactly
51
+ sudo host-guard rollback --to 0.3.0
52
+ sudo host-guard uninstall # keeps settings, secrets and backups
53
+ sudo host-guard status
54
+ sudo host-guard history
55
+ ```
56
+
57
+ Everything lives in `/opt/host-guard`: one folder per release (three kept) and a
58
+ manifest per install, with a copy of every file it replaced. A rollback restores a
59
+ file only while it still holds what host-guard wrote; a file you changed since is kept
60
+ and reported. SSH and fail2ban settings are checked before they apply.
61
+
62
+ Docs, profiles and the source: https://github.com/855princekumar/host-guard
@@ -0,0 +1,246 @@
1
+ <div align="center">
2
+
3
+ <img src="docs/assets/banner.svg" alt="host-guard: one Linux server watched, patched, backed up and proven restorable. Python standard library and systemd, no agent, no bill." width="100%">
4
+
5
+ <a href="docs/assets/host-guard-intro.mp4" title="Watch the 42-second intro with sound (MP4)"><img src="docs/assets/host-guard-intro.webp" alt="host-guard in 42 seconds: health and intrusion watch every 5 minutes, encrypted backups with restore tests, early warning, the patch window and a one-command install" width="100%"></a>
6
+
7
+ <sub>host-guard in 42 seconds. <a href="docs/assets/host-guard-intro.mp4">Watch with sound (MP4)</a></sub>
8
+
9
+ **Security, health, backups and early warning for one Linux server.**<br>
10
+ For anyone running a product on a single cloud instance, VPS or bare-metal box without a platform team.
11
+
12
+ [![CI](https://github.com/855princekumar/host-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/855princekumar/host-guard/actions/workflows/ci.yml)
13
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
14
+ [![Version](https://img.shields.io/badge/version-0.3.0-blue)](CHANGELOG.md)
15
+ [![CodeQL](https://github.com/855princekumar/host-guard/actions/workflows/codeql.yml/badge.svg)](https://github.com/855princekumar/host-guard/actions/workflows/codeql.yml)
16
+ [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
17
+
18
+ [![Python](https://img.shields.io/badge/python-3.10%2B%2C%20standard%20library%20only-3776AB?logo=python&logoColor=white)](guard/hostguard.py)
19
+ [![systemd](https://img.shields.io/badge/runs%20on-systemd%20timers-30D475?logo=linux&logoColor=white)](guard/systemd/)
20
+ [![Ubuntu | Debian](https://img.shields.io/badge/OS-Ubuntu%2022.04%20to%2026.04%20%7C%20Debian%2012-E95420?logo=ubuntu&logoColor=white)](docs/INSTALL.md)
21
+ [![Anywhere](https://img.shields.io/badge/runs%20on-AWS%20%7C%20Google%20Cloud%20%7C%20Azure%20%7C%20Oracle%20%7C%20VPS%20%7C%20bare%20metal-0f172a)](docs/CLOUDS.md)
22
+
23
+ [![Bandit](https://img.shields.io/badge/security%20lint-Bandit-yellow)](.github/workflows/ci.yml)
24
+ [![gitleaks](https://img.shields.io/badge/secret%20scan-gitleaks-blueviolet)](.github/workflows/ci.yml)
25
+ [![Red team](https://img.shields.io/badge/red%20team-43%20attacks%20stopped%2C%203%20gaps%20open-c0392b)](docs/REDTEAM.md)
26
+ [![Rollback](https://img.shields.io/badge/install-manifest%20%2B%20rollback-success)](docs/VERSIONS.md)
27
+ [![No agent](https://img.shields.io/badge/agent-none-lightgrey)](#why-host-guard)
28
+
29
+ [Install](docs/INSTALL.md) · [Versions and rollback](docs/VERSIONS.md) · [How it works](docs/HOW-IT-WORKS.md) · [Clouds](docs/CLOUDS.md) · [Mail](docs/MAIL.md) · [Red team](docs/REDTEAM.md) · [Configuration](docs/CONFIGURATION.md) · [Running cost](docs/COST.md) · [Panel](docs/PANEL.md) · [Releasing](docs/RELEASING.md) · [Security](SECURITY.md)
30
+
31
+ </div>
32
+
33
+ ## Why host-guard
34
+
35
+ Small products often run on one server. Nobody watches it at night, backups are
36
+ "probably fine", and security updates wait until something breaks. Monitoring
37
+ suites and security agents cost money, need their own servers, and send data
38
+ somewhere else.
39
+
40
+ host-guard is one Python file (standard library only) and a few systemd timers.
41
+ It installs with one command, keeps every secret in one root-only file on the
42
+ server, and mails every admin when a person is needed. Nothing leaves the server
43
+ except the mail and, if you want, an encrypted backup copy in S3.
44
+
45
+ <img src="docs/assets/how-it-works.svg" alt="How host-guard works: systemd timers start the jobs; health and intrusion watch every 5 minutes, early warning every 6 hours, a nightly encrypted backup, a weekly scan, restore test and patch window; results go to every admin's inbox and to an optional local panel" width="100%">
46
+
47
+ ## What it does
48
+
49
+ | Job | How often | What it checks or does | When something is wrong |
50
+ |---|---|---|---|
51
+ | Health | every 5 min | disk, memory, containers, HTTPS answer, TLS certificate, database replication, backup age, pending reboot, new bans | one alert, then a "resolved" mail |
52
+ | Intrusion watch | every 5 min | extra root accounts, new login accounts and SSH keys, changed sudo, SSH, cron and systemd files, rootkit preload, crypto miners, programs in memory-only folders, root SSH from the internet | critical mail at once; extra root accounts locked, miners killed (a copy kept); optional lockdown of the web server |
53
+ | Early warning | every 6 h | CISA's exploited vulnerabilities, Ubuntu security notices, OSV advisories for the Python packages in your containers, matched to what runs here | mail with the advisory and the fixed version |
54
+ | Backup | nightly | your database (MariaDB or PostgreSQL) or any command's output, gzipped, encrypted with AES-256, checksummed, newest 3 kept, optional S3 copy | alert if the dump, encryption or upload fails |
55
+ | Restore test | weekly | the newest backup decrypted and loaded into a throwaway database (or unpacked completely) | alert: a backup that does not restore is no backup |
56
+ | Scan | weekly | Trivy on every running image, Lynis on the host | mail with what to fix |
57
+ | Patch window | weekly | security updates install daily; the reboot they need happens here, after a fresh backup and only with healthy replication | reboot postponed, with the reason |
58
+ | Daily report | daily | at a glance (OK or ATTENTION per area), what needs a person, every detail, the running cost and where it could cost less | problems listed first |
59
+
60
+ On install it also hardens the base: SSH by key only for one user, fail2ban for
61
+ SSH and repeat offenders (and for sign-in floods and probes when you give it the
62
+ web logs), kernel network settings, outbound mining ports blocked, automatic
63
+ security updates.
64
+
65
+ ## Proven by attack
66
+
67
+ Every change is attacked in CI before it can merge: 46 real attacks on an isolated
68
+ network against a server installed by the version manager, plus the dashboard attacked
69
+ from a real browser, each mapped to MITRE ATT&CK.
70
+ **43 stopped or detected, 3 known gaps, 0 failed.** The suite lives in
71
+ [ci/redteam/](ci/redteam/) and runs as the `Red team` job, required for every merge and release.
72
+
73
+ | Phase | Attacks | Result |
74
+ |---|---|---|
75
+ | SSH: brute force, password, root, wrong user | 6 | 6 stopped |
76
+ | Web: probes for secrets, request floods | 3 | 3 stopped |
77
+ | Host: root backdoor, miners, SSH keys, sudoers, cron, preload | 9 | 8 stopped, 1 gap |
78
+ | Network: mining-pool egress, port scan | 2 | 1 stopped, 1 gap |
79
+ | Backups: theft, tampering of the off-site copy, restore | 4 | 4 stopped |
80
+ | Secrets: leaks, file permissions, panel account | 3 | 3 stopped |
81
+ | Dashboard in a real browser: sign-in, screenshots | 2 | 2 stopped |
82
+ | Dashboard attacks: DNS rebinding, CSRF, CORS, framing, stored XSS, SQL injection, session fixation and theft, code replay, guessing, methods, path traversal | 17 | 16 stopped, 1 gap |
83
+
84
+ Known gaps, reported rather than hidden: a miner renamed like a kernel thread, run from /usr/local/bin; a port scan of 20 common ports; stolen session cookie replayed from another browser.
85
+ The suite found and fixed five real defects on its first runs.
86
+ [Full report, screenshots and samples of the mails it sent](docs/REDTEAM.md).
87
+
88
+ ## Runs anywhere, sets itself up
89
+
90
+ The cloud is read from its own metadata service; anything else is a VPS or bare metal.
91
+ The installer records it and adapts: the off-site store that fits, the cost estimate
92
+ (AWS prices only on AWS), the usual login user.
93
+
94
+ | | AWS | Google Cloud | Azure | Oracle Cloud | VPS or bare metal |
95
+ |---|---|---|---|---|---|
96
+ | Detected by | IMDSv2 | `Metadata-Flavor: Google` | `Metadata: true` | `Bearer Oracle` | no metadata service |
97
+ | Off-site copy | S3 | Cloud Storage (S3 interop) | Blob (SAS URL) | Object Storage (pre-authenticated URL or S3 API) | any S3-compatible store |
98
+ | Tested in CI with | Floci, AWS Emulator | Floci GCP | Azurite | Floci OCI | |
99
+
100
+ [docs/CLOUDS.md](docs/CLOUDS.md).
101
+
102
+ ## Mail that sorts itself
103
+
104
+ ```
105
+ [P1 Critical] Intrusion | web-01 | Intrusion signs on the server
106
+ [P2 Attention] Attack | web-01 | Blocked 3 address(es)
107
+ [P3 Info] Backup | web-01 | Restore test passed
108
+ [Daily] Daily report | web-01 | Daily report: all good
109
+ ```
110
+
111
+ Severity, then category, then server, in every subject, plus `List-Id` and
112
+ `X-Host-Guard-*` headers for filters. P1 always goes out at once; similar P2 and P3
113
+ mails are capped per hour, so an attack does not bury the inbox.
114
+ [docs/MAIL.md](docs/MAIL.md).
115
+
116
+ ## Quick start
117
+
118
+ On the server (Ubuntu 22.04 to 26.04 or Debian 12), with an SSH key that works and a
119
+ second session open:
120
+
121
+ ```bash
122
+ sudo apt install -y pipx
123
+ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install host-guard
124
+ sudo host-guard install --mail-to you@gmail.com,teammate@example.com \
125
+ --profile examples/profiles/plain-vps.conf --with-trivy
126
+ ```
127
+
128
+ (From a clone instead: `sudo ./host-guard install ...` in the repository folder.)
129
+
130
+ It asks for the Gmail app password of the first address (not shown as you type),
131
+ then sends a test mail. Copy the backup passphrase somewhere offline:
132
+ `sudo grep BACKUP_PASSPHRASE /etc/host-guard/.env`.
133
+
134
+ Pick the profile closest to your server, or start from `plain-vps.conf` and edit
135
+ `/etc/host-guard/guard.conf` later:
136
+
137
+ | Profile | For |
138
+ |---|---|
139
+ | [plain-vps.conf](examples/profiles/plain-vps.conf) | any VPS or bare-metal box; backs up `/etc` and `/home` |
140
+ | [compose-postgres.conf](examples/profiles/compose-postgres.conf) | a Docker Compose app with PostgreSQL |
141
+ | [bare-metal-mariadb.conf](examples/profiles/bare-metal-mariadb.conf) | nginx and MariaDB installed on the host |
142
+ | [edgeshell.conf](examples/profiles/edgeshell.conf) | [EdgeShell](https://github.com/855princekumar/edgeshell): Compose, MariaDB primary and replica |
143
+
144
+ Full steps for EC2, a VPS and bare metal, other mail providers and an off-site
145
+ S3 copy: [docs/INSTALL.md](docs/INSTALL.md).
146
+
147
+ ### Upgrade, roll back, remove
148
+
149
+ Every install is recorded file by file in `/opt/host-guard`, so it can be undone exactly:
150
+
151
+ ```bash
152
+ sudo host-guard upgrade # same options as the install
153
+ sudo host-guard rollback # undo the last install (or --to 0.3.0)
154
+ sudo host-guard uninstall # settings, secrets and backups stay
155
+ host-guard history
156
+ ```
157
+
158
+ A failed install undoes itself; a file you edited since is kept, not overwritten;
159
+ SSH settings are checked before they apply. [docs/VERSIONS.md](docs/VERSIONS.md).
160
+
161
+ ## How it fits together
162
+
163
+ ```mermaid
164
+ flowchart LR
165
+ T["systemd timers"] --> H["hostguard health / watch / feeds"]
166
+ T --> B["hostguard backup"]
167
+ T --> R["hostguard restore-test"]
168
+ T --> P["hostguard patch-window"]
169
+ T --> D["hostguard report"]
170
+ H --> S[("state in /var/lib/host-guard")]
171
+ B --> K["encrypted file, AES-256"]
172
+ K --> L["local, newest 3"]
173
+ K -. optional .-> S3["S3 with Object Lock"]
174
+ R --> K
175
+ H --> M["msmtp"]
176
+ D --> M
177
+ M --> A["every admin's inbox"]
178
+ S --> E["hostguard export: status without secrets"]
179
+ E --> UI["panel, 127.0.0.1 only"]
180
+ ```
181
+
182
+ More diagrams (the life of an alert, a night's backup, the weekly rhythm, the
183
+ panel's security split): [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md).
184
+
185
+ ## The dashboard (optional)
186
+
187
+ One page with everything host-guard knows, for the admin: open problems, health,
188
+ intrusion watch, bans, backups and restore tests, scans, early warning and recent mails.
189
+ Password (scrypt) plus an authenticator code; it runs as an unprivileged user that
190
+ cannot read any secret, and listens on `127.0.0.1` only.
191
+
192
+ <p align="center">
193
+ <img src="docs/assets/panel-signin.png" alt="The panel's sign-in page" width="40%">
194
+ <img src="docs/assets/panel-dashboard.png" alt="The panel's dashboard" width="58%">
195
+ </p>
196
+
197
+ Install it with `--with-panel`, then open it through a tunnel, no port opened and no VPN:
198
+
199
+ ```bash
200
+ ssh -N -L 8650:127.0.0.1:8650 you@your-server # then http://127.0.0.1:8650
201
+ ```
202
+
203
+ AWS SSM, Google IAP, Azure Bastion and OCI Bastion tunnels work the same way:
204
+ [docs/PANEL.md](docs/PANEL.md#open-it). Every change is attacked in a real browser in CI
205
+ (stored script injection, CORS, cross-site posts, framing, session fixation, guessing).
206
+
207
+ ## Everyday commands
208
+
209
+ | Task | Command |
210
+ |---|---|
211
+ | Installed version, then status and open problems | `sudo host-guard status` |
212
+ | The daily report now | `sudo hostguard report` |
213
+ | Check that mail reaches everyone | `sudo hostguard test-mail` |
214
+ | When each job runs next | `systemctl list-timers 'host-guard-*'` |
215
+ | Back up now / restore test now | `sudo systemctl start host-guard-backup` / `host-guard-restore-test` |
216
+ | Unban an address | `sudo fail2ban-client set <jail> unbanip <address>` |
217
+ | End a web lockdown | `sudo hostguard unlock` |
218
+
219
+ ## Tests
220
+
221
+ ```bash
222
+ python -m pytest -q tests guard/tests panel/tests
223
+ docker run --rm -v "$PWD:/src:ro" ubuntu:26.04 bash /src/ci/fresh_install.sh
224
+ python ci/build_dist.py && docker run --rm -v "$PWD:/src:ro" -v "$PWD/dist:/dist:ro" debian:12 bash /src/ci/lifecycle.sh
225
+ ```
226
+
227
+ | CI job | What it proves |
228
+ |---|---|
229
+ | Tests (Python 3.10, 3.12, 3.14) | the guard, the panel and the version manager, without root |
230
+ | Fresh install (Ubuntu 24.04, 26.04, Debian 12) | a real install, a real `sshd -t`, a rerun, a backup and a restore test |
231
+ | Install, upgrade, rollback, uninstall (same three) | the pip package through its whole life; after `uninstall --purge` the server is byte-for-byte as before |
232
+ | Database backups and restore tests | real MariaDB and PostgreSQL, restored into throwaway databases |
233
+ | Package | sdist and wheel carry what runs on a server; `twine check`; VERSION matches the changelog |
234
+ | Red team | 46 real attacks on an isolated network, scored per MITRE ATT&CK; a failed defense fails CI |
235
+ | Clouds | AWS, Google Cloud, Azure, Oracle Cloud and bare metal detected; backups off-site to emulated stores and restore-tested; forged signatures refused |
236
+ | CodeQL (Python, Actions) | security-extended queries on every change and weekly |
237
+ | Lint, Bandit, gitleaks, ShellCheck, systemd units | code quality, security patterns, no secret in the whole history, unit files valid |
238
+ | Docs and text | every local link resolves; no em dash |
239
+
240
+ ## Contributing and security
241
+
242
+ Issues and pull requests are welcome: [CONTRIBUTING.md](CONTRIBUTING.md).
243
+ Please report vulnerabilities privately: [SECURITY.md](SECURITY.md).
244
+
245
+ MIT licensed. Built by [Prince Kumar](https://github.com/855princekumar), first
246
+ for the server that runs [EdgeShell](https://github.com/855princekumar/edgeshell).
@@ -0,0 +1 @@
1
+ 0.3.0
@@ -0,0 +1,39 @@
1
+ # host-guard
2
+
3
+ Hardening, monitoring, encrypted backups with restore tests, and mail alerts for one
4
+ Linux server (Ubuntu 22.04 to 26.04, Debian 12 and 13): a cloud instance, a VPS or
5
+ bare metal. Python standard library and systemd timers, nothing else to run.
6
+
7
+ This package is the installer. It installs host-guard on the server, records every
8
+ file it changes, and can roll back or remove it again.
9
+
10
+ ## Install
11
+
12
+ System Python refuses `pip install` on current Ubuntu and Debian (PEP 668), so use pipx:
13
+
14
+ ```bash
15
+ sudo apt install -y pipx
16
+ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install host-guard
17
+ sudo host-guard install --mail-to you@example.com --profile examples/profiles/plain-vps.conf
18
+ ```
19
+
20
+ The installer asks for the Gmail app password that sends the mail (not shown as you type).
21
+
22
+ ## Upgrade, roll back, remove
23
+
24
+ ```bash
25
+ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx upgrade host-guard
26
+ sudo host-guard upgrade # uses the options given at install
27
+ sudo host-guard rollback # undo the last install, exactly
28
+ sudo host-guard rollback --to 0.3.0
29
+ sudo host-guard uninstall # keeps settings, secrets and backups
30
+ sudo host-guard status
31
+ sudo host-guard history
32
+ ```
33
+
34
+ Everything lives in `/opt/host-guard`: one folder per release (three kept) and a
35
+ manifest per install, with a copy of every file it replaced. A rollback restores a
36
+ file only while it still holds what host-guard wrote; a file you changed since is kept
37
+ and reported. SSH and fail2ban settings are checked before they apply.
38
+
39
+ Docs, profiles and the source: https://github.com/855princekumar/host-guard
@@ -0,0 +1,56 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "host-guard"
7
+ dynamic = ["version"]
8
+ description = "Hardening, monitoring, encrypted backups with restore tests and mail alerts for one Linux server, with versioned installs and manifest-based rollback."
9
+ readme = "docs/PYPI.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Prince Kumar" }]
14
+ keywords = ["security", "hardening", "monitoring", "backup", "fail2ban", "server", "vps", "ec2"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Environment :: Console",
18
+ "Intended Audience :: System Administrators",
19
+ "Operating System :: POSIX :: Linux",
20
+ "Programming Language :: Python :: 3",
21
+ "Topic :: Security",
22
+ "Topic :: System :: Systems Administration",
23
+ "Topic :: System :: Monitoring",
24
+ "Topic :: System :: Archiving :: Backup",
25
+ ]
26
+ dependencies = []
27
+
28
+ [project.scripts]
29
+ host-guard = "host_guard.manager:main"
30
+
31
+ [project.urls]
32
+ Homepage = "https://github.com/855princekumar/host-guard"
33
+ Changelog = "https://github.com/855princekumar/host-guard/blob/main/CHANGELOG.md"
34
+
35
+ [tool.setuptools]
36
+ package-dir = { "" = "src" }
37
+ include-package-data = true
38
+
39
+ [tool.setuptools.packages.find]
40
+ where = ["src"]
41
+ include = ["host_guard*"]
42
+
43
+ [tool.setuptools.package-data]
44
+ host_guard = ["payload/**/*"]
45
+
46
+ [tool.setuptools.dynamic]
47
+ version = { file = "VERSION" }
48
+
49
+ [tool.ruff]
50
+ line-length = 140
51
+ target-version = "py310"
52
+ extend-exclude = ["src/host_guard/payload"]
53
+
54
+ [tool.ruff.lint]
55
+ # correctness and bug patterns; security patterns are Bandit's job (its own CI job)
56
+ select = ["E", "F", "W", "B"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,2 @@
1
+ """host-guard: hardening, monitoring, encrypted backups with restore tests, and mail alerts for one
2
+ Linux server, installed and rolled back by a version manager (host_guard.manager)."""