Task: Lock Down a Hub

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.0p0 Hot Tips

CONFIDENTIAL

CodeSecure Inc

Task: Lock Down a Hub

This task will walk you through the process of restricting access to the hub, including:

Removing some of the default role-permission settings from built-in roles.
Setting up the hub to use HTTPS.
Establishing a strong password policy.
Configuring the hub to use third-party authentication services.
Creating ordinary hub user accounts and setting up their initial role assignments.

Preliminaries
Lock Down The Hub
Additional Steps for Previously-Modified Hubs
What's Next?
Links

Preliminaries

As part of this task, you will configure a hub server certificate. For best security, we recommend using a certificate from a trusted certificate authority. If you do not already have such a certificate, you may wish to purchase one before working through the steps of this task.

For uploading, the certificate must be in a PEM-encoded file that also contains the private key corresponding to the certificate's public key, along with any additional certificates required to form a trust chain from the Server Certificate to a self-signed (root) certificate.
The certificate must satisfy the hub server certificate requirements.

If you don't want to purchase a certificate, you will still be able to configure a self-signed hub server certificate.

Lock Down The Hub

The steps in this section describe the process of locking down a new hub, or one whose configuration has not been changed.

If the hub configuration has been changed, work through the steps in this section and then those under If Your Hub is Not New: Additional Steps.

If the CodeSonar Web GUI is not already open, open it now.
If you are signed into a user account, sign out: click your username in the GUI page header , then click the Sign Out link that pops up.
Sign in as Administrator:
1. Click the Sign In link in the GUI page header:
  The Sign In page will open.
2. Enter Administrator in the Username field.
3. Enter the Administrator password in the Password field.
4. Click Sign In.
If you haven't already specified an email address for the Administrator account, you will be prompted to provide one.
1. Enter a secure email address for the Administrator account in the text field.
2. Click Submit.
Navigate to the Security Dashboard.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the User Administration tab.
3. Click the Security Dashboard link.
  The Security Dashboard will open.
Over the next few steps of this task, you will work through the individual Security Dashboard items. For best security, you should have a next to each dashboard item at the end of this process.
Adjust default role-permissions as recommended.
1. Click the Restrict Permissions button.
The page will reload, with several content changes to indicate success.
- The lists of outstanding role-permissions are no longer present.
- The default role-permissions item is marked with .
- There is a confirmation message.
Set up the hub to use HTTPS.
This involves configuring a hub server certificate.
1. Click the Change HTTP Settings link.
  The Configure HTTPS page will open. If necessary, click the Configure HTTPS button to display all page contents.
2. Scroll to the Server Certificate section.
3. Do you already have a suitable SSL/TLS certificate available?
  - YES:
    1. Select Upload Private Key and Certificate(s) from the menu.
    2. Click the Browse button.
    3. Use your browser's file upload functionality to select and upload the PEM-encoded file containing your certificate(s) and private key.
  - NO:
    1. Select Generate Self-Signed Certificate from the menu.
    2. Enter certificate details in the form as directed.
    Important note: a self-signed certificate will probably not be trusted by the web browsers and other HTTP clients on your system, so you and other users are likely to experience HTTPS warnings when you attempt to access the hub. See Browser Warnings and Self-Signed Certificates for more information about this issue and how to resolve it.
4. Scroll down to the HTTP Configuration section.
5. Select always fail from the HTTP requests should menu.
6. Click the Enable HTTPS button (at the bottom of the page).
  If you are changing an existing HTTPS configuration, the button will be labeled Reconfigure HTTPS.
  The Settings: HTTP tab will be loaded over HTTPS. It will include a confirmation message.
7. Navigate back to the Security Dashboard.
  1. Change to the User Administration tab.
  2. Click the Security Dashboard link.
Reload the page to check your progress.
You should have green check marks next to the first three items.
Instruct the hub to use TLS for hub-database communication.
1. Click Edit Settings To Use TLS For Database Communication.
  The Settings: HTTP tab will open.
2. Select the Use TLS for database communication? checkbox.
3. Click the Update button.
4. Use your browser's "back" functionality to navigate back to the Security Dashboard.
  (You will see a message noting that the hub should be restarted for this last change to take effect. You will do this in a later step.)
Strengthen the hub password policy.
1. Click Change Password Policy.
  The Settings: Password Policy tab will open.
2. Adjust settings so that all the security recommendations are satisfied:
  - Minimum Password Length is 12 or higher.
  - Minimum Password Character Classes is 3 or higher.
  - PBKDF2 Iterations is 100000 or higher.
  - No more than 10 authentication attempts per 300 seconds are permitted.
3. Click the Update button.
4. Use your browser's "back" functionality to navigate back to the Security Dashboard.
Strengthen the hub HTTP session policy.
1. Click Change Session Policy.
  The Settings: HTTP tab will open.
2. Adjust the HTTP Session Timeout value so that it is no greater than 900 (seconds).
3. Click the Update button.
4. Use your browser's "back" functionality to navigate back to the Security Dashboard.
Disable annotation sharing (by specifying that warning groups have project scope).
1. Click Edit Settings.
  The Settings: Analysis tab will open.
2. Click to deselect the Share annotations between projects checkbox.
3. Click the Update button.
4. Use your browser's "back" functionality to navigate back to the Security Dashboard.
Reload the page. You should now have green check marks next to all items except that the TLS connection item will be marked with and contain a message indicating that you need to restart the hub.
1. If any other items still have or icons, work through the instructions above to resolve the security issue described.
Restart the hub to make sure all your changes take effect.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the Other Links tab.
3. Click the Hub Shutdown link.
  A Shutdown Server button will be displayed.
4. Click the Shutdown Server button.
5. Restart the hub.
  codesonar hub-start hubdir interface:port
  where hubdir is the hub directory and interface:port is the hub location.
Go back to the Security Dashboard to confirm that all items are now showing green check marks .
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the User Administration tab.
3. Click the Security Dashboard link.
  The Security Dashboard will open.
4. Look at the items. They should all have green check marks.
If you haven't already configured an SMTP server for the hub, do it now.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the SMTP tab.
3. Fill in the form fields on the tab as necessary to configure the hub to use your local SMTP server.
4. Click Update.
Create and define any additional roles that you require.
1. Change to the User Administration tab.
2. Click the Roles link in the tab.
  The Roles page will open.
3. For each new role that you wish to create:
  1. Enter a unique name for the role in the Create Role text field.
  2. Click the Create New Role button.
4. Set up global role-permissions for the new roles.
  1. Click Global Permissions (under the Roles page heading).
    The Global Role-Permissions page will open.
  2. Click in the table rows corresponding to the new roles to assign your desired global permissions.
    (You may need to scroll to the right to see all the permissions in the table.)
  3. Click the Save Changes button.
5. Set up root project tree role-permissions for the new roles.
  1. Click the CodeSonar logo in the GUI page header to navigate to the hub Home page.
  2. Click the Project Tree Details link under the page header.
    The Project Tree Details section will expand.
  3. Click the permissions link in the Project Tree Details section.
    The Resource Role-Permissions page for the root project tree will open.
  4. Click in the table rows corresponding to the new roles to assign your desired permissions.
    (You may need to scroll to the right to see all the permissions in the table.)
  5. Click the Save Changes button.
6. Set up root launchd group role-permissions for the new roles.
  1. Click the Settings icon in the page header to view the Settings page.
  2. Change to the Other Links tab.
  3. Click the Analysis Cloud link.
    The Analysis Cloud page will open.
  4. Click the Launchd Group Details link under the page header.
    The Launchd Group Details section will expand.
  5. Click the permissions link in the Launchd Group Details section.
    The Resource Role-Permissions page for the root launchd group will open.
  6. Click in the table rows corresponding to the new roles to assign your desired permissions.
  7. Click the Save Changes button.
Set up the special Default Template User account to have your preferred set of properties.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the User Administration tab.
3. Click the Users link in the tab.
  The Users page will open.
4. Click on Default Template User in the table.
  The Account Editor for Default Template User will open.
5. Click View and Edit Roles .
  The User Roles page for Default Template User will open.
6. Click to select the Assigned checkboxes for the roles that you want to assign to Default Template User (and unassign the ones that you do not).
7. Click the Save Changes button.
8. Click the Default Template User link in the page breadcrumbs.
  The Account Editor for Default Template User will open.
9. On the Account Settings tab, set the following properties to the values you wish to use as defaults (for accounts created with Default Template User as template).
  - Default Role for Saved Resources
  - Email Alerts
10. Click the Update button.
11. Change to the Visibility Settings tab.
12. Select the visibility filters that you wish to use as defaults (for accounts created with Default Template User as template).
  For a factory-new hub, only "Visible Warnings" will have options other than "all".
13. Click the Update button.
Edit the general template configuration file to set ANALYSIS_MASTER_USE_TLS=Yes and DAEMON_MASTER_USE_TLS=Yes.
1. Open the general template configuration file $CSONAR/codesonar/template.conf for editing.
  (Where $CSONAR is the CodeSonar installation directory.)
2. Add two new rule at the end of template.conf.
```
ANALYSIS_MASTER_USE_TLS=Yes
DAEMON_MASTER_USE_TLS=Yes
```
3. Save and close template.conf.
[Optional] If you wish to use one or more third-party authentication services to manage access to the hub, configure them as follows.
1. Change to the User Administration tab.
2. Click the Authentication Services link in the tab.
  The Authentication Services page will open.
3. Scroll down to the Add Service form.
4. Select an authentication service type from the Type menu.
  The Configuration section of the Add Service form will update to contain form fields corresponding to your selected types.
  If none of the available Type options are suitable, you will need to add a custom hub authentication plug-in, then come back to this step.
5. Enter a suitable name for the service in the Service Name field.
6. Fill in the remaining fields in the Add Service form.
7. Click Add Service.
Click the Settings icon in the page header to view the Settings page.
[Optional] If necessary, set up hub user accounts for the expected users of the hub.
For each expected user, you will only need to create a hub user account if:
- such an account does not already exist (for a table of accounts, change to the User Administration tab and click the Users link to open the Users page),
  and
- the user is not covered by automatic account creation: either
  - they will be signing in using hub account credentials directly (rather than through a third-party authentication service),
    or
  - they will be signing in through a third-party authentication service for which automatic account creation is disabled.
If there are user accounts that you need to add, proceed with the following steps.
1. Change to the User Administration tab.
2. Click the Bulk Add Users link in the tab.
  The Bulk Add Users page will open.
3. Enter the new account usernames in the text field on the page, with one name per line. To specify an email address for an account, use a line of the form username | emailaddress. If you do not specify an email address, the Email for the corresponding account will be set to NULL.
  For example:
```
alice
bob | bob@example.com
carol | carol@example.com
dan       
```
4. Select a suitable template user for the new accounts.
5. If you want the new account to have the special Enabled role (and thus have G_SIGN_IN permission), select the Enable Users checkbox.
6. Click the Add Users button.
If you started with a new hub (or one whose configuration had not previously been changed), go on to What's Next?
Otherwise, go on to Additional Steps for Previously-Modified Hubs.

Additional Steps for Previously-Modified Hubs

If you did not start with a hub with factory configuration, you may need to take additional steps to lock down the hub. In particular, you may need to do one or both of the following.

Make further adjustments to role-permissions for Anyone and User.
Reconfigure or remove third-party authentication plug-ins.

The remainder of this section provides detailed instructions for these operations.

Further adjustments to role-permissions for Anyone and User

The Restrict Permissions button on the CodeSonar Security Dashboard removes a subset of the default role-permission assignments from the built-in Anyone and User roles. If the hub's roles and role-permission assignments have not been changed (for example, because the hub is new), this results in a configuration where ordinary users will have only a limited degree of access to hub information and functionality. However, if role ancestors or role-permissions have been modified, you may need to take additional steps to make sure that ordinary users do not have elevated permissions.

Remove most of the direct role-permission assignments from Anyone and User.
If ancestor roles have been added for the Anyone or User roles, remove them.

These steps are especially important for the Anyone role, since all users always have this role.

Adjust global role-permissions.

Navigate to the Global Role-Permissions page.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the User Administration tab.
3. Click the Global Permissions link.
  The Global Role-Permissions page will open.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.
(Click links to see full permission names as rendered in the table.)

Anyone	remove all permissions
User	G_ANNOTATION_EXPORT, G_RECOVER_OWN_PASSWORD, G_CHANGE_OWN_EMAIL, G_CHANGE_OWN_PASSWORD, G_CHANGE_OWN_EMAIL_ALERTS, G_CHANGE_OWN_CERTIFICATES, G_CREATE_USER, G_PRIORITY_ADD, G_FINDING_ADD, G_STATE_ADD, G_SIGN_IN_CERTIFICATE, G_LIST_USERS, G_SIGN_IN_PASSWORD, G_LIST_PROPERTIES, G_LICENSE_READ, G_LICENSE_UTILIZATION_READ

Click the Save Changes button.

Adjust launchd group role-permissions.

Navigate to the Resource Role-Permissions page for the root launchd group.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the Other Links tab.
3. Click the Analysis Cloud link.
  The Analysis Cloud page will open.
4. Click the Launchd Group Details link under the page header.
  The Launchd Group Details section will expand.
5. Click the permissions link in the Launchd Group Details section.
  The Resource Role-Permissions page for the root launchd group will open.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.
(Click links to see full permission names as rendered in the table.)

Anyone	remove all permissions
User	LAUNCHD_READ, LAUNCHD_EXISTS, LAUNCHD_START_SLAVE, LAUNCHD_START_MASTER, LAUNCHDGROUP_READ, LAUNCHDGROUP_EXISTS, LAUNCHDGROUP_ADD_CHILD

Click the Save Changes button.
If you have added any other launchd groups, or any launch daemons, repeat this process on their respective Resource Role-Permissions pages.

Adjust project tree role-permissions

Navigate to the Resource Role-Permissions page for the root project tree.
1. Click the CodeSonar logo in the GUI page header to navigate to the hub Home page.
2. Click the Project Tree Details link under the page header.
  The Project Tree Details section will expand.
3. Click the permissions link in the Project Tree Details section.
  The Resource Role-Permissions page for the root project tree will open.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.

Anyone	remove all permissions
User	PTREE_READ, PTREE_EXISTS, PTREE_ADD_CHILD, PROJECT_READ, PROJECT_EXISTS, PROJECT_ADD_CHILD, ANALYSIS_READ, ANALYSIS_EXISTS, ANALYSIS_WARNING_READ, ANALYSIS_WARNING_EXISTS, ANALYSIS_DEBUG, ANALYSIS_IR_QUERY, ANALYSIS_CONSOLE, ANALYSIS_TERMINATE

Click the Save Changes button.
If you have added any other project trees, or any projects or analyses, repeat this process on their respective Resource Role-Permissions pages.

Adjust warning processor role-permissions.

Navigate to the Manage Warning Processors page.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the Other Links tab.
3. Click the Manage Warning Processors link.
  The Manage Warning Processors page will open.

For each warning processor in the table, do the following.

Click the permissions link in the table entry.
The Resource Role-Permissions page for the corresponding warning processor will open.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.

Anyone	remove all permissions
User	WPROCESSOR_EXISTS, WPROCESSOR_EXECUTE, WPROCESSOR_READ

Click the Save Changes button.

Adjust saved search role-permissions.

Navigate to the Saved Searches page.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the Other Links tab.
3. Click the Saved Searches link.
  The Saved Seaches page will open.

For each saved search in each tab of the Saved Searches page, do the following.

Click the permissions link in the table.
The Resource Role-Permissions page for the corresponding saved search will open.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.

Anyone	keep for "all" searches only: NAMEDSEARCH_READ, NAMEDSEARCH_EXISTS
User	keep for every existing named search: NAMEDSEARCH_READ, NAMEDSEARCH_EXISTS, NAMEDSEARCH_WRITE, NAMEDSEARCH_DELETE

Click the Save Changes button.

Adjust saved chart role-permissions.

Navigate to the Open a saved chart dialog.
1. Click the CodeSonar logo in the GUI page header to navigate to the hub Home page.
2. Click the Charts and Tables link under the page header.
  The Charts and Tables section will expand.
3. Click the open saved chart link in the Charts and Tables section.
  The dialog will open.

For each saved chart listed in the dialog, do the following.

Click the chart name to select it.
Click the permissions button.
The Resource Role-Permissions page for the corresponding saved chart will open.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.

Anyone	remove all permissions
User	SAVEDCHART_READ, SAVEDCHART_EXISTS, SAVEDCHART_WRITE, SAVEDCHART_DELETE

Click the Save Changes button.

Adjust report template role-permissions.
For each report template that you have added to the hub, do the following. (Built-in report templates are not securable)

Navigate to the corresponding Resource Role-Permissions page.
The navigation steps will depend on the template scope.
Find the Anyone and User rows in the role-permissions table.

Click the checkboxes in the Anyone and User rows to remove all direct role-permission assignments except for the following.

Anyone	remove all permissions
User	REPORTTEMPLATE_READ, REPORTTEMPLATE_EXISTS, REPORTTEMPLATE_WRITE, REPORTTEMPLATE_DELETE

Click the Save Changes button.

Adjust ancestor roles.
1. Navigate to the Role Ancestors page for Anyone.
  1. Click the table row for Anyone.
    The Role Users page for Anyone will open.
  2. Click the Ancestor Roles tab.
    The Role Ancestors page for Anyone will open.
2. If any of the checkboxes in the Is Ancestor table are selected, click to deselect them, then click the Save Changes button.
  If the table has multiple pages, make sure you have checked all pages.
3. Click on User in the table.
  The Role Ancestors page for User will open.
4. If any of the checkboxes in the Is Ancestor table are selected, click to deselect them, then click the Save Changes button.
  If the table has multiple pages, make sure you have checked all pages.

The Anyone and User roles will now have the same global, root launchd group, and root project tree role-permissions as they would have if you had started a new hub and then clicked the Restrict Permissions button on the Security Dashboard.

If you have added role-permissions for other roles or other securable resources, you may wish to amend these as well: use the process outlined above to edit the settings in the appropriate Role Ancestors and Global/Resource Role-Permissions pages.

Reconfiguring/removing third-party authentication plug-ins

If any third-party authentication services have been configured for the hub, make sure they are providing an appropriate level of security. It is also a good idea to remove any low-security authentication plug-ins from the auth/ directory: this eliminates the risk that you might accidentally configure the hub to use them.

Navigate to the Authentication Services page.
1. Click the Settings icon in the page header to view the Settings page.
2. Change to the User Administration tab.
3. Click the Authentication Services link.
  The Authentication Services page will open.
If there are any entries in the table of current services, select those that don't provide a sufficient level of security for your needs.
In particular, if you have any TutorialAuthExample services left over from trying the custom hub authentication plug-in tutorial, select them now.
Click the Remove Selected Services button.
The selected entries will be deleted, and the page reloaded to show the updated set of current services.
If any table entries remain, work through them one at a time to check that you are satisfied with their configurations.
For each table entry:
1. Click the table row.
  The Edit Authentication Service page for the service will open.
2. Check the current configuration settings for the service.
3. If you wish to make any changes, edit the correponding form fields and then click the Modify Service button.
4. Use your browser's "back" functionality to go back to the Authentication Services page.
Look at the contents of the authentication plug-in directory $CSONAR/codesonar/py/hub/auth.
For example:
ls $CSONAR/codesonar/py/hub/auth
If any of these plug-ins provide an insufficient level of security for your needs, remove (or relocate) them from this directory so that they will not be made available in the Authentication Services: Add Service form.
In particular, remove the tutorial example plug-in if it is present.
For example:
rm $CSONAR/codesonar/py/hub/auth/tutorial_authplugin.py

What's Next?

The following Tasks describe some typical next steps.

Task: Create a New, Empty Project Tree
Because you have locked down the role-permission settings on the root project tree, neither Anyone nor User has hub-wide permissions to analyze projects or browse analysis results. If you have a large number of projects, it is useful to set up project trees to manage access to projects on the hub. For example, you may decide to create one project tree per product team: TeamAprojects, TeamBprojects, and so forth.
Task: Create a New, Empty Project
If you want to set up permissions for your projects before any analyses take place, create them as empty projects.
Task: Grant Select Users Access to a Project
Once projects (empty or otherwise) exist on the hub, you can set up permissions for those projects
Task: Move Multiple Projects or Project Trees (or both) To a Different Parent Project Tree
If you change your mind about the location of a project or project tree within the hierarchy on the hub, you can move it.
Similarly, you may wish to set up launchd groups to manage the launch daemons on your hub. This mirrors the process for setting up project trees.
- Create new launchd groups from the Analysis Cloud page.
- Set role-permissions for each launchd group from its Resource Role-Permissions page.
- Move launch daemons and launch daemon groups to different parent launchd groups from Analysis Cloud/Launchd Group pages.
Task: Modify a Role's Permissions
Make any further role-permission changes that you require.
Task: Modify a User's Roles
Change role assignments for one or more users.

Task: Lock Down a Hub

Preliminaries

Lock Down The Hub

Additional Steps for Previously-Modified Hubs

Further adjustments to role-permissions for Anyone and User

Reconfiguring/removing third-party authentication plug-ins

What's Next?

Links