# Octopussy (software)

Octopussy, also known as 8Pussy, is a free and open-source computer-software which monitors systems, by constantly analyzing the syslog data they generate and transmit to such a central Octopussy server (thus often called a SIEM solution). Therefore, software like Octopussy plays an important role in maintaining an information security management system within ISO/IEC 27001-compliant environments.
Octopussy has the ability to monitor any device that supports the syslog protocol, such as servers, routers, switches, firewalls, load balancers, and its important applications and services. The main purpose of the software is to alert its administrators and users to different kinds of events, like system outages, attacks on systems or errors in applications. However, unlike Nagios or Icinga, Octopussy is not a state-checker and therefore problems cannot be resolved within the application. The software also makes no prescription whatsoever on which messages must be/must not be analyzed. As such, Octopussy can be seen as less powerful than other popular commercial software in the same category (event monitoring and log analysis).
Octopussy is compatible with many Linux system distributions like Debian, Ubuntu, OpenSUSE, CentOS, RHEL and even meta-distributions as Gentoo or Arch Linux. Although Octopussy was originally designed to run on Linux, it could be ported to other Unix variants like FreeBSD with minimal effort. Octopussy has extensive report generating features and also various interfaces to other software, like e.g. NSCA (Nagios), Jabber/XMPP and Zabbix. With the help of software like Snare even Windows EventLogs can be processed.
Octopussy is licensed under the terms of the GNU General Public License.

## Characteristics

Although Octopussy is free and open-source software it has a variety of characteristics also found in some professional enterprise applications like Splunk, SAWMILL or Kiwi Syslog.

### Octopussy features

At the time of writing, Octopussy comes with the following set of features:
* Basic LDAP support (v1.0+) for Octopussy users and contacts with filter mechanism
* Alert sending by email, IM (Jabber), NSCA (Nagios) and Zabbix
* Map functionality to show the system infrastructure known to Octopussy
* Exportable reports by email, FTP and SCP
* Input & output plugins for manual and automatic reports
* Report scheduling and automated report generation based on parameters
* A log viewer to search for syslog messages received by Octopussy
* An RRDtool to provide data graphing of syslog activity for enabled services
* Comprehensive service definitions (Apache 2, BIND, BSD Kernel ...)
* A wizard to easily create new services and/or message patterns for existing services
* An option to enable or disable services and alerts for every system under surveillance
* Online updates for services, tables and l18n (language support)
* Multi-language support: English French German Italian Spanish Portuguese Russian
* A web-interface for viewing current devices status, alerts, log messages, etc.
* A themable interface and report documents
* Manageability of Octopussy core services from the operating system shell
* Flat-text formatted configuration files (integrates with many configuration editors)
* An option to timely rotate and store received syslog messages in various locations
* User management with the ability of granular permission configuration
* Simple outline of styles and GUI components in ASP for easy modification

### Supported services

Some of the (meta-)services supported by/known by Octopussy are:
Apache 2, BIND, BSD Kernel, BSD PAM, BSD System, Cisco Routers (ASR), Cisco Switches, ClamAV, DenyAll Reverse Proxy, DRBD, F5 BigIP, Fortinet FW, HP-Tools, Ironport MailServer, Juniper Netscreen FW, Juniper Netscreen NSM, LDAP, Linux AppArmor, Linux Auditd, Linux IPTables, Linux Kernel, Linux PAM, Linux System, Monit, MySQL, Nagios, Neoteris/Juniper FW, NetApp NetCache, Postfix, PostgreSQL, Samba, Samhain, SNMPd, Squid, SSHd, Syslog-ng, TACACS, VMware ESX(i), Windows Snare Agent, Windows System, Xen ...

### Processible events

Events receivable from services and thus processible by Octopussy include:
* Failed and/or successful logins, especially of higher privileged users
* Violation of access permissions or policies in applications and operating systems
* Write and/or read access in critical environments, e.g. with AppArmor or SELinux
* Established or terminated VPN tunnels in systems, like e.g. Juniper Netscreen
* Objects like processes or files which security context or configuration changed
* Started or stopped processes on an operating system level
* Critical system states like (unrecoverable) hardware or software failure
* Change in operating system state due to boot, reboot or shutdown
* Information regarding network connections/traffic, including ICMP messages, etc.
* Detection or otherwise handling of malware (i.e. worms, viruses, trojans)

## Dependencies

The software requires RSYSLOG installed on the syslog-server and expects systems that are monitored to run one of the numerous available syslog services, like e.g. syslogd/klogd, RSYSLOG or syslog-ng.
The software further depends on the Apache 2 HTTP Server installed, with Apache::ASP, Mod_Perl and Mod_SSL. Octopussy also requires a MySQL DBMS (actual database is installed/copied during Octopussy setup) as well as a recent Perl interpreter installed on the operating system, with a variety of Perl modules from CPAN (e.g. Crypt::PasswdMD5, DBD::mysql, JSON, Unix::Syslog, XML::Simple). A comprehensive list of those modules can be found within the software packages/archives README.txt file. In addition to that NSCD and RRDtool are a requirement. RRDtool aids in the creation of graphs that will be displayed on the Octopussy dashboard or shown on a per-device/per-service level.

## Architecture

Octopussy receives syslog messages via syslog protocol and therefore behaves passively, not running any type of network agent on the remote machines under monitoring/surveillance. Octopussy completely conforms to RfC 3164 and RfC 3195 of the IETF, describing syslog as the logging mechanism in Unix-like/BSD operating systems. That especially includes the internal representation of the facility and severity-principle where applicable.
The software is driven by a semi-stateful event correlation engine. This means that the engine records and thus knows its internal state, but only uses it to some extent to link together logically related elements for the same device, in order to draw a conclusion (i.e. to generate an alert). In Octopussy the semi-stateful correlation engine, with its so called sliding window (a shifting window being the logical boundary of a number of events during a certain period of time), is capable of comparing known past events with present ones based on a limited number of comparative values.

### Octopussy Dispatcher

The Octo-Dispatcher is the component used by the Octopussy software to receive syslog lines from RSYSLOG and dispatch them into device directories. Every device registered and activated within Octopussy gets its syslog messages assigned to it depending on the device name. Noteworthy is also the adjacent Octo-Replay component, which is the program used by the Octopussy software to replay log messages for some device or service (it receives and processes recognized logs and puts them back into the incoming directory).

### Octopussy Parser

The Octo-Parser and Octo-Uparser are two of Octopussy's most important core components. The Octo-Parser is the program used by the Octopussy software to parse logs in syslog format for each device registered within Octopussy. It basically uses a regex-engine and commences pattern matching on incoming syslog messages. The Octo-Uparser is restarted every time device's services are changed, to check if previously received "unknown" log messages can be associated with a service.
In some cases Octo-Pusher is also called in advance to process non-syslog messages incoming from some devices. In that regard, the device setting "asynchronous" is helpful to process such log messages, after they were sent to an Octopussy server using e.g. FTP, rsync or SSH/SCP.

### Octopussy Interface

The Octopussy interface (GUI) is the default user-interface and provides configuration management, device and service management as well as alert definition and therefore extends the Octopussy core components. Devices are displayed in tabular form on the Devices page, with the following descriptors as a minimum: hostname, IP address, log type, device model/type, FQDN and OS.
Hence, the interface (Octo-Web) mainly provides access to other Octopussy core components like Octo-Commander, Octo-Message-Finder, Octo-Reporter and Octo-Statistic-Reporter. The Octopussy front-end/GUI is written in Perl 5, employing Apache::ASP to structure and display content.
In addition to that, Octopussy core services can also be accessed from the operating system shell. That represents a convenient way for administrators to start/stop services or make fundamental configuration changes.

### Octopussy RRD

The Octopussy RRD graph generator is a core component of the software and installed by default. Since the generation of such graphs is very resource intensive administrators may opt to disable it on an Octopussy syslog server with a less powerful CPU and a low amount of RAM. The generated RRD graphs displays the activity of all active services for monitored devices, highly depending on the specific service. After a restart of the Octopussy software or during operation, Octo-Dispatcher and Octo-Parser will always process syslog messages in their buffer and queue first and RRD graph generation is delayed. Octo-RRD further depends on Octo-Scheduler, to execute the Octopussy::Report function in order to generate syslog activity RRD graphs, that have been scheduled previously. Finally Octo-Sender has the capability to send report data to arbitrary recipients.

## Extensions

There is a plug-in/module system in Octopussy, which is mainly geared towards the modification of Octopussy reports. Such a plug-in consists out of a description file, which defines the plug-in name and functions, and a code file with perl code to process the actual data.
There are also extensions for software related to Octopussy, like e.g. a Nagios plug-in that checks the Octopussy core services (i.e. Octo-Dispatcher, Octo-Scheduler, etc.) as well as the Octopussy parser states and log partitions.

## Services & Patterns

The creation of new services and service patterns presents the most important way to extend Octopussy without making changes to the source code. However, since patterns are outlined as simplified regular expressions, administrators should have at least some basic knowledge about regex in general. It is further strongly recommended to build on already existing services and also understand the meaning of a message objects' basic fields, which are message ID, pattern, log level, taxonomy, table and rank.
Usually the logs wizard is used to search the system for unrecognized syslog messages per device to generate new service patterns. During the process the creation of patterns should be in a way that enables Octopussy to distinguish messages based on their severity and taxonomy.