Anti-forensic macOS tray application designed to safeguard your system by monitoring USB ports.
Left: Manipulation button to defuse the alarm. Right: Whitelist and Settings menu.
A few reasons to use this tool:
Tip: You might also want to use a cord to attach a USB key to your wrist. Then plug the key into your computer and run swiftGuard. If your computer is robbed, the USB is removed and the computer shuts down immediately.
swiftGuard.dmg
file.Open
, see Note below)
Important: Make sure you use FileVault, macOS's built-in disk encryption feature, encrypt your entire disk, ensuring that your data remains secure even if your device falls into the wrong hands. Otherwise, unauthorized users may gain access to your data easily:
System Preferences > Security & Privacy > Security > FileVault
> Do NOT enable iCloud Recovery!
Note: If you get a warning that the application is from an unidentified developer, you have to open
System Preferences > Security & Privacy > Security
and clickOpen Anyway
to allow the application to run.
Guarding/Inactive
entry to start or pause the guarding of your USB ports.Devices
menu displays all allowed and connected devices. Allowed devices are indicated with a checkmark,
even if they are not connected.Manipulation
) will appear in the main menu. Clicking on it
will reset the alarm. The Exit
button will not work.Settings
menu you can set a delay (0 - 60 seconds) and an action (Shutdown
or Hibernate
). The delay
determines how long swiftGuard will wait for you to reset/defuse the alarm before executing the action.
Notes:
- swiftGuard alerts you if devices are removed that were connected before or while the application was started, except you add them to the whitelist.
- Connecting new devices will always trigger an alert, if these devices are not whitelisted.
- If you encounter any problems, please check the log file in the
~/Library/Logs/swiftGuard
folder.- Your settings and whitelisted devices are stored in the
~/Library/Preferences/swiftGuard/swiftguard.ini
file.
You can run swiftGuard as a simple Python script from the command line without a graphical user interface (GUI). This is useful when operating swiftGuard on a headless system or saving system resources. However, you will lose the ability to defuse the shutdown process via the GUI, but you can kill the swiftGuard process from the command line instead. The preferences and whitelists are stored in the same location as the GUI version and can be edited manually. For further information, please refer to the src/swiftguard/cli.py file.
Open a terminal and navigate to the desired install directory.
cd ~/Desktop
Clone the repository.
git clone https://github.com/Lennolium/swiftGuard.git
Navigate to the swiftGuard directory.
cd swiftGuard
Create a virtual environment and activate it.
python3 -m venv venv
source venv/bin/activate
pip install poetry
Install poetry
in the venv.
pip install poetry
Install swiftguard
in development mode.
poetry install
This installs swiftguard and its python packages in the virtual environment venv/bin/swiftguard
and venv/lib/python3.11/site-packages
in development mode, so you can
change code in the src/swiftguard
folder and immediately test it in the terminal.
Run it in CLI mode.
swiftguard
GUI mode: swiftguardgui
Notes:
- Settings/Whitelist:
~/Library/Preferences/swiftGuard/swiftguard.ini
- Logs:
~/Library/Logs/swiftGuard/swiftguard.log
Logs are rotated every 2 MB with a maximum of 5 files. You can set the log level (Debug=1, ..., Critical=5) and the log output (file, syslog, stdout; required: file) in theswiftguard.ini
file.
As an open-source project, I strive for transparency and collaboration in my development process. I greatly appreciate any contributions members of our community can provide. Whether you are fixing bugs, proposing features, improving documentation, or spreading awareness - your involvement strengthens the project. Please review the code of conduct to understand how we work together respectfully.
Now | Next | Later |
---|---|---|
Unit tests | Linux support | CI/CD |
Code quality | Bluetooth and WiFi detection (Apple Watch) | Website/Docs/Wiki |
Custom system wide hotkey for defusing | Auto update (yet: just notifying) | Encrypted configuration |
E-Mail notification | Native Apple silicon support | Code sign (Apple) |
Countdown dialog | More actions (wipe ram, delete files/folders, email) | User defined actions |
Passwort protected defusing (Dialog) | Translations | Professional security audit |
Regarding swiftGuard is a security application and therefore security is of the utmost importance. I am committed to ensuring that it is secure and reliable for all users. I am grateful for any feedback regarding security issues and will do my best to address them as quickly as possible. Please refer to the security policy for more information.
Additionally, I let my code be checked by several code quality and security tools (Bandit, Black, Codacy, CodeQL, PMD CPD, Prospector, Pylint, Pysa, Pyre, Trivy and Radon). The results can be found by clicking on the badges below. These routines are no replacement for a manual code and security audit, but they help to find errors and vulnerabilities. Please note that the results of these tools are not always accurate and may contain false positives.
Thank you so much for giving feedback, implementing features and improving the code and project!
This application is heavily inspired and based on project usbkill by Hephaestos and BusKill by Michael Altfield. I want to thank him and all the other great contributors of usbkill for their great work, inspiration and help. I firmly believe in the principles of the open source community, which call for the sharing and enhancement of one another work. The purpose of this project is to revive an abandoned project and to support others in learning and comprehending the fundamentals of Python, Qt and macOS, and to develop their own projects.
Many more credits are in the acknowledgments file.
Provided under the terms of the GNU GPL3 License © Lennart Haack 2023.
See LICENSE file for details. For the licenses of used third party libraries and software, please refer to the ACKNOWLEDGMENTS file.