ConfigServer Outgoing Spam Monitor
==================================

ConfigServer Outgoing Spam Monitor (osm) has been designed to use multiple methods to monitor outgoing email and SMTP connections for activity that could indicate a spammer is active on a server.

With the proliferation of web scripts in shared hosting environments that are often poorly maintained or badly written, the chances of a hacker exploiting vulnerabilities in scripts is at an all time high. Additionally, end-user PC's and other devices that send email through a server (relay) that have been compromised and used as a spam source has always been a problem. These issues along with spammers deliberately targeting hosting providers by purchasing accounts simply to send out spam have kept the diligence required to prevent spam from being sent from servers all the more difficult.

osm tries to tackle this problem by automated checking of email log entries and SMTP packet interception to identify patterns of email abuse on cPanel servers. It does this through a running daemon process called osmd and a WHM UI to configure its actions and to provide a central resource to view event reports.

osm uses three main methods to detect spamming events together with several specific sub-methods. Configurable actions allow a range of options once a series of events triggers a report. These include Account suspension, email queuing, script renaming, IP address blocking. Additionally, a custom action is available that will run a user supplied script.

Threshold triggers for each type of event down to the account level together with an ignore list allow for finely grained trigger level configuration if desired.


osm Daemon
##########

1. SMTP Packet Interception (packet)
===========================

osm uses a hook into the Linux kernel to intercept outbound (or to localhost) SMTP connections on port 25, 465 and 587. While this technique cannot count the number of actual emails (it cannot look inside the packets), it does provide information about the outgoing connection including the source IP and port and the destination IP and port. Using this information osm determines which process is using this connection and obtains information from the process that provides that details needed to track the emails.

osm keeps track of the number of outgoing connections made by each cPanel account in use as well as the path used by the process sending the email. If the number of connections made by a single cPanel account exceeds the configured limit, a report is triggered.

See possible restrictions on this functionality in the Requirements section.

Additionally, the packet inspection process also tries to match the running process with related URL's being accessed to try and determine the possible script in use (see Apache Status section).

1a. SMTP Packet Interception Path Matching (packet:cwd)
------------------------------------------

As part of the Packet interception process, osm determines the path being used by the process sending email. osm counts matching paths used by connections and if the number for the same path exceeds the configured limit, a report is triggered.

2. Exim Log Line Processing (logline)
===========================

osm monitors the exim email log for lines generated when exim sends out email. osm uses the information from these log lines to determine how the email is being sent. If it is via an authorised email account login, that account will be tracked and if it exceeds the configured limit, a report is triggered. The source IP address of the account relaying email through the server is also noted.

If the log lines are being generated from a local source (script) then the cPanel use account that is used is tracked and if it exceeds the configured limit, a report is triggered.

Additionally, the packet inspection process also tries to match the running process with related URL's being accessed to try and determine the possible script in use (see Apache Status section).

2a. Exim Log Line Subject Matching (logline:subject)
----------------------------------

As part of the Exim log line processing, if the email is being sent by a local script then osm identifies the process and the path it uses. osm counts matching paths used by the process and if the number for the same path exceeds the configured limit, a report is triggered.

3. Exim Log Line Path Processing (cwdcheck)
================================

In addition the logline processing, osm also monitors the log lines generated by exim that specify the path (cwd=/path/to/script/) that exim determines is used by the process sending out email. osm counts the cPanel user that owns the path being used and if the number for the same account exceeds the configured limit, a report is triggered. 

Additionally, the packet inspection process also tries to match the running process with related URL's being accessed to try and determine the possible script in use (see Apache Status section).

3a Exim Log Line Path Matching (cwdcheck:cwd)
------------------------------

As part of the Path Processing, osm keeps track of matching paths being used and if the number for the same path exceeds the configured limit, a report is triggered.


Apache Status
=============

If enable in settings, whenever one of the three event types is triggered osm tries to match the event with URL's currently being accessed by the cPanel account involved. If it can determine matching connections, it will use these to list possible scripts that are currently in use and provides this information to the generated report. See possible restrictions on this functionality in the Requirements section.


Reports/Triggers/Actions
========================

When the number of events being monitored by osm _exceeds_ the configured trigger level within the configured time interval, a report is generated and any configured actions are performed based on the information proved in the report from each of the events that exceeded the trigger level.

Events are discarded when their age exceeds the configured time interval or if they are used in a report but only for the trigger exceeded.

One or more actions can be performed when a report is generated depend on the information obtained by osm for each event. They include: report notification by email; storing of the report data for inspection through the WHM UI; cPanel Account suspension; cPanel Account sending block; Email account suspension; Email account login blocking; Email account sending block; Email queuing (hold); rename script path; rename script; firewall IP address; custom action passing data from osmd using configurable formats (JSON, XML, YAML, PERL).


osm WHM User Interface
######################

Settings
========

All configuration for osm is done through the WHM UI. 


Event Configuration
===================


Custom Action
=============


osmd Controls
=============


Requirements
============
cPanel
Apache for mod_status
Pcap kernel access via libpcap (for packet interception)
