ping-shield is a real-time tripwire for Linux workstations. It watches the places attackers use to stay on your machine: SSH keys, auto-start entries and IDE extensions. It also follows the threat news that matches your stack, and alerts you on Telegram within seconds. Each finding is sent exactly once.
Attackers rarely break in twice. They leave something behind that brings them back. ping-shield watches those places and tells you when something new appears.
Linux inotify wakes ping-shield the moment a watched directory changes. Alerts arrive in about two seconds, and the watcher uses no CPU while idle.
authorized_keys, crontab, systemd user units, autostart, environment.d and your shell rc files, each with an exact diff.
Reports installs, removals and updates in VS Code, Cursor, VSCodium and Windsurf. Extension code changed without a version bump is flagged as possible tampering.
Follows RSS feeds, official advisories and public Telegram channels. You only hear about severe threats that mention software installed on your machine.
A change is recorded as seen only after Telegram confirms delivery. If the network is down, the alert waits for the next run. A story covered by several outlets is sent once, matched by link, title and CVE.
Tap It was me or Not me to get a response checklist, or mute a noisy keyword. Use /scan, /status and /catalog from your phone.
No root required, and no YAML or systemd files to write. ping-shield sets itself up as a user service.
--init stores your bot token with owner-only permissions, and can find your chat id for you.
The first scan fingerprints every watched location quietly. After that, only changes produce alerts.
The real-time watcher catches changes within seconds. A full scan every 15 minutes covers everything else.
$ pipx install ping-shield $ pshield --init ✓ Token verified: bot @YourShieldBot ✓ Message sent. Check Telegram. $ pshield --test [PASS] Test 0: Telegram connectivity [PASS] Test 1: SSH monitoring (~/.ssh/authorized_keys) [PASS] Test 2: Threat-intel news alerting $ pshield --setup-service ✓ enabled and started ping-shield.timer (every 15 min) ✓ enabled and started ping-shield-bot.service # that's it. go back to work.
The places attackers use to keep access to a machine, checked against a SHA-256 baseline.
~/.ssh/authorized_keys · rc · environment
~/.config/systemd/user/
.bashrc · .bashrc.d · .profile · .zshrc · config.fish
~/.config/autostart · environment.d
~/.vscode · ~/.cursor · ~/.vscode-oss · ~/.windsurf
crontab -l
An item alerts only if it's severe (actively exploited, a zero-day, a backdoor, CVSS ≥ 9…) and it mentions something installed on this machine. You add sources from the terminal or from Telegram.
$ pshield --add-source t.me/yourchannel
A tool that guards your supply chain shouldn't add risk to it.
Only the Python standard library, so no third-party packages to audit or trust.
Runs as your user, as a systemd user service. Nothing system-wide is installed.
Baselines stay in ~/.config/ping-shield with owner-only permissions. Alerts are the only thing that leaves your machine.
API keys, passwords and tokens in diffs are masked before anything is sent to Telegram.
The bot answers only the chat you configured. Strangers are refused.
MIT licensed. Read every line on GitHub before you run it.
The same zero-dependency approach, extended to the other operating systems developers use.
Real-time watching, the bot and threat intel on any systemd distribution.
LaunchAgents, login items and zsh, with kqueue watching and a launchd schedule.
Registry Run keys, the Startup folder and scheduled tasks, scheduled with Task Scheduler.
Discord, Slack and ntfy alerts, plus package-manager and git hook tampering.
No. It doesn't scan every file for malware, and it doesn't watch processes or network traffic. ping-shield is a tripwire: it tells you when the places attackers use to keep access to a machine change. It complements other security tools rather than replacing them.
Only the alerts, and only to your own Telegram bot. Baselines, configuration and the news cache stay in ~/.config/ping-shield. Values that look like credentials are masked before an alert is sent.
You get one alert, and you tap ✅ It was me. The new state becomes the baseline, so you're never alerted about the same change twice.
Yes, and it takes about a minute: message @BotFather, send /newbot, then paste the token into pshield --init. With your own bot, nobody else can read your alerts or send messages as your bot.
No. Everything runs as your user, and the services are systemd user units. To keep scanning while you're logged out, run loginctl enable-linger once.
pipx command isn't found. What now?pipx is a separate tool that installs Python apps in their own isolated environment. Install it with sudo dnf install pipx (Fedora), sudo apt install pipx (Ubuntu/Debian) or sudo pacman -S python-pipx (Arch), run pipx ensurepath, open a new terminal, then pipx install ping-shield.
Issues and pull requests are welcome on GitHub. CONTRIBUTING.md covers the ground rules (no dependencies, no root, exactly-once alerts), the project layout and the review process. Please report security issues privately, as described in SECURITY.md.
Any public channel. ping-shield reads its public web preview, so it needs no login or API key. Private channels can't be read this way.
Free, open source, and running in under five minutes.