Centrify Identity Services Platform SIEM Integration Guide

Transcription

1 Centrify Identity Services Platform SIEM Integration Guide March 2018 Centrify Corporation Abstract This is Centrify s SIEM Integration Guide for the Centrify Identity Services Platform. Centrify Corporation TEL (669) Tannery Way URL Santa Clara, CA 95054

2 Legal Notice This document and the software described in this document are furnished under and are subject to the terms of a license agreement or a non-disclosure agreement. Except as expressly set forth in such license agreement or non-disclosure agreement, Centrify Corporation provides this document and the software described in this document as is without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability or fitness for a particular purpose. Some states do not allow disclaimers of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This document and the software described in this document may not be lent, sold, or given away without the prior written permission of Centrify Corporation, except as otherwise permitted by law. Except as expressly set forth in such license agreement or nondisclosure agreement, no part of this document or the software described in this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, or otherwise, without the prior written consent of Centrify Corporation. Some companies, names, and data in this document are used for illustration purposes and may not represent real companies, individuals, or data. This document could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein. These changes may be incorporated in new editions of this document. Centrify Corporation may make improvements in or changes to the software described in this document at any time Centrify Corporation. All rights reserved. Portions of Centrify software are derived from third party or open source software. Copyright and legal notices for these sources are listed separately in the Acknowledgements.txt file included with the software. U.S. Government Restricted Rights: If the software and documentation are being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), in accordance with 48 C.F.R (for Department of Defense (DOD) acquisitions) and 48 C.F.R and (for non-dod acquisitions), the government s rights in the software and documentation, including its rights to use, modify, reproduce, release, perform, display or disclose the software or documentation, will be subject in all respects to the commercial license rights and restrictions provided in the license agreement. Centrify, DirectControl, DirectAuthorize, DirectAudit, DirectSecure, and DirectControl Express are registered trademarks and Centrify User Suite, Centrify Server Suite, Centrify for Mobile, Centrify for SaaS, Centrify for Mac, DirectManage, Centrify Suite, Centrify Express, DirectManage Express, Centrify Identity Platform, Centrify Identity Service, and Centrify Privilege Service are trademarks of Centrify Corporation in the United States and other countries. Microsoft, Active Directory, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. Centrify software is protected by U.S. Patents 7,591,005; 8,024,360; 8,321,523; 9,015,103; 9,112,846; 9,197,670; 9,442,962 and 9,378,391. The names of any other companies and products mentioned in this document may be the trademarks or registered trademarks of their respective owners. Unless otherwise noted, all of the names used as examples of companies, organizations, domain names, people and events herein are fictitious. No association with any real company, organization, domain name, person, or event is intended or should be inferred. CENTRIFY CORPORATION ALL RIGHTS RESERVED II

3 Contents Legal Notice... ii Introduction... 1 Setting up the SIEM OAuth app and user on a tenant... 2 Adding an OAuth client app... 2 Creating a user for SIEM... 3 Add a Role... 4 Final Checks... 6 Setting up the environment for Linux... 7 Step 1: Set up Docker on Linux... 7 Step 2: Set up Syslog server on local host machine... 8 Setting up the environment for Windows Server 2012 R Step 1: Set up Docker on Windows Server (Machine #1)... 9 Step 2: Set up remote Syslog server on Linux (Machine #2) Running the Syslog Writer Starting syslog writer Automatic restarting Checking execution logs Re-running syslog writer after cleanup Restarting a stopped syslog writer container Stopping syslog writer container Splunk CISP add-on Setting up Splunk Forwarder Installing the Splunk Add-on Configuring Data input Searching for CISP events CENTRIFY CORPORATION ALL RIGHTS RESERVED III

4 Introduction Syslog Writer is a dockerized application that captures events from Centrify Identity Services Platform (CISP) and logs them to a syslog server. This syslog then becomes the data source for a SIEM solution using Splunk. Syslog Writer is configured to start fetching CISP events from the previous day and then run every five minutes to fetch events incrementally. Events are fetched from the CISP server by using REST APIs after authenticating using OAuth client credentials. Although the Syslog Writer can be set up on any Linux or Windows platforms that support Docker, this document focuses on CentOS 6.9 and Windows Server 2012 R2, especially installing and configuring Docker and Syslog server. Supported platforms for Syslog Writer. CentOS 6.9, CentOS 7 RHEL 6.5, RHEL 7 Windows Server 2012 R2 Any version of Linux or Windows that supports Docker This document gives step-by-step details for configuring the OAuth app and SIEM user on a tenant as a prerequisite for setting up Syslog Writer, followed by installation of Docker and an interactive configuration to set up the Syslog Writer on Linux or Windows. Finally, this document guides the user in setting up the Splunk add-on for CISP. This section applies to Splunk 6.5.x and above. CENTRIFY CORPORATION ALL RIGHTS RESERVED 1

5 Setting up the SIEM OAuth app and user on a tenant There are four parts to setting up the SIEM OAuth app and user on the tenant: 1. Adding an OAuth client app 2. Creating a user for SIEM 3. Adding a role 4. Performing final checks Step-by-step procedures for each of these activities are provided in the following sections. Adding an OAuth client app 1. In the Centrify Admin Portal, select the Apps page from the Dashboards list and click on Add Web Apps. 2. Click Add for OAuth2 Client (Preview) and confirm by clicking Yes. 3. Enter oauthsiem as the Application ID. CENTRIFY CORPORATION ALL RIGHTS RESERVED 2

6 4. In the General Usage section, do not make any changes to the default settings. 5. Click on the Tokens tab, then select Client Creds under Auth Methods. 6. Click on the Scope tab, then click Add to add a new scope. 7. Give it the Name siem. 8. Under Allowed REST APIs, click Add and add Redrock/query.* Creating a user for SIEM 1. Select the Settings > Users page in the Dashboards list. 2. Enter siemuser for the Login Name and centrify.com as the Suffix. 3. Enter a Password and Confirm Password. Kindly make sure that this password does not have either a + or : character. CENTRIFY CORPORATION ALL RIGHTS RESERVED 3

7 4. In status, select Password never expires and Is OAuth confidential client (Preview). 5. Click the Create User button. Add a Role 1. Select the Core Services > Roles page in the Dashboards list. 2. On the Description tab, enter service account as the Name for the role. CENTRIFY CORPORATION ALL RIGHTS RESERVED 4

8 3. On the Members tab, click Add and enter the Login Name for the SIEM user created earlier. 4. On the Administrative Rights tab, click Add and select Read Only System Administrator: CENTRIFY CORPORATION ALL RIGHTS RESERVED 5

9 5. Click Add in the Add Rights box. 6. On the Assigned Applications tab, click Add and select the oauthsiem app you added earlier. 7. Click Save. Final Checks Before proceeding it is good to verify a few key settings: For the SIEM user, make sure that the service account role is listed in Core Services > Users > Roles Verify that service account is selected on the Apps > User Access tab for the OAuth app: CENTRIFY CORPORATION ALL RIGHTS RESERVED 6

10 Verify that Client Creds is selected under Auth Methods on the Apps > Tokens tab. Setting up the environment for Linux Syslog Writer on Linux will most likely involve only one machine, as the syslog server can be a local one. This machine will have Docker to run syslog writer, and the syslog server. Step 1: Set up Docker on Linux Note: The installation commands in this section are specific to CentOS 6.9. If you have another supported OS, this link will take you to installation instructions for Docker on your OS: 1. Make sure that the existing yum packages are updated and EPEL repository is enabled: CENTRIFY CORPORATION ALL RIGHTS RESERVED 7

11 sudo yum update sudo yum install y epel-release 2. Install Docker: sudo yum install y docker-io 3. Start the Docker daemon: sudo service docker start 4. Make sure that the Docker service is running: sudo service docker status Step 2: Set up Syslog server on local host machine 1. Allow TCP input in the syslog server configuration. Note: TCP ensures that no messages are lost even when the load is high, so it is used by Syslog Writer for logging events to the syslog server (local or remote). The steps in this section are specific to setting up rsyslog to receive TCP input. If you have a different syslog server, you will need to modify the syntax accordingly. a. Open the rsyslog configuration file sudo vi /etc/rsyslog.conf b. If they are commented out, uncomment these two lines in the rsyslog.conf file: $ModLoad imtcp $InputTCPServerRun 514 c. Restart the rsyslog server sudo service rsyslog restart 2. Monitor syslog CENTRIFY CORPORATION ALL RIGHTS RESERVED 8

12 Before starting syslog writer, it is helpful to keep another terminal window open to check syslog: sudo tail f /var/log/messages Note that the path for Ubuntu will be: /var/log/syslog Setting up the environment for Windows Server 2012 R2 Syslog Writer on Windows can currently only write the CISP events to a remote syslog server on Linux, so the setup involves 2 machines. Machine #1 runs Windows with Docker and the Syslog writer app; Machine #2 runs Linux with syslog server, and is in the same network. Step 1: Set up Docker on Windows Server (Machine #1) Note: The installation commands in this section are specific to Windows 10 Professional edition, running a VMWare virtual machine of Windows Server 2012 R2. If you are using another supported platform, you will need to modify the syntax for setting up Docker Toolbox for your machine, but these steps should give you the information you need to do that. 1. To enable virtualization, power OFF your Windows Server VM and in Virtual Machine Settings navigate to Hardware > Processors, then select Virtualize Intel VT-x/EPT or AMD-V/RVI as the Virtualization engine. CENTRIFY CORPORATION ALL RIGHTS RESERVED 9

13 2. Power ON the Windows server VM again. 3. Install Docker Toolbox for windows by following the instructions here: 4. Open the Docker Quickstart terminal to create a default Docker machine and provide a prompt for running the Docker commands. 5. Add a shared folder on host machine by opening Oracle Virtualbox and clicking Settings > Shared Folders for the default Docker machine. 6. In Shared Folders, make sure that c:\users is listed. CENTRIFY CORPORATION ALL RIGHTS RESERVED 10

14 Step 2: Set up remote Syslog server on Linux (Machine #2) The steps in this section are specific to setting up rsyslog on CentOS 6. If you have a different syslog server, you will need to modify the syntax accordingly. 1. Allow TCP input in syslog server configuration: a. Open the rsyslog configuration file: sudo vi /etc/rsyslog.conf b. If they are commented out, uncomment these two lines in the conf file: $ModLoad imtcp $InputTCPServerRun 514 c. Restart the rsyslog server: sudo service rsyslog restart 2. Allow the firewall to accept TCP input on port 514: a. Open the iptables config file: CENTRIFY CORPORATION ALL RIGHTS RESERVED 11

15 sudo vi /etc/sysconfig/iptables b. Add this line before the COMMIT line, if it is not present already: -I INPUT p tcp - dport 514 j ACCEPT c. Restart iptables: sudo service iptables restart 3. Monitor syslog: Before starting syslog writer, it is helpful to keep another terminal window open to check the syslog: sudo tail f /var/log/messages Note that path for Ubuntu will be /var/log/syslog Running the Syslog Writer Note: The commands in this section are shown in Linux format and are run in a terminal window on Linux. For Windows, open a Docker Quickstart terminal window and enter these commands without the sudo prefix. Starting syslog writer 1. Check images list. If it contains syslogwriter_image, delete that file. sudo docker images 2. Copy the zip file cisp_syslog_writer.zip from SFTP to a convenient location and extract it. Note: On Windows Server VM, make sure that the extracted folder is under the shared folder c:\users. For example, extracted folder: C:\Users\<username>\apps\cisp_syslog_writer 3. Load the image from the tar file and make sure that syslogwriter_image is in the images list. CENTRIFY CORPORATION ALL RIGHTS RESERVED 12

16 cd <extracted_path>/cisp_syslog_writer sudo docker load < syslog-writer-img.tar.gz sudo docker images 4. Configure the syslog writer By default, syslog writer will start with fetching the events for last 24 hours (rollback), and for a larger window, it will fetch data in batches of 10 mins (batch_size). Further, once the initial rollback fetch is completed, it will run once every five mins (frequency) to fetch the incremental data. You can skip this section if you are fine with these default settings, depending upon your data load. For a data load of 50 events per second and a rollback of 24hrs, it will take approximately 6.5 hours to catch up with current events after starting syslog writer. To avoid this delay, you might want to consider using a smaller rollback value. To run syslog writer with custom configurations, before starting the syslog writer as mentioned in the following steps, create a copy of config.ini.default under the data folder and call it config.ini. Edit the values for the below parameters in config.ini and save. rollback (in hours, default value: 24) The number of hours before current time for the syslog writer to start fetching events. batch_size (in minutes, default value: 10) The number of minutes to fetch data for, when the time range is big. By default it fetches data in batches of 10 minutes. frequency (in minutes, default value: 5) The frequency (in minutes) to trigger the syslog writer. Note: You can also change this parameter after the syslog writer has started. This kind of a change will be reflected after the pending job run is triggered. 5. Run the syslog writer container: sudo docker run --name syslog-writer -it --log-driver json-fil e --log-opt max-size=10m --net=host -v `pwd`/data:/home/centri fy-syslog-writer/data syslogwriter_image 6. When asked, enter: The Tenant URL (for example, CENTRIFY CORPORATION ALL RIGHTS RESERVED 13

17 The Username, along with suffix, of SIEM user The Password of the SIEM user The IP address of syslog server if it is remote; otherwise just press enter for a local syslog server. Note that for Windows Servers, this will be IP address of machine #2. 7. Check CISP events on the syslog server. Congratulations! Your syslog writer is up and running! The first run starts immediately. Because the default value for the frequency parameter is five minutes, the syslog writer runs once every five mins. Automatic restarting Note: If you want the container and syslog writer to start automatically if the Docker daemon restarts, you can use the option --restart=always in the run command, as shown below. The container and syslog writer will not automatically restart if the container was manually stopped. sudo docker run --name syslog-writer -it --log-driver json-fil e --log-opt max-size=10m --net=host - restart=always -v `pwd`/ data:/home/centrify-syslog-writer/data syslogwriter_image Checking execution logs You can see the current console logs of the syslog writer container by using the logs command in a Quickstart terminal: sudo docker logs -f systog-writer All execution logs are saved in the cisp_syslog_writer/data/logs/logs.log file on the host machine. Re-running syslog writer after cleanup If there was a failure during the initial interactive configuration, or if you wish to rerun or configure the syslog writer with a fresh account: 1. Delete the earlier container: sudo docker rm -f syslog-writer 2. Remove the local conf file in the cisp_syslog_writer/data folder: CENTRIFY CORPORATION ALL RIGHTS RESERVED 14

18 sudo rm data/config.ini 3. Run the container again using the same run command in the cisp_syslog_writer folder: sudo docker run --name syslog-writer -it --log-driver json-fil e --log-opt max-size=10m --net=host -v `pwd`/data:/home/centri fy-syslog-writer/data syslogwriter_image Restarting a stopped syslog writer container To start the container/syslog writer if the container stops (due to the Docker daemon or machine restart, etc. sudo docker start syslog-writer Stopping syslog writer container To stop the container/syslog writer: sudo docker stop syslog-writer Splunk CISP add-on The Splunk CISP add-on is responsible for data on-boarding and parsing CISP logs into Splunk events. These parsed events can be used for ad-hoc queries or can be used to create visualizations. This add-on co-exists with other Splunk add-ons without conflicts. Apart from data onboarding and parsing, the add-on handles the following: Timestamp correction: The timestamp in syslog is the time when logging happened and not the actual time when the event occurred. The timestamp of the CISP event in Splunk is corrected by using the WhenOccurred field in the event payload. Custom sourcetype assignment: A new sourcetype called centrify_cisp_syslog is assigned to CISP events. This ensures that CISP events and other syslog messages are not touched unintentionally. Applying Centrify headers: Headers such as product, category, and eventname present in the payload are assigned to CISP events in Splunk. CIM compliance: The add-on maps CISP Authentication events to the Authentication model of CIM. CENTRIFY CORPORATION ALL RIGHTS RESERVED 15

19 Setting up Splunk Forwarder In a distributed Splunk environment, the Splunk Universal Forwarder needs to be set up on the machine with the syslog server, so that the CISP events in syslog get forwarded to the Indexer. To configure Splunk Forwarder for a distributed setup: 1. In a terminal, navigate to the path of Splunk Universal Forwarder: cd splunkuniversalforwader/bin 2. Add the Forward server in the bin folder, using the IP address of the Splunk Indexer as the <ipaddress> and the Receiver port configured on the Splunk Indexer as the <port> (usually 9997):./splunk add forward-server <ipaddress>:<port> 3. Add syslog to the monitored files list:./splunk add monitor /var/log/messages Installing the Splunk Add-on The Splunk add-on is required to be installed on the indexer, and on the search head. To install the Splunk add-on from the command prompt, enter: $SPLUNK_HOME/bin/splunk install app centrify-splunk-add-on-cis p.tgz To install the Splunk add-on from the Splunk Web UI: a. Go to Apps > Manage Apps >Install app from file. b. Select centrify-splunk-add-on-cisp.tgz and click Upload. Configuring Data input To configure data input: In a distributed Splunk environment with a Forward Server: 1. Open the Splunk Enterprise web UI. 2. Go to Settings > Forwarding and receiving > Configure Receiving > Add New. CENTRIFY CORPORATION ALL RIGHTS RESERVED 16

20 3. In the Listen to Port text box, enter 9997 and click Save to send messages from the Forward Server to port In a standalone Splunk environment with local syslog: 1. Go to Settings > Data Inputs > Files and Directories. 2. Enable /var/log/messages (this is disabled by default). Searching for CISP events To search for CISP events, enter this command: Search sourcetype = centrify_cisp_syslog CENTRIFY CORPORATION ALL RIGHTS RESERVED 17