Skip to content
This repository has been archived by the owner on Feb 8, 2018. It is now read-only.
/ security-growler Public archive

📡 A Mac menubar app that notifies you whenever SSH, VNC, sudo, or other auth events occur.

Notifications You must be signed in to change notification settings

pirate/security-growler

Repository files navigation

Development is temporarily on hold, check out these alternatives in the meantime:

I have a refactor in-progress to fix Security Growler for macOS Sierra using Bitbar, but I'm too busy to finish it at the moment.


This menubar app for OS X will notify you via Notification Center (or Growl) when various security events occur (see list).

It's very useful if you're paranoid about people trying to hack into your computer. Or... if you simply like having information about people using your computer's resources.

It's extremely lightweight, the app is 3MB including the icon, with <0.01% CPU and <15MB of RAM used when running. It's easily extensible in Python, you can add parsers that detect new TCP connections or poll logfiles. You can even forward alerts as push notifications to your iOS devices using Prowl.

Install:

  1. Download and run Security Growler.app >> (dark mode)
  2. Click on the menubar icon once to start detecting events.

Download Security Growler Light.app if you don't use OS X Dark Mode. If you prefer Growl to the OS X Notification Center, run sudo easy_install gntp in Terminal and relaunch to switch.

Note: the app must be run under an account that has read access to cat /var/log/system.log (i.e. run by an admin). It will not function under a non-admin-permissions account on mac, as it needs access to several root-owned logfiles to be of any use. Running this app as a non-admin user simply doesn't make sense, because it wouldn't be able to alert on any log events in /var/log/system.log or on ports opened by other users. It would be of very limited use, and would very few security assurances if it could only alert on sockets opened by your own user account.

It can do cool things like:

Alert you of attempted and successful SSH logins:

Notify you of incoming & outgoing TCP connections: FTP, VNC, SMB, MySQL, etc.:

(using less RAM than Little Snitch)

Notify you whenever a command is run with sudo:

Let you know when you're being portscanned:

More Screenshots...

Documentation:

The currently working alert types are:

  • SSH
  • VNC
  • FTP, SMB, AFP
  • MySQL, PostgreSQL
  • iTunes Sharing
  • sudo commands
  • Ostiarius
  • port-scans (e.g. if you're on the receiving end of nmap)

Get more alerts like Wifi, VPN, LAN, bluetooth, USB device and other config changes using HardwareGrowler and MetaGrowler.

TODO:

  • new alerts types like ARP resolution, DNS resolution, etc. tracked via issues
  • keychain auth events (/var/log/authd.log, /var/log/accountpolicy.log)
  • new listening sockets under port 1000 opened

Config:

Settings are changed by editing a text file settings.py, accessible via the menubar dropdown item 'Settings...'.

To enable or disable alert types:

You can enable and disable certain alerts by editing the WATCHED_SOURCES section of the file. Add or remove event sources on the left (either port numbers or logfile paths), and put the parser names you want to enable for each source on the right. Parser names can by found by looking at the filenames in the parsers/ folder.

# this config alerts for FTP, iTunes Sharing, sudo, & SSH
WATCHED_SOURCES = {
    21:                    'connections',      # FTP
    3689:                  'connections',      # iTunes Sharing
    '/var/log/system.log': ('sudo', 'ssh'),    # sudo & ssh
}

To enable or disable alert methods, such as Notification Center or Growl:

Change the LOGGERS section to suit your needs.

LOGGERS = [
    'stdout',
    'logfile',
    'growl',
    # 'osxnotifications',  # prepend a hash to disable a certain method
]

To change notification preferences:

Change POLLING_SPEED to make the app update more or less frequently (2-10 seconds is recommended).

Change the INFO_ and ALERT_ items to modify properties such as alert sounds, icons, and text.

How should you respond to alerts?

In general, don't assume you're being attacked just because you get an alert, there are many possible situations where you may get false positives. That being said, it's good to have some documented responses in case you actually are being attacked. Here are some safe recommendations for what to do if you get different alerts in order to protect your system.

  • New TCP connections: make sure the affected service (e.g. postgresql) is not publicly accessible, or has a strong password set (check your configs and firewall)
  • New SSH connections: turn off Remote Login (ssh) under System Preferences > Sharing > Remote Login
  • New VNC connections: turn off Screen Sharing & Remote Administration under System Preferences > Sharing > Screen Sharing/Remote Administration
  • New FTP/AFP/SMB connections: turn off file sharing under System Preferences > Sharing > File Sharing
  • iTunes Sharing: turn off iTunes sharing under iTunes > Preferences... > Sharing > Share my library on my local network
  • Port scans: unplug your ethernet cable, turn off public services, or turn on your firewall to stealth mode: sudo defaults write /Library/Preferences/com.apple.alf stealthenabled -bool <true|false>
  • Sudo commands: check for any open ssh connections using the w command in terminal and check for background processes running with Activity Monitor

You can check for processes listening on a given TCP port (e.g. 80) using sudo lsof +c 0 -i:80.
You can see active network connections with sudo netstat -t or iftop (brew install iftop).
You can check for persistent background tasks and unauthorized processes running using KnockKnock and TaskExplorer.

Developer Info:

This app is composed of 3 main parts: sources, parsers, and loggers.

  • sources are either file paths or port numbers, e.g. /var/log/system.log or 5900
  • parsers e.g. ssh or sudo are fed new logfile lines yielded from sources, and parse out various alerts
  • loggers are output methods for alerts, e.g. stdout, osxnotifications, or growl

The main runloop is in growler.py, it reads lines out of the sources, passes them through parsers, then dispatches alerts before waiting a short delay and then looping.

The menubar app is a simple wrapper compiled using Platypus. Security Growler.app is packaged with copies of growler.py and all the other files it needs. To make changes to the app, change the files you need, test using sudo python growler.py and sudo ./menubar.sh, then re-run Platypus to generate a new app.

The menubar app works by displaying the output of menubar.sh, and spawning a growler.py agent in the background to write new events to a logfile. See menubar.sh for more details.

The python Foundation library that provides access to OS X API's like notification center is not available by default for python3.5, so for the moment only 2.7 is supported.

Background:

I was tired of not being able to find an app that would quell my paranoia about open ports, so I made one myself. Now I can relax whenever I'm in a seedy internet cafe or connected to free Boingo airport wifi because I know if anyone is trying to connect to my computer.

Little Snitch is still hands-down the best connection-alerting software available for Mac, I highly suggest you check it out if you want a comprehensive firewall/alerting system, and are willing to pay a few bucks to get it. Security Growler is centered around parsing logfiles for any kind of generic pattern, not just monitoring the TCP connection table like Little Snitch. For example, my app can alert you of sudo events, keychain auth events, and anything else you can think of that's reported to a logfile. This app is significantly more lightweight than Little Snitch, it comes in at <15mb of RAM used, because it aims to solve a simpler problem than Little Snitch. This app is not designed to prevent malicious connections, that's what firewalls are for, it's just meant to keep an unobtrusive log, and alert you whenever important security events are happening. The more informed you are, the better you can protect yourself.

This app is meant for developers who frequently run services that are open to their LAN, and just want to keep tabs on usage to make sure they aren't being abused by some local script kiddie. Since the target audience is developers, I opted to leave some parts a little less user-friendly, such as the settings.py config system. It's also just plain fun to enable lots of alerts types if you like to see every little detail of your computer's operation.

Feel free to submit a pull-request and add a new parser (e.g. try writing one for nginx http-auth)!

Basic Linux support will be finished soon, in the meantime check out a similar project written by @benjojo: PushAlotAuth, it uses the PushALot push-notification platform.

Also check out our growing list of community-shared useful Mac menubar apps!

Some security apps I recommend:

  • HardwareGrowler provides alerts on many hardware, network, and other config changes
  • MetaGrowler provides alerts on bonjour and network changes on other LAN hosts
  • Little Snitch comprehensive macOS alerting and firewall solution
  • Micro Snitch get alerts on camera and microphone access
  • Everything by Objective-See, a great security app developer
  • CIRCL ALOD alerts you whenever a program tries to add a login hook with launchAgents or LaunchDaemons (incredibly useful, goes well with Objective-See's KnockKnock)

License:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, pulverize, distribute, synergize, compost, defenestrate, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

If the Author of the Software (the "Author") needs a place to crash and you have a sofa available, you should maybe give the Author a break and let him sleep on your couch.

If you are caught in a dire situation wherein you only have enough time to save one person out of a group, and the Author is a member of that group, you must save the Author.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO BLAH BLAH BLAH ISN'T IT FUNNY HOW UPPER-CASE MAKES IT SOUND LIKE THE LICENSE IS ANGRY AND SHOUTING AT YOU.