dskfh / flockflock Goto Github PK

FlockFlock - file access policy enforcement
by Jonathan Zdziarski 

This project is currently UNDER DEVELOPMENT and ALPHA VERSION.

USE AT YOUR OWN RISK!

NOTE: I have applied for a kext signing certificate from Apple. Without 
one, FlockFlock only works with SIP's kext checking turned off on the 
host machine, therefore FlockFlock should be used only for testing until 
Apple provides a cert.

WHY WE NEED FLOCKFLOCK

One of the worst parts about being compromised is not knowing you're 
compromised, and having your data stolen by spyware, or hijacked by
ransomware, only to find out about it too late. Most security researchers 
aren't even 100% positive that their system hasn't been compromised. 
Between spyware, ransomware, misbehaving applications, government hacking, 
and other threats, simply relying on file permissions and a secure 
execution environment no longer cuts it. There's a much needed solution 
for a tool that can keep your personal data protected from potentially 
malicious software that has rooted your system, or to monitor applications 
that you have to have installed, but don't necessarily trust.

WHAT IS FLOCKFLOCK?

In Simple Terms:

FlockFlock is a utility to help protect your personal files in OS X,
to be able to tell if your system has been compromised, to ensure your
applications are respecting your privacy, and to defend your personal data 
against ransomware, spyware, infection, and other threats by preventing 
unauthorized processes (even by super user processes) from being able to 
open and read your files without your explicit permission.

In short, FlockFlock is like the popular "Little Snitch" program, but for
file access instead of network connections. It integrates with the
operating system on a low level, and has capabilities higher than root.

For Developers:

FlockFlock is a programmable OS X kernel extension that enforces file access
policy using OS X's kernel-level MAC (mandatory access control) framework.
The MAC framework began in TrustedBSD and was later adopted into the
Darwin kernel; it allows FlockFlock to intercept every file open call on
the system and analyze it against a set of rules programmed into the kernel
at login time. Even if an attacker gets root on your system and kills off
the helper daemon, the kernel module will continue to enforce the user's
rules (and also attempt to defend FlockFlock from being unloaded or
deleted).

FlockFlock comes in two pieces: the kernel extension, which contains a live
copy of all active rules (so that a rooted device should not be able to
disable it), and a user space client, which runs when the user logs in to
program the kernel module, prompt the user for unauthorized file access
attempts, and add new rules to the user's ~/.flockflockrc file.

FlockFlock is also open source, because there is such a lack of good
driver and kernel code for Mac. I think you'll find FlockFlock to be
very useful in developing your own kernel-mode drivers. FlockFlock is an
IOKit based driver, and the source code should help you understand
complex concepts such as mach messages, user-space client communication,
driver contruction, memory and locking, and much more. Enjoy the knowledge!

WHY THE STUPID NAME?

It's a play on words with the old unix "flock" style advisory locking
combined with a hat tip to Patrick Wardle, author of BlockBlock, which
is a different type of system integrity protection tool you should also
be using.

NOTE: FlockFlock's locking is much more advanced than the flocks of olde,
    it's just a play on words, and does not rely on (or use) flocks.

FEATURES

- Real-time, kernel-level protection against unauthorized access to files
- Defend against ransomware, spyware or other malicious programs that
  might attempt to steal or encrypt your personal
- Monitor applications to ensure they aren’t misbehaving, and are
  respecting your personal privacy by accessing your data files.
- A user-friendly interface to add new rules and receive notifications of
  unauthorized access attempts.
- Persistence; protects itself against root processes from unloading
  the kernel extension or tampering with core files.
      * This feature has been disabled in alpha versions

INSTALLATION

NOTE: Until Apple provides me with a kext signing certificate, you 
will have to disable SIP's kext checks in order to use FlockFlock, but
can leave the rest of SIP on. This slightly compromises the security of 
macOS, so I only recommend using FlockFlock for testing until Apple cuts a 
kext signing cert for me. 

Reboot your computer into "Recovery Mode" by rebooting and holding in
Command-R after the chime, until it boots to the recovery partition.
Start a Terminal (Utilities->Terminal) and type:

    csrutil enable --without kext; reboot

After your system reboots, double click the FlockFlock.pkg file and follow 
the installation process. A reboot is recommended after installation, but 
not required.

FIRST RUN

When the system comes back up, FlockFlock should be active on your
system, and you should start being prompted to grant file access
permissions to various programs you might run.

When first running your favorite applications for the first time,
you'll be prompted to allow or deny access to specific files or folders.
This allows you to set up initial access rules. FlockFlock will remember
your choices so it won't bother you again, unless you check the box
"Forget after Restart".

RULES EDITING

For manual rules editing, edit the .flockflockrc file in your home
directory. You will need to reboot in order for the changes to take effect,
since they are programmed directly into the kernel.

REMOVAL 

sudo -s
rm -rf /Library/Extensions/FlockFlock.kext
rm -rf /Library/Application\ Support/FlockFlock
rm -f /Library/LaunchDaemons/com.zdziarski.FlockFlock.plist
rm -f ~/Library/LaunchAgents/com.zdziarski.FlockFlockUserAgent.plist
rm -f ~/.flockflockrc
reboot

PERSISTENCE 

The module prevents deletion of core files. Any attempt to unload the
kernel extension, except through recovery mode, will cause a kernel
panic and subsequent reboot. Its data files and core files are protected
from modification, and its processes are protected from being killed. 

The user interface has a convenient menu option to disable FlockFlock so
that it can be removed or upgraded without booting into recovery mode. This
requires user interaction, providing a reasonable compromise between
security and usability.

NOTE: Persistence is disabled for alpha versions

COMPATIBILITY

Tested With:
    El Capitan
    Sierra Beta 4

    NOTE: THIS SOFTWARE IS ALPHA SOFTWARE AND MAY HAVE BUGS

KNOWN BUGS

- Please send me bug reports

FUTURE PLANS
- Implement a rules editing tool in user-space and give it exclusive
  editing capabilities (to avoid having to boot into recovery mode)
- Implement activity logging
- Richer popup screen to support more configurations

FAQ

- What does this protect?
  The default ruleset protects files in /Users only, although this can
  be changed. If FlockFlock tried to block on every file acccess in the
  system, everything would come to a screeching halt. 

- Does this impact performance?
  When an application attempts to access a protected file, FlockFlock
  performs a policy lookup. The lookup is generally fast, and should not
  impact performance except possibly on extremely busy systems that are
  opening a lot of files in the background.

- Where performance is impacted is the quarantine during a user prompt.
  If FlockFlock decides the user must approve the file access, then the
  program is blocked on the file access until the user responds. This, 
  obviously, is the behavior you want, but if you let the prompt sit there
  forever, you'll end up getting a backlog of prompts to answer, which can
  become a bottleneck for you. It could possibly also make some programs
  malfunction, such as those that are waiting for a file to open and let
  a network connection time out due to being blocked.

ACKNOWLEDGMENTS
Thanks to Patrick Wardle for providing some initial code to peruse on the
MAC framework and his blog posts on pid task tracking.

CHANGELOG

0.0.1	Initial alpha release
0.0.2   Temporarily disable persistence mechanisms for alpha testing
        Break lock if driver disconnects
        Truncated /Application apps to their .app container
        Resolved issued with duplicate queries
        Reduced the sleep time between waiting for policy lock
        Re-checked policy list before sending blocked queries
0.0.3   Added radio buttons for choosing "Once", "Until Restart",
        and "Forever"
0.0.4   Fixed issues with OSDictionary, replaced with custom structure
0.0.5	Implemented KAuth to replace vnode_check_exec hooks
        Added process hierarchy (e.g. "/bin/sh via Xcode")
        Improvements to locking and memory allocation
        Significant code cleanup
        Added keychain files to default ruleset, as many apps use it
        Other various improvements
        Hopefully added (some) stability for Sierra
0.0.6	Added MAC hooking to detect and associate posix spawned procs
        Cleanup temporary tables in memory
        Added "Until Quit" option, made the default
        Added application icon to user prompt
0.0.7	Fixed a crash in the user agent when adding "Any Files"
	Stability improvements for Sierra 
0.0.8	Fixed a bug that led to a kernel panic
0.0.9 	Manicured display names for the user
	Improvements to finding the application path icon
	Fixed a bug that caused a crash in the user agent
	Incorporated master userspace/kernel security protocol
	Fixed a bug causing ~/Library/LaunchAgents to not get creaetd
0.0.10 	Don't blow up the agent on unicode filenames
	Rolled agent into an app with status bar icon for enable/disable
0.0.11* Fixed packaging issues and macOS relocation, etc
        Made small change to help hide agent from dock better
        Nicer icon for the status bar
0.0.12	Treat /Library/Application Support/FlockFlock/.flockflockrc as a
	    a system-wide configuration file, append to ~/.flockflockrc
	Support $HOME in rules for current home directory
	Deny driver connection attempts by root (userland only)
	Don't start filter until initial programming is complete