florianoverkamp / yourls-abusedesk

======================================================================================
Abusedesk plugin for Yourls - URL Shortener

Copyright (c) 2010-2012, Florian Overkamp <florian@tty.nu>

Abusedesk for Yourls is a plugin module written and tested with Yourls SVN rev. 755 
(a.k.a. release 1.5.1) but is probably functional with any release of 1.4 or higher.

Abusedesk is designed to allow YOURLS-administrators to prevent or restrict abuse by
link-posters. It does this by the following methods:

1) Implement a blacklist and a report-page. If any visitor states a short URL is abusive, 
the system will automatically mark the URL as 'bad' and report future visitors of this.

2) Implement a banlist and allow the administrator to prevent certain IP-addresses to
post, or prevent certain (partial) URL's to be shortened.

3) If Google Safe Browsing is activated, prevent visitors from running into (known) phishing or
malware sites

======================================================================================
REQUIREMENTS

1) An installed and working Yourls setup
2) Subversion (for downloading phpGSB)

HOW TO INSTALL

1) Place the yourls-abusedesk folder in the user/plugins directory from Yourls
2) Copy config-sample.php to config.php (in the plugin directory, not the main yourls 
   configuration) and insert appropriate values
3) Activate Abusedesk for Yourls from the Yourls Admin interface
4) (Optional) Link report.php from the pages/ subdirectory

NOTE: The plugin will automatically attempt to create two new database tables if they 
don't yet exist. However, this does mean that if the Yourls database user does not have 
CREATE TABLE grants on the database, you will need to do that manually.

HOW TO ACTIVATE Google Safe Browser

Google Safe Browsing is implemented by installing/using phpGSB.

1) Get a Google Safe Browsing API key
2) Adjust config.php: uncomment and insert yout API key
3) Run the install-gsb script once, it will download phpGSB from subversion and create the database tables
4) Run the update-gsb script periodically (i.e. once per hour) from cron to 
   load the hash-tables

PLEASE NOTE: Full population of the hash-tables will take around 24 hours. This is because Google gives
you the hash-tables in small chunks over time. (Thanks to Sam Cleaver for noting this omission in the docs)

You can test Google Safe Browsing by using the check-gsb script from the shell on the webserver: For example:

| florian@web01:~/apps/yourls/user/plugins/yourls-abusedesk$ ./check-gsb http://blog.tty.nu/
| 
| Clean: http://blog.tty.nu/
| 
| florian@web01:~/apps/yourls/user/plugins/yourls-abusedesk$ ./check-gsb http://malware.testing.google.test/testing/malware/ 
| 
| MALWARE: http://malware.testing.google.test/testing/malware/
|

======================================================================================