Guide for Administrators

Security

Traditionally, when you access a URL like http://www.example.com/pages/help.html from your browser there is a corresponding file on the webserver in the pages directory with the name help.html. This is how resources like HTML, images, Javascript, CSS, and other files are made available for download.

Cerb uses a different approach for serving content, which is known to web application developers as the Model-View-Controller (MVC) [1] architectural pattern. As a consequence of this, all the public interaction with the application occurs with two main files in the root directory of your Cerb installation. The pages that your workers interact with are virtual. In other words, there isn’t a file on your webserver that corresponds with each URL.

  • index.php returns responses for “full-cycle” HTTP requests. These requests occur when you type a URL into your browser, click a link, or request a resource (e.g. image, script, stylesheet, file download). The typical response is to render a new page of output, often including a header, top-level menu, body content, and footer.
  • ajax.php returns responses for Asynchronous Javascript And XML (Ajax) [2] requests. “Asynchronous” refers to the fact that these requests happen silently in the background, and your browser won’t clear the existing page contents as it would during a full-cycle request. Ajax requests are used to provide functionality aimed at making web applications feel more responsive and interactive (in a way that only desktop applications used to be). These requests generally only affect one part of the greater whole.

Here are some common examples of Ajax functionality:

  • Autocomplete suggestions from the address book when you begin typing an email address.
  • A list that refreshes its contents after sorting or paging without redrawing the entire page.
  • Pulling up supplemental information from the server without leaving the page you’re on. For example, if you hover over an email address the interface may display a tooltip with the past 10 conversations you’ve had with that particular contact. This information is being downloaded from the server in real-time, as it’s usually far too much information to send in advance for all possible interface interactions.

Protecting filesystem access

You only need to expose three Cerb files to the outside world. The application will transparently manage access to other resources, such as images or file attachment downloads.

You should make the following files available to web requests:

  • ajax.php
  • index.php
  • favicon.ico

Browser access to the following locations should be forbidden:

  • .git/
  • api/
  • features/
  • libs/
  • storage/

If you’re using the provided .htaccess file for friendly URLs, then we’ve already given you some defaults for blocking access to these directories:

RewriteRule ^(.*/)?\.git(/|$) - [F,L]
RewriteRule ^(.*/)?api(/|$) - [F,L]
RewriteRule ^(.*/)?features(/|$) - [F,L]
RewriteRule ^(.*/)?libs(/|$) - [F,L]
RewriteRule ^(.*/)?storage(/|$) - [F,L]

With Apache, you can use directives in your virtual host configuration to protect these directories:

You can also prevent PHP from executing in certain locations (such as storage/) with the following directive:

php_flag engine off

The above directive may be placed in a <VirtualHost> block or an .htaccess file.

With nginx, you can use the following directive in your server configuration:

location ~ ^/cerb/(\.git|api|features|libs|storage)/ {
    return 403;
}

File permissions

The Cerb files should be owned by your webserver user. The webserver should have read access to all files and directories, but only write-access to the storage/ directory. The webserver user should never have write access to PHP files, because if the application is compromised through a vulnerability then it allows an attacker to modify a .php file and then execute arbitrary code.

The following permissions are recommended:

chown -R www-data:www-data .

find . -type f -exec chmod 400 {} \;

find . -type d -exec chmod 500 {} \;

chmod -R u+w storage/

Note

Your webserver’s user and group may be something other than www-data.

Restricting PHP functions

It’s a good idea to restrict PHP functions that allow arbitrary commands to be executed on the system. In the php.ini file you can use the following option:

disable_functions = show_source,system,exec,passthru,proc_nice,proc_open,popen,shell_exec,pcntl_fork,pcntl_exec

Considerations for HTTP Authentication and IP-based security

Your organization may have a requirement that all worker access should be password protected or restricted to requests coming from inside your corporate network. That’s a fine policy, but there are a few things you need to consider when implementing a firewall, HTTP authentication, or IP-based security restrictions.

Scheduled tasks

All scheduled tasks are triggered by automated requests to the /cerb/cron URL. If these requests are coming from a cronjob on the same webserver then this usually doesn’t present a problem. However, once you’ve established IP-based restrictions you should test the scheduled automated access to that URL to make sure it can get through. These scripts will also need to provide HTTP authentication details if you’re enforcing them.

Web-API

If you have applications that use the Web-API to integrate with Cerb then you’ll need to make sure they can make requests to the /cerb/rest/* path. You’ll need to provide some extra code to handle HTTP Authentication.

Community portals

Community portals also make requests to Cerb. If you install the Support Center, or another community portal, on an external webserver then you need to make sure that machine can make requests to the /cerb/portal/* path. The default community portal script doesn’t provide a mechanism for HTTP authentication, but you could provide an override by IP address. This feature is on the project wishlist [3].

Footnotes

[1]Wikipedia: Model-View-Controller (MVC) http://en.wikipedia.org/wiki/Model-View-Controller
[2]Wikipedia: Asynchronous Javascript and XML (Ajax) http://en.wikipedia.org/wiki/Ajax_(programming)
[3]Feature request: Community Tools should support HTTP authentication if the parent helpdesk is password protected. http://wgmdev.com/jira/browse/CHD-679
Previous topic:
« Plugin Library
Next topic:
Performance »