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 prevents anonymous users from viewing any Helix Core 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.

Prevent login

When your Helix Core Server has users that should not be able to log in to Swarm, for example service users involved with Helix Core 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 Core Server are prevented from logging into Swarm.

For more information, see Service users in Helix Core Server Administrator Guide.

Auto-create new users

Swarm supports the automatic-creation of new users in Perforce on login if the Helix Core Server is configured to allow it and the user exists in LDAP. This function is configured in the Helix Core Server and no Swarm configuration is required. For instructions on how to configure Helix Core Server to automatically create new users in Perforce on login, see auth.ldap.userautocreate and auth.default.method in the Defining LDAP-related configurables section of the Helix Core Server Administrator Guide.

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, // lifetime in seconds, default value is 0=expire when browser closed
        'remembered_cookie_lifetime' => 60*60*24*30,  // lifetime in seconds, default value is 30 days
        'user_login_status_cache'    => 10, // Set in seconds, default value is 10 seconds. 
                                                 // Set to 0 to disable the cache and make Swarm 
                                                 // check the user login status for every call to Helix Server.     
        'gc_maxlifetime'             => 60*60*24*30, // lifetime in seconds, default value is 30 days
        'gc_divisor'                 => 100, // 100 user requests
    ),

• cookie_lifetime

  Optional: Limits the lifetime of session cookies (in seconds).

  Default is 0, which causes the session cookie to expire when the user's browser is closed.

  Maximum value is 2147483647 seconds.

  Note

  When the Remember Me checkbox on the login dialog is checked, the remembered_cookie_lifetime value will be used for cookie_lifetime.

• remembered_cookie_lifetime

  Optional: Limits the lifetime of session cookies when the Remember Me checkbox on the login dialog is checked.

  Default is 60*60*24*30 seconds (30 days). You can enter the value in seconds if you prefer. For example, 2592000 seconds (30 days) is also valid.

  Maximum value is 2147483647 seconds.

• user_login_status_cache

  Swarm 2022.1 and later: Swarm caches the Helix Core Server login status of users. When Swarm makes any single request, it tests the user's login status many times. The default 10 second cache value is intended to reduce the number of checks performed, reducing the load on the Helix Core Server.

  Default is 10 seconds.

  Set to 0 to disable the cache and make Swarm check the login status for every call to the Helix Core Server.

  Note

  If a user requests a Swarm operation on the Helix Core Server when logged out of the Helix Core Server, but their login cache status shows them as logged in, the operation will fail. If you get too many reports of failed operations, reduce your cache setting.

• gc_maxlifetime

  Optional: If a session is inactive for the specified number of seconds, the user is logged out. User sessions are stored in SWARM_ROOT/data/sessions/.

  Default is 60*60*24*30 seconds (30 days). You can enter the value in seconds if you prefer. For example, 2592000 seconds (30 days) is also valid.

  Maximum value is 2147483647 seconds.

  Note

  By default, the user's Perforce ticket expires after 12 hours, which also causes them to be logged out.

• gc_divisor

  Optional: Sets how often garbage collection is run based on the number of user requests that are made. The setting range is 1 to 100. Garbage collection deletes user session files that are older than the gc_maxlifetime setting from SWARM_ROOT/data/sessions/.

  • gc_divisor = 100: Garbage collection runs after every 100th user request. 100 is the default setting.
  • gc_divisor = 1: Garbage collection runs after every user request.
  Important

  If your Swarm system has a large number of users, setting gc_divisor to a low number can result in performance issues.

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:

• 'SAMEORIGIN' - Swarm can only be displayed in a frame hosted on the same domain.
• 'DENY' - Swarm cannot be displayed in a frame.
• 'ALLOW-FROM URI' - Swarm can only be displayed in a frame hosted on the specified URI.
• false - The X-Frame-Options header is not emitted, so Swarm can be embedded without restriction.

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 Core 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,
        ),
    ),

Limit adding projects to administrators

Limit adding projects to members of specific groups

IP address-based protections emulation

A Helix Core 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 Core 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 disabled by default. To enable IP address-based protections emulation for your Swarm installation, include the following configuration item in the SWARM_ROOT/data/config.php file:

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

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 code the review list, code reviews, jobs, 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 Helix Core Server 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.

For more information, see Access authorization in Helix Core Server Administrator Guide.

Disable system info

Swarm provides a System Information page, available to users with admin or super privileges, which displays information about Helix Core 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 Laminas Framework 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'       => 10, // default value is 10 seconds 
    
        // path to the SSL certificate directory
        'sslcapath'     => '',
    
        // the path to a PEM-encoded SSL certificate
        'sslcert'       => '',

        // the path to Certificate Authority file 
        'sslcafile'       => '',
    
        // 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(
                'sslcafile'     => '/path/to/certs/jira.pem',
                'sslpassphrase' => 'keep my JIRA secure',
                'timeout'       => 15,
            ),
            'jenkins.example.com' => array(
                'sslcafile'       => '/path/to/certs/jenkins.pem',
                'sslpassphrase'   => 'keep my jenkins very secure',
                'timeout'         => 15,
            ),
        ),
    ),

See the Laminas Framework Socket Adapter documentation for more information.

<?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:

• HTTP requests to Swarm include a meta-refresh to the HTTPS version. If a load balancer handles encryption before requests reach Swarm, the meta-refresh should be disabled. See below.
• A strict transport security header is included for all 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 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_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:

• 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.

proxy_mode

By default, Swarm works in proxy mode, passing the end-user's browser IP address to the Helix Core Server. The Helix Core Server checks the IP address against its IP protection table to work out what permissions the end-user has.

Set the Swarm proxy_mode in the p4 configuration block of the SWARM_ROOT/data/config.php file:

<?php
    'p4' => array(
        'proxy_mode' => true, // defaults to true
    ),

• true: Swarm passes the end-user's browser IP address to the Helix Core Server allowing the Helix Core Server to work out the what permissions the end-user has. This is the default setting.
• false: the Swarm server IP address is passed to the Helix Core Server. The Helix Core Server checks the Swarm IP address against its protections table to work out the permissions the end-user has. The result is that all of the Swarm users will have the same permissions.