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.

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.

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"
        unique_id: "CEL expression for unique identifier"
        rule_expression:
          - event_type: "event_type_name"
            expression: "CEL expression for detection logic"
      profile_dependency: 0  # 0=Required, 1=Optional, 2=NotRequired
      severity: 1
      support_policy: false
      tags:
        - "tag1"
        - "tag2"

• 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

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

r####-descriptive-name/

Example:

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

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

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

Run the tests to ensure your rule works correctly:

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

The gen.sh script automatically combines all individual rule YAML files into a single CRD instance.

./gen.sh

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)

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

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

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 ./gen.sh
6. Deploy the generated rules-crd.yaml to your Kubernetes cluster

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

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

./gen.sh
# Check the generated rules-crd.yaml file

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

Defines the alert message format:

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

Creates a unique identifier for deduplication:

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

Defines the detection logic:

"!data.profile_checks.exec_path"

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

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