Security
There are many strategies for securing a Swarm installation. This section provides guidance on security features Swarm controls, and recommendations for several areas for the system hosting Swarm.
Require login
By default, Swarm permits any users to view most Perforce resources available in the associated Perforce service, restricted only by the protections configuration in the Perforce service.
Swarm can be configured to require all users to be logged in. Add the
following configuration block to the data/config.php
file, at the same level as the p4
entry:
<?php
// this block should be a peer of 'p4'
'security' => array(
'require_login' => true, // defaults to false
),
Once enabled, non-authenticated users see a login page for most Swarm requests.
By default, there are two exceptions:
-
the login page
-
the
/queue/worker
endpoint.
Authenticated users attempting to visit the login page are redirected to Swarm's home page.
Prevent login
When your Perforce service has users that should not be able to log in to
Swarm, for example service users involved with
Perforce replicas, the prevent_login
configuration
item can be used to prevent successful authentication.
Add or update the following configuration block to the
data/config.php
file, at the same level as the
p4
entry:
<?php
// this block should be a peer of 'p4'
'security' => array(
'prevent_login' => array(
'service_user1',
'service_user2',
),
),
prevent_login
defaults to
array()
, which means no users in your Perforce service
are prevented from logging into Swarm. However,
license restrictions might also
prevent logins.
Tip
For more information, see: Distributing Perforce: Service users.
Disable commit
Swarm provides the ability to commit reviews within the Swarm interface. You may want to disable this capability to prevent reviews from being committed by someone other than the review's author. When disabled, the states available to a code review.
(and if the review is already committed) option is removed from the list of
To disable commits, set disable_commit
to
true
within the reviews
item in
the data/config.php
file. For example:
<?php
// this block should be a peer of 'p4'
'reviews' => array(
'disable_commit' => true,
),
),
Restricted Changes
The Perforce service provides two changelist types:
public
(the default), and
restricted
. Swarm honours restricted changelists by
preventing access to the changelist, and any associated comments or
activity related to the changelist.
If a user has list-level privileges to at least one file in the changelist, Swarm allows the user to see the changelist and any of the files they have permission to see.
To prevent unintended disclosures, email notifications for restricted
changes are disabled by default. To enable email notifications for
restricted changes, set email_restricted_changes
to
true
within the security
item in
the data/config.php
file. For example:
<?php
// this block should be a peer of 'p4'
'security' => array(
'email_restricted_changes' => true,
),
),
Note
When email_restricted_changes
is set to
true
, email notifications for restricted changes are
sent to all interested parties with no permissions screening. These
notifications might disclose sensitive information.
Swarm can only report on changes that the configured
admin-level user has access to. When using
restricted changes, we advise that you grant the Swarm
admin-level user access to the restricted files and
set
require_login
= true
to avoid leaking information to unauthenticated users.
IP address-based protections emulation
A Perforce service can be configured via protections to restrict access to a depot in a variety of ways, including by IP address. As Swarm is a web application acting as a client to the Perforce service, often with admin-level privileges, Swarm needs to emulate IP address-based restrictions. It does so by checking the user's IP address and applying any necessary restrictions during operations such as browsing files, viewing file content, viewing and adding comments on files.
IP address-based protections emulation is enabled by default. Swarm performs somewhat faster without this emulation; if you do not require them for your Swarm installation these can be disabled by setting the configuration:
<?php
// this block should be a peer of 'p4'
'security' => array(
'emulate_ip_protections' => false,
),
Known limitations
-
Notification e-mails for reviews or commits include the list of affected files. Swarm cannot reliably know the IP address used to retrieve that e-mail, and makes no attempt to filter the files and their depot paths nor any details included in the description. However, when a user follows a link from the notification e-mail to a restricted resource, that access is denied.
-
Swarm filters comments from activity streams, but any comments created prior to upgrading to the 2013.3 release cannot be filtered and may leak sensitive information.
-
Swarm displays a comment count in review queues and activity streams, but the count does not account for any comments that may be hidden from the user due to association with files the user is restricted from viewing.
-
Should Swarm users connect to Swarm via a proxy or VPN, the protections will generally use the IP address of the proxy/VPN.
-
When the user's IP address and Swarm's IP address both have restrictions applied, the user experiences the most constraining of the two IP address-based restrictions; Swarm cannot bypass restrictions applied to itself.
-
Swarm performs a variety of operations with admin-level privileges, on behalf of a user. Even if the Perforce service has IP-based, or userid-based protections, installed to prevent access to some or most of its versioned data, Swarm typically does have access to this data. Therefore, Swarm cannot guarantee that no information leakage will occur, particularly when custom modules are in use, or Swarm source has been customized.
Tip
For more information, see Perforce System Administrator's Guide: Administering Perforce: Protections.
HTTP client options
Swarm permits configuration of options that are passed through to the underlying Zend Framework 2's HTTP client. These options can be used to specify SSL certificate locations, request timeouts, and more, and can be specified globally or per host.
Here is an example configuration:
<?php
// this block should be a peer of 'p4'
'http_client_options' => array(
'timeout' => 5,
// path to the SSL certificate directory
'sslcapath' => '',
// the path to a PEM-encoded SSL certificate
'sslcert' => '',
// the passphrase for the SSL certificate file
'sslpassphrase' => '',
// optional, per-host overrides;
// host as key, array of options as value
'hosts' => array(
'jira.example.com' => array(
'sslcapath' => '/path/to/certs',
'sslcert' => 'jira.pem',
'sslpassphrase' => 'keep my JIRA secure',
'timeout' => 15,
),
),
),
See the Zend Framework 2's Socket Adapter documentation for more information.
Strict HTTPS
To improve the security when users work with Swarm, particularly if they need to do so outside of your network, Swarm provides a mechanism that tries to force web browsers to use HTTPS. When enabled, Swarm's behaviour changes in the following ways:
-
HTTP requests to Swarm include a meta-refresh to the HTTPS version.
-
A strict transport security header is included for all HTTPS requests, which pins the browser to using HTTPS for your Swarm installation for 30 days.
-
All qualified URLs that Swarm produces use HTTPS for the scheme.
-
Cookies on HTTPS connections are flagged as HTTPS-only.
Here is an example of how to enable strict HTTPS:
<?php
// this block should be a peer of 'p4'
'security' => array(
'https_strict' => true,
'https_port' => null, // optional; specify if HTTPS is configured
// on a non-standard port
),
Apache security
There are several Apache configuration changes that can improve security for Swarm:
-
Disable identification
By default, each Apache response to a web request includes a list of tokens identifying Apache and its version, along with any installed modules and their versions. Also, Apache can add a signature line to each response it generates that includes similar information. By itself, this identification information is not a security risk, but it helps would-be attackers select attacks that could be successful.
To disable Apache identification, add the following two lines to your Apache configuration:
ServerSignature Off ServerTokens ProductOnly
-
Disable TRACE requests
TRACE
requests cause Apache to respond with all of the information it has received, which is useful in a debugging environment.TRACE
can be tricked into divulging cookie information, which could compromise the credentials being used to login to Swarm.To disable
TRACE
requests, add the following line to your Apache configuration:TraceEnable off
-
Update SSL configuration
Swarm works correctly with an SSL-enabled Apache. Several attacks on common SSL configurations have been published recently. We recommend that you update your Apache configuration with the following lines:
<IfModule mod_ssl.c> SSLHonorCipherOrder On SSLCipherSuite ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL:!EDH SSLCompression Off </IfModule>
PHP security
There are several PHP configuration changes that can improve security for Swarm:
-
Disable identification
By default, PHP provides information to Apache that identifies that it is participating in a web request, including its version.
To disable PHP identification, edit your system's php.ini file and change the line setting
expose_php
to:expose_php = Off
-
Remove scripts containing
phpinfo()
During module development or other debugging, you may need to call
phpinfo()
, which displays PHP's active configuration, compilation details, included modules and their configuration. Typically, you would add a script to Swarm's public directory containing:<?php phpinfo() ?>
Any such scripts should be removed from a production instance of Swarm.