Create custom policies

Learn how to implement custom security policies for your environment.

4 minute read

In addition to using the default out-of-box policies, you can also create custom policies in the StackRox Kubernetes Security Platform.

To build a new policy, you can clone an existing policy, or create a new one from scratch. If you are using the StackRox Kubernetes Security Platform version 3.0.45 and newer:

Create policy from System policies view

To create a new policy:

  1. Navigate to Platform Configuration > System policies.

  2. Select + New Policy below the filter box on the top right side.

  3. Turn off the Enable Policy toggle if you want to create a policy but enable it later.

  4. Fill in the following details about your policy in the Policy Details section:

    • Enter a Name for the policy.

    • Select a Severity level for this policy, either Critical, High, Medium, or Low.

    • Choose Lifecycle Stages to which your policy is applicable, from Build, Deploy, or Runtime. You can select more than one stage.

      • Build-time policies apply to image fields such as CVEs and Dockerfile instructions.
      • Deploy-time policies can include all build-time policy criteria but they can also include data from your cluster configurations, such as running in privileged mode or mounting the Docker socket.
      • Runtime policies can include all build-time and deploy-time policy criteria but they can also include data about process executions during runtime.
    • Enter details about the policy in the Policy Description box.

    • Enter an explanation about why the policy exists in the Rationale box.

    • Enter steps to resolve violations of this policy in the Remediation box.

    • Select policy Categories you want to apply to this policy.

    • Select Notifications channels to forward StackRox alert notifications when a violation occurs for this policy.

      You must integrate the StackRox Kubernetes Security Platform with your notification provider (for example webhooks, Jira, or PagerDuty) before you can use this feature.

    • Use Restrict to Scope to enable this policy only for a specific cluster, namespace, or label. You can add multiple scopes and also use regular expressions (RE2 Syntax) for namespaces and labels.

    • Use Exclude by Scope to exclude deployments, clusters, namespaces, and labels you specify, it means that the policy won’t apply to the entities you select. You can add multiple scopes and also use regular expressions (RE2 Syntax) for namespaces and labels. However, you can’t use regular expressions for selecting deployments.

    • For Excluded Images (Build Lifecycle only) select all images from the list for which you don’t want to trigger a violation for the policy.

      The Excluded Images setting only applies when you check images in a continuous integration system (the Build lifecycle stage). It won’t have any effect if you use this policy to check running deployments (the Deploy lifecycle stage) or runtime activities (the Runtime lifecycle stage).

  5. In the Policy Criteria section, configure the attributes on which you want to trigger the policy. See the Policy criteria section for more details.

    If you are using the StackRox Kubernetes Security Platform version 3.0.45 or newer:

  6. Select Next on the panel header.

  7. The new policy panel shows a preview of the violations that get triggered if you enable the policy.

    Policy preview
    Policy preview

  8. Select Next on the panel header.

  9. Choose the enforcement behavior for the policy. It’s only available for the stages you select when configuring Lifecycle Stages. Select ON (enable) to enforce policy and report a violation, and OFF (disable) to only report a violation.

    Policy enforcement options
    Policy enforcement options

    The enforcement behavior is different for each lifecycle stage.

    • Build - The StackRox Kubernetes Security Platform fails your continuous integration (CI) builds when images match the conditions of the policy.
    • Deploy - The StackRox Kubernetes Security Platform blocks creation of deployments that match the conditions of the policy. In clusters with admission controller enforcement, the Kubernetes (or OpenShift) API server blocks all noncompliant deployments. In other clusters, the StackRox Kubernetes Security Platform edits noncompliant deployments to prevent pods from being scheduled.
    • Runtime - The StackRox Kubernetes Security Platform kills all pods that match the conditions of the policy.

    Policy enforcement can impact running applications or development processes. Before you enable enforcement options, be sure to inform all stakeholders and plan about how to respond to automated enforcement actions.

Create policy from Risk view

While evaluating risks in your deployments in the Risk view, when you apply local page filtering, you can create new security policies based on the filtering criteria you are using.

To create security policies from the Risk view, you need the StackRox Kubernetes Security Platform version 3.0.45 or newer.

To create a new policy from the Risk view:

  1. Select Risk from the left-hand navigation menu.
  2. Apply local page filtering criteria for which you want to create a policy.
  3. Select New Policy and fill in the required fields to create a new policy. For more information about the required and other policy fields, see the Create policy from System policies view section.

Based on the filtering criteria you apply, not all criteria are directly applied to the new policy. The StackRox Kubernetes Security Platform:

  1. Converts the Cluster, Namespace, and Deployment filters to equivalent policy scopes.

    • When you use local page filtering on the Risk View:
      • it combines the search terms within the same category with an OR operator. For example, if the search query is Cluster:A,B, the filter matches deployments in cluster A or cluster B.
      • it combines the search terms from different categories with an AND operator. For example, if the search query is Cluster:A+Namespace:Z, the filter matches deployments in cluster A and in namespace Z.
    • When you add multiple scopes to a policy, the policy matches violations from any of the scopes.
    • For example, if you search for (Cluster A OR Cluster B) AND (Namespace Z) it results in two policy scopes, (Cluster=A AND Namespace=Z) OR (Cluster=B AND Namespace=Z).
  2. Drops or modifies filters that don’t directly map to policy criteria. The StackRox Kubernetes Security Platform reports the dropped filters. The following table lists how the filtering search attributes maps to the policy criteria:

    Search attributePolicy criteria
    Add CapabilitiesAdd Capabilities
    AnnotationDisallowed Annotation
    CPU Cores LimitContainer CPU Limit
    CPU Cores RequestContainer CPU Request
    CVECVE
    CVE Published On✕ Dropped
    CVE Snoozed✕ Dropped
    CVSSCVSS
    Cluster→ Converted to scope
    ComponentImage Component (name)
    Component VersionImage Component (version)
    Deployment→ Converted to scope
    Deployment Type✕ Dropped
    Dockerfile Instruction KeywordDockerfile Line (key)
    Dockerfile Instruction ValueDockerfile Line (value)
    Drop Capabilities✕ Dropped
    Environment KeyEnvironment Variable (key)
    Environment ValueEnvironment Variable (value)
    Environment Variable SourceEnvironment Variable (source)
    Exposed Node Port✕ Dropped
    Exposing Service✕ Dropped
    Exposing Service Port✕ Dropped
    Exposure LevelPort Exposure
    External Hostname✕ Dropped
    External IP✕ Dropped
    Image✕ Dropped
    Image Command✕ Dropped
    Image Created TimeDays since image was created
    Image Entrypoint✕ Dropped
    Image LabelDisallowed Image Label
    Image OSImage OS
    Image Pull Secret✕ Dropped
    Image RegistryImage Registry
    Image RemoteImage Remote
    Image Scan TimeDays since image was last scanned
    Image TagImage Tag
    Image Top CVSS✕ Dropped
    Image User✕ Dropped
    Image Volumes✕ Dropped
    Label→ Converted to scope
    Max Exposure Level✕ Dropped
    Memory Limit (MB)Container Memory Limit
    Memory Request (MB)Container Memory Request
    Namespace→ Converted to scope
    Namespace ID✕ Dropped
    Pod Label✕ Dropped
    PortPort
    Port ProtocolProtocol
    Priority✕ Dropped
    PrivilegedPrivileged
    Process AncestorProcess Ancestor
    Process ArgumentsProcess Arguments
    Process NameProcess Name
    Process Path✕ Dropped
    Process Tag✕ Dropped
    Process UIDProcess UID
    Read Only Root FilesystemRead-Only Root Filesystem
    Secret✕ Dropped
    Secret Path✕ Dropped
    Service Account✕ Dropped
    Service Account Permission LevelMinimum RBAC Permission Level
    Toleration Key✕ Dropped
    Toleration Value✕ Dropped
    Volume DestinationVolume Destination
    Volume NameVolume Name
    Volume ReadOnlyWritable Volume
    Volume SourceVolume Source
    Volume TypeVolume Type

Policy criteria

In the Policy Criteria section you can configure the data on which you want to trigger a policy.

You can configure the policy based on the attributes listed in the following table.

To use logical operators (AND, OR, and NOT) for creating security policies, you need the StackRox Kubernetes Security Platform version 3.0.45 or newer. However, on earlier versions you can still use regular expressions for the fields listed in the Regular expressions column.

  • The Regular expressions, AND, OR, and NOT column indicates whether you can use regular expressions and other logical operators along with the specific attribute. ! in the Regular expressions column indicates that you can only use regular expressions for the listed fields.
  • You can’t use logical combination operators (AND, OR) for attributes which have:
    • Boolean values (true and false)
    • Minimum-value semantics, for example:
      • Minimum RBAC permissions
      • Days since image was created
  • You can’t use the NOT logical operator for attributes which have:
    • Boolean values (true and false)
    • Numeric values that already use comparison (<, >, <=, >=) operators.
    • Compound criteria that can have multiple values, for example:
      • Dockerfile Line, which includes both instructions and arguments.
      • Environment Variable, which consists of both name and value.
    • Other meanings, including Add Capabilities, Drop Capabilities, Days since image was created, and Days since image was last scanned.
AttributeDescriptionRegular expressionsNOTAND, ORPhase
NamespaceThe name of the namespace. The Namespace policy criteria only works when you are using the StackRox Kubernetes Security Platform version 3.0.51 or newer.Deploy
Image RegistryThe name of the image registry.Deploy
Image RemoteThe full name of the image in registry, for example library/nginx.Deploy
Image TagIdentifier for an image.Deploy
Days since image was createdThe number of days from image creation date.Build
Days since image was last scannedThe number of days since the last image scan.Build
Dockerfile LineA specific line in the Dockerfile, including both instructions and arguments.! (for values)Build
Image is NOT ScannedNo scan data is available for the image.Build
CVSSCommon Vulnerability Scoring System, use it to match images with vulnerabilities whose scores are greater than (>), less than (<), or equal to (=) the specified CVSS.Build
Fixed ByThe version string of a package that fixes a flagged vulnerability in an image.Build
CVECommon Vulnerabilities and Exposures, use it with specific CVE numbers.Build
Image ComponentName and version number of a specific software component present in an image.Build
Image OSName and version number of the base operating system of the image. The Image OS policy criteria only works when you are using the StackRox Kubernetes Security Platform version 3.0.47 or newer.Build
Environment VariableCheck environment variables by name or value.! (for key and value)Deploy
Disallowed AnnotationAn annotation which is not allowed to be present on Kubernetes resources in a specified environment.Deploy
Disallowed Image LabelCheck for the presence of a Docker image label that shouldn’t be in use. The policy triggers if any image in the deployment has the specified label. You can use regular expressions (for both key and value fields) to match labels. The Disallowed Image Label policy criteria only works when you are using the StackRox Kubernetes Security Platform version 3.0.40 or newer and integrate with a Docker registry.Deploy
Required Image LabelCheck for the presence of a required Docker image label. The policy triggers if any image in the deployment doesn’t have the specified label. You can use regular expressions (for both key and value fields) to match labels. The Required Image Label policy criteria only works when you are using the StackRox Kubernetes Security Platform version 3.0.40 or newer and integrate with a Docker registry.Deploy
Required LabelCheck for the presence of a required label in Kubernetes.Deploy
Required AnnotationCheck for the presence of a required annotation in Kubernetes.Deploy
Volume NameName of the storage.Deploy
Volume SourceIndicates the form in which the volume is provisioned (for example, persistentVolumeClaim or hostPath).Deploy
Volume DestinationThe path where the volume is mounted.Deploy
Volume TypeThe type of volume.Deploy
Writable VolumeVolumes that are mounted as writable.Deploy
ProtocolProtocol (such as TCP or UDP) used by exposed port.Deploy
PortPort numbers exposed by a deployment.Deploy
PrivilegedPrivileged running deployments.Deploy
Read-Only Root FilesystemContainers running with the root filesystem configured as read only.Deploy
Drop CapabilitiesLinux capabilities that must be dropped from the container. For example CAP_SETUID or CAP_NET_RAW.Deploy
Add CapabilitiesLinux capabilities that must not be added to the container, for instance the ability to send raw packets or override file permissions.Deploy
Process NameName of the process executed in a deployment.Runtime
Process AncestorName of any parent process for a process executed in a deployment.Runtime
Process ArgumentsCommand arguments for a process executed in a deployment.Runtime
Process UIDUnix user ID for a process executed in a deployment.Runtime
Port ExposureExposure method of the service, for example, LoadBalancer or NodePort.Deploy
Service AccountThe name of the service account.Deploy
Writable Host MountResource has mounted a path on the host with write permissions.Deploy
Unexpected Process ExecutedCheck deployments for which process executions are not listed in the deployment’s locked process baseline.Runtime
Minimum RBAC PermissionsMatch if the deployment’s Kubernetes service account has Kubernetes RBAC permission level equal to (=) or greater than (>) the specified level.Deploy
Container NameThe name of the container. The Container Name policy criteria only works when you are using the StackRox Kubernetes Security Platform version 3.0.52 or newer.Deploy
Container CPU RequestCheck for the number of cores reserved for a given resource.Deploy
Container CPU LimitCheck for the maximum number of cores a resource is allowed to use.Deploy
Container Memory RequestCheck for the amount of memory reserved for a given resource.Deploy
Container Memory LimitCheck for the maximum amount of memory a resource is allowed to use.Deploy
Kubernetes ActionThe name of the Kubernetes action, such as Pod Exec. The Kubernetes Action policy criteria only works when you are using the StackRox Kubernetes Security Platform version 3.0.55 or newer.✓ (OR only)Runtime

If you are using the StackRox Kubernetes Security Platform version 3.0.44 or older, the policy criteria you specify in the Policy criteria section are “AND”ed. It means that the violation only triggers if all the specified policy criteria match.

Add logical conditions

If you are using the StackRox Kubernetes Security Platform version 3.0.45 or newer, you can use the new drag-and-drop policy fields panel to specify logical conditions for the policy criteria:

  1. In the Policy Criteria section, select Add a new condition to add a new policy section.

    • You can select the Edit icon to rename the policy section.
    • The Drag out a policy field section lists available policy criteria in multiple categories. You can expand and collapse these categories to view the policy criteria attributes.
  2. Drag an attribute to the Drop a policy field inside area of the policy section.

  3. Depending on the type of the attribute you select, you get different options to configure the conditions for the selected attribute.

    boolean configuration

    For example:

    • if you select an attribute with Boolean values Read-Only Root Filesystem, you’ll see READ-ONLY and WRITABLE options.
    • if you select an attribute with compound values Environment variable, you’ll see options to enter values for Key, Value, and Value From fields, and an icon to add more values for the available options.
    1. To combine multiple values for an attribute, select the Add icon.
    2. You can also select the logical operator AND (or OR) listed in a policy section, to toggle between AND and OR operators. Toggling between operators only works inside a policy section and not between two different policy sections.
  4. You can specify more than one AND and OR condition by repeating these steps. After you configure the conditions for the added attributes, select Next to continue with the policy creation.

Questions?

We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.