SECURITY file for PHP Shell
Copyright (C) 2005-2020 the PHP Shell-team
Licensed under the GNU GPL.  See the file COPYING for details.


PHP Security
============

Installing PHP on your server is an inherently dangerous thing to do,
somewhat similar to the danger one faces when one buys a car: it might
kill you if you have an accident.  On the other hand a car makes so
many things so much more convenient, so most people are willing to
accept the risk of accidents.

Likewise, PHP is a powerful tool which will let you build your
webpages easier and faster than without.  But it is a *very* powerful
tool --- PHP is a full programming language which can be used for
general purpose programming and not just to format HTML for display in
a browser.

So PHP has support for reading and writing files on the filesystem.
But PHP also has support for *deleting* files.  PHP even has support
for executing other programs.  In other words, PHP has lots of support
for interacting with the rest of the computer it runs on.  This
interaction is potentially much more powerful than you want it to, and
this can be a problem if this power ends up in the wrong hands.


Disabled functions
------------------

The admin may have disabled some PHP functions using the
``disabled_functions`` setting in php.ini. Functions, that execute
system commands may be disabled for security reasons.
If the ``proc_open()`` function used by PHP Shell has been disabled,
then you will see an error like this:

    Fatal Error!

    proc_open() has been disabled for security reasons

    in /path/to/your/installation/phpshell.php, line 329.

PHP shell will not work, if that is the case.


PHP Shell Security
==================

As noted above, PHP is a powerful tool --- how does PHP Shell fit into
this?  PHP Shell is actually quite simple and does one thing: it uses
the standard PHP function ``proc_open()`` to execute programs.

Executing other programs is probably the most powerful thing you can
do in PHP, and so PHP Shell gives you a convenient interface to this
the most powerful feature of PHP.  Nothing more.


Is PHP Shell Dangerous?
-----------------------

Short answer: *yes*!  PHP Shell has been used in the past by people
with not-so-good intentions to destroy valuable content on servers.

The longer answer is that installing PHP Shell is like building a new
door in your house --- if you leave it unlocked, then people can (and
probably will!)  walk into it and steal your possessions.  So you want
to lock it, and make sure you use a good lock.

With PHP Shell that is equivalent of using a secure password.  A
secure password is one which is hard to guess (make it long, make it
random, and put both numbers, special characters and normal letters in
it).

  Remember that guessing the password is all that stands between the
  crackers and your files!

If you use a good password, then PHP Shell does not make your system
any more insecure than it already was.  Security is always a matter of
finding the weakest link in the chain: if you use FTP with a simple
password for updating your site, then it would be much easier for the
crackers to attack that instead of trying to guess your super-hard PHP
Shell password.  So make sure that you tighten security on all fronts
you know of.

If you use PHP Shell not very often, you can also remove all 
permissions from the "phpshell" directory as an additional security
measure, when it is not used, so that the webserver can not access
PHP Shell (and only set the normal permissions (755 usually in 
Unix/Linux) when you use it).


Common attacks against PHP applications
=======================================

There are several classes of common attacks that are often used 
against PHP. 

SQL injection and Cross Site Scripting (XSS)
--------------------------------------------

SQL injection does not concern PHP Shell, as it does not use a 
database. XSS is hopefully protected against by properly escaping all 
variables, and PHP Shell does not display any content from one user to 
another user so there should not be any opportunities for XSS. 

Cross-Site Request Forgery attacks (CSRF)
-----------------------------------------

PHP Shell is in principle vulnerable to CSRF attacks. CSRF attacks 
happen as follows: 

While you are logged in to PHP Shell, you visit another webpage in a 
different tab or window. The other page has a hidden form with a 
command and an 'action' attribute set to the address of PHP Shell. The 
other page uses javascript to submit that form. The browser then adds 
PHP Shell's cookie, the request is authenticated by PHP Shell and 
executed. 

The standard protection against this is to include a hidden input in 
every form with a secret value that changes every session, known as a 
CSRF token. PHP Shell checks on every request if the token is provided 
and matches the current session, if not the request is discarded. A 
form generated by a different webpage does not know the secret csrf 
token, so it cannot construct a valid form. PHP Shell implements this 
protection as of version 2.5. 

Attacks against the session
---------------------------

PHP Shell includes several features to prevent unauthorized third 
parties from gaining access to an authenticated session cookie. 
However, none of them help if an attacker can monitor network traffic. 
Therefore, you should if at all possible RUN PHP SHELL OVER HTTPS!

If you are for any reason unable to run PHP Shell over HTTPS, it is 
especially important to log out after finishing with your PHP Shell 
tasks. 

PHP Shell attempts to do the following to protect sessions: 
* create a new session token immediately after authentication and on 
  logout, 
* generate the session token from cryptographically secure randomness, 
* lock the session cookie to PHP Shell's URI, set httponly and https
  only, 
* lock the session to the users IP address, 
* time out the users authentication after a configurable amount of 
  time, 
* include a nonce every time the login form is generated. 

Brute-force password guessing
-----------------------------

One of the most general attacks against online systems that are 
protected by passwords is attempting to guess a password by trying 
lots of possibilities. The first line of defence against such attacks
is to use strong passwords: passwords that are long, do not consist of
dictionary words or simple variations thereof, and include characters 
from a large character set, e.g. lower case and upper case letters, 
numbers, and special characters. 

As of version 2.5, PHP Shell also implements rate limiting. Every time 
a login attempt fails, this is logged in a file (the location of which 
is configurable). After the third failed log in attempt from one IP 
address, PHP Shell enforces a timeout during which a user won't be 
able to log in. The length of the timeout increases exponentially with 
the number of failed login attempts. After a successful login, the 
counter is reset. 




If you have comments or suggestions for improvements to this little
guide in system security, then please do not hesitate to contact the
PHP shell team.
