Open topic with navigation

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

Important

Prior to Swarm's 2016.1 release, require_login defaulted to false. For 2016.1 and later releases, the default is true.

By default, Swarm prevents anonymous users from viewing any Helix Server resources; users must login to see commits, reviews, etc.

Swarm can be configured to allow anonymous users to access any readable resources (creating or editing resources by anonymous users is not permitted). Add the following configuration block to the SWARM_ROOT/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' => false, // defaults to true
    ),

There is one exception: the /queue/worker endpoint is available to any user.

Note

Service and operator users are not permitted to login. For more information on these user types, see User types in Helix Core Server Administrator Guide: Fundamentals.

Prevent login

When your Helix Server has users that should not be able to log in to Swarm, for example service users involved with Helix Server replicas, the prevent_login configuration item can be used to prevent successful authentication.

Add or update the following configuration block to the SWARM_ROOT/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 Helix Server are prevented from logging into Swarm.

For more information, see Service users in Helix Core Server Administrator Guide: Multi-Site Deployment.

Sessions

Swarm manages logged-in sessions using cookies in the browser, and PHP session storage on the server. Swarm uses reasonable defaults for the cookie and session lifetimes (measured in seconds); when the lifetime is exceeded users need to login again. To specify session lifetimes and garbage collection frequency, add the following configuration block to the SWARM_ROOT/data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'session' => array(
        'cookie_lifetime'             => 0, // 0=expire when browser closed
        'remembered_cookie_lifetime'  => 60*60*24*30,  // 30 days        
        'gc_maxlifetime'              => 60*60*24*30, // 30 days
        'gc_divisor'                  => 100, // 100 user requests
    ),

X-Frame-Options header

By default, Swarm emits a X-Frame-Options HTTP header set to SAMEORIGIN. This prevents embedding of the Swarm interface into other web pages, which avoids click-jacking attacks.

If your deployment of Swarm needs to be integrated into another web interface, you can adjust the X-Frame-Options header by adjusting the x_frame_options item within the security configuration block, found in the SWARM_ROOT/data/config.php file. For example:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'x_frame_options' => value,
        ),
    ),

Where value can be one of:

For more information on the X-Frame-Options header, see this Mozilla Developer Network article.

For more information on click-jacking attacks, see this Wikipedia article.

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 Approve and Commit (and Commit if the review is already approved) option is removed from the list of states available to a code review.

To disable commits, set disable_commit to true within the reviews item in the SWARM_ROOT/data/config.php file. For example:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'disable_commit' => true,
        ),
    ),

Restricted Changes

The Helix Server provides two changelist types: public (the default), and restricted. Swarm honors 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 SWARM_ROOT/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 Swarmadmin-level user access to the restricted files and set require_login = true to avoid leaking information to unauthenticated users.

Limit adding projects to administrators

Important

For Swarm 2016.1, the configuration item add_project_admin_only was moved from the security block to the projects block, and the item was renamed to add_admin_only. The functionality of this configuration item remains unchanged.

If you do not update your SWARM_ROOT/data/config.php configuration file, the old configuration for restricting project creation to administrators continues to work.

If you add the new configuration item add_admin_only to the projects block, it takes precedence over any remaining add_project_admin_only setting in the security block.

Limit adding projects to members of specific groups

Important

For Swarm 2016.1, the configuration item add_project_groups was moved from the security block to the projects block, and the item was renamed to add_groups_only. The functionality of this configuration item remains unchanged.

If you do not update your SWARM_ROOT/data/config.php configuration file, the old configuration for restricting project creation to specific groups continues to work.

If you add the new configuration item add_groups_only to the projects block, it takes precedence over any remaining add_project_groups setting in the security block.

IP address-based protections emulation

A Helix Server 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 Helix Server, 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.

Swarm also emulates proxy-based protections, in addition to regular IP-based protections emulation. However, Swarm does not detect whether it is connecting to a Helix Proxy or not; it merely attempts to emulate protections table entries that use proxy syntax.

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

For more information, see "Authorizing Access" in Helix Core Server Administrator Guide: Fundamentals.

Disable system info

Swarm provides a System Information page, available to users with admin or super privileges, which displays information about Helix Server that Swarm is configured to use, as well as PHP information and the Swarm log file.

While this information can be invaluable when communicating with Perforce support engineers, you may wish to prevent disclosure of any system information. The System Information page can be disabled for all users by adding the following configuration block to the SWARM_ROOT/data/config.php file, at the same level as the p4 entry:

<?php
    // this block should be a peer of 'p4'
    'security' => array(
        'disable_system_info' => true, // defaults to false
    ),

Once disabled, the System Information link disappears from the About Swarm dialog, and 403 errors are generated for any attempts to browse to the System Information page.

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.

Warning

While it is possible to use a self-signed SSL certificate, adding the configuration to do so disables certificate validity checks, making connections to the configured host less secure. We strongly recommend against using this configuration option.

However, if you need to configure continuous integration, deployment, or JIRA connections and those connections must use a self-signed SSL certificate, set the sslallowselfsigned item to true for the specific host that needs it, as in the following example:

<?php
    // this block should be a peer of 'p4'
    'http_client_options' => array(
        'hosts'     => array(
            'jira.example.com'  => array(
                'sslallowselfsigned'  => true,
            ),
        ),
    ),

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 behavior changes in the following ways:

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_strict_redirect' => true, // optional; set false to avoid meta-refresh
        'https_port'            => null, // optional; specify if HTTPS is
                                         // configured on a non-standard port
    ),

When the https_strict_redirect item is set to false, Swarm does not add a meta-refresh for HTTP clients. This prevents an endless redirect when a load balancer in front of Swarm applies HTTPS to the client-to-load balancer connection, but not the load balancer-to-Swarm connection.

Apache security

There are several Apache configuration changes that can improve security for Swarm:

PHP security

There are several PHP configuration changes that can improve security for Swarm: