Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/defuse/swatd

Run a script when one or more sensors fail.
https://github.com/defuse/swatd

Last synced: about 12 hours ago
JSON representation

Run a script when one or more sensors fail.

Awesome Lists containing this project

README 

        
SWATd

=====



[![Build Status](https://travis-ci.org/defuse/swatd.svg?branch=master)](https://travis-ci.org/defuse/swatd)



SWATd lets you configure 'sensors' that check your PC's external environment.

When enough sensors 'fail', SWATd will run a script for you.



Sensors are commands or scripts that get executed repeatedly. A sensor is said

to fail when its exit code makes a transition from zero (working) to non-zero

(not working). This makes configuration easy and powerful. For example, you can

make a sensor that checks if your website is online, and then make a command to

alert you when the sensor fails.



SWATd was originally written as a tool to defend against theft by criminals or

to detect when your computer is captured by police. For example, you can set

a sensor to detect if your WiFi network is in range, and when it goes out of

range, automatically unmount encrypted volumes. So if someone steals your laptop

from your house, your files will be safe. Since SWATd only counts the failure

when the sensor *changes* from a "WiFi in range" state to a "WiFi out of range"

state, if you use your laptop somewhere else, you don't need to worry about

disabling SWATd every time you leave your house.



**WARNING:** While this may be helpful for some, there are significant risks.

For one, in some countries, including the United States, you could go to jail on

obstruction of justice charges just for *running* SWATd, even though you are

innocent. Second, SWATd is not perfect: law enforcement or a smart thief can

still dump your RAM, thus getting your encryption keys, before doing anything

that would make a sensor fail. Use with caution, and consult an attorney first.

**It's most likely the case that if you find yourself needing to rely on SWATd,

then you have already lost.**



Building and Installing

-----------------------



To build SWATd, `cd` into the source code directory and run `make`. This will

create a `swatd` executable. If you want to install it as a daemon, refer to

your operating system's manuals. To run SWATd from a terminal (non-daemon), pass

the `-s` option.



### Arch Linux



To install SWATd on Arch Linux, copy `swatd` into `/usr/local/bin`:



    # make

    # install swatd /usr/local/bin/



Create the configuration file (See the Configuration section below):



    # mkdir /etc/swatd

    # chmod 700 /etc/swatd

    # vim /etc/swatd/swatd.conf



If you want SWATd to start when you boot, add the following to

`/etc/systemd/system/swatd.service`.



    [Unit]

    Description=SWATd

    

    [Service]

    Type=forking

    PIDFile=/var/run/swatd.pid

    ExecStart=/usr/local/bin/swatd -p /var/run/swatd.pid

    Restart=on-abort

    

    [Install]

    WantedBy=multi-user.target



Then run:



    # systemctl enable swatd.service

    # systemctl start swatd.service



You can check the status of SWATd by running:



    # systemctl status swatd.service



Read SWATd's log entries by running:



    # journalctl /usr/local/bin/swatd



### Debian 



To install SWATd on Debian, copy `swatd` into `/usr/local/bin`:



    # make

    # install swatd /usr/local/bin/



Create the configuration file (See the Configuration section below):



    # mkdir /etc/swatd

    # chmod 700 /etc/swatd

    # vim /etc/swatd/swatd.conf



Then copy `swatd.init` to `/etc/init.d/` and enable it:



    # cp swatd.init /etc/init.d/swatd

    # update-rc.d swatd defaults



Configuration

-------------



By default, SWATd looks for a configuration file in `/etc/swatd/swatd.conf`.

Alternatively, you can provide a configuration file path to SWATd with the `-c`

option. In any case, the configuration file must not be world writable, or SWATd

will refuse to run.



The configuration file syntax is extremely simple. There are only three options:

`interval`, `threshold`, and `execute`. To set a value for one of the options,

begin a line with its name, followed by a colon, followed by the value.

Everything after a '#' is treated as a comment (ignored). Blank lines are

ignored. All other lines define a sensor command.



`interval` is the number of seconds to wait between sensor checks. `threshold`

is the number of sensors that must fail before assuming you are being raided.

`execute` is the command to execute when you are being raided.



Here is an example configuration file:



    # This configuration makes SWATd continually check if /tmp/foobar exists. If

    # /tmp/foobar stops existing (goes from existing to not existing), SWATd will

    # write some text to the file /tmp/ran.

    

    # =============================================================================

    # The number of seconds to wait between sensor checks.

    # =============================================================================

    interval: 30

    

    # =============================================================================

    # The number of sensors that must 'fail' at the same time.

    # =============================================================================

    threshold: 1

    

    # =============================================================================

    # The command to execute when 'threshold' sensors fail.

    # =============================================================================

    execute: echo "haiii" > /tmp/ran

    

    # =============================================================================

    # Sensor commands.

    # A sensor has 'failed' when the exit code transisions from zero to non-zero.

    # If a sensor's exit code is transitions from zero to 255, the command will be 

    # executed immediately regardless of the 'threshold' setting, and the failure

    # count will not be incremented.

    # WARNING: Sensor commands MUST terminate.

    # =============================================================================

    

    test -e /tmp/foobar