Audit logging policy controller

The audit logging foundational service provides support to cluster services that need or are required to generate an audit trail. The audit logging service provides a policy-based feature to identify compliance.

An audit logging policy defines an audit ruleset for services that run in the cluster.

The audit logging policy controller verifies the compliance of audit logging policy rules for services that are identified in the policy. The audit logging policy controller is enabled by default.

An audit policy is created when an audit policy Custom Resource Definition (CRD) is instantiated. For more information about CRDs, see Extend the Kubernetes API with CustomResourceDefinitions .

After an audit policy is created, the audit logging controller continuously evaluates the value of the audit_enabled setting that is associated with a service. The audit_enabled parameter is defined in a configmap associated with a specific service. If the audit logging policy rule for a service specifies a value of validate, the audit logging controller checks the audit configuration for the service and reports it as compliant. If the audit logging policy rule specifies the rule for a service as ignore, the audit logging controller does not check the audit configuration of the service. The audit policy controller also supports verification of the audit configuration of the Kubernetes API server. The audit logging service does not support processing Kubernetes audit records.

Configuring the policy controller for Audit logging version 3.8.0

Configuring the audit policy controller by using the Red Hat® OpenShift® Container Platform console

To deploy the audit policy controller, policyController.enabled must be set to true in the AuditLogging CR. If the policyController.enabled field is omitted, the audit policy controller is deployed by default. To disable the audit policy controller, set policyController.enabled to false.

Complete the following steps to configure the audit policy controller from the Red Hat® OpenShift® Container Platform console.

1. From the Red Hat® OpenShift® Container Platform navigation menu, click Operators > Installed Operators.
2. From the Project field menu, select ibm-common-services.
3. Select the ibm-auditlogging-operator.
4. Select AuditLogging
5. Set policyController.enabled: true
6. To set the level of log output, add field, policyController.verbosity: log-level. The log level ranges from debug-level (0-4) to trace-level (5-10). Default log level is 0.
7. To set the status update frequency (in seconds) of an audit policy, add field, policyController.frequency: number-of-seconds. Default update frequency is 10.

Configuring the policy controller for Audit logging version 3.7.0

Configure levels of log output and the status update frequency for audit policies in one of the following ways.

• Configuring the audit policy controller by using the Red Hat® OpenShift® Container Platform console
• Configuring the audit policy controller by using the command-line interface (CLI)

Configuring the audit policy controller by using the Red Hat® OpenShift® Container Platform console

Complete the following steps to configure the audit policy controller from the Red Hat® OpenShift® Container Platform console.

1. From the Red Hat® OpenShift® Container Platform navigation menu, click Operators > Installed Operators.
2. From the Project field menu, select ibm-common-services.
3. Select the ibm-auditlogging-operator.
4. Select the YAML tab.
5. Scroll down to the containers spec.
6. To set the level of log output, add the argument --v=<log-level> to the audit-policy-controller container arguments list. The log level ranges from debug-level (0-4) to trace-level (5-10). Default log level is 0.
7. To set the status update frequency (in seconds) of an audit policy, add the argument --update-frequency=<number-of-seconds> to the audit-policy-controller container arguments list. Default update frequency is 10.

The audit-policy-controller container arguments list resembles the following code:

   name: audit-policy-controller
   args:
           - '--v=0'
           - '--update-frequency=10'

Configuring the audit policy controller by using the command-line interface (CLI)

Complete the following steps to configure the audit policy controller from the command-line interface (CLI).

1. Update and run the following command with the wanted <log level> and <update frequency> for your 3.7.z version of the Audit logging operator:

   kubectl patch csv ibm-auditlogging-operator.v3.7.z --namespace ibm-common-services --type='json' -p='[{"op": "replace", "path":  "/spec/install/spec/deployments/0/spec/template/spec/containers/1/args", "value":[--v=<log-level>,--update-frequency=<number-of- seconds>]}]'
   

2. Verify that args were applied.

   kubectl get deployment ibm-auditlogging-operator --namespace ibm-common-services -o=json | jq '.spec.template.spec.containers[1].args'
   

Audit logging policy

Each service runs as a container. The audit logging policy contains the list of containers for which audit logging compliance needs to be checked. The policy can include any service that runs in your cluster. You can configure the logging level for each service.

Note: Ensure that each audit policy has a unique name.

Following is a sample audit policy definition:

apiVersion: audit.policies.ibm.com/v1alpha1
kind: AuditPolicy # Verify if audit is enabled
metadata:
  name: iam-audit-policy-example
  label:
    category: "System-Integrity"
spec:
  severity: low
  namespaceSelector:
    include: ["ibm-common-services"]
    exclude: []
  clusterAuditPolicy:
    auditPolicyRules:
      "kubernetes": ignore
      "platform-api": validate
      "helmapi": validate
      "platform-identity-manager": validate
      "platform-identity-provider": validate
      "vulnerability-advisor": validate
  remediationAction: inform # enforce or inform
  disabled: false

Note: kubernetes is the container name of the Kubernetes API server.

Audit logging policy elements

In the namespaceSelector.include section, you can specify the namespaces that the controller must watch. Use the namespaceSelector.exclude section to specify the namespaces that the controller must ignore.

In the auditPolicyRules section, you must add the container names of the services for which logging compliance must be checked. Add "<container-name>": [validate|ignore] for each container. You can set the following logging level by using the remediationAction parameter:

• Set to enforce to fix the gap as reported by the compliance check.

• Set to inform only to report whether the services are compliant or not.

  When you set the auditPolicyRules for a service as validate, and you set the remediationAction as enforce, the controller checks the AUDIT_ENABLED parameter value that is set in the configmap of the container. If the parameter value is set to true, the controller reports the service as compliant. If the parameter value is set to false, the controller reports the service as non-compliant and updates the parameter value to true in the configmap. However, the updated value reflects in the container only after the container restarts. The controller does not restart the container after it updates the parameter value.

  Note: For the kubernetes service, the enforce option has no effect. Even if remediationAction: enforce is set, the controller reports only the compliance status, and does not fix the gap in compliance.

Note: For Kubernetes API server, the controller checks the audit-policy-file flag to verify compliance.

Creating an audit logging policy

You can create a YAML file for your audit logging policy.

Complete the following steps to create an audit logging policy from the command-line interface (CLI):

1. Create a YAML file with the audit logging policy definition. See Audit policy.

2. Apply the policy by running the following command:

   kubectl apply -f <audit-logging-policy-file-name>  --namespace=<ibm-common-services>
   

3. Verify and list the policy by running the following command:

   kubectl get <audit-logging-policy-file-name> --namespace=<ibm-common-services>
   

Getting the container names

To get the container names, run the following command. You need kubectl to run the command. For more information about installing kubectl, see Installing the Kubernetes CLI (kubectl).

  kubectl get pods -n <namespace> -o json | jq '.items[].spec.containers[].name' | grep -v null | sort | uniq

Following is a sample output from the ibm-common-services namespace:

"catalog-ui"
"grafeas"
"hcm-ui"
"hcm-ui-api"
"helmapi"
"helm-repo"
"image-manager"
"platform-api"
"platform-auth-service"
"platform-header"
"platform-identity-manager"
"platform-identity-provider"
"platform-ui