psal / anonymouth

#Anonymouth

Document Anonymization Tool, Version 0.5

The Privacy, Security and Automation Lab (PSAL)
Drexel University, Philadelphia PA
http://psal.cs.drexel.edu/

#Index

1. Set Up
   • Introduction
   • Dependencies
   • Installation
   • How to Build and Run
2. Development
   • Basic Logic Flow
   • Basic Class Strucutre
   • To Do List
   • Known Bugs
3. Credits
   • Developers
   • License

#Set Up

###Introduction

Anonymouth is a Java-based application that aims to give users to tools and knowledge needed to begin anonymizing documents they have written.

It does this by firing up JStylo libraries (an author detection application also develped by PSAL) to detect stylometric patterns and determine features (like word length, bigrams, trigrams, etc.) that the user should remove/add to help obsure their style and identity.

Though Anonymouth and it's team works hard to provide you with tools to help remove your identity from documents you have written, WE CAN IN NO WAY GUARANTEE THAT YOUR DOCUMENT IS ANONYMOUS OR NOT ANONYMOUS. Anonymouth is always giving you it's best guess, it's best idea of where your document stands, though that should not any any time be taken as an absolute (for example, you could have forgotten to remove your name from the document and Anonymouth has no way to know that that's your name and should remove it). What we can say is Anonymouth is only as good as you make it, and when used right can be helpful in guiding your document towards the right direction.

Back to top

###Dependencies

Java 7 is required to run Anonymouth. If you don't yet have it, get it at Oracle's website here and follow the installation instructions provided there.

If you are unsure whether or not you have it installed, follow these steps to see:

• OS X:
  1. Open up Terminal (Applications/Utilities)
  2. Type "java -version" without the quotes
  3. If you see something like java version "1.7.x_xx" then you're ready to go! If not, then that means you most likely don't have Java 7 installed, in which case you should go to the download link above
• Windows:
  1. Follow the instructions here: http://www.java.com/en/download/help/version_manual.xml. if you have version "1.7.x_xx", then you're good to go! If not, then that means you most likely don't have Java 7 installed, in which case you should go to the download link above

If you are using Eclipse, also make sure that Java 7 is your selected compiler by checking Preferences/Java/Compiler and is an included Library in your java Build Path (Not sure how to do this? Google is your friend).

Anonymouth requires the included jsan_resources directory in it's running directory (The main Anonymouth directory containing lib, src, etc.). It should be in the correct directy by default.

Anonymouth requires a corpus (basically a database of other authors and documents they have written) to run. It needs this so it can classify your documents with respect to these other documents and their styles so that Anonymouth can give you an idea of how anonymous it thinks your document is and what features to remove/add to help you get there. Three different corpi are included in the project directory for you to choose and are located at:

• ./anonymouth/jsan_resources/corpora/amt
• ./anonymouth/jsan_resources/corpora/drexel_1
• ./anonymouth/jsan_resources/enron_demo

Though we included corpi, you are more than welcome to use any other corpus you may have. It is recommended to use many different combinations of authors so you can get the best posisble picture of where your document stands anonymously with respect to others.

Anonymouth also needs the following jars in the lib directory (everything should already be included):

Package Name	Version
weka	3.7.9
fasttag	2.0
Jama	1.0.3
jaws	1.3
jcommon	1.0
freechart	1.0.14
jgaap	5.4.0
microsoft translator	0.6.1
miglayout	4.0
tt4j	1.0.15
Stanford postagger	-
ui	-

Back to top

###Installation

There quickest and easiest way to install Anonymouth is to clone or download the zip of the Anonymouth github project here

And then import this project as an existing project into Eclipse (or clone and import directly within Eclipse if you have the Eclipse eGit plugin).

This is currently the only ready way to compile and run Anonymouth. We will be including a updated build file soon so that you may build and run Anonymouth easily within the command land, but sadly it hasn't been done yet so this is the only option currently

Back to top

###How to Build and Run

Once Anonymouth is all set up in Eclipse, you need only run ThePresident from the package edu.drexel.psal.anonymouth.gooie to begin using it.

Please note that there are two main package categories, JStylo and Anonymouth. The majority of Anonymouth developement should be in the Anonymouth packages as Anonymouth simply uses the JStylo libraries for parts of the initial document process, so beginners need only concern themselves with the Anonymouth packages.

Back to top

#Development

###Basic Logic Flow

#####↓ ---LAUNCH---

Setup and start up: anonymouth.gooie.ThePresident

Should never be accessed in any other class (or at least limit it). It's only purpose is to initialize the main class and other start up classes.

• Readies and displays splash screen
• Prepares the Logger
• Initializes the GUIMain instance (and with it all Anonymouth class instances)
• Displays the start window, which from there it takes over

#####↓ ---AUTOMATICALLY DISPLAYS---

Start up window: anonymouth.gooie.StartWindow

The first window that shows up (not counting the splash screen) when Anonymouth loads up. Allows the user to change advanced processing settings, access the pre process set up wizard, or start Anonymouth

#####↓ ---USER CLICKED START BUTTON---

Initial document processing begins immediately with: anonymouth.engine.DocumentProcessor

Inititalized within GUIMain as should nearly all Anonymouth class instances, this holds the main method and thread that handles processing and reprocessing documents. All processing events can be traced back to this class.

#####↓ ---PROCESSING COMPLETE---

Main GUI Code: anonymouth.gooie.GUIMain

The main gui window is displayed. This is also the central "hub" for Anonymouth. This should be the main instance center, and anytime you want to access code from other classes from another class you more than likely will be going through this.

• Houses and initialized nearly all class instances in Anonymouth
• Lays out and creates the main Anonymouth window

From here the logic flow depends largely on what the user does:

• If they're editing in the editor, the main class handling that is anonymouth.googie.EditorDriver
• If they are using translations the main class handling that is anonymouth.gooie.TranslationsPanel
• If they are using word suggestions, the main class handling that is anonymouth.gooie.WordSuggestionsDriver
• If they are changing Preferences, the main class handling that is anonymouth.gooie.PreferencesWindow
• etc.

Back to top

###Basic Class Structure

#####---Naming Convention---

For the most part, Anonymouth splits UI objects into two classes: [Class name]Panel/Window and [Class name]Driver. By convention and a general guideline, the Panel/Window class:

• Creates and lays out all swing components
• Handles all get, set, and is methods (if any)
• Handles assert methods (if any)
• Handles UI update/panel switch methods (if any)

While the cooresponding Driver class:

• Handles all listeners
• Hanldes most backend/data manipulation and updating

Again, these are just general guidelines. Sometimes it makes more sense to just have one class handle everything if it's a small object, or sometimes it doesn't make sense to have a seperate Panel/Window class but it does to have a Driver class, etc. You just need to use your best judgement on what will make things more organized and easier to understand.

#####---Package / Organizing Convention---

Anonymouth loosly follows these guidelines for class organization in packages:

• anonymouth.engine For all processing code and any classes you deem "enginey" (for example, HighlighterEngine, VersionControl, etc.)
• anonymouth.gooie For all classes displaying or creating swing components and their respective Driver classes
• anonymouth.helpers For classes that aren't necessarily Anonymouth specific, but are used by Anonymouth for general purposes and tasks (for example, FileHelper, ScrollToTop, ImageLoader, etc.)
• anonymouth.utils For classes that serve only as a means for storing and manupulating data (For example, TaggedSentence, TaggedDocument, Word, TextWrapper, etc.)

There are still quite a few classes that are clearly where they don't belong, so feel free to oragnize Anonymouth so that it best fits these guidelines.

Back to top

###To Do List Add features as they are conceived and strikethrough as they are completed ([1] means most important and [5] means relatively small and not particularly a priority at the moment)

• [1] AUTOMATE AS MUCH OF THE ANONYMIZATION PROCESS AS POSSIBLE. This should be the top priority as of now, see Andrew for the plan and details.
• [1] An internal thesaurus must be implemented to help users change words to remove (that or nicely implement the one built into the system, preferable if possible)
• [2] An intelligent method to search and filter through words to add (start with simple search box, then possibly extend to automatic filtering based on synonyms?)
• [5] The clusters window should be updated to be easier to understand and use (it's hidden away in Window > Clusters)

Back to top

###Known Bugs Add bugs as they are discovered and strikethrough as they are completed ([1] means fatal or breaks usability and [5] means relatively small and does not have much of an impact on usability)

• [1] During processing on OS X (though the problem may extend to other operating systems as well) the Stanford POS tagger is extremely prone to breaking due to a fatal threading issue which results in heap space or out of memory exceptions. This absolutely MUST be fixed.
• [2] The threading with the words to add refresh is not that great, fails to refresh at times and throws exceptions every once in a while.
• [3] For whatever reason, Anonymouth does not seem to process or recognize all cap words LIKE THIS when working in the editor.
• [5] The max features slider in Preferences does not work as expected at times and is a little finicky.
• [5] Currently Anonymouth is all running on the initial thread which should NOT be the case. This should be done in a GUI creation and show task thread, though when I tried this in the past it breaks the slash screen.

Back to top

#Credits

###Developers

P.I. Dr. Rachel Greenstadt:

• Forward questions or concerns pertaining to the lab or its other projects to [email protected]

Developed by:

• Andrew W.E. McDonald
  • Forward questions or concerns pertaining to Anonymouth in general or document processing to [email protected]
• Marc Barrowclift
  • Forward questions or concerns pertaining to Anonymouth's UI or front end/editor to [email protected]
• Jeff Ulman
• Joe Muoio

Back to top

###License

Anonymouth was released by the Privacy, Security and Automation lab at Drexel University in 2011 under the AGPLv3 license. A copy of this license is included with the repository/program. If for some reason it is absent, it can be viewed here.

Back to top

anonymouth's Issues

Attempting to `javac ThePresident.java`

Having an issue to try and run the GUI from the command line is this possible without Eclipse?

$ ~/Repos/anonymouth/ >  javac src/edu/drexel/psal/anonymouth/gooie/ThePresident.java
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:3: error: cannot find symbol
import edu.drexel.psal.ANONConstants;
                      ^
  symbol:   class ANONConstants
  location: package edu.drexel.psal
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:4: error: package edu.drexel.psal.anonymouth.helpers does not exist
import edu.drexel.psal.anonymouth.helpers.ImageLoader;
                                         ^
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:5: error: package edu.drexel.psal.anonymouth.utils does not exist
import edu.drexel.psal.anonymouth.utils.About;
                                       ^
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:6: error: package edu.drexel.psal.jstylo.generics does not exist
import edu.drexel.psal.jstylo.generics.Logger;
                                      ^
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:40: error: cannot find symbol
    protected static StartWindow startWindow;
                     ^
  symbol:   class StartWindow
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:41: error: cannot find symbol
    public GUIMain main;
           ^
  symbol:   class GUIMain
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:52: error: cannot find symbol
    public static SplashScreen splash;
                  ^
  symbol:   class SplashScreen
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:47: error: cannot find symbol
    public static int max_Features_To_Consider = PropertiesUtil.defaultFeatures;
                                                 ^
  symbol:   variable PropertiesUtil
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:48: error: cannot find symbol
    public static int num_Tagging_Threads = PropertiesUtil.defaultThreads;
                                            ^
  symbol:   variable PropertiesUtil
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:49: error: cannot find symbol
    public static boolean should_Keep_Auto_Saved_Anonymized_Docs = PropertiesUtil.defaultVersionAutoSave;
                                                                   ^
  symbol:   variable PropertiesUtil
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:50: error: cannot find symbol
    public static boolean autosave_Latest_Version = PropertiesUtil.defaultAutoSave;
                                                    ^
  symbol:   variable PropertiesUtil
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:74: error: cannot find symbol
        splash = new SplashScreen();
                     ^
  symbol:   class SplashScreen
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:77: error: cannot find symbol
        logo = ImageLoader.getImage(ANONYMOUTH_LOGO_LARGE);
               ^
  symbol:   variable ImageLoader
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:78: error: cannot find symbol
        aboutLogo = ImageLoader.getImageIcon(ANONYMOUTH_LOGO);
                    ^
  symbol:   variable ImageLoader
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:79: error: cannot find symbol
        dialogLogo = ImageLoader.getImageIcon(ANONYMOUTH_LOGO_SMALL);
                     ^
  symbol:   variable ImageLoader
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:80: error: cannot find symbol
        dialogIcon = ImageLoader.getIcon(ANONYMOUTH_LOGO_SMALL);
                     ^
  symbol:   variable ImageLoader
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:82: error: cannot find symbol
        if (ANONConstants.IS_MAC) {
            ^
  symbol:   variable ANONConstants
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:85: error: cannot find symbol
            Logger.logln(NAME+"We're on a Mac!");
            ^
  symbol:   variable Logger
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:97: error: cannot find symbol
                    if (PropertiesUtil.getWarnQuit() && !main.documentSaved) {
                        ^
  symbol: variable PropertiesUtil
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:109: error: cannot find symbol
                    } else if (PropertiesUtil.getAutoSave()) {
                               ^
  symbol: variable PropertiesUtil
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:110: error: cannot find symbol
                        main.menuDriver.save(GUIMain.inst);
                                             ^
  symbol: variable GUIMain
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:121: error: cannot find symbol
                            About.aboutAnonymouth,
                            ^
  symbol: variable About
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:137: error: cannot find symbol
        File log_dir = new File(ANONConstants.LOG_DIR); // create log directory if it doesn't exist.
                                ^
  symbol:   variable ANONConstants
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:139: error: cannot find symbol
            Logger.logln(NAME+"Creating directory for DocumentMagician to write to...");
            ^
  symbol:   variable Logger
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:144: error: cannot find symbol
        File dm_write_dir = new File(ANONConstants.DOC_MAGICIAN_WRITE_DIR);
                                     ^
  symbol:   variable ANONConstants
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:146: error: cannot find symbol
            Logger.logln(NAME+"Creating directory for DocumentMagician to write to...");
            ^
  symbol:   variable Logger
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:149: error: cannot find symbol
        File ser_dir = new File(ANONConstants.SER_DIR);
                                ^
  symbol:   variable ANONConstants
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:151: error: cannot find symbol
            Logger.logln(NAME+"Creating directory to save serialized objects to...");
            ^
  symbol:   variable Logger
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:155: error: cannot find symbol
        if (!ANONConstants.IS_USER_STUDY) {
             ^
  symbol:   variable ANONConstants
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:161: error: cannot find symbol
        main = new GUIMain();
                   ^
  symbol:   class GUIMain
  location: class ThePresident
src/edu/drexel/psal/anonymouth/gooie/ThePresident.java:162: error: cannot find symbol
        startWindow = new StartWindow(main);
                          ^
  symbol:   class StartWindow
  location: class ThePresident
Note: src/edu/drexel/psal/anonymouth/gooie/ThePresident.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
31 errors

Make a browser plugin

Would be very useful

Add compiled releases to GitHub

Love the project. Is there any reason why you couldn't offer pre-compiled files for people to use and test. Forcing them to compile would seem an unnecessary barrier to participation. Thanks!

/me goes off to install eclipse :)

hideSplashScreen() opacity issue

When running in eclipse in linux I get the below error :

Exception in thread "main" java.lang.UnsupportedOperationException: TRANSLUCENT translucency is not supported.
    at java.awt.Window.setOpacity(Window.java:3598)
    at java.awt.Frame.setOpacity(Frame.java:962)
    at edu.drexel.psal.anonymouth.gooie.SplashScreen.hideSplashScreen(SplashScreen.java:154)
    at edu.drexel.psal.anonymouth.gooie.ThePresident.<init>(ThePresident.java:164)
    at edu.drexel.psal.anonymouth.gooie.ThePresident.main(ThePresident.java:70)

I was able to rectify this by removing line 154 in SplashScreen.java

Program Errors On Proces

Every time I click the process button I get a popup "Something went very wrong error". Then the program proceeds to crash after pressing okay.

Porting out of Java

Not sure if you're aware, but the Tails Live project is interested in a stylometry tool. The Java dependency is an issue for them, although I'm not sure there's anything to be done about this. But yet, thinking maybe you were considering a rewrite anyhow, so thought I'd put it out there :)

https://labs.riseup.net/code/issues/5726

Migrate this project to java 8 ,9 or 10

Is this a bug:
No
I need to migrate this project from java 7 to9 ,10 or at least 8 , since Java 7 is not compatible with JavaFx 8 , hence Is there a fast or easy solution for migrating the project to newer version of Java?

Maintenance

Is this project being maintained by anyone? It looks very interesting and increasingly useful in today's world.

Compile without Eclipse

I'd love to try this out, but Eclipse is a bit of a bulky install. Do you think there are any plans for an Ant build system?

Cheers.