kubescape/docs/proposals/container-image-vulnerability-adaptor.md

Container image vulnerability adaptor interface proposal

Rationale

source #287

Big picture

• Kubescape team is planning to create controls which take into account image vulnerabilities, for example: looking for public internet facing workloads with critical vulnerabilities. These are seriously affecting the security health of a cluster and therefore we think it is important to cover it. We think that most container registries are/will support image scanning like Harbor and therefore, the ability to get information from them is important.
• There is information in the image repository which is important for the existing controls as well. They are incomplete without it, this example sees this issue: Non-root containers check is broken #19. These are not necessarily image vulnerability related. These can be information in the image manifest (like the issue before), but it can also be the image BOM related.

Relation to this proposal

Multiple changes and design decisions need to be made before Kubescape will support the above outlined controls. However, a focal point in the whole picture is the ability to access vulnerability of databases of container images. We anticipate that most container image repositories will support image vulnerability scanning, like some major players already do. Since there is no single API available which all of these data sources support, it is important to create an adaption layer within Kubescape so that different data sources can serve Kubescape's goals.

High level design of Kubescape

Layers

• Controls and Rules: That actual control logic implementation, the "tests" themselves. Implemented in rego
• OPA engine: the OPA rego interpreter
• Rules processor: Kubescape component, it enumerates and runs the controls while also preparing all the input data that the controls need for running
• Data sources: Set of different modules providing data to the Rules processor so that it can run the controls with them. Examples: Kubernetes objects, cloud vendor API objects and adding the vulnerability information in this proposal
• Cloud Image Vulnerability adaption interface: The subject of this proposal, it gives a common interface for different registry/vulnerability vendors to adapt to.
• CIV adaptors: Specific implementation of the CIV interface, for example Harbor adaption

 -----------------------
| Controls/Rules (rego) |
 -----------------------
            |
 -----------------------
|      OPA engine       |
 -----------------------
            |
 -----------------------
|    Rules processor    |
 ----------------------- 
            |
 -----------------------
|     Data sources      |
 -----------------------              
            |
 =======================
| CIV adaption interface|    <- Adding this layer in this proposal
 ======================= 
            |
 -----------------------
| Specific CIV adaptors |    <- will be implemented based on this proposal
 -----------------------      

        

Functionalities to cover

The interface needs to cover the following functionalities:

• Authentication against the information source (abstracted login)
• Triggering image scan (if applicable, the source might store vulnerabilities for images but cannot scan alone)
• Reading image scan status (with last scan date and etc.)
• Getting vulnerability information for a given image
• Getting image information
  • Image manifests
  • Image BOMs (Bill Of Material)

Go API proposal

/*type ContainerImageRegistryCredentials struct {
	   map[string]string
	Password string
	Tag        string
	Hash       string
}*/

type ContainerImageIdentifier struct {
	Registry   string
	Repository string
	Tag        string
	Hash       string
}

type ContainerImageScanStatus struct {
	ImageID         ContainerImageIdentifier
	IsScanAvailable bool
	IsBomAvailable  bool
	LastScanDate    time.Time
}

type ContainerImageVulnerabilityReport struct {
	ImageID ContainerImageIdentifier
	// TBD
}

type ContainerImageInformation struct {
	ImageID       ContainerImageIdentifier
	Bom           []string
	ImageManifest Manifest // will use here Docker package definition
}

type IContainerImageVulnerabilityAdaptor interface {
	// Credentials are coming from user input (CLI or configuration file) and they are abstracted at string to string map level
	// so an example use would be like registry: "simpledockerregistry:80" and credentials like {"username":"joedoe","password":"abcd1234"}
	Login(registry string, credentials map[string]string) error

	// For "help" purposes
	DescribeAdaptor() string

	GetImagesScanStatus(imageIDs []ContainerImageIdentifier) ([]ContainerImageScanStatus, error)

	GetImagesVulnerabilties(imageIDs []ContainerImageIdentifier) ([]ContainerImageVulnerabilityReport, error)

	GetImagesInformation(imageIDs []ContainerImageIdentifier) ([]ContainerImageInformation, error)
}

Integration

Input

The objects received from the interface will be converted to an Imetadata compatible objects as following

{
    "apiVersion": "image.vulnscan.com/v1",
    "kind": "VulnScan",
    "metadata": {
        "name": "nginx:latest"
    },
    "data": {
        // returned by the adaptor API (structure like our backend gives for an image)
    }
}

Output

The rego results will be a combination of the k8s artifact and the list of relevant CVEs for the control

{
    "apiVersion": "result.vulnscan.com/v1",
    "kind": "Pod",
    "metadata": {
        "name": "nginx"
    },
    "relatedObjects": [
        {
            "apiVersion": "v1",
            "kind": "Pod",
            "metadata": {
                "name": "nginx"
            },
            "spec": {
                // podSpec
            },
        },
        {
            "apiVersion": "container.vulnscan.com/v1",
            "kind": "VulnScan",
            "metadata": {
                "name": "nginx:latest",
            },
            "data": {
                
                // returned by the adaptor API (structure like our backend gives for an image)  
            }
        }
    ]
}