IBM Multicloud Manager security findings

Use IBM® Cloud Security Advisor (SA) to manage your cluster security findings.

IBM Cloud Security Advisor (SA) is a security dashboard to manage any application and system security findings in your IBM Cloud Private cluster. SA displays any security alerts or vulnerabilities in your cluster as Security findings on the Governance and risk page of the IBM Multicloud Manager console.

View the descriptions of the following core microservices from SA in IBM Multicloud Manager:

Grafeas: A microservice that implements the Grafeas standard and specification. Grafeas is used to track and govern software resources using metadata called notes. For example, occurrences are descriptions of when and where the note is identified on your cluster.
Legato: A microservice that provides GraphQL query access to the security findings data.
Findings API: A microservice that uses Grafeas and Legato to provide a standard API for managing security findings.

For more information about SA, see About Security Advisor in the IBM Cloud documentation.

View the descriptions of the three data sources that comprise the Security Advisor:

Policy adapter creates security findings for non-compliant policies.
The Vulnerability Advisor (VA) runs security checks on running containers in your environment. It is installed on managed clusters. Mutation Advisor (MA) is installed when you install VA. MA creates security findings for process and file mutations.
Security Advisor API can be used to create, update, query and delete security findings.

Security findings

Security findings in SA is called an occurrence. Security Advisor uses the policy-adapter microservice on the hub cluster to report non-compliant policies to the SA. An occurrence is created for each policy that is non-compliant on any managed cluster. An SA occurrence created by the policy adapter might resemble the following example:

   {
      "author": {
        "account_id": "ServiceId-4294102b-f0c6-4b47-8215-a748bba6fc85",
        "email": "icp@ibm.com",
        "id": "iam-ServiceId-4294102b-f0c6-4b47-8215-a748bba6fc85",
        "kind": "service-id"
      },
      "context": {
        "account_id": "id-mycluster-account",
        "cluster_name": "clusterhub",
        "namespace_name": "Excludes: [kube-*], Includes: [default]",
        "region": "clusterhub",
        "resource_id": "777f5cb2-c360-11e9-bb07-005056a0c35d",
        "resource_name": "cert-expiration",
        "resource_type": "Policy",
        "service_name": "security-advisor"
      },
      "create_time": "2019-08-20T17:32:09.633473Z",
      "create_timestamp": 1566322329633,
      "finding": {
        "next_steps": [
          {
            "title": "View the details for the compliance problem in the occurrence of the findings."
          }
        ],
        "severity": "HIGH"
      },
      "id": "clusterhub-policy-777f5cb2-c360-11e9-bb07-005056a0c35d",
      "insertion_timestamp": 1566322329634,
      "kind": "FINDING",
      "long_description": "MCM Policy that is not compliant",
      "name": "id-mycluster-account/providers/security-advisor/occurrences/clusterhub-policy-777f5cb2-c360-11e9-bb07-005056a0c35d",
      "note_name": "id-mycluster-account/providers/security-advisor/notes/policy-not-compliant",
      "provider_id": "security-advisor",
      "provider_name": "id-mycluster-account/providers/security-advisor",
      "remediation": "NonCompliant; Non-compliant certificates (expires in less than 50h0m0s) in kube-system[1]: [test-policy-cert, test-policy-cert-secret]",
      "reported_by": {
        "id": "mcm-policy-adapter",
        "title": "Security Advisor MCM Policy Findings Adapter"
      },
      "security_classification": {
        "security_categories": [
          "SystemAndCommunicationsProtections"
        ],
        "security_control": "CertManager",
        "security_standards": [
          "PCI"
        ]
      },
      "short_description": "Policy that is not compliant",
      "update_time": "2019-08-20T17:32:09.633506Z",
      "update_timestamp": 1566322329634,
      "update_week_date": "2019-W34-2"
    }

Security findings data retention policy

Required access: At least Operator

Use the security findings data retention policy to manage data size from your findings. By default, all of the security findings are retained in MongoDB in 90 days.

Note: You must install IBM Multicloud Manager hub-chart. For more information, see Configuring IBM Multicloud Manager during installation.

Modifying your security findings data retention policy from the console

Complete the following steps to modify your security findings data retention policy:

Log in to the IBM Multicloud Manager console.
From the navigation menu, select Local Cluster > Manage Local Cluster from the navigation menu.
From the navigation menu, click Configuration > ConfigMaps.
Find the <mcm-chart-release-name>-findingsapi-configuration in the list of configuration maps.
Click the Options icon () and select Edit. The Edit ConfigMap dialog box appears.
Set the FINDINGS_OCCURRENCES_RETENTION_DAYS parameter value to the wanted number of days. For example, set the retention days to 180 days. Your retention policy might resemble the following content:
```
 "FINDINGS_OCCURRENCES_RETENTION_DAYS": "180"
```
Set the DELETE_ALL_FINDINGS_OCCURRENCES_BY_PROVIDERS parameter value to the target providers. For example, to delete the security findings for the mutation-advisor and security-advisor providers, your retention policy might resemble the following content:
```
 "DELETE_ALL_FINDINGS_OCCURRENCES_BY_PROVIDERS": "mutation-advisor, security-advisor"
```
Click Submit to save the changes.

Your security findings retention policy is successfully updated. Learn how to view your security findings from the console. For more information, see the Viewing security findings section on the Managing a security policy page.

Security Advisor API

Before you run Security Advisor API commands, retrieve the authentication token and download the CA certificate for your cluster. For more information, see Preparing to run component or management API commands. Complete the following steps to access the SA API:

Access the SA API by providing the ID token and access token, the following sample command shows how to specify both tokens:

curl -k --request GET  --url "https://<Cluster Master Host>:<Cluster Master API Port>/findings/v1/id-mycluster-account/providers/security-advisor/occurrences" --header 'accept: application/json' --header "Authorization: Bearer $ID_TOKEN" --header "AccessToken: $ACCESS_TOKEN"

To access the SA API with an API key, provide only the ID token for authorization. Run the following command to obtain the token from an API key:
```
curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$API_KEY&response_type=cloud_iam" https://<Cluster Master Host>:<Cluster Master API Port>/iam-token/oidc/token
```
- The following sample command shows how to specify the token that is obtained from the API key to make API requests to the Security Advisor. The ID_TOKEN is the value returned as the access_token from the previous command:
```
curl -k --request GET  --url "https://<Cluster Master Host>:<Cluster Master API Port>/findings/v1/id-mycluster-account/providers/security-advisor/occurrences" --header 'accept: application/json' --header "Authorization: Bearer $ID_TOKEN"
```
Notes:
- You can replace the -k option in the curl commands with --cacert <downloaded CA cert file> to create a secure connection.
- You are unable to modify the id-mycluster-account value. It is the account ID that the security finding is associated with.

You can access the SA API. For more information, see Security findings API.

Security Advisor RBAC

Security Advisor supports role-based access control for SA APIs. View the following access control table:

Access control	Role	Description
security-advisor.metadata.write	Operator	Create SA metadata
security-advisor.metadata.read	Viewer	Query and read SA metadata
security-advisor.findings.read	Viewer	Query and read SA findings
security-advisor.metadata.delete	Operator	Delete SA metadata
security-advisor.findings.delete	Operator	Delete SA findings
security-advisor.findings.write	Editor	Create SA findings
security-advisor.findings.update	Editor	Update SA findings
security-advisor.metadata.update	Operator	Update SA metadata

Third-party data providers

Third-party providers must have access control to the Security Advisor services. See the following descriptions of the SA Grafeas services:

grafeas-admin-service-id: Create, update, view, and delete notes and occurrences with the admin service. You can create metadata and use the pruning microservice with the admin service.
grafeas-internal-service-id: Create, update, and view occurrences with the internal service for internal communications between services. You can only view notes with the internal service.
grafeas-external-service-id: Create, view, and update occurrences with the external service. You can only view notes with the external service. Use the external service to allow communication between third-party providers and the SA.
grafeas-viewer-service-id: View notes and occurrences with the viewer service. Use the viewer service to allow third-party data consumers to have access to the SA.

IAM access control policies exist on each of the SA Grafeas service IDs. Any API keys created are limited to only the functions described previously.

See IBM Multicloud Manager Governance and risk for more policy topics.