SwiftGuard

<!--- Logo --> <div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./img/banner/banner_dark.png" width="600vw"> <source media="(prefers-color-scheme: light)" srcset="./img/banner/banner_light.png" width="600vw"> <img alt="Application Banner" src="./img/banner/banner_light.png" width="600vw"> </picture> </div> <br> <!--- Badges --> <div align="center"> <a href="https://github.com/Lennolium/swiftGuard/branches" > <img src="https://img.shields.io/github/last-commit/Lennolium/swiftGuard?label=Last%20Updated&color=orange" alt="last updated" > <a></a> <a href="https://app.codacy.com/gh/Lennolium/swiftGuard/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade" > <img src="https://app.codacy.com/project/badge/Grade/7e4271efc8894c9fab80e2f27f896a87" alt="code quality" > <a></a> <a href="https://github.com/Lennolium/swiftGuard/commits/main" > <img src="https://img.shields.io/github/commit-activity/m/Lennolium/swiftGuard?label=Commit%20Activity" alt="commit activity" > <a></a> <a href="https://github.com/Lennolium/swiftGuard/releases" > <img src="https://img.shields.io/badge/Version-0.0.2-brightgreen" alt="stable version" > <br> <a href="https://github.com/Lennolium/swiftGuard/issues" > <img src="https://img.shields.io/github/issues-raw/Lennolium/swiftGuard?label=Open%20Issues&color=critical" alt="open issues" > <a href="https://github.com/Lennolium/swiftGuard/issues?q=is%3Aissue+is%3Aclosed" > <img src="https://img.shields.io/github/issues-closed-raw/Lennolium/swiftGuard?label=Closed%20Issues&color=inactive" alt="closed issues" > <a href="#" > <img src="https://img.shields.io/github/repo-size/Lennolium/swiftGuard?label=Repo%20Size&color=yellow" alt="repo size" > <a href="https://github.com/Lennolium/swiftGuard/blob/main/LICENSE" > <img src="https://img.shields.io/github/license/Lennolium/swiftGuard?label=License&color=blueviolet" alt="License" > <a></a> </a> </a> </a> </a> </a> </a> </a> </a> </div> <!--- Title --> <div align="center"> <h1></h1> </div> <!--- Description --> <div align="center"> Anti-forensic macOS tray application designed to safeguard your system by monitoring USB ports. It ensures your device's security by automatically initiating either a system shutdown or hibernation if an unauthorized device connects or a connected device is unplugged. It offers the flexibility to whitelist designated devices, to select an action to be executed and to set a countdown timer, allowing to disarm the shutdown process. <br><br>

</div> <div align="center"> <h3></h3> </div> &nbsp; <!--- Table of contents -->

Contents

• Features
• Screenshots
• Why should you care?
• Installation
• Usage
  • GUI
  • CLI
• Development
• Roadmap
• Security & Code Quality
• Contributors
• Credits
• License

 

<!--- Features -->

Features

• Monitoring: Continuously monitors USB ports for device activity, even in sleep mode.
• Whitelisting: Allows users to whitelist authorized devices, ensuring hassle-free connectivity.
• Discrete: Operates in the macOS system tray, minimizing interruptions.
• Customizable: Allows users to configure various settings, including action (shutdown/hibernate), countdown timer and auto start.
• Lightweight: Designed to consume minimal system resources for optimal performance.
• Privacy: Only connects to the internet to check for updates at startup.
• Open Source: Provides transparency and allows community contributions for continuous development.

 

<!--- Screenshots -->

Screenshots

<div align="center"> <picture> <source srcset="./img/screenshots/screenshots.png" width="600vw"> <img alt="Application Screenshots" src="./img/screenshots/screenshots.png" width="600vw"> </picture>

Left: Manipulation button to defuse the alarm. Right: Whitelist and Settings menu.

</div> <br>

 

<!--- Why -->

Why should you care?

A few reasons to use this tool:

• Anti-Forensic Measures: In case the police or other thugs break in. The police often use a mouse jiggler to prevent the screen saver or sleep mode from being activated.
• Prevent Data Exfiltration: You do not want someone adding or copying documents to or from your computer via USB.
• Public Environments: If you frequently use your Mac in public places like libraries or cafés, swiftGuard acts as an additional layer of security against physical attacks in a potentially vulnerable setting.
• Server Protection: You want to improve the security of your home or company server (e.g. your Raspberry Pi, NAS, etc.).
• Data Protection Regulations: Many industries and organizations are subject to strict data protection regulations. swiftGuard helps maintain compliance by preventing unauthorized data transfers and access through USB ports.

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.

 

<!--- Installation -->

Installation

1. Obtain the most recent version by downloading it from Releases tab (Apple Silicon M1/M2/M3/M4: swiftGuard_arm64.dmg, Intel: swiftGuard.dmg).
2. Open the downloaded swiftGuard.dmg file.
3. Drag the swiftGuard application into the Applications folder.
4. Open the swiftGuard application from the Applications folder (by right-clicking and selecting Open, see Note below)
5. swiftGuard should now appear in the macOS system tray.
6. Test at least once if the shutdown or hibernation is executed correctly. On first run you will be asked to grant the necessary permissions by macOS.
7. Automatic startup at login can be enabled in the app's settings menu.

 

Important: Make sure you use FileVault, macOS's built-in disk encryption feature, to 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 click Open Anyway to allow the application to run.

See INSTALL.md for further details and instructions if you are upgrading from an older version.  

<!--- Usage -->

Usage

GUI

1. Open the swiftGuard application from the Applications folder.
2. Click on the application icon in the macOS system tray to open the main menu.
3. Click the Guarding/Inactive entry to start or pause the guarding of your USB ports.
4. The Devices menu displays all allowed and connected devices. Allowed devices are indicated with a checkmark, even if they are not connected.
5. To add or remove a device from the whitelist, simply click on the corresponding device entry.
6. If manipulation is detected, an alert (Manipulation) will appear in the main menu. Clicking on it will reset the alarm. The Exit button will not work.
7. In the 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.

 

CLI

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.

1. Open a terminal and navigate to the desired install directory.

   cd ~/Desktop
   

2. Clone the repository.

   git clone https://github.com/Lennolium/swiftGuard.git
   

3. Navigate to the swiftGuard directory.

   cd swiftGuard
   

4. Create a virtual environment and activate it.

   python3 -m venv venv
   source venv/bin/activate
   pip install poetry
   

5. Install poetry in the venv.

   pip install poetry
   

6. Install swiftguard in development mode.

   poetry install
   

   This installs swiftguard and its python packages in the vir