ibm-auditlogging-operator

README

ibm-auditlogging-operator

The ibm-auditlogging-operator contains a Fluentd solution to forward audit data that is generated by IBM Cloud Platform Common Services to a configured SIEM. The operator deploys a Fluentd daemonset containing a systemd input plugin, remote_syslog output plugin, and fluent-plugin-splunk-hec output plugin. It also deploys the Audit logging policy controller.

Important: Do not install this operator directly. Only install this operator using the IBM Common Services Operator. For more information about installing this operator and other Common Services operators, see Installer documentation. If you are using this operator as part of an IBM Cloud Pak, see the documentation for that IBM Cloud Pak to learn more about how to install and use the operator service. For more information about IBM Cloud Paks, see IBM Cloud Paks that use Common Services.

Supported platforms

Red Hat OpenShift Container Platform 4.3 or newer installed on one of the following platforms.

• Linux x86_64
• Linux on Power (ppc64le)
• Linux on IBM Z and LinuxONE

Operator versions

• 3.8.0

• 3.7.1

• 3.7.0

• 3.6.2

• 3.6.1

• 3.6.0

• 3.5.0

  Technology Preview - Included in version 3.6.0, 3.6.1, and 3.6.2 support for sending audit log records over HTTP.

Prerequisites

Before you install this operator, you need to first install the operator dependencies and prerequisites:

• For the list of operator dependencies, see the IBM Knowledge Center Common Services dependencies documentation.

• For the list of prerequisites for installing the operator, see the IBM Knowledge Center Preparing to install services documentation.

• ibm-auditlogging-operator must run in the ibm-common-services namespace

SecurityContextConstraints Requirements

The ibm-auditlogging-operator supports running with the OpenShift Container Platform 4.3 default restricted Security Context Constraints (SCCs).

For more information about the OpenShift Container Platform Security Context Constraints, see Managing Security Context Constraints.

OCP 4.3 restricted SCC:

allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
allowPrivilegeEscalation: true
allowPrivilegedContainer: false
allowedCapabilities: null
apiVersion: security.openshift.io/v1
defaultAddCapabilities: null
fsGroup:
  type: MustRunAs
groups:
- system:authenticated
kind: SecurityContextConstraints
metadata:
  annotations:
    kubernetes.io/description: restricted denies access to all host features and requires
      pods to be run with a UID, and SELinux context that are allocated to the namespace.  This
      is the most restrictive SCC and it is used by default for authenticated users.
  creationTimestamp: "2020-03-27T15:01:00Z"
  generation: 1
  name: restricted
  resourceVersion: "6365"
  selfLink: /apis/security.openshift.io/v1/securitycontextconstraints/restricted
  uid: 6a77775c-a6d8-4341-b04c-bd826a67f67e
priority: null
readOnlyRootFilesystem: false
requiredDropCapabilities:
- KILL
- MKNOD
- SETUID
- SETGID
runAsUser:
  type: MustRunAsRange
seLinuxContext:
  type: MustRunAs
supplementalGroups:
  type: RunAsAny
users: []
volumes:
- configMap
- downwardAPI
- emptyDir
- persistentVolumeClaim
- projected
- secret

Documentation

To install the operator with the IBM Common Services Operator, follow the installation and configuration instructions within the IBM Knowledge Center.

• If you are using the operator as part of an IBM Cloud Pak, see the documentation for that IBM Cloud Pak. For a list of IBM Cloud Paks, see IBM Cloud Paks that use Common Services.

• If you are using the operator with an IBM Containerized Software, see the IBM Cloud Platform Common Services Knowledge Center Installer documentation.

• For more information, see the IBM Cloud Platform Common Services documentation.

Developer guide

As a developer, if you want to build and test this operator to try out and learn more about the operator and its capabilities, you can use the following developer guide. The guide provides commands for a quick installation and initial validation for running the operator.

Important: The following developer guide is provided as-is and only for trial and education purposes. IBM and IBM Support does not provide any support for the usage of the operator with this developer guide. For the official supported install and usage guide for the operator, see the the IBM Knowledge Center documentation for your IBM Cloud Pak or for IBM Cloud Platform Common Services.

Overview

• To learn more about how the ibm-auditlogging-operator was implemented, see Operator Guidelines and Operator SDK

• All of the resources that were created by our Helm chart are now created by a controller.

• Audit logging has three CRDs:

  1. AuditLogging - [DEPRECATED] A cluster scoped fluentd solution that utilizes journald.
  2. AuditPolicy - generated by audit-policy-controller repo.
  3. CommonAudit - A namespace scoped fluentd solution that utilizes https.

Configuration

• In order for audit logs to be forwarded to an SIEM, the fluentd.enabled spec field must be set to true.
• In order to deploy the policy controller, the policyController.enabled spec field must be set to true.
• If a field in a spec is omitted, the default value will be used.
• The list of all ibm-auditlogging-operator settings can be found in the IBM Cloud Platform Common Services Knowledge Center Configuration Documentation.

Developer Guide

• These steps are based on Operator Framework: Getting Started and Creating an App Operator.

• Repositories: ibm-auditlogging-operator

• Set the Go environment variables:

  export GOPATH=/home/<username>/go
  export GO111MODULE=on
  export GOPRIVATE="github.ibm.com"

• For more information, follow the Operator SDK Quickstart Guide

• IMPORTANT: Anytime you modify <kind>_types.go, you must run operator-sdk generate k8s, operator-sdk generate crds, and openapi-gen again to update the CRD and the generated code.

Testing

Installing by using the OCP Console

1. Create the ibm-common-services namespace.
2. Create the CatalogSource in your cluster.
3. Select the Operators tab and in the drop-down select OperatorHub.
4. Search for the ibm-auditlogging-operator.
5. Install the operator in the ibm-common-services namespace.

Prerequisites for building the operator locally

• Install linters

Run the operator

• make install
• make run
• Run tests on the cluster.
• make uninstall

Test Framework

• To run unit tests use, make test

Debugging the Operator

Run these commands to collect information about the audit logging deployment.

1. kubectl get pods -n ibm-common-services | grep audit
2. kubectl get serviceaccount -n ibm-common-services | grep audit
3. kubectl get secrets -n ibm-common-servces | grep audit
4. kubectl get services -n ibm-common-services | grep common-audit

These steps verify:

• The ibm-auditlogging-operator is running.
• The audit logging operand, fluentd, is running.
• The secrets (audit-server-certs, audit-certs) are created.
• The ibm-auditlogging-operator and ibm-auditlogging-operand service accounts are created.
• The common-audit-logging service is created.

Run these commands to collect logs:

1. kubectl logs <ibm-auditlogging-operator-pod> -c ibm-auditlogging-operator -n ibm-common-services
2. kubectl logs <ibm-auditlogging-operator-pod> -c audit-policy-controller -n ibm-common-services
3. kubectl logs -n ibm-common-services <audit-logging-fluentd-pods>

End-to-End testing

• For more instructions on how to run end-to-end testing with the Operand Deployment Lifecycle Manager, see ODLM guide.