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.
- host_guard-0.3.0/LICENSE +21 -0
- host_guard-0.3.0/MANIFEST.in +4 -0
- host_guard-0.3.0/PKG-INFO +62 -0
- host_guard-0.3.0/README.md +246 -0
- host_guard-0.3.0/VERSION +1 -0
- host_guard-0.3.0/docs/PYPI.md +39 -0
- host_guard-0.3.0/pyproject.toml +56 -0
- host_guard-0.3.0/setup.cfg +4 -0
- host_guard-0.3.0/src/host_guard/__init__.py +2 -0
- host_guard-0.3.0/src/host_guard/manager.py +960 -0
- host_guard-0.3.0/src/host_guard/payload/LICENSE +21 -0
- host_guard-0.3.0/src/host_guard/payload/VERSION +1 -0
- host_guard-0.3.0/src/host_guard/payload/examples/profiles/bare-metal-mariadb.conf +12 -0
- host_guard-0.3.0/src/host_guard/payload/examples/profiles/compose-postgres.conf +18 -0
- host_guard-0.3.0/src/host_guard/payload/examples/profiles/edgeshell.conf +18 -0
- host_guard-0.3.0/src/host_guard/payload/examples/profiles/plain-vps.conf +14 -0
- host_guard-0.3.0/src/host_guard/payload/guard/README.md +21 -0
- host_guard-0.3.0/src/host_guard/payload/guard/conf/52host-guard-unattended +11 -0
- host_guard-0.3.0/src/host_guard/payload/guard/conf/base-hardening.sh +153 -0
- host_guard-0.3.0/src/host_guard/payload/guard/conf/firewall.sh +8 -0
- host_guard-0.3.0/src/host_guard/payload/guard/conf/sysctl-hardening.conf +20 -0
- host_guard-0.3.0/src/host_guard/payload/guard/hostguard.py +1932 -0
- host_guard-0.3.0/src/host_guard/payload/guard/install.sh +246 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-backup.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-backup.timer +10 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-boot.service +12 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-feeds.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-feeds.timer +11 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-firewall.service +12 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-health.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-health.timer +10 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-patch-window.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-patch-window.timer +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-report.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-report.timer +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-restore-test.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-restore-test.timer +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-scan.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-scan.timer +10 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-watch.service +9 -0
- host_guard-0.3.0/src/host_guard/payload/guard/systemd/host-guard-watch.timer +10 -0
- host_guard-0.3.0/src/host_guard/payload/panel/hgpanel.py +533 -0
- host_guard-0.3.0/src/host_guard/payload/panel/install.sh +44 -0
- host_guard-0.3.0/src/host_guard/payload/panel/systemd/host-guard-export.service +7 -0
- host_guard-0.3.0/src/host_guard/payload/panel/systemd/host-guard-export.timer +10 -0
- host_guard-0.3.0/src/host_guard/payload/panel/systemd/host-guard-panel.service +43 -0
- host_guard-0.3.0/src/host_guard.egg-info/PKG-INFO +62 -0
- host_guard-0.3.0/src/host_guard.egg-info/SOURCES.txt +50 -0
- host_guard-0.3.0/src/host_guard.egg-info/dependency_links.txt +1 -0
- host_guard-0.3.0/src/host_guard.egg-info/entry_points.txt +2 -0
- host_guard-0.3.0/src/host_guard.egg-info/top_level.txt +1 -0
- host_guard-0.3.0/tests/test_manager.py +331 -0
host_guard-0.3.0/LICENSE
ADDED
|
@@ -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,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
|
+
[](https://github.com/855princekumar/host-guard/actions/workflows/ci.yml)
|
|
13
|
+
[](LICENSE)
|
|
14
|
+
[](CHANGELOG.md)
|
|
15
|
+
[](https://github.com/855princekumar/host-guard/actions/workflows/codeql.yml)
|
|
16
|
+
[](CONTRIBUTING.md)
|
|
17
|
+
|
|
18
|
+
[](guard/hostguard.py)
|
|
19
|
+
[](guard/systemd/)
|
|
20
|
+
[](docs/INSTALL.md)
|
|
21
|
+
[](docs/CLOUDS.md)
|
|
22
|
+
|
|
23
|
+
[](.github/workflows/ci.yml)
|
|
24
|
+
[](.github/workflows/ci.yml)
|
|
25
|
+
[](docs/REDTEAM.md)
|
|
26
|
+
[](docs/VERSIONS.md)
|
|
27
|
+
[](#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).
|
host_guard-0.3.0/VERSION
ADDED
|
@@ -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"]
|