The Halo Operations Guide explains everything ... - CloudPassage

208 downloads 213 Views 3MB Size Report
The Halo Operations Guide explains everything you need to know in order to access, configure, use, and administer the CloudPassage Halo service— allowing ...
Halo Operations Guide Operations Overview Using the Halo Portal Setting Up Server Groups Installing Halo Agents Assigning Servers to Server Groups Using Halo Security Modules and Services Using Halo Reports Using the Halo REST API Appendix A

Halo Site Administration

Appendix B

Multi-Factor Authentication

Appendix C

Adding Single Sign-On to Halo

Appendix D

Search Expression Syntax

Operations Overview Who should read this guide? The Halo Operations Guide explains nearly everything you need to know if you access, configure, use, and administer the CloudPassage Halo service—everything that allows you to provide strong, dynamic protection to all of your cloud and physical servers, all across the globe. From your first login to the portal, through your serverarchitecture implementations, agent installations, and security scans, this guide steps you through the procedures and best practices that can guard your assets and intellectual property against malicious actions. Consult portions of this manual if you are— A DevOps architect responsible for designing Halo protection for your organization. Also be sure to read How Halo Works for a broad overview of Halo's capabilities and depth of protection. A security specialist responsible for monitoring and addressing security issues and events. Also be sure to read Interpreting Halo Security Issues and Events for detailed recommendations. A Security Ops admin responsible for implementing strong policies to secure your server infrastructure. Also be sure to read the policy-implementation portions of each of the individual Halo module Setup Guides. A sysadmin responsible for conducting ongoing Halo operations across your networks. Also be sure to read the procedural portions of each of the Halo module Setup Guides. A developer looking to add Halo capabiities to your existing or new orchestration and security tools. This and other Halo guides describe the capabilities that you can implement through the Halo REST API. Note: This guide is the core of a suite of documents that describe in detail the core Halo platform and each of the specific security modules and services that Halo offers. The entire documentation suite is available on 1

our Customer Support forums site.

About Halo and the Halo Portal (For a more comprehensive overview of the capabilities of Halo, see How Halo Works: a Technical Summary.) CloudPassage Halo is a software-as-a-service offering that provides strong security for your cloud servers, across all public, private, and hybrid could environments. In use, the components of Halo are distributed across the customer's clouds and other clouds, as shown below.

The Halo agent is a lightweight and secure software component that runs as a service on each cloud server. The agent monitors important server security factors, communicates with the Halo security analytics engine as needed, and takes actions based on pre-configured or customized security policies. The Halo security analytics engine is a powerful elastic compute grid that provides sophisticated analytics that evaluate data collected by the Halo agents. The analytics engine does the "heavy lifting" on behalf of the agents, preserving customer server resources and performance. The Halo portal is the convenient "single pane of glass" used to manage all Halo product capabilities, create policies, set up alerting, view reports, manage users, and other tasks. The Halo REST API gives you an alternative to the Halo portal for managing Halo operations. Your developers can create new tools or add Halo capability to existing tools. Through the Halo portal, you apply Halo's group-based policy management to efficiently add and manage security to server fleets of all sizes. You can apply security policies at initial server launch, or at any time for operational servers. Halo automatically monitors all servers and reports any security violations in real time. You can view recent and historical violations in the portal, and you can use the portal to create, assign, and retire policies as needed. All Halo users automatically have access to the portal to create and manage server groups, control their Halo accounts, apply any available Halo security features, conduct scans to detect security issues, respond to events and alerts, and automate tasks through the Halo REST API. Depending on your account type, you may also be able to install Halo agents, add and manage new Halo users, and activate additional Halo security features. Note: This document describes all portal features, equivalent to what a Halo site administrator user can access.

Using the Halo Portal 2

The Halo portal is your view into your organization's Halo account and your control panel for managing it. the portal gives you access to all Halo features, activities, and information that you are authorized to view or manipulate. Note also that only your account's information appears; you can see nothing of other Halo accounts, just as other accounts' users can see nothing of yours. Depending on the type of Halo user you are, you may be able to use the portal to Manage your password and account. Invite others to become Halo users within your account. Set Halo server groups, install Halo agents, and assign servers to groups. Use Halo features to protect your servers' configurations, firewalls, file integrity, exploit resistance, or user access. Manage the site settings for your Halo account—for example, configure security settings or manage API keys. Create security policies that define issues to track, events to log, and alerts to send. Review scan results for detected security issues and logged events. Use this information to perform remediations or initiate incident response procedures, as indicated. This section shows you how to perform the above tasks and more. Note: If you are interested in a highly abbreviated tutorial to get you started using Halo, consider the Halo QuickStart.

Log Into the Portal You start using Halo by logging into the Halo portal. Depending on your organization's policies, you will log in using either password authentication or multi-factor authentication. 1. Use your browser to log into the Halo portal, at https://portal.cloudpassage.com. The portal login page appears:

2. Enter your Halo username and password. 3. Click Submit. For multi-factor authentication only: After you enter your username and password, the Multi-Factor Authentication page for either SMS or YubiKey appears. (If you are enabled for both types of authentication, the page allows you to choose which to use.)

3

Enter your SMS authentication code or insert your YubiKey. See Authenticate With an SMS Code or Authenticate With a YubiKey for details. Authorize your browser: To ensure enhanced security for Halo portal access, Halo users are in most cases required to register the individual web browser instances that they use to log into the Halo portal. 4. If this is your first time logging into the portal, click Yes to authorize the browser you are using.

If you click Yes, you will be logged in and the browser will be authorized for 30 days, during which time you will not be challenged to provide an authorization code. If you click No, you will be logged in but the browser will not be authorized for future logins. 5. If this is not your first login but you are logging in from a browser that is not already authorized, register that browser by entering an authorization code that Halo sends to you separately (by email).

If the code is not accepted, you cannot log in. If the code is accepted, you will be logged in and the browser will be authorized for 30 days. If the code is accepted but you have cleared the Remember this device for 30 days checkbox, you will be logged in but the browser will not be authorized for future logins. You can have any number of authorized browsers at any moment, but all authorizations last for 30 days only. Note: All Halo users that use only username and password for Halo login must also use browser authorization. For those that use multi-factor authentication or single sign-on for Halo login, browser 4

authorization is optional and can be disabled on the Authentication Settings tab of the Site Administration page of the Halo portal. Nevertheless, CloudPassage recommends that it remain enabled for all users.

If your password or multi-factor authentication is successful, the login is complete and the Halo Dashboard page appears.

6. From the Dashboard, use the links and menus to access any of your available Halo features and information. Besides logging into the portal, you can also use the login page to reset your Halo password or even to register for Halo if you aren't yet a user. Note: Certain aspects and requirements for your organization's Halo login process are under the control and responsibility of your Halo site administrator(s). If you are a site administrator, see Authentication Settings for an explanation of the settings that you can modify. See also Advanced Settings if you need to control the IP addresses from which Halo users are permitted to log in.

Get Help Whenever you are logged into the Halo portal, help with learning or using Halo is always just a few clicks away. Select Support > Getting Started With Halo to view a short document that walks you through using Halo. Select Support > File Support Request to contact CloudPassage Customer Support for help. Select Support > Documentation and Forums to open the following dialog box:

To look up information about Halo, click Browse Documentation or Browse Support Forums to peruse the documents in the Customer Support forums, including the Halo product documentation. See About the Support Forums for more information. To search for documentation on a specific topic, enter the topic into the field and click Search. Links to relevant forum and documentation articles containing that term appear below the search box:

5

If instead you want to file a request for help with Customer Support, click File a Support Request. The New Support Request form opens:

Fill in the fields of the form and click Submit. A support ticket for you is entered into the system. The support team will contact you by email within 24 hours.

About the Support Forums CloudPassage sponsors a number of user forums on the CloudPassage Support Community site. These forums are open to the public and are a great source of information and ideas on how to learn and use CloudPassage Halo. There are over 25 active forums, in the following categories: Documentation. About a dozen forums, one for each available product guide. Plus two release-note forums, one for Halo (product) release notes and one for Halo agent release notes. Frequently Asked Questions. Several forums answering questions about Halo in general. Feature FAQ. Forums answering specific questions about specific Halo features. Tips and Tricks. Videos and insider insights from CloudPassage developers on how to harness the power of Halo. 6

All documents in the forums are indexed for searching, making answers easy to find. You can also submit your own questions, ideas, tips, and articles in the forums to help your fellow users or to receive help yourself. Note: The Halo product team periodically runs beta programs on new features and content. If you'd like to become one of our next beta testers, email us at [email protected].

Change Your Password When you need or wish to change your Halo password, you can do that from within the Halo portal by selecting My Account from the User menu (your name in the page header). The Password Reset section of your account page lists your organization's password requirements (modifiable by a site administrator; see Halo Site Administration). It also includes fields for entering your current and requested new password. Enter the information and click Save to submit the change request.

Note that you can also request a new password without being logged into the portal. Click Reset your password on the portal login page and follow the instructions.

Manage Your Account and Subscription To review or edit the details of your Halo account, select My Account from the User menu (your name in the portal page header). There you can view or change your username, first and last name, and time zone. And you can choose to stop receiving daily status emails from CloudPassage, if you wish. Note that you can't change your email address on this page. If you need to associate a different email address with your account, contact a Halo site administrator within your organization. If you are a site administrator, you can change your own email address and the email addresses of other users on another page; see Edit an Existing User. You can also reset your Halo password from this page, as described in Change Your Password.

7

If you are a Halo site administrator, you can also see the details of your Halo subscription. Select Manage Subscription from the Site Administrator menu (the gears icon [

] in the portal page header).

If the Manage Subscription page is available to you, you can use it to See the type of your billing plan (Halo or Halo Evaluation) and your billing method, and view your invoices. View your server-hour usage for the current billing period. Cancel your Halo account.

Halo standard users (non-site-administrators) do not have access to the Manage Subscription page. Note: Your organization's Halo account may be registered directly with CloudPassage, or it may be registered with a third party that manages your security services through a CloudPassage master account. If you are a Halo site administrator, you have the ability to link your account to a master account or disconnect from that master account. See Master Account for more information.

Invite and Manage Halo Users If you are a Halo site administrator, one of your privileges is the ability to add other users to your Halo account. (Other site-administrator responsibilities are described in Halo Site Administration.) Having multiple users allows you to spread responsibility for separate Halo tasks (such as server-group administration versus policy design versus security-event response) across multiple specialists in your organization. Select Site Administration from the Site Administrator menu (the gears icon 8

in the portal page header),

then select the Users tab. The User Administration table displays information about all current Halo users in your organization. If there are many users, the list may break across several pages. You can sort the list by any of the columns, and you can search for a value that appears in any column.

If you want to add a new Halo user to the account, click Invite New User (see next). If you want to delete or deactivate a user, see Deactivate or Delete a User. If you want to edit the information for an existing user, click Edit for that user. (See Edit an Existing User.)

Invite a New User When you click Invite New User on the User Administration page, the following page appears. You "invite" a user because the candidate receives an email invitation from Halo, and the user account is not active until the invitee accepts by logging into the portal. 1. To prepare the invitation, start by filling in the required personal information about the invited user. Note that the username must be unique among all Halo users. A good way to ensure a unique name is to use your email address as your username.

9

2. Decide whether to enable portal access for the user. (A server administrator who will use Halo only for multi-factor network authentication to servers—called GhostPorts in the Halo portal—will not need portal access.) If the user is to have portal access, decide whether it is to be as a standard user or as a site administrator. The following table explains the differences. Site administrator

Portal access

Standard user

GhostPortsonly

View the Halo Dashboard View Security Events History, Scan History Run scans Install agents (can access Halo agent key) Manage the Halo subscription Administer the Halo site (see Halo Site Administration) Manage "My Account" Open GhostPorts Manage policies, exceptions, alert profiles Access Halo Customer Support

3. Decide whether to enable multi-factor authentication for the user. There are two reasons for doing this: The user will be using multi-factor network authentication (GhostPorts) to log onto to one or more Haloprotected servers. See Multi-Factor Network Authentication Setup Guide for details on why and how to use multi-factor network authentication. The user will be logging into the Halo portal with multi-factor authentication. See Multi-factor authentication for details on enabling it for your Halo users. To enable multi-factor authentication, first specify the user's authentication method. Select SMS code and Halo Password, YubiKey and Halo Password, or both. The page expands to display additional fields. 4. Enter the required information into the fields. For detailed instructions, see Enable Multi-Factor Authentication for a User. 5. Select the GhostPorts checkbox if you want to enable GhostPorts access for the user, and have already enabled multi-factor authentication. 6. Click Invite to commit your settings and close the Invite New User page. The user will receive the invitation by email.

Edit an Existing User When you click Edit for a Halo user listed on the User Administration page, the following page appears. Note that on this page you can change only the following: The user's email address The user's multi-factor authentication enablement The user's portal access and user type The user's GhostPorts enablement

10

See the descriptions of those fields in the previous section (Invite a New User) if you need more information. Users can themselves view and change other information about their accounts on a different page; see Manage Your Account and Subscription for details.

Deactivate or Delete a User The Halo portal gives you two ways to remove a Halo user from your organization's Halo account: You can deactivate the user if he or she is no longer using Halo and is not expected to return to active status in the near future. The user can no longer log into the portal, but the user's name remains (marked "deactivated") on the list of Halo users on the Site Administration page, the user's profile information is retained, and the user can easily be re-activated by a Halo Site Administrator. To deactivate a user, locate the user's name in the table on the Users tab of the portal's Site Administration page, then click Deactivate for that user in the Status column. You can delete the user if it is certain that the user will never be re-activated, and if it is appropriate to destroy all information about the user. A deleted user is not listed on the Site Administration page and cannot be reactivated; however, all historical information about the user is retained in the Halo database for audit purposes. To delete a user, locate the user's name in the table on the Users tab of the portal's Site Administration page, then click Delete for that user in the Status column.

Setting Up Server Groups The concept of server groups is fundamental to Halo. Halo uses group-based policy management, meaning that an individual security policy is designed to apply to any number of individual servers of a given kind. There is no need to create an individual policy for each individual server. By applying policies in this manner, you can efficiently scale your protection to fleets of thousands of servers. And in the dynamic environment of the cloud, Halo can instantly apply the proper group policy to any newly cloned or auto-scaled server.

Design GroupsThat Match Your Organization ***Implement this section for Halo 2*** 11

Design GroupsThat Match Server Purpose A server group is a set of similar servers—such as all of the web servers, or all of the load-balancers—that can share a single Halo security policy. For example, all servers in a given group will use the same firewall policy and the same configuration policy. In the Halo portal, you will assign a policy to a server group, not to an individual server. So you'll need to create server groups before any of your Halo policies can take effect.

To come up with the best set of groups for your organization, examine all of the servers you currently use, and categorize them in terms of platform, applications, and purpose, while trying to end up with the smallest possible number of groups. The basic idea is that all the servers in a group need to be very similar (same O.S. and version, same applications, same firewall needs, same local user accounts) because a single set of policies covers all of them. However, it is not always strictly true: You can mix Linux and Windows servers in the same server group for those features (such as workload firewalls, configuration security monitoring, and file integrity monitoring) that allow assigning both a Windows and a Linux policy to a group.

You can do this because Halo automatically applies only Windows policies to Windows servers, and only Linux policies to Linux servers. Servers (of a given platform) within a group must have identical firewall needs if you are implementing Halo workload firewalls. Servers (of a given platform) within a group must have identical or very similar system-file and directory structures if you are implementing system configuration scanning or file integrity monitoring at the system level. Servers (of a given platform) within a group must have the same general application security needs if you are extending configuration security monitoring or file integrity monitoring to the application level. You probably will not want to mix strongly dissimilar distributions of the Linux platform (Ubuntu with CentOS, for example) within a server group, as this will make it harder to define configuration-policy rules that apply across all servers. You can share a single policy among several groups when that makes sense. For example, a web-server group might need a different firewall policy from a database-server group, but if the two groups' operating systems are identical, they might be able to share the same system-level configuration policy.

Implement Your Groups Once you have designed your groups, create them in the Halo portal. Go to the Dashboard page by clicking the CloudPassage icon on the toolbar (or by selecting a security module from the Servers menu). 12

Note that the list of server groups shows each group's name followed by the number of servers in the group. The number of critical and non-critical issues that Halo has detected for the group appear below the group name. Click the Add a New Group link at the bottom of the list of server groups. For now, just give each group a name; you'll assign servers and policies to the groups later. The group now appears in the list of server groups on the Dashboard.

About Halo built-in server groups Halo includes a few built-in groups that you can use in special situations. Root group. The name of this group is by default the name of your organization, as it appears in your Halo account. The root group consists of all servers that have not been assigned to a server group. As soon as you install an agent on a server, it appears in this group, from which you can move it to the server group of your choice. All other server groups can be considered children of the root group. Retired. This group consists of all servers that explicitly have been retired (see Maintain and Manage Your Servers). Move servers to this group when they are no longer used and you expect never to use them again. Unretired. This group consists of servers that were retired, but are now deemed useful again. Note that when a server is retired, it loses its server-group membership; therefore, unretiring it puts it into the "Unretired" group, not into its previous server group. However, you can assign servers from this group to any actual server group for reuse.

Maintain and Manage Your Groups Use the Halo portal on an ongoing basis to manage your server groups. You can edit a group's name, add or remove any of its servers, and add or remove security policies as noted in Assign Policies to Server Groups. When you no longer need a given server group, you can delete it. Select the server group on the Halo Dashboard, and click Delete below the group's name. If the group contains servers, Halo moves those servers to the root group and then permanently deletes the group.

13

Installing Halo Agents Every Halo-protected server must have a running Halo agent that performs security tasks and communicates with the Halo analytics engine on a regular basis. Readying your servers to be protected by CloudPassage Halo is a fairly simple three-step process: 1. Create groups of structurally and functionally similar servers. 2. Install a Halo agent on each server that is to be protected. 3. Assign each protected server to its appropriate server group. You can perform the first two steps in either order: define groups first and then install agents, or install agents first and then define groups. Also, you can perform the steps manually through the Halo portal, or in an automated fashion through integration with third-party provisioning tools or by executing scripts that leverage the Halo REST API. Note: If you are a Halo site administrator, you have the ability to configure certain aspects of the behavior of installed agents. See Agent Settings for an explanation.

Install Linux Agents For every Linux server that you want Halo to protect, take steps such as the following. (Other installation procedures are possible; this is just one example of how to do it.) 1. Install a version of the sudo package on the server. 2. SSH into the server. 3. From your browser, log into Halo and follow instructions to download the correct script for your Linux distribution. Or SSH into the server and download the script directly to the server.

What the Linux installation scripts do: In case you want to write your own commands to automate your agent installation, here's a summary of what the script for each supported distribution family does: It copies the appropriate Halo agent installation package from CloudPassage, at http://packages.cloudpassage.com/debian or http://packages.cloudpassage.com/redhat It imports the CloudPassage public key, from http://packages.cloudpassage.com/cloudpassage.packages It updates the local apt or yum repository with the new Halo agent package (cphalo). It installs the Halo agent package. It starts the agent for the first time. This is the point at which you might customize the script by adding any of several startup options to a two-line startup sequence with this syntax: 14

sudo /opt/cloudpassage/bin/configure --agent-key=yourAgentKey [--server-label=yourLabel] [--tag=serverTag] [--readonly=[true|false]] [--proxy=ip:port --proxy-user=username -proxy-password=passwd] [--dns=[true|false]] sudo /etc/init.d/cphalod start

where --agent-key=yourAgentKey

Your 32-character Halo agent registration key.

--server-label=yourLabel

(optional) This agent's server label. See Add Custom Labels to Your Servers.

--tag=serverTag

(optional) Specify this agent's server tag. See Automatically Assign Servers to Groups.

--readonly=[true|false]

(optional) Specify true to run the agent in audit mode, or false to return to full functionality. See Run Halo Agents in Audit Mode.

--proxy=ip:port --proxy-user=username --proxy-password=passwd

(optional) Proxy settings. To configure the agent to use an outbound proxy, enter the required values. See Configuring Linux Agents for a Proxy.

--dns=[true|false]

(optional) Specify false to disable DNS resolution, or true to re-enable it. See Disable DNS Resolution by Halo Agents.

Note that all options are added to the configure line; you cannot pass options on the cphalod start command line. See the Install Linux Daemons page in the Halo portal for the full source code of each installation and startup script. 4. On the server, execute the entire script at once, or perform each of its commands interactively, as shown on the instructions page. The script supplies your unique Daemon registration key to Halo. That's it! Your Linux server now appears in the Halo portal Dashboard, in the root group (at the top of the list of server groups).

Performing an upgrade installation on Linux On any of the supported Linux platforms, you perform an upgrade installation by executing the appropriate upgrade script for the platform. Download the script from the Install Linux Daemons page in the Halo portal. For Debian and Ubuntu: sudo apt-get update && sudo apt-get install cphalo For CentOS, Fedora, RHEL, Oracle Linux, and Amazon Linux AMI: sudo yum update cphalo If you perform an upgrade while the older agent is running, the new agent will start automatically when the upgrade is complete. If you stop the older agent and then upgrade, the new agent will not start automatically.

Install Windows Agents Every Halo-protected server must have a running Halo agent that performs security tasks and communicates with the Halo analytics engine on a regular basis. When you first log into the Halo portal, you are prompted to install agents. When you are ready to do that, click either Install Linux Daemons or Install Windows Daemons and follow the instructions on the page. Then repeat the process for each of your servers. If you need to find these pages again, navigate in the Halo portal to Servers > Install Linux Daemons or Servers > Install Windows Daemons. 15

You can install the agents manually, or you can automate the installation process. Note: If you are a Halo site administrator, you have the ability to configure certain aspects of the behavior of installed agents. See Agent Settings for an explanation.

Install Windows Agents With the Installer For every Windows server that you want Halo to protect, repeat the following steps: 1. Remotely log into your Windows server and start Internet Explorer as administrator. 2. From IE on the server, Log into the CloudPassage Halo portal. 3. Navigate to Servers > Install Windows Daemons and download the Halo agent installer.

4. Run the installer and enter your Halo agent key. That's it! Your Windows server now appears in the Halo portal Dashboard, in the root group (at the top of the list of server groups).

Performing an upgrade installation on Windows If you are upgrading from a 64-bit Halo agent (version 2.7.8 or later), you need not perform any explicit upgrade procedure. The Windows installer senses that there is an existing agent and takes the appropriate upgrade steps. If you are upgrading from a 32-bit Halo agent (version 2.5.6 or earlier), take these steps: a. Connect to your server through RDP and open Add/Remove Programs. b. Remove the agent from your server by following the steps in Uninstall Halo Agents. c. In the Halo portal, note the server group that the (now deactivated) server belongs to. Then move the server into the "Retired" group, or simply delete it from Halo if you do not want to preserve a record of its configuration or history. d. Proceed to install the new server as described above. e. Back in the Halo portal, select your server from the root group and add it back into its appropriate server group. Note that Halo considers this as a new installation rather than an upgrade, since the configuration of your 32-bit server and its server-group assignment are not carried over to your 64-bit server.

Install Windows Agents From the Command Line You can use the CloudPassage installer in a non-interactive mode to install a Halo agent without user intervention. This capability allows you schedule installs, perform remote installs without a remote administrator, and use a single command to bulk-provision an entire server installation with Halo agents. Note: The non-interactive installer works for upgrade installs as well as for new installs. See Performing an upgrade installation on Windows, above, for information on upgrading from different agent versions. 16

1. Run a command-prompt window as administrator: right-click the command-prompt icon (for example, in the Start menu) and select Run as administrator from the context menu. 2. Change the current directory to the folder that contains the Halo installer file. 3. Execute a command with the following syntax: cphalo-x.y.z-win64.exe /S /AGENT-KEY=RegKey [/D=installdir] [/TAG=servertag] [/NOSTART] [/SERVER-LABEL serverlabel] [/read-only=[true|false] [/DNS=[true|false] where x.y.z

The version number of the Windows agent that you are installing. The version number is part of the filename of the downloaded installer executable.

S

Specifies that the installation should be silent (unattended). Must be uppercase.

RegKey

Your 32-character Halo agent registration key.

installdir

(optional) The directory into which to install the agent. If you specify nothing, the agent is installed in the Program Files folder. (Enclose the path in quotes if it contains spaces.) The /D option must be uppercase.

servertag

(optional) This agent's server tag. See Automatically Assign Servers to Groups.

NOSTART

(optional) Specifies that the agent should not start up after installation. By default, the agent starts when installation completes.

serverlabel

(optional) This agent's server label. See Add Custom Labels to Your Servers.

/read-only

(optional) Specifies whether to run the agent in audit mode (true)or with full functionality (false). See Run Halo Agents in Audit Mode.

/DNS

(optional) Specifies whether or not to allow the the agent to use DNS resolution. See Disable DNS Resolution by Halo Agents.

After you have constructed this command line, you can execute it directly or you can enclose it in a batch file for later execution.

Customize Agent Functionality By making use of startup command parameters, by integrating Halo agents into template images, and by applying server-orchestrtation tools to the installation process, you can extend Halo's capabiities and automate agent deployment.

Install an Agent on Your Gold Master Server If you use "gold master" versions of your servers as templates from which to create cloud instances, you may want to install Halo agents on the gold masters. Then, when you create server instances, each will already have an installed agent. The installation process is the same as for installing on a cloud server. And CloudPassage recommends that you start the Halo agent service after installing, by leaving the Start CloudPassage Halo Daemon now checkbox selected. Doing that will ensure that any cloud instances created from the gold master will have unique Halo IDs and will receive all updated Halo policies.

Deploy Agents in Bulk With Automation Tools and Scripts You can integrate Halo with cloud management and IT automation tools—such as RightScale, Puppet Labs Puppet, and OpsCode Chef—to transparently embed Halo security into an automated server provisioning process. For example: Puppet is a well-known tool that you can use to provision Halo across multiple servers. CloudPassage has made an example Puppet module available to customers. It uses a standalone Puppet deployment in which both the master and agent are running on the same server. You may wish to use our Puppet example as a starting point 17

for developing your own automated Halo provisioning method. See this Blog post for more details. CloudPassage has also prepared a pair of Chef cookbooks—one for Linux servers and one for Windows servers— containing recipes for installing Halo Demons on your servers. You would add the appropriate cookbook to your Chef run list, and then execute the run list on a set of servers. See this Blog post for more details. CloudPassage has also created integration scripts with RightScale to automate the installation of Halo agents in a RightScale-managed environment. The RightScript works with any type of RightScale account, and can be run as either a boot script or an operational script. See this forum post on the CloudPassage Support site for more details.

Add Custom Labels to Your Servers An optional label attribute has been added to Halo servers. The attribute is called label in the Halo portal, and server_label in the Halo API. It is an alternative to the existing hostname and FQDN attributes assigned to each server. If a non-null value exists for a server's label attribute, the label is displayed everywhere in the portal UI, in place of the hostname or FQDN. The label attribute has been implemented to allow you to use Halo to assign more user-friendly or explanatory names to your servers. Note: A server label can be up to 80 characters long and can contain only alphanumeric characters plus dots, dashes, and underscores. No spaces or other characters are allowed. You cannot assign a server label to a server from within the Halo portal or through the Halo API; instead, you add a parameter to the agent startup command (Windows), or to a configuration file just before executing the startup command (Linux): (Linux) Modify the agent startup script: Use the --server-label option, like this: sudo /opt/cloudpassage/bin/configure --agent-key=yourAgentKey --serverlabel=yourServerLabel sudo /etc/init.d/cphalod start

(Windows) Execute an unattended installation: Use the /server-label yourServerLabel option on the command line. (Windows) Use the Windows Service Manager after installation: a. Open the Services control panel. For example, from the Start menu, select Administrative Tools and then Services. b. Right-click the line for the CloudPassage Halo Daemon service, then select Properties from the drop-down menu.

c. In the Properties dialog, enter the label assignment in the Start parameters field, using this format: /server-label=yourServerLabel

18

d. Now start the service by clicking Start. Important: Do not click OK without first clicking Start. If you click OK first, the tag will not be assigned to the agent.

Run Halo Agents in Audit Mode On both Linux and Windows platforms, the Halo agent can be set to run in audit mode. In that mode, the agent is not able to make any changes to the host on which it runs, but it is otherwise a fully functional Halo agent. In enterprise environments in which the security team does not have the authority to employ tools that have privileged access to the organization's servers, running Halo in audit mode is a viable alternative that retains most Halo capabilities. While running in audit mode, an agent cannot update its host's firewall, it cannot support multi-factor network authentication, and it cannot create, delete, or make any changes to a server's local user accounts. You specify the running mode at agent startup: On Windows, add a /read-only flag with a value of either true or false to the start command. (Default = false.) On Linux, add add a --readonly option with a value of either true or false before the start command (Default = false): sudo /opt/cloudpassage/bin/configure --agent-key=yourAgentKey --readonly=true sudo /etc/init.d/cphalod start

The mode setting persists through agent restarts and upgrades. Therefore, to switch from audit mode (read only) back to full functionality (read/write), you need to explicitly reset it, as in /read-only=false or -readonly=false.

Configure Agents for a Proxy Configuring Linux agents for a proxy If your Linux server is configured to use a proxy, you'll need to supply the proxy information to Halo so that the server's agent will be able to communicate with the Halo analytics engine. You can do that by adding the following options to the configuration command line (on the same line where you supply the agent registration key), before executing the startup command to initially start the Halo agent: --proxy=ip:port --proxy-user=username --proxy-password=userpassword On subsequent starts, it is not necessary to include the proxy-related options (or the Halo agent key) on the command line. Note that if you later remove proxy support from the server, you should restart the agent and use the --noproxy option. Or, if the proxy information changes, you can restart and include the updated values for the proxy-related options.

Configuring Windows agents for a proxy If your Windows server is configured to use a proxy, you'll need to supply the proxy information to Halo so that the server's agent will be able to communicate with the Halo analytics engine. You can do that in the Windows agent installer, on the Enter Proxy Information screen:

19

If you later remove proxy support from the server, you can use the Windows Service Manager to stop and restart the service, specifying /noproxy in the Service Manager's "switches to pass to the service" field. Or, if the proxy information changes, you can restart and include the updated values for the /proxy, /proxy-user, and /proxypassword options in the "switches..." field.

Disable DNS Resolution by Halo Agents The Halo agent supports a startup switch that prevents the agent from performing DNS resolution to access the Halo analytics engine. This is useful in environments where host-based DNS resolution is not permitted, and hosts rely on proxies or hosts files to resolve external addresses. DNS resolution by the Halo agent is is enabled by default; to disable it, use the --dns=false configuration setting (on Linux) or the /dns=false command-line option (on Windows). Note that this action disables DNS resolution by the agent only; the rest of the host is unaffected. The disabled state persists through restarts. If you need to re-enable DNS, use the analogous startup options -dns=true or /dns=true.

Uninstall Halo Agents If you no longer want Halo to protect a server, you can uninstall its Halo agent. Once you do that, the server does not appear on the Dashboard or other pages in the Halo portal, and you can no longer access it or manipulate it from the portal. Note: Uninstallation instructions appear on the Daemon installation pages of the Halo portal.

Uninstalling on Linux For Debian or Ubuntu, run this command on a server to remove its agent: sudo apt-get purge cphalo For CentOS, Fedora, RHEL, and Amazon Linux AMI, run this command on a server to remove its agent: sudo yum remove cphalo

Uninstalling on Windows Through the Windows user interface: You can uninstall the Halo agent using Add/Remove Programs. 1. From the Start menu, select Control Panel. 2. Open the Add/Remove Programs control panel. 20

3. Select CloudPassage Halo from the list, and click Uninstall. The Halo installer launches, displaying the Uninstall page:

4. Click Uninstall. The Halo agent is removed from your server. 5. Log into the Halo Portal and locate the uninstalled agent's server; it will be marked as deactivated. If this uninstallation is for the purpose of upgrading to a newer Daemon, record the name of the server's server group so that you can re-assign the upgraded server to the same group. 6. Retire or delete the deactivated server, as desired. From the command line: You may be able to use the following command to silently uninstall the Halo agent from a server: installDir\Uninstall.exe /S where installDir is the agent's installation directory (by default C:\Program Files\CloudPassage or C:\Program Files (x86)\CloudPassage). Note: If User Account Control is enabled on a server, it may not be possible to execute this script unattended on that server.

Assigning Servers to Server Groups If you have both created Halo groups and installed Halo agents on your servers, you can now assign the servers to the groups. A server must be a member of a group to receive the Halo security policies that protect it.

Manually Assign Servers to Groups 1. On the Halo portal Dashboard page, Locate the servers on which you have installed agents but have not yet explicitly assigned to a group. They are listed in the root group:

21

2. If you want to assign any of the servers in the root group to a group that you have created, select the checkboxes for those root-group servers, then select Move Server(s) from the Actions drop-down list, and finally select from the group list the name of the group to move those servers into.

Your selected servers are now assigned to the server group you chose. As you create policies (see following sections), you can return to the Dashboard page to assign the policies to the appropriate groups.

Automatically Assign Servers to Groups Halo also allows you to automate the process of assigning servers to groups, bypassing manual assignment in the portal. To set it up, do this: 1. When you create or edit a server group in the Halo portal, specify a server tag for that group. The server tag is a string of your choice. Enter the string into the Server Tag field on the Edit Group Details page for that group. Note: A server tag can be up to 40 characters long and can contain only alphanumeric characters plus dots, dashes, and underscores. No spaces or other characters are allowed. 2. Then, when you install a Halo agent on a server, supply the server tag of the group to be associated with that agent. If an agent's server tag matches that of any existing server group, that server is automatically assigned to the group whenever the agent starts up. There are several ways to assign a server tag to an agent: (Linux) Modify the server startup script: Use the --tag option on the line before the start command line, as in sudo /opt/cloudpassage/bin/configure --agent-key=yourAgentKey --tag=servertag sudo /etc/init.d/cphalod start (Windows) Run the installer: The installer includes a screen that you can enter the tag into. 22

(Windows) Execute an unattended installation: Use the /TAG servertag option on the command line. (Windows) Use the Windows Service Manager after installation: a. Open the Services control panel. For example, from the Start menu, select Administrative Tools and then Services. b. Right-click the line for the CloudPassage Halo Daemon service, then select Properties from the dropdown menu.

c. In the Properties dialog, enter the tag assignment in the Start parameters field, using this format: /tag=tagName

d. Now start the service by clicking Start. Important: Do not click OK without first clicking Start. If you click OK first, the tag will not be assigned to the agent. Note: It is also possible to add servers to groups programmatically. See the Servers section of the Halo REST API Developer Guide for details.

Maintain and Manage Your Servers Use the Halo portal on an ongoing basis to manage any of your servers. On the Dashboard page, activate a Halo ), and then select a server group. Then scroll or search to find the server(s) of module by clicking its icon (such as interest, selecting the checkbox for each server you want to act on. 23

Searching for a server To use the Dashboard search to find a server, enter any portion of the server's hostname, fully qualified domain name (FQDN), or server label into the search box, then click Search. The search results are limited to the currently active Halo module and the currently selected server group. From the search results, select the checkboxes of the servers you want to act on.

Acting on a selection of servers

Once you have selected one or more servers to act on, use the Actions drop-down menu to Launch scans of the servers. Move the servers servers from one server group to another, including the root group if you do not want the servers to belong to any explicitly created group. Retire the servers if they are not currently needed, putting them into the "Retired" group. Unretire the servers from the "Retired" group, transferring them to the root group. Delete the servers when you no longer need them and are sure that you never will again. The servers disappear from the server group on the Dashboard and cannot be recovered. Note: The Delete action removes the server's record from Halo, but it does not uninstall the Halo agent from the server, and the Linux or Windows server still exists as a virtual or physical server, even though it is no longer visible to Halo. To actually remove the agent from the server, follow the instructions in Uninstall Halo Agents.

Using Halo Security Modules and Services Note: This section is a summary that is not required reading. Everything discussed here is described in more detail in the module-specific Halo documernts referenced below. The capabilities of Halo to protect your server infrastructure can be grouped under several security control objectives: Visibility and intelligence Layered access control Security exposure management Compromise detection and prevention To implement each of these broad control objectives, you'll enable one or more specific Halo security modules (for example, firewalls) to achieve both broad and deep protection for your server fleet. A given control module might contribute to more than one control objective. For some objectives, you might need also to implement or customize one or more Halo platform services (for example, logging and alerting) to meet the objective. 24

Whether your goal is to meet organizational or regulatory compliance requirements, to protect valuable intellectual property, or to guard against destructive attacks on your organizational infrastructure, deploying the appropriate set of Halo modules and services can significantly strengthen the security posture of your systems and applications, regardless of architecture.

Choose the Modules and Services to Employ Depending on the type of Halo user you are, you may have access to only a subset of these security features, or you may be able to implement them all. Implementation is in general fast and simple.

Configuration Security Monitoring . Use this module to automatically monitor operating system and application configurations, processes, network services, privileges, and more. Availability: Windows and Linux platforms. Implement it by creating configuration policies or cloning them from templates, and then assigning them to server groups. See the Configuration Security Monitoring Setup Guide for details.

File Integrity Monitoring . Use this module to detect unexpected changes to the content or ownership/permissions of system binaries, configuration files, source code, and other critical files (including registry keys on Windows servers). Availability: Windows and Linux platforms. Implement it by creating or cloning file integrity policies, running baseline scans, and assigning the baselines and policies to server groups. See the File Integrity Monitoring Setup Guide for details.

Software Vulnerability Assessment. Use this module to scan the packages installed on your server for security vulnerabilities (NIST CVEs). Availability: Windows and Linux platforms. Implementing it requires no action; it is always enabled. See the Software Vulnerability Assessment Setup Guide for details.

Workload Firewall Management. Use this module to centrally manage host-based firewalls including automatic updates for when servers are added, changed or retired. Availability: Windows and Linux platforms. Available to all Halo users. Implement it by creating firewall policies and assigning them to server groups. See the Workload Firewall Management Setup Guide for details.

Multi-Factor Network Authentication. Use this feature of the Firewall module to implement strong authentication to dynamically provision and de-provision network access for authorized users. Availability: Windows and Linux platform. Implement it by enabling specific users and modifying certain firewall policies. See the Multi-Factor Network Authentication Setup Guide for details.

Server Account Management. Use this module to evaluate who has accounts on which cloud servers, what privileges they operate under, and how the accounts are being used. Availability: Linux platforms. See the Server Account Management Setup Guide for details.

Log-Based Intrusion Detection . Use this module to monitor system and application log files across your servers, generate alerts whenever events that could indicate compromise or attack are logged. Availability: Windows and Linux platforms. Implement it by creating or customizing a log-based intrusion detection policy that specifies which log files to inspect and what event text or ID to alert on. See the Log-Based Intrusion Detection Setup Guide for details.

Reporting . Use this service to conduct simple or complex parametric searches of your servers and generate reports from the results. 25

Availability: Windows and Linux platforms. Implementing it requires no action; it is available as long as you have Halo-protected servers. See Using Halo Reports in this document for details.

Event logging and alerting . Use these two services to securely store events and generate real-time alerts for server creation, changes, exposures, policy violations, and more. Availability: Windows and Linux platforms. Available to all Halo users. Implement it by flagging policy rules for logging and alerting, and by creating special events policies. See Halo Issues, Events, and Alerts for details.

Where to go from here... Consult the above-mentioned documents for the complete instructions you need to implement and manage these Halo modules. Then continue with this Operations Guide for Instructions for assigning security policies to server groups and running scans of your servers. Information needed by site administrators for ongoing Halo configuration and administration. Instructions for using the Halo portal's reporting service.

Assign Security Policies to Server Groups Once you have implemented one or more Halo modules, you can then complete the setup of any of your server groups. The final step is to assign a Halo security policy to the group. In particular, you cannot use Halo Workload Firewall Management, Configuration Security Monitoring, File Integrity Monitoring, or Log-Based Intrusion Detection until you assign the appropriate policy to the appropriate group or groups. Do that from the Halo portal Dashboard by first choosing to edit a particular server group:

Then make the policy assignment on the group's Edit Details page:

These instructions may also be found in the individual feature documents listed in the previous section. Note also that other server-group settings you can enter on this page include Special Events Policy and Alert Profiles (described later, under Set Up a Special Events Policy and Set Up Alert Profiles), and Server Tag (described earlier, under Automatically Assign Servers to Groups). 26

Conduct Scans Once you have set up and configured one or more Halo features, use the Halo portal on an ongoing basis to scan your servers and interpret the results. For configuration security monitoring, file integrity monitoring software vulnerability assessment, and server account management, you can conduct scans of your servers either manually or automatically.

Configure Automatic Scans If you are a Halo site administrator, you can enable, disable, and schedule automatic scans of your servers. Select Site Administration from the Site Administrator menu (the gears icon the Scanner Settings tab.

in the portal page header), then click

For each Halo feature, select the checkbox to enable automatic scanning, and choose a scan frequency (from hourly to weekly). Select Execute scan on A start if you want each server to be initially scanned as soon as its agent starts up, instead of at a default time of day. (This is recommended, to avoid having all servers on your network being scanned at the same time.) To turn autoscanning off, clear the Enable Automatic Scanning checkbox. You can modify certain other scan settings on this page: Mark finding as Failed if the check was indeterminate. See About Indeterminate Results in Monitoring Server Configuration Security for an explanation of when you might want to enable this setting for configuration scans. Mark finding as Critical if CVSS score is above. Default threshold value = 5.00. See Adjust the Vulnerability Threshold in Assessing Software Vulnerabilities for an explanation of when you might want to alter this value in software vulnerability scans.

Manually Scan Selected Servers

27

At any time, you can manually kick off a scan of a single server, a selected set of servers, or all servers in a given server group. You might want to run a manual scan if, for example, you have just remediated a reported issue or vulnerability and you don't want to wait for the next scheduled scan to verify that the issue is no longer reported in the scan results. On the portal Dashboard, select any server group (including the root group, if desired) and scroll or search for servers of interest. Use the checkboxes to select a single server, multiple servers, or all servers in the group. Then select Launch Scan from the Actions menu. Your scan starts immediately.

Address Detected Issues and Events After a manual or automatic scan completes, you can interpret the resulting security issues and events by consulting the scan-results screens and event tables of the Halo portal. You may also be notified through email alerts that Halo has detected security events that warrant your attention. On the dashboard page of the Halo portal, you can view summary results of a scan of any type conducted on any of your server groups:

To view the details of an individual server's scan results, navigate from the dashboard page to the server scan results page, showing details of any security issues that may have been uncovered during the scan:

28

For full information on how to view, interpret, and act upon Halo scan results, see Halo Issues, Events, and Alerts: Addressing Scan Results and Security Notifications.

Using Halo Reports The reporting service of the Halo portal allows you to perform detailed parametric searches of the Halo database to locate items or sets of items that you may wish to act on. The current release of the reporting service focuses on searching for individual servers or collections of servers that match any of a large number of criteria. The Reports menu appears in the top menu bar in the Halo portal. Click it to open the Reports page:

29

Use the search-criteria selectors on this page to set up a search query, and then click Submit to run it. The results of the most recent search are always displayed in the table below the criteria selectors. You can search for servers using any combination of over 20 criteria. For some of the criteria you enter a text string; for others, you select a value or values from a dropdown list. To select multiple values from a list, select each value separately, by opening the list and clicking the desired value: to remove a selected value, click the small "x" beside the value in the filter.

Search results include a link to the summary page for each server returned. You can optionally save the results of a search in PDF or CSV format. A PDF report includes just the server fields displayed on the Reports page; a CSV report includes all fields of the server object, as defined in the Servers endpoint of the Halo REST API.

Examples of reports you might generate For any of these reports, you can further narrow the scope by applying additional filters, such as Group Name, Hostname, Server Label, or a fully qualified domain name—any of which can also be a partial match, allowing you to retrieve, for example, multiple servers by providing a substring that matches more than one hostname. Missing or deactivated servers. To list all servers that are no longer sending heartbeats to the analytics engine, use the State filter set to "Missing". To list all servers that have been shut down or whose agents have been stopped, use the State filter set to "Deactivated". Servers with out-of-date agent versions. To list all servers whose Halo agent needs to be upgraded, run one or more reports with the Agent Version filter set to a known older version of the agent that you expect may still be running on some servers. Agents that may be compromised. To get a quick indication of how wide a suspected attack on Halo agents might be, use the Self Verification Failed filter. Servers with a known vulnerability. To list all servers on which a package containing a specific common vulnerability and exposure (CVE) is present, use the CVE Reference Number filter set to that reference number. You can specify more than one CVE in a comma-separated list, to retrieve all servers on which any of the listed vulnerabilities is present. Windows servers patched to a specific level. To list all Windows Servers that have been patched to comply with a specific Windows knowledge base article, Use the KB filter set to the ID of the article. Conversely, to list all Windows Servers that have not yet been patched to comply with the knowledge base article, use the Missing KB filter set to the ID of that article.

Using the Halo REST API The CloudPassage Halo application programming interface (API) offers a secure, authenticated way for programs to directly access Halo functionality. Your client software can automatically perform many of the same functions that 30

Halo portal users perform manually, such as creating and managing policies, creating or deleting server groups, and running scans. All Halo users have access to the API.

About the API The Halo REST API is a representational state transfer (REST) API. Its calls accept and return stored Halo resources. You access those resources through URL paths. To make an API call, your application submits an HTTP request and parses the response. The request and response are both in Javascript Object Notation (JSON) format.

Authentication and API Keys All access to the Halo REST API requires authentication. First, your application or script client must authenticate with Halo to request an access token for the session. Your client then submits that token with every API call that it makes. (Note that the token is valid for only 15 minutes, so if your session lasts longer than that, you'll need to obtain another token.) Your client must provide client credentials in the form of an API key when making the token request. One responsibility of a Halo site administrator is to generate API keys for use by Halo client programs that access the API. Your API keys are available in the Halo portal, on the API Keys tab of the Site Administration page. See API Keys for instructions on generating API keys and using them in your programs.

API Coverage The API allows you to automate many aspects of Halo functionality. These are the API endpoints, the Halo resources that you can manipulate in various ways through calls to the API: Users [Halo users] Server Commands File Integrity Policies Firewall Interfaces Special Events Policies

Server Groups Server Scans File Integrity Baselines Firewall Services Events

Servers Scan History Firewall Policies Firewall Zones Alert Profiles

Server Accounts Configuration Policies Firewall Rules Log-Based Intrusion Detection Policies Saved Searches

Documentation The Halo REST API is fully documented in the Halo REST API Developer Guide. Related blog posts are also available, on the Cloud Security Blog.

API Examples, Sample Code, and the Halo Toolbox CloudPassage customers have used the API to construct their own server-security management tools and to integrate Halo with other systems. CloudPassage employees have also created code samples, scripts and libraries that use the API to accomplish various useful tasks. The Halo Toolbox is a set of GitHub repositories where CloudPassage customers and employees can share and compare code that automates tasks by calling the Halo REST API. The Toolbox facilitates collaboration: You are encouraged to fork any of the repo's in the toolbox that interest you, then extend or improve them. If you would like to share your extension or improvement, just send a pull request. Click Watch for any repo to be alerted of changes to it. The following are a few examples of the kinds of automation and integration solutions that have been developed by customers and employees and posted to the Toolbox.

Authenticating to Halo and retrieving user or server information 31

Any client that uses the API must first authenticate to the Halo API's "Authorization" endpoint by providing the Halo account's API key, and then submit the returned session token when making each API call. This ensures constant API security. The authentication method is an HTTPS POST call, as documented in the Halo REST API Developer Guide. But your software can use other languages to accomplish this task, as in this Python example: connection = httplib.HTTPSConnection(host) authstring = "Basic " + base64.b64encode(clientid + ":" + clientsecret) header = {"Authorization": authstring} params = urllib.urlencode({'grant_type': 'client_credentials'}) connection.request("POST", '/oauth/access_token', params, header) response = connection.getresponse() jsondata = response.read().decode() data = json.loads(jsondata) key = data['access_token'] ...or as in this Ruby example: client = OAuth2::Client.new(clientid, clientsecret, :connection_opts => { :proxy => my_proxy }, :site => "https://#{host}", :token_url => '/oauth/access_token' ) token = client.client_credentials.get_token.token After authenticating, your client could, for example, call the API's "Servers" endpoint to retrieve information for all active Halo-protected servers, and then print out a list of server names before closing the connection. The call is documented in the API Guide as an HTTPS GET request. In Python, it might look like this: tokenheader = {"Authorization": 'Bearer ' + key} connection.request("GET", "/v1/servers", '', tokenheader) response = connection.getresponse() jsondata = response.read().decode() data = json.loads(jsondata) # iterate through json result and print out hostnames servers = data['servers'] for server in servers: print server['hostname'] connection.close() ...or in Ruby, like this: result = RestClient.get "https://#{host}/v1/servers", { 'Authorization' => "Bearer #{token}" } data = JSON result.body servers = data['servers'] servers.each do |server| puts server['connecting_ip_address'] + " " + server['hostname'] end To examine the complete source code of these specific examples in the Toolbox, go to https://github.com/cloudpassage/api_examples.

Exporting Halo events to third-party SIEM or log-management tools The Halo REST API includes an "Events" endpoint that clients can query to obtain complete information on all Halo 32

security events (for example, detected server configuration errors or file-tampering) within a range of dates. You can use this capability to create an integration tool that feeds event data to a third-party tool for analysis. CloudPassage has developed such a tool (the Halo Event Connector) and has made it available to customers. The tool provides direct integration with Splunk Enterprise and SumoLogic, and integration through syslog to ArcSight and other tools. For more information, see https://github.com/cloudpassage/halo-event-connector-python.

Other example API client code Here are a few other code examples that you can examine by browsing through the Toolbox. They demonstrate a variety of ways that you can exploit the power of the Halo REST API to automate and streamline your server-security monitoring tasks. Manipulating Halo workload firewall policies Two Ruby examples use the API to add a rule to a firewall policy and to modify a firewall policy's source or destination IP zone. Copying security policies and saving to archives An example Ruby script downloads all firewall policies and file integrity policies for a Halo account, and formats them as a report for use in auditing policy changes. Discovering servers that have no installed Halo agent An example script uses the Ruby fog library to retrieve all of your server IP addresses from cloud providers and then cross-checks them against servers that have installed Halo agents, to let you determine whether you have any unprotected cloud servers. Scanning servers within a group to detect differences among them A script calls the "Server Issues" method of the Servers API endpoint for all servers in each server group in turn, analyzes the results, and prepares a report for each group that summarizes how well the servers in the group have the same consistent configuration status. Detecting server-local accounts whose passwords should be changed A script searches all of your Linux servers for local user accounts whose passwords are stale or expired and should be changed. The script accesses the Servers API endpoint to examine all local accounts on all servers in all server groups, then reports on any accounts whose last change date is older than the system-specified maximum password age. Identifying the IP addresses from which Halo users have logged into the portal This sample accesses the Events API endpoint and extracts the values of the user name, IP address, and country of every Halo login event within the time range that you choose. Besides browsing the Toolbox, be sure to consult the Halo REST API Developer Guide and the Integrations forum on the CloudPassage Support site to learn more about leveraging the Halo REST API and integrating Halo with your other tools.

Appendix A Halo Site Administration (For Halo site administrators only) If you are a Halo site administrator, you are the user (or one of the users) responsible for managing your organization's Halo service. Your responsibilities include management of Halo users, authentication settings, automatic scan configurations, API keys, Halo Daemon settings, Master Account connections, and other advanced settings. You access all of these tasks from the Site Administrator menu (the gears icon header). 33

in the Halo portal page

Note: This appendix is a reference to the Halo portal Site Administration page. Each subsection here describes (or links to the description of) one of the tabs across the top of that page.

Users See Invite and Manage Halo Users.

API Keys In Halo, API Keys are required for using the Halo REST API. Accessing the API requires the client to first authenticate to the authorization server by providing a valid API key. (See Call Authentication in the Halo REST API Developer Guide for details.) Halo site administrators can create and manage API keys. CloudPassage recommends that you create different API keys for different purposes—in particular, you should create a read-only key to use for programs that only read from (and do not write to) the Halo database. For example, applications that use the Halo Event Retrieval API should use a read-only key, since that key allows only GET requests from the API. Each Halo account initially has no API keys. If you are a site administrator, you can generate any number of API keys as needed. For example, you might generate a separate API key for each application that accesses the API To view or create API keys for your account, select Site Administration from the Site Administrator menu, then click the API Keys tab. Your current set of keys is displayed on the tab.

To create a new API key, click Add New Key, then enter a name for the key and specify its permission level (full-access or read-only). Specify allowed IP addresses. Optionally, for increased security you can enter a comma-separated list of one or more IP addresses or CIDR blocks. If you do so, an API client using this API key will be permitted to authenticate to the Halo API only from one of the specified addresses.

34

The key's 8-character ID and secret key values are generated by the system, and the key appears in the list on the API Keys tab. Note: Every time a secret key is generated, the action is logged and the user who created the key is identified. To edit a key in the list, click its name. You can change the key's name and permission level (full-access or readonly), and you can activate or deactivate it. To view the secret key value, click Show on the Edit API Key popup window or in the key's line on the API Keys tab.

You'll need to copy the secret key's value from this window and use it to obtain an API token, which allows you to access the Halo REST API (see Call Authentication in the Halo REST API Developer Guide). Note: Every time a secret key is viewed, the action is logged and the user who viewed the key is identified. On the API Keys tab, use the Actions drop-down menu for a given key to either edit or delete the key. Note: Every time an API key is deleted, the action is logged and the user who deleted the key is identified.

Authentication Settings To minimize the potential for damage from stolen, intercepted, copied, recycled, or guessed passwords, you can specify various requirements and settings for passwords and for login control. Select Site Administration from the Site Administrator menu, then click the Authentication Settings tab.

35

Password Settings Password Construction Rules. You can increase the minimum required password length from its default minimum of 8 characters. You can also require that every password must contain at least one number, or one symbol, or both (in addition to both uppercase and lowercase letters). If you choose to require symbols in passwords, the following are supported: ()`~!@#$%^&*-+=|\{}[]:;"',.?/ Password Expiration. You can enable password expiration and set the maximum lifetime (time to expiration) of a newly created password to any number of days from 1 to 365. You can also enable and specify the minimum lifetime of a newly created password (time that it must remain in effect before it can be changed again) to any number of days from 1 to 999. These two settings are independent. You can enable one or both or neither.

Login Settings User lockout. You can change the failed login limit (number of consecutive times a user can attempt to log in until the account is locked to prevent further login attempts) to any value from 1 to 25. Default value = 10. You can also change the duration of a lockout to any number of minutes from 5 to 1440 (24 hours). Default value = 60. Note: For a locked-out user to log in again, the user can either complete a password reset (from the Halo portal login page) or wait until the lockout period ends. Idle session timeout. By default, the timeout for Halo portal sessions (the time after which an idle session logs out) is 30 minutes. But you can keep idle sessions open for much longer, or you can cut them off more quickly. Use drop-down list to choose a timeout value of as little as 15 minutes up to as much as 24 hours.

36

Multi-factor authentication for Halo login. As a site administrator, you have the option of requiring Halo users to use multi-factor authentication when logging into the Halo portal. Multi-factor authentication to the portal is optional, but it is all-or-nothing—if you choose to activate it, it must apply to all Halo users in your account. To activate the requirement, select the checkbox Require multifactor authentication for Halo portal logins.

You cannot activate multi-factor authentication for portal login until all Halo users on your account have been individually enabled for multi-factor authentication. Once it is active, all newly created users must also be enabled for multi-factor authentication. When multi-factor authentication for portal login is active: A new user logging into the portal for the first time is initially brought to the Change Password page to create the user's Halo password. The user is then brought to the either the SMS Phone Verification page to enter an SMS verification code, or the YubiKey authentication page to insert a YubiKey. Then the user may log in in the same way as an existing user. A existing user logging into the portal initially provides the Halo password at the login page, and then enters an SMS authentication code (or inserts a YubiKey) at the multi-factor authentication page. (A user enabled for both types of authentication first chooses which method to use.) The user is then logged in.

For more details, see Log In With Multi-Factor Authentication.

Single Sign-On Settings

37

If you are implementing an integration of Halo with your organization's SAML 2.0-based single sign-on solution, you may need to develop a plug-in or application according to the identity provider's requirements, so that the proper SAML assertions are sent to Halo to perform the authentications. Or the identity provider may have already created the integration app for Halo. Part of setting up the integration involves enabling single-sign on and entering information into fields in the Single Sign-On Settings section of the Authentication Settings tab on the Site Administration page

1. Select the Enable Single Sign-On (SSO) check box. The section expands to display the single sign-on settings form.

2. Copy the account ID from this form and supply it to the SSO identity provider. 3. Obtain information to enter into the remaining fields from the identity provider. 4. Make SSO Required. If you want to disallow all direct logins to the Halo portal, select this checkbox at the bottom of the form. If you do select the box, you must provide SSO access to all existing and future Halo users. Note that you cannot select the box unless you are currently logged in through SSO. Note: As long as this checkbox remains selected, Halo users' account pages have no displayed password field, Halo users cannot reset their passwords, and new Halo users do not receive email invitations to log into Halo. 5. Click Save to commit your SSO settings. For detailed instructions on creating the SSO integration, see Appendix C: Adding Single Sign-On to Halo in the Halo Operations Guide.

Scanner Settings See Configure Automatic Scans. 38

Daemon Settings As site administrator, you can control various settings for the Halo agents currently running or to be installed on your servers. Select Site Administration from the Site Administrator menu, then click the Daemon Settings tab. Halo agent key. A valid key is needed whenever you install a Halo agent (see Install Agents). You can use the same key value for all installations, as long as it remains confidential. If you feel that it might have been compromised, click Regenerate to get a new key, and use that one in future installs.

Daemon Heartbeat. For security reasons, all communication between a Halo agent and the Halo analytics engine is always initiated by the agent. The agent connects to the analytics engine at regular intervals to report status and to receive instructions. You can select an interval from 60 seconds to15 minutes. Default value = 60 seconds. If you have a large number of servers, selecting a longer interval may have the benefit of less impact on your network performance, although Halo updates and commands sent to your servers may take longer.

Deactivate Missing Servers. Halo re-classifies an active server as missing if its agent has unexpectedly not contacted the analytics engine for an interval of 10 or more heartbeats. To keep missing servers that do not recontact the analytics engine from remaining in a missing state perpetually, Halo will automatically delete them after a time interval that you specify. Use the drop-down list to select the threshold for auto-deactivation to any available value from 15 minutes to 24 hours.

An important benefit of automatically deactivating missing servers is that it prevents the buildup of large numbers of missing, unused servers as sources or destinations in firewall policy rules. Daemon Self-Verification. The agent can continually monitor itself for evidence of compromise and report any evidence that it has been tampered with. You can enable or disable self-verification, you can choose to have compromised agents shut themselves down automatically, and you can set the interval between self-verification checks to any number of hours from 1 to 23. Default = 1 hour.

39

Advanced Settings A variety of other Halo settings are available to site administrators. To review or change them, select Site Administration from the Site Administrator menu, then click the Advanced Settings tab. Set GhostPorts Session Length: Set the length of time that a server administrator will have to log into a server after authenticating to and opening GhostPorts. Select a number of hours from 1 to 24. Default value = 4.

A longer time window may be more convenient for an administrator, but it may be riskier (less secure) than a shorter one. List IP Addresses Authorized to Access Halo Portal: For added security, you can specify that your Halo users (including yourself) are permitted log into the Halo portal, or request a password reset, only from identified IP addresses. Enter a comma-separated list of IP addresses or CIDR blocks into the IP Addresses field.

Note: The list of authorized addresses must always include (or encompass) the address from which you are accessing the portal in order to create or edit the list. To remove all address restrictions for logging into the portal, delete all addresses from the field and click Save. Choose Your Email Preferences Pick a time of day and a time zone to specify when Halo should send out its daily status emails to the Halo users in your account.

40

Note that individual users can choose whether or not to receive daily status emails; see Manage Your Account and Subscription. Enable Halo Beta Features CloudPassage may release some Halo features or capabilities when they are still at the beta stage of development. In some cases the features are by default disabled. If you want them to be available to your Halo users, select the Enable Beta Features checkbox. Conversely, clear the checkbox to make the features unavailable.

Audit Events Besides logging events that may directly indicate serious security issues, Halo also logs a large variety of audit events, which mostly represent normal, everyday actions of Halo portal users. Recording the history of audit events is useful for demonstrating compliance, and also useful in supporting correlation and forensic analysis in the wake of a security breach. Halo site administrators can use the Audit Events tab on the Site Administration page to specify which events should be logged, which should be flagged as critical, and which should generate alerts.

For each listed event, select "Log Event" if you want Halo to record occurrences of the event, select "Flag Critical" if you want those occurrences to be flagged as critical ( ), and select "Generate an Alert" if an occurrence should cause an email alert to be sent to the appropriate personnel in your organization. Note: The list of events displayed on this tab does not include the server-related Halo special events (for example, "Server firewall modified" or "server restarted") or any security events generated by scans (for example, "Configuration rule matched" or "File integrity object signature changed"), because those events are configured elsewhere, in various Halo policies. 41

Master Account Your organization, with its own CloudPassage Halo account, may be one of several organizations that are part of a larger entity (such as a parent company) that wishes to have oversight and control over all of its sub-organizations' security operations. Halo supports this with the concept of master accounts. A master account administrator has access to all of the sub-accounts through the Halo portal, allowing the administrator to review all sub-account settings and configurations, audit all actions and events in the sub-accounts, and even directly manage and run their Halo activities. The administrator can operate within each sub-account as a site administrator of that account. If your account needs to be linked to a master account, you will have received a master account invitation code from your master account administrator. Enter that code into the field on the Master Account tab of the Site Administration page, and click Link to complete the connection to the master account.

If your account is currently linked to a master account and you need to sever that relationship, click the Disconnect button on the Master Account tab.

If your organization wishes to connect to a master account, please contact CloudPassage Sales or your account representative to have the master account created for you.

Appendix B

Multi-Factor Authentication

For site administrators, this appendix details how to enable multi-factor authentication for Halo users. For Halo users, it details how to log into the Halo portal with multi-factor authentication. Note: Multi-factor authentication for login to the Halo portal is a different Halo feature from multi-factor network authentication, which server administrators use for secure remote access to servers. Multi-factor network authentication is described in Multi-Factor Network Authentication Setup Guide.

42

Enable Multi-Factor Authentication for a User To enable multi-factor authentication for a Halo user, you must be a Halo NetSec or Halo Professional user with siteadministrator privileges. Important: Enabling multi-factor authentication for a user will not take effect until you activate multi-factor authentication for the Halo portal as a whole, on the Site Administration page; see Multi-factor authentication for Halo login. Also, since multi-factor authentication to the Halo portal is all-ornothing, you will not be able to activate it until you have enabled it for all of your organization's individual Halo users. Before enabling: If the user is to use SMS authentication, obtain that person's valid mobile phone number. Text messaging must be enabled for that mobile account. If the user is to use hardware authentication, acquire a YubiKey. You can order the keys directly from Yubico. Then: 1. Log into the Halo portal and navigate to [

] > Site Administration > Users.

If the person is not already a Halo user, click Invite New User. If the person is an existing Halo user, find the user's name in the user list and click Edit. 2. Specify or change the user's information, including portal access and user type, as described in Invite a New User or Edit an Existing User. (You will be able to enable GhostPorts access for the user, if desired, only after enabling multi-factor authentication for the user.) 3. Specify the user's authentication method(s): select SMS code and Halo Password or YubiKey and Halo Password, or both.

4. The page then expands to display additional fields. Enter the following information: If you selected SMS code and Halo password—

a. In the "Phone Number" field, enter the telephone number at which the user will receive the SMS authentication codes. It must be a valid mobile phone account with text messaging enabled. b. Click Save. The user receives an email notification of being enabled for multi-factor authentication and an invitation to log into the portal. At the next login, the user will be asked to verify the SMS phone number. If you selected YubiKey and Halo password—

43

a. Place the YubiKey into a USB port on your computer, with the metal contacts and circle facing upward ( ). Place your cursor into the "YubiKey Code" field on the page. Initiate the YubiKey by lightly touching the top circle with the green centered light. The YubiKey key will write its complete key value into the field. b. Click Save. You will notice a portion of the key value disappear. The first twelve characters of the key value will remain displayed in the key field. The user receives an email notification of being enabled for multi-factor authentication.

Log In With Multi-Factor Authentication If you are a Halo user who must use multi-factor authentication to access the Halo portal, or if you are a GhostPorts user, follow the steps listed here to log in. The login processes for SMS authentication and YubiKey authentication differ slightly. Also, SMS authentication adds a one-time preliminary step of verifying the SMS phone number.

Verify Your Phone Number (for SMS Authentication) If you will be authenticating to the Halo portal with an SMS code, you first need to verify to Halo that the authentication phone number assigned to you is the correct one. The verification process includes demonstrating that the phone can receive a code from Halo. 1. After you receive your notification that you are enabled for SMS-based multi-factor authentication, log into the Halo portal with your Halo password. You will see a Dashboard banner notifying you that your SMS phone number is unverified. 2. Click the link in the banner to go to the Phone Verification page for SMS authentication. 3. In the Verify Phone form, inspect the partially masked phone number, of the form XXX-XXX-XX67. If the displayed digits of the phone number are not correct, contact your Halo site administrator to change your assigned number. 4. If the displayed digits match your phone number, click the Send Verification Code button. A code will be sent to your mobile phone. 5. When you receive the message on your phone, copy the six-digit verification code into the Verification Code field on the Verification page, then click Submit. You have 5 minutes from the time you click Send Verification Code until the code expires. If you do not complete this step within that time, you can click Send Verification Code again to have another code sent to you. If the verification succeeds, a success page and banner are displayed. You are now able to log into the Halo portal.

Authenticate With an SMS Code Note: You must already have verified your phone number (see previous section, Verify Your Phone Number) before you will be permitted to perform these steps. If you are authenticating to Halo with an SMS code, follow these steps: 1. Log into the portal with your Halo username and password. The Multi-Factor Authentication page for SMS appears:

44

2. An SMS code has been sent to your mobile phone. When it arrives, enter it into the Authentication Code field and click Submit. You have 5 minutes from the time you click Submit until the code expires. If you do not complete this step within that time, you can click Re-send Authentication Code to have another code sent to you. Note: The code is sent by SMS, and normal text-messaging charges for your account may apply. After you have authenticated successfully, the portal Dashboard page appears, displaying a success banner.

Authenticate With a YubiKey Note: You must be in possession of your assigned YubiKey device to perform these steps. If you are authenticating to GhostPorts with a YubiKey, follow these steps: 1. Log into the portal with your Halo username and password. The Multi-Factor Authentication page for YubiKey appears:

2. Place your YubiKey into a USB port on your computer, with the metal contacts and circle facing upward (

).

3. Place your cursor in the blank field on the Multi-Factor Authentication page. Initiate your YubiKey by lightly touching the top of the key on the green-centered light for about one second. Do not press any other key on your keyboard. You will see the field fill with the value generated by your YubiKey. After you have authenticated successfully, the portal Dashboard page appears, displaying a success banner.

Site Administrators: Set Up a Backup Authentication Method! If you are a Halo site administrator who uses multi-factor authentication to log into the Halo portal, you may need to enable both SMS and YubiKey authentication methods for yourself, so that you can use one method as a backup in case the other one becomes unavailable. Without a backup, you could permanently lock yourself out of access to the 45

portal. Whether you are a site administrator or standard Halo user, if you lose your mobile phone or your assigned YubiKey, any other site administrator in your organization can log in and reset your authentication method to use a different method or device that is available to you. However, if you are the only Halo site administrator in your organization and you lose the assigned device, you will be unable to log into the portal. In that situation, you will have to contact Halo Customer Support and go through a lengthy identity-verification process in order to restore your access. Our strong recommendation is that, if your Halo account includes only a single Halo site administrator, you enable both of the multi-factor authentication methods (SMS and YubiKey) for that administrator.

Appendix C

Adding Single Sign-On to Halo

About SAML-Based Single Sign-On Integrating Halo With a Single Sign-On Provider Automatic Provisioning of Halo Users for SSO Example: Integrating Halo With OneLogin

About SAML-Based Single Sign-On Implementing a single sign-on (SSO) infrastructure enables your users to sign in once and have access to all authorized resources in your organization. Single sign-on is a very desirable convenience for users who need to use many different remote applications in their daily work. A number of different approaches to single sign-on have been developed over the years, some proprietary and some based on open standards. The Security Assertion Markup Language (SAML) is an open standard that supports a secure, XML-based solution for exchanging user security information between an identity provider (the organization that establishes the identity of a user, or principal) and a service provider (the provider of an application or service that the principal wishes to use). The user must initially establish an identity with the identity provider. Then, when the user attempts to access the desired application, the identity provider sends a SAML assertion to the service provider, attesting to the user's identity and privileges. The service provider accepts the assertion because it trusts the identity provider, and the user gains access to the application.

The current version (SAML 2) supports, among other capabilities, two workflows for logging in. In identity providerinitiated login, the user first logs into the identity provider's site and chooses the desired resource; the identity provider then sends an assertion to the service provider, who in turn makes the resource available to the user. In service provider-initiated login, the user attempts to log directly into the service provider's site; that login is temporarily 46

redirected to the identity provider along with a request for an assertion. The identity provider returns an assertion, and the service provider then gives the user access to the service.

SAML-based SSO is available as a cloud service from several identity providers, including OneLogin, Okta, Ping Identity, and others. CloudPassage Halo is designed to integrate with most single sign-on identity providers that are SAML v2.0-compliant, and the integration has been tested and verified with one vendor (OneLogin). Note: Halo currently requires SAML 2.0, and it supports identity provider-initiated login only. The next section of this document provides general instructions for integrating Halo with a SAML identity provider. The following appendix gives more detailed, identity provider-specific instructions for integrating Halo into the OneLogin SSO service.

Integrating Halo With a Single Sign-On Provider This section contains general instructions for integrating Halo with a SAML 2.0-based SSO identity provider, to implement single sign-on with identity-provider-initiated login. It explains which steps to take in Halo, and it lists the information that needs to be exchanged with the identity provider. Note: These instructions assume that you already have an administrative account on your identity provider's site, and that you are a site administrator user in Halo.

1

Enable and configure SSO To enable your Halo users to log into the Halo portal through a SAML 2.0-based single sign-on solution, start by enabling single sign-on in the Halo portal. 1. Log into the portal and navigate to the Authentication Settings tab on the Site Administration page. Scroll down to the Single Sign-On Settings section. 2. Select the Enable Single Sign-On (SSO) check box. The page expands to display the single sign-on settings form.

47

3. Copy the account ID from this form. The ID identifies your organization's Halo account to the identity provider, and it is passed from identity provider to service provider (Halo) in the SAML assertion. You will need to provide this ID to your identity provider when configuring SSO for Halo in the provider's portal. The provider will use the ID to construct two URLs for connecting to Halo: Login URL: https://portal.cloudpassage.com/saml/init/account_id Consumer URL: https://portal.cloudpassage.com/saml/consume/account_id Depending on your identity provider's requirements, you may need to construct these URLs yourself and provide them, or you may be able to simply provide the account ID. 4. Obtain the following items of information from your identity provider, and enter them into the following fields on the single sign-on settings form in the Halo portal: SAML issuer URL. Paste in the URL that uniquely specifies the identity provider. SAML endpoint URL. Paste in the URL of the identity provider's endpoint that receives requests. Note: Your identity provider might supply only one URL for you to use. If so, paste that URL into both of the above fields. Logout landing page. In this field, optionally enter the URL of the page to display to a user that has logged out of Halo. Typically, it might be the identity provider's page from which your organization's users can log back into Halo or other applications. (This item is not specified by the identity provider; whether and which page to specify is your decision.) x.509 certificate. An x.509 certificate for your organization's account with the identity provider. Paste the entire certificate (including the Begin Certificate and End Certificate sections) into the field. 5. Make SSO Required. If you want to disallow all direct logins to the Halo portal, select this checkbox at the bottom of the form. If you do select the box, you must provide SSO access to all existing and future Halo users. Note that you cannot select the box unless you are currently logged in through SSO. Note: As long as this checkbox remains selected, Halo users' account pages have no displayed password field, Halo users cannot reset their passwords, and new Halo users do not receive email invitations to log into Halo. 6. Click Save to commit your SSO settings.

2

Configure users in Halo 48

Every person in your organization that will use SSO needs to have an account with the identity provider and in the Halo portal. In the Halo portal, you create users by adding them from the Users tab of the Site Administration page. Note that user accounts in Halo are identified by a unique username, and this username must match the username passed by the identity provider to Halo in the SAML assertion. Therefore, the identity provider must be aware of every user's Halo username. See also Automatic provisioning of Halo Users for SSO, below, for an alternative to manually creating Halo users in the portal.

3

For Halo users: Logging into Halo with SSO If you are a Halo user and your organization has integrated Halo with a SAML-based single sign-on solution, you will have been provided with a mechanism (such as a URL) for accessing the identity provider's protected applications, including the Halo portal. You start by logging into the identity provider. You then select Halo or some other SSO-protected application to access, and you are immediately logged into it. Your login context with the identity provider serves as your authentication to Halo and to all other applications covered by your SSO solution. Note: Whenever a Halo user logs into the portal through SSO, a Halo event of type "Halo login success" (or "Halo login failure", if it fails) is logged,

Using GhostPorts with SSO: If you are a Halo GhostPorts user using SSO, the workflow for opening GhostPorts is the same as with multifactor login to Halo: If you log into Halo through SSO, and if you open GhostPorts less than one minute after logging in, you are not required to authenticate to GhostPorts. If you log into Halo through SSO, and If you wait longer than a minute before opening GhostPorts, you are required to authenticate to GhostPorts using either SMS or YubiKey two-factor authentication.

Automatic Provisioning of Halo Users for SSO When you integrate Halo into a SAML-based SSO system, you can choose the administrative workflow you prefer for creating Halo users. Given that all of your users that access Halo must have accounts with both the identity provider and with Halo itself, you can create those Halo user accounts in either of two ways: Manually, by logging into the Halo portal and creating Halo users. Automatically, by using Halo's just-in-time provisioning capability. With just-in-time autoprovisioning, Halo uses information passed to it in the identity provider's SAML assertion to determine whether a user requesting access is already an existing Halo user. If the user is not, Halo creates the user's Halo account from the information in the assertion. If the user already exists but some of the passed information is different from what is in the current Halo account, the Halo account is updated with the new information.

Setting Up Automatic Provisioning: If you are administering the SSO solution for your organization and are implementing just-in-time provisioning, you will need to provide the following additional user parameters for the SAML assertion that the identity provider sends to Halo. You may implement the parameters and store the user information in any convenient way—for example, as extra fields in your organization's user database. admin. Whether the user is a Halo site administrator (true or false). ghostport_access. Whether the user is a GhostPorts user (true or false). portal_access. Whether the user has portal access (true or false). 49

firstname. lastname. email. sms. The user's mobile phone number for receiving SMS authentication codes (if the user uses SMS authentication and (1) is a GhostPorts user, or (2) if multi-factor login to the Halo portal is required). yubikey. The user's YubiKey key value (if the user uses a YubiKey for authentication and (1) is a GhostPorts user, or (2) if multi-factor login to the Halo portal is required). Other important parameters that are in every assertion, regardless of whether autoprovisioning is used, include these: NameID. The user's Halo username, as noted in Step 2, above. Halo usernames must be unique across your Halo account. Account ID. The ID that identifies your organization's Halo account to the identity provider. It is passed in the assertion as the Consumer URL, as noted in Step 1, above. When autoprovisioning is in use, the first time that a user who is not an existing Halo user attempts to log in, all of the above parameters are used to initialize the Halo user in the portal. On subsequent access attempts, if any of the passed parameters have different values from what is stored in Halo, the user's Halo information is updated accordingly. Note: Whenever a Halo user is created or updated, either manually or through automatic provisioning, a Halo event of type "Halo user added" or "Halo user modified" is logged.

Example: Integrating Halo With OneLogin OneLogin (http://www.onelogin.com/) is an identity and access management provider that offers a cloud-based single sign-on solution. CloudPassage has worked with OneLogin to make single sign-on available to Halo users. The SSO use case currently supported for Halo with OneLogin is for identity-provider-initiated login. This appendix describes in detail the steps you need to take in the Halo portal and in the OneLogin portal to complete the configuration. Note: These instructions assume that you already have an account with Administrator privileges on OneLogin, and that you are a site administrator user in Halo.

Enable and Configure SSO with OneLogin To enable your Halo users to log into the portal through OneLogin SSO, first log into the Halo portal in one browser window or tab, and simultaneously log into your OneLogin portal in a separate window or tab. 1. In the Halo portal, navigate to the Authentication Settings tab on the Site Administration page. Scroll down to the Single Sign-On Settings section. Enable single sign-on in Halo: 2. Select the Enable Single Sign-On (SSO) check box. The page expands to display the single sign-on settings form.

50

3. Copy the account ID at the top of this form into your browser's clipboard. The ID identifies your organization's account with OneLogin. Install OneLogin's Halo Application and Transfer the Account ID to OneLogin: 4. Go to the OneLogin portal in the other browser window, navigate to Apps > Find apps, and search for CloudPassage Halo. Two CloudPassage apps may be available:

CloudPassage Halo (auth-only) requires you to manually create (in Halo) the Halo user accounts for all of your users that need SSO access to Halo. CloudPassage Halo (with provisioning) is functionally the same application, except that it automatically creates Halo accounts for any of your users when they first log into Halo. You will not have to explicitly provision any users within Halo. See Automatic Provisioning of Halo Users for SSO for more information on this feature. 5. Click add for the app that you wish to use. 6. In the Add Halo form, select your chosen CloudPassage Halo application as the app to be used by your organization, then click Continue. The app is now visible under the Apps > Company Apps tab. 7. Under Company Apps, locate the appropriate CloudPassage Halo application and click its edit link. 8. Click the Configuration tab and paste the account ID (which you just copied from the single sign-on settings form in the Halo portal) into the Account ID field.

51

9. Click Update to save your change. Transfer Provider URLs to Halo: 10. In the OneLogin portal, click the Single Sign-On tab for the Cloudpassage Halo:

a. Copy the URL displayed under Issuer URL, switch to the browser window displaying the single sign-on settings form in the Halo portal, and paste the URL into the SAML issuer URL field. b. Back in the OneLogin browser window, copy the URL displayed under SAML Endpoints, then switch to the Halo window and paste the URL into the SAML endpoint URL field. c. For Credentials, select "Configured by admin" or "Shared", depending on how user credentials are determined in your organization. d. For Default values, choose what the Halo username for a user added to this application should default to— for example, the OneLogin username, email address, or other identifier. For any user whose actual Halo username does not match the default, you will need to manually specify the user's Halo username. e. Click Update to save any settings you have changed. 52

Transfer x509 certificate to Halo: 11. In the OneLogin portal, navigate to the SAML tab under the top-level Security tab:

12. Copy the contents of the x.509 certificate (including the Begin Certificate and End Certificate sections), then once again switch to the Halo portal and and paste the certificate into the x.509 certificate field in the single sign-on settings form.

Complete the configuration: 13. Logout landing page (optional). If you want a certain page to be displayed to a user who logs out of Halo, enter the URL to that page in this field. A typical page to specify here might be your organization's Company Apps tab in the OneLogin portal. Logged-out users could then immediately log back into Halo or any other SSOprotected application. 14. Make SSO Required. If you want to disallow all direct logins to the Halo portal, select this checkbox at the bottom of the single sign-on settings form. If you do select this checkbox, you must provide SSO access to all existing and future Halo users. Note: you cannot select the box unless you are currently logged in through SSO. Note: As long as this checkbox remains selected, Halo users' account pages have no displayed password field, users cannot reset their passwords, and new users do not receive email invitations to log into Halo. 15. Click Save at the bottom of the single sign-on settings form to save your changes.

Test your SSO setup: 53

Use your own account to test the connection between Halo and OneLogin. Take these steps: 1. Make sure that you are logged out of Halo, and then log into OneLogin. Note: If your Halo username is different from your OneLogin username, take these steps first: a. Click Apps, then Company Apps. b. Click edit beside the Halo application icon, then click the Logins tab. c. Locate your username and click Edit. The Halo field should be blank, if it is defaulting to the (OneLogin) Username parameter. d. Type your Halo username in the Username field, and click Update. e. Navigate back to Company Apps. 2. Click the Halo application icon. You should immediately log into Halo, without having to provide credentials.

You're done with the configuration! Once you provision Halo users in both OneLogin and the Halo portal, they will have have SSO access to Halo.

Replicate Selected OneLogin Users in Halo If your organization has an existing integration with an SSO identity provider, all of your users are already mirrored as users on the identity provider's site. Of those users, the ones that will use Halo need to be Added as "logins" to the CloudPassage Halo application in the OneLogin portal, and Created as Halo users, either manually in the Halo portal itself, or automatically as described in Automatic provisioning of Halo Users for SSO. To give you greater flexibility in naming users with accounts on both OneLogin and Halo, OneLogin allows a user to have a different username in Halo than on OneLogin. When adding a user to the Halo application in OneLogin, you have the opportunity to specify the user's Halo username. (You can also do that when editing a user, under the Logins tab in your CloudPassage Halo application.) When you add a user to your Halo Application in OneLogin, the new user's Halo login name defaults to a value (for example, OneLogin username or email address) that you can specify on the Single Sign-On tab of the application. Depending on your conventions for both OneLogin and Halo usernames, by specifying the appropriate default you may not need to explicitly specify a Halo username in many cases.

For Halo Users: Logging Into Halo with OneLogin SSO If you are a Halo user and your organization has integrated Halo with OneLogin, you will have been provided with a mechanism (such as a URL) for accessing the Halo portal and all other applications protected by your OneLogin SSO solution. The URL will take you to your Company Apps page on the OneLogin site, from which you can then access Halo itself with a single click. Your login context with OneLogin will serve as your authentication to Halo and to all other applications covered by your SSO solution. When you wish to use Halo: 1. Follow the URL for accessing your SSO-protected applications. You are taken to the OneLogin site. 2. If you are not already logged into OneLogin, log in with your OneLogin credentials. If you are currently logged in, you will not need to provide those credentials again. Your company's application page in OneLogin appears, displaying (perhaps among others) a Halo icon. 3. Click the icon for Halo. You are immediately logged into the Halo portal, and your Dashboard page is displayed. That's it! You now can use any parts of Halo that you are authorized for.

Using GhostPorts with SSO: 54

If you are a Halo GhostPorts user using SSO, the workflow for opening GhostPorts is the same as with multi-factor login to Halo: If you log into Halo through SSO, and if you open GhostPorts less than one minute after logging in, you are not required to authenticate to GhostPorts. If you log into Halo through SSO, and If you wait longer than a minute before opening GhostPorts, you are required to authenticate to GhostPorts using either SMS or YubiKey two-factor authentication.

Appendix D Search Expression Syntax Several Halo features (for example, the "string presence" rule check in configuration security monitoring, and policy rules in log-based intrusion detection) support the use of search patterns. Halo search patterns are strings of plain text, special characters, and metacharacters—very similar to regular expressions, although not as full-featured. This appendix lists the special characters and metacharacters supported by Halo, describes what each one means, and gives usage examples. Note: All searches are case-sensitive. Character

Represents

Usage Example

.

Any character

abc. matches abcd, abcZ, abc3, abc$, abc/...

\w

Any alphanumeric character

C\wPO matches CAPO, C3PO, CbPO...

\W

Any character that is not alphanumeric c\Wpo matches c@po, c#po, c%po...

\d

Any digit (numeric character)

C\dPO matches C3PO, C4PO, C0PO... (not c0pO)

\D

Any character that is not a digit

C\DPO matches CAPO, C@PO, CaPO...

\s

Any whitespace character

abc\sd matches abc d

\S

Any non-whitespace character

abc\Sd matches abc.d, abcCd, abc$d...

[ ]

One instance of any of the characters inside the brackets

cloud[9Sy] matches cloud9, cloudS, cloudy

[^ ]

Any character that is not one of the characters inside the brackets

cloud[^9Sy] matches cloud8, cloud#, cloudZ...

*

Zero or more consecutive occurrences of the previous character

cloud9* matches cloud, cloud9, cloud99, cloud999...

+

One or more consecutive occurrences of the previous character

cloud9+ matches cloud9, cloud99, cloud999...

?

Optional presence of the preceding character

555[-.]?1212 matches 555-1212, 555.1212, 5551212

\

Escape character (precedes a special character)

Use \$ to match a dollar-sign character, or \. to match a period (dot).

-

(hyphen) range operator

[a-d]loud[1-9] matches cloud9 (but also aloud1...)

^

The search expression must match at the beginning of the target string (file).

^cloud will find a match in cloud9 but not in 9cloud

$

The search expression must match at the end of the target string (file).

cloud$ will find a match in 9cloud but not in cloud9

Note: To use a special character as a literal character, be sure to precede it with the escape character, as in \55

for a hyphen.

Copyright ©2015 CloudPassage Inc. All rights reserved. CloudPassage ® and Halo ® are registered trademarks of CloudPassage, Inc.

56