SCheck Getting Started¶

• Version: 1.0.7-7-g251eead
• Release Date: 2023-04-06 11:17:57
• Supported OS: windows/amd64,windows/386,linux/arm,linux/arm64,linux/386,linux/amd64

This document describes how to use the basic features of SCheck after installing SCheck, including the following aspects:

SCheck Directory Structure¶

SCheck currently supports two mainstream platforms: Linux and Windows.

Tips: Check kernel version

• Linux: uname -r
• Windows: Run cmd (press Win + R, type cmd, press Enter), then type winver to get the system version.

After installation, the SCheck directory structure looks like this:

├── [   6]  custom.rules.d
├── [ 12K]  rules.d
├── [ 17M]  scheck
├── [ 664]  scheck.conf
└── [ 222]  version

Where:

• scheck: SCheck main program, scheck.exe on Windows
• custom.rules.d: User-defined rules directory
• rules.d: SCheck system rules directory
• scheck.conf: SCheck main configuration file
• version: SCheck version information

Note: On Linux, SCheck runtime logs are stored in /var/log/scheck.

Commands¶

View help:

$ scheck -h
Usage of scheck:
  -check-md5
        md5 checksum
  -config string
        configuration file to load
  -config-sample
        show config sample
  -funcs
        show all supported lua-extend functions
  -test string
        the name of a rule, without file extension
  -testc int
        test rule count
  -version
        show version
  -doc
        Generate doc document from manifest file
  -tpl
        Generate doc document from template file
  -dir
        Use with `-doc` `-tpl` to output files to a specified directory
  -luastatus
        Show all Lua runtime status and output to the current directory in Markdown format.
  -sort
        Use with `-luastatus` to sort by: name, time, count (default: count)
     ./scheck -luastatus -sort=time
  -check
        Pre-compile all Lua files in the user directory to check for syntax errors.
  -box
        Show the list of all files embedded in the binary

Detection Rules¶

Detection rules are stored in rule directories: specified by the rule_dir configuration or the user-defined custom_dir. Each rule consists of two files:

1. Script file: Written in Lua, must have .lua extension.
2. Manifest file: Written in TOML format, must have .manifest extension. See Manifest File.

The script file and manifest file must have the same name.

SChecker periodically executes the detection script at intervals specified by the cron field in the manifest file. Each time the Lua script runs, it checks whether a security event (e.g., file modification, new user login) has occurred. If triggered, it uses the trigger() function to send the event (in line protocol format) to the address specified by the output field in the configuration file.

SChecker defines several Lua extension functions and, for security, disables some Lua packages or functions. Only the following Lua built-in packages/functions are supported:

• The following built-in base packages are supported:

  • table
  • math
  • string
  • debug

• In the os package, all functions are available except the following:

  • execute()
  • remove()
  • rename()
  • setenv()
  • setlocale()

Adding or modifying rule manifest files and Lua code does not require restarting the service. SChecker scans the rule directories every 10 seconds.

Manifest File¶

The manifest file describes the content detected by the current rule, such as file changes, port start/stop, etc. The final line protocol data will only contain the fields from the manifest file. The details are as follows:

# ---------------- Required Fields ---------------

# Rule ID of the event, e.g., k8s-pod-001, will be used as the metric name in line protocol
id = ''

# Event category, custom based on business
category = ''

# Severity level of the event, custom based on business, e.g., warn, error
level = ''

# Title of the event, describing the detection content, e.g., "Sensitive file modification"
title = ''

# Content of the event (supports templates, see below for details)
desc = ''

# Execution interval of the rule (using Linux crontab syntax)
cron = ''

# Supported platforms
os_arch = ["Linux", "Windows"]
# ---------------- Optional Fields ---------------

# Disable the rule
#disabled = false

# By default, hostname is added as a tag
#omit_hostname = false

# Explicitly set hostname
#hostname = ''

# ---------------- Custom Fields ---------------

# Supports custom key-value pairs, value must be a string
#instanceID=''

Cron Rules¶

Currently only supports interval-based execution.

# ┌───────────── Second
# │ ┌───────────── Minute
# │ │ ┌───────────── Hour
# │ │ │ ┌───────────── Day-of-Month
# │ │ │ │ ┌───────────── Month
# │ │ │ │ │
# │ │ │ │ │
# │ │ │ │ │
# * * * * *

Examples:

*/10 * * * *: Run every 10 seconds. * */5 * * *: Run every 5 minutes. disable: If set to disable or empty string, the Lua script becomes long-running, e.g., monitoring file changes. This type of Lua script will not stop once started.

Template Support¶

The desc string in the manifest file supports template variables with the syntax {{.<Variable>}}. For example:

File {{.FileName}} was modified, the modified content is: {{.Content}}

This means FileName and Content are template variables that will be replaced (including the preceding dot .). When the trigger() function is called, the variables are substituted. The function accepts a Lua table containing the replacement values for the template variables. For example, if the following parameters are passed:

tmpl_vals={
    FileName = "/etc/passwd",
    Content = "delete user demo"
}
trigger(tmpl_vals)

The final desc value will be:

File /etc/passwd was modified, the modified content is: `delete user demo`

Testing Rules¶

When writing rule code, you can use scheck --test to test the correctness of the code. For example, suppose there is a demo rule in the rules.d directory:

$ scheck --test  ./rules.d/demo

The --test option can also test multiple rules simultaneously. For example, if the script depends on another script:

$ scheck --test  rules.d/0000-global-cache,rules.d/0400-k8s-node-conf-priv

Lua Functions¶

See Functions

Creating Common Libraries¶

SChecker allows importing Lua modules in detection scripts using the require function. Module files must be placed in the rules.d/lib directory. You can modularize common functions and place them in this lib subdirectory for use by detection scripts.

For example, create a Lua module common.lua:

module={}

function modules.Foo()
    -- function body...
end

return module

Place common.lua in the /usr/local/scheck/rules.d/lib directory.

Suppose a rule script demo.lua uses this common module:

common=require("common") -- no need to include the file extension
common.Foo()

Line Protocol¶

SCheck output is in line protocol format, using the rule ID as the metric name.

Tags List¶

Current category values:

• network: Network-related, involving connections, ports, firewalls, etc.
• storage: Storage-related, such as disk, HDFS, etc.
• db: Various databases (MySQL/Redis/...)
• system: Operating system related
• container: Includes Docker and Kubernetes

Fields List¶

SCheck Resource Limits¶

Resource limits for SCheck (e.g., CPU usage) can be set via cgroups. This is only supported on Linux. Go to the SCheck installation directory, modify the scheck.conf configuration file, and set enable to true. Example:

[cgroup]
# Optional, disabled by default, can control CPU and memory
enable = false
cpu_max = 30.0
cpu_min = 5.0
mem = 0