Kubescape Rule Library

Kubescape's CEL (Common Expression Language) runtime threat detection rules library. This repository contains a collection of security rules that can be used for runtime threat detection in Kubernetes environments.

Overview

The rule library provides a structured way to define security rules using YAML format. Each rule is defined as a Custom Resource Definition (CRD) instance that can be deployed to Kubernetes clusters for runtime threat detection.

Rule Format

Each rule is defined in a YAML file with the following structure:

apiVersion: kubescape.io/v1
kind: Rules
metadata:
  name: rule-name-rule
  namespace: kubescape
  labels:
    app: kubescape
spec:
  rules:
    - name: "Rule Display Name"
      enabled: true
      id: "R####"
      description: "Description of what the rule detects"
      expressions:
        message: "CEL expression for alert message"
        uniqueId: "CEL expression for unique identifier"
        ruleExpression:
          - eventType: "eventType_name"
            expression: "CEL expression for detection logic"
      profileDependency: 0  # 0=Required, 1=Optional, 2=NotRequired
      severity: 1
      supportPolicy: false
      tags:
        - "tag1"
        - "tag2"

Rule Fields

Field	Type	Description	Required
name	string	Human-readable rule name	Yes
enabled	boolean	Whether the rule is active	Yes
id	string	Unique rule identifier (format: R####)	Yes
description	string	Detailed description of the rule	Yes
expressions.message	string	CEL expression for alert message	Yes
expressions.uniqueId	string	CEL expression for unique event ID	Yes
expressions.ruleExpression	array	Array of detection expressions	Yes
profileDependency	integer	Profile dependency level (0,1,2)	Yes
severity	integer	Rule severity level	Yes
supportPolicy	boolean	Whether rule supported by rule policy	Yes
tags	array	Array of tags for categorization	Yes
state	object	Rule state	No

Supported Event Types

• exec - Process execution events
• open - File access events
• capabilities - Linux capability events
• dns - DNS query events
• network - Network connection events
• syscall - System call events
• randomx - XMRig mining events
• symlink - Symbolic link events
• hardlink - Hard link events
• ssh - SSH connection events
• http - HTTP request events
• ptrace - Process tracing events
• iouring - IO_uring events
• fork - Process fork events
• exit - Process exit events
• procfs - Proc filesystem events

Writing Rules

1. Create Rule Directory

Create a new directory in pkg/rules/ with the naming convention:

r####-descriptive-name/

Example:

pkg/rules/r0001-unexpected-process-launched/

2. Create Rule YAML File

Create a YAML file in your rule directory with the rule definition (see example unexpected-process-launched.yaml)

3. Add Test Cases

Create a rule_test.go file in your rule directory (see example rule_test.go)

4. Test Your Rule

Run the tests to ensure your rule works correctly:

go test -v ./pkg/rules/r0001-unexpected-process-launched/

Rule Generation Script

The gen.sh script automatically combines all individual rule YAML files into a single CRD instance. The recommended entrypoint is the Make target below, which wraps the script.

Usage

make generate-rules-crd

What it does

1. Scans the pkg/rules/ directory for all YAML files
2. Combines all individual rule definitions into a single Rule instance
3. Generates rules-crd.yaml with all rules in the spec array
4. Validates the generated YAML (if yq is available)

Output

The script generates rules-crd.yaml containing:

apiVersion: kubescape.io/v1
kind: Rules
metadata:
  name: kubescape-rules
  namespace: kubescape
  labels:
    app: kubescape
spec:
  rules:
    - name: "Rule 1"
      # ... rule 1 definition
    - name: "Rule 2"
      # ... rule 2 definition
    # ... all other rules

Prerequisites

• bash shell
• yq (optional, for YAML validation)

Development Workflow

1. Create a new rule following the directory structure and naming conventions
2. Write the rule YAML with proper CEL expressions
3. Add comprehensive tests in rule_test.go
4. Test your rule with go test -v ./pkg/rules/your-rule/
5. Generate the combined CRD with make generate-rules-crd
6. Deploy the generated rules-crd.yaml to your Kubernetes cluster

Testing

Run all tests

go test -v ./pkg/rules/...

Run specific rule tests

go test -v ./pkg/rules/r0001-unexpected-process-launched/

Test the generation script

make generate-rules-crd
# Check the generated rules-crd.yaml file

CEL Expressions

Rules use Common Expression Language (CEL) for expressions. Key concepts:

Message Expression

Defines the alert message format:

"'Unexpected process launched: ' + event.Comm + ' with PID ' + string(event.Pid)"

Unique ID Expression

Creates a unique identifier for deduplication:

"event.Comm + '_' + string(event.Pid) + '_' + event.ExePath"

Rule Expression

Defines the detection logic:

"!data.profile_checks.exec_path"

Best Practices

1. Use descriptive names for rules and directories
2. Follow the ID numbering convention (R####)
3. Write comprehensive tests for each rule
4. Use appropriate tags for categorization
5. Set correct severity levels based on impact
6. Document complex CEL expressions with comments
7. Test both positive and negative scenarios
8. Validate generated YAML before deployment

Declaring profileDataRequired

When a rule's profileDependency is Required (0) or Optional (1), it must declare profileDataRequired listing which profile surfaces the rule queries at runtime. Look at every CEL guard that passes an event field to a profile helper (ap.* / nn.*) and translate the argument into a pattern under the correct surface key:

Event field	Surface key
event.path / event.exepath (open events)	opens
event.path / event.exepath (exec events)	execs
event.syscallName	syscalls
event.capName	capabilities
event.name (DNS)	egressDomains
event.dstAddr / event.dstIp (network)	egressAddresses
event.endpoint (HTTP)	endpoints

Guard operator	Pattern type
==	exact
.startsWith(...)	prefix
.endsWith(...)	suffix
.contains(...)	contains

If the helper receives a fully dynamic argument with no co-located literal guard, declare the surface as all.

Example:

profileDependency: 0
profileDataRequired:
  opens:
    - exact: "/var/run/docker.sock"
    - prefix: "/etc/cron.d/"
  execs: all

The lint at cmd/lint-projection/ enforces that declarations are present and schema-valid. Run it locally with make lint-projection. Getting the patterns right is the rule author's responsibility — runtime metrics in node-agent catch drift after deployment.

Rules with profileDependency: 2 (NotRequired) must not declare profileDataRequired; the lint emits a warning if they do.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your rule following the guidelines
4. Write comprehensive tests
5. Run the generation script
6. Submit a pull request