docs: add lua-lsm documentation and update references

Add design doc and CLI reference for Lua-LSM. Update README, top-level
CLI reference, build-and-test guide, seharden docs, and profile format
spec with lua-lsm mentions, benchmark metadata fields, and e2e test
instructions.

Author: chenzongyao200127

README.md

@@ -8,6 +8,7 @@ profile-driven auditing, optional hardening actions, and RPM package file verifi
 ```sh
 loongshield seharden --scan --config dengbao_3 --verbose
 loongshield rpm --verify nginx --config https://example.com/sbom.json
+loongshield lua-lsm status
 ```
 
 ## Quick Start
@@ -47,12 +48,14 @@ make rpm-in-docker
 - Development, testing, and packaging workflows assume an RPM-based Linux environment.
 - `loongshield seharden` defaults to the bundled `cis_alinux_3` profile.
 - `loongshield rpm` defaults to the OpenAnolis SBOM service.
+- `loongshield lua-lsm` requires a kernel with Lua-LSM enabled and never auto-loads policies.
 - On other RPM-based distributions, expect to pass an explicit `--config` or `--sbom-url`.
 
 ## Project Scope
 
 - Currently focused on host hardening and verification on RPM-based Linux with systemd.
 - The optional kernel module under `src/kmod/` is not required for normal userspace workflows.
+- Lua-LSM support manages a kernel-provided built-in LSM through securityfs;
 - The project is released under the [MIT License](LICENSE).
 
 ## Versioning And Compatibility
@@ -70,6 +73,7 @@ make rpm-in-docker
 - SEHarden usage: [docs/reference/seharden-cli.md](docs/reference/seharden-cli.md)
 - SEHarden profile format: [docs/reference/seharden-profile-format.md](docs/reference/seharden-profile-format.md)
 - RPM verification usage: [docs/reference/rpm-cli.md](docs/reference/rpm-cli.md)
+- Lua-LSM usage: [docs/reference/lua-lsm-cli.md](docs/reference/lua-lsm-cli.md)
 - Build and test: [docs/developer/build-and-test.md](docs/developer/build-and-test.md)
 - Docker workflow: [docs/developer/docker-development.md](docs/developer/docker-development.md)
 - Submodule source policy: [docs/developer/submodule-sources.md](docs/developer/submodule-sources.md)

docs/README.md

@@ -8,6 +8,7 @@ This tree is split by audience, not by implementation detail. Public caller docs
 - SEHarden operators and profile authors: [reference/seharden-cli.md](./reference/seharden-cli.md)
 - AgentOS baseline automation: [skill/agent-sec-seharden.md](./skill/agent-sec-seharden.md)
 - RPM verification users: [reference/rpm-cli.md](./reference/rpm-cli.md)
+- Lua-LSM operators: [reference/lua-lsm-cli.md](./reference/lua-lsm-cli.md)
 - Contributors: [developer/build-and-test.md](./developer/build-and-test.md)
 - Maintainer roadmap: [developer/roadmap.md](./developer/roadmap.md)
 - Community and process: [../CONTRIBUTING.md](../CONTRIBUTING.md), [../SECURITY.md](../SECURITY.md), [../SUPPORT.md](../SUPPORT.md), [../CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md), [../CHANGELOG.md](../CHANGELOG.md), [../RELEASING.md](../RELEASING.md)
@@ -23,12 +24,14 @@ docs/
     seharden-cli.md
     seharden-profile-format.md
     rpm-cli.md
+    lua-lsm-cli.md
   skill/
     agent-sec-seharden.md
   design/
     runtime-architecture.md
     boot-and-runtime-flow.md
     clean-architecture.md
+    lua-lsm-native-support.md
     agentos-seharden-design.md
     seharden-enforcer-guidelines.md
     rpm-verification-design.md

docs/design/clean-architecture.md

@@ -154,6 +154,8 @@ The optional `sysmon` kernel module sits at the edge for cases where kernel-leve
 
 That is a good design choice for a security tool that still needs to be buildable, deployable, and operable on ordinary hosts. Kernel code is higher cost and higher risk, so Loongshield keeps it optional instead of making it a hard dependency for everything.
 
+Lua-LSM follows the same boundary from the Loongshield side. The kernel owns the built-in LSM and `/sys/kernel/security/lua` ABI, while Loongshield only manages readiness checks, policy validation, and explicit securityfs load/unload operations.
+
 ## Why Testing Is Layered This Way
 
 The test layout matches the architecture:

docs/design/lua-lsm-native-support.md

@@ -0,0 +1,83 @@
+# Lua-LSM Native Support
+
+Lua-LSM is a kernel-provided built-in Linux Security Module. Loongshield treats
+it as a runtime capability exposed through securityfs, not as another
+out-of-tree kernel module under `src/kmod/`.
+
+## Boundary
+
+Loongshield owns:
+
+- readiness checks for the running kernel
+- policy validation before explicit load
+- securityfs read/write orchestration
+- operator CLI and packaging of example policies
+- fake-securityfs tests for normal CI
+
+The kernel owns:
+
+- `CONFIG_LUA`
+- `CONFIG_SECURITY_LUA_LSM`
+- LSM hook registration
+- `/sys/kernel/security/lua/*`
+- policy execution inside the kernel Lua VM
+
+## Runtime ABI
+
+The userspace manager talks to these securityfs files:
+
+- `version`
+- `register`
+- `unregister`
+- `modules`
+- `stats`
+- `lsm_funcs`
+
+Only `register` and `unregister` are written. The CLI checks effective
+`CAP_MAC_ADMIN` before writes so operators get a clear userspace error before
+the kernel rejects the write.
+
+## Package Layout
+
+Bundled example policies are installed under:
+
+```text
+/etc/loongshield/lua-lsm/policies.d/
+```
+
+The example manifest is informational and does not trigger autoload:
+
+```text
+profiles/lua-lsm/manifest.yml
+```
+
+## Safety Gate
+
+The feature remains experimental because the inspected Lua-LSM source tree has
+documented high-risk audit findings, including memory lifetime, refcount, RCU,
+and hook contract issues. Loongshield therefore does not auto-load policies and
+marks the CLI surface as experimental in status/help/docs.
+
+Before production use, either fix the kernel audit blockers or enforce a
+conservative policy allowlist in Loongshield that only permits audited hook
+wrappers.
+
+## Test Strategy
+
+Normal CI uses a fake securityfs root through
+`LOONGSHIELD_LUA_LSM_SECURITYFS_ROOT` or direct module options. That covers
+status, doctor, list, load, unload, stats, and hooks behavior without requiring
+privileged kernel state.
+
+Privileged end-to-end coverage should run in a VM with:
+
+```text
+CONFIG_SECURITY=y
+CONFIG_SECURITYFS=y
+CONFIG_LUA=y
+CONFIG_SECURITY_LUA_LSM=y
+CONFIG_LSM=...,lua,...
+```
+
+The VM test should load a narrow policy, prove the target hook behavior, unload
+the policy, and verify the behavior is gone.

docs/developer/build-and-test.md

@@ -42,13 +42,13 @@ You can also install packages directly with `dnf` or `yum`:
 
 ```sh
 dnf install -y \
-  git cmake gcc gcc-c++ make \
-  perl perl-IPC-Cmd perl-FindBin which \
-  audit-libs-devel dbus-devel elfutils-libelf-devel \
-  libarchive-devel libattr-devel \
-  libcurl-devel libmount-devel libpsl-devel libyaml-devel \
-  libcap-devel libzstd-devel openssl-devel rpm-devel \
-  systemd-devel xz-devel
+  audit-libs-devel cmake dbus-devel elfutils-libelf-devel \
+  gcc gcc-c++ git libarchive-devel libattr-devel \
+  libcap-devel libcurl-devel libmount-devel libpsl-devel \
+  libyaml-devel libzstd-devel make openssl-devel \
+  perl-ExtUtils-MakeMaker perl-FindBin perl-IPC-Cmd \
+  rpm-build rpm-devel rpmdevtools systemd systemd-devel \
+  which xz-devel
 ```
 
 Then initialize submodules and build:
@@ -68,17 +68,19 @@ submodules that still intentionally point at public forks.
 make
 make test
 make test-quick
+make test-e2e
 make rpm
 make rpm-in-docker
 ```
 
-`make test` builds first and then runs the full Lua suite. `make test-quick` reuses the current build output and is the fastest way to rerun the full test suite after Lua-only or documentation changes.
+`make test` builds first and then runs the full Lua suite. `make test-quick` reuses the current build output and reruns only the source-loaded unit and integration tests; use `make test` or `make test-e2e` after changes that affect the embedded `loongshield` binary.
+`make test-e2e` builds first and then runs only the process-level CLI suite under `tests/e2e/`. Real bundled-profile scans require root privileges and are skipped by the test process when it is not running as root.
 
 ## Test Layout
 
 - `tests/unit/`: fast isolated module tests
 - `tests/integration/`: filesystem and system-behavior tests
-- `tests/e2e/`: reserved for full-flow suites; some revisions may not yet carry checked-in e2e cases
+- `tests/e2e/`: process-level full-flow suites that drive the built `loongshield` CLI
 - `tests/run.lua`: custom test discovery and runner
 
 ## Documentation Layout

docs/reference/loongshield-cli.md

@@ -23,12 +23,14 @@ Local builds produce the binary at `build/src/daemon/loongshield`. Installed sys
 - `version`: print the build version and commit.
 - `seharden`: audit or reinforce a security profile.
 - `rpm`: verify an installed RPM against a remote SBOM.
+- `lua-lsm`: inspect and manage Lua-LSM policies through securityfs.
 
 Run subcommand help directly:
 
 ```sh
 loongshield seharden --help
 loongshield rpm --help
+loongshield lua-lsm --help
 ```
 
 ## Typical Usage Examples
@@ -37,10 +39,12 @@ loongshield rpm --help
 loongshield version
 loongshield seharden --config agentos_baseline
 loongshield rpm --verify bash
+loongshield lua-lsm status
 ```
 
 ## Documentation Map
 
 - SEHarden usage: [seharden-cli.md](./seharden-cli.md)
 - SEHarden profile format: [seharden-profile-format.md](./seharden-profile-format.md)
 - RPM verification usage: [rpm-cli.md](./rpm-cli.md)
+- Lua-LSM usage: [lua-lsm-cli.md](./lua-lsm-cli.md)

docs/reference/lua-lsm-cli.md

@@ -0,0 +1,68 @@
+# Lua-LSM CLI
+
+`loongshield lua-lsm` manages Lua-LSM policies through the kernel securityfs
+ABI at `/sys/kernel/security/lua`.
+
+Lua-LSM support is experimental. Loongshield does not auto-load policies during
+install or startup. Loading a policy is always an explicit operator action.
+
+## Syntax
+
+```sh
+loongshield lua-lsm <command> [options]
+```
+
+## Commands
+
+- `status`: show whether the Lua-LSM securityfs ABI is present.
+- `doctor`: run readiness checks for securityfs, active LSM order, and kernel config.
+- `list`: show loaded Lua-LSM modules.
+- `load <policy.lua>`: validate policy metadata and write the policy to `register`.
+- `unload <name>`: write the module name to `unregister`.
+- `hooks`: print `lsm_funcs` when `CONFIG_SECURITY_LUA_LSM_STATS=y`.
+- `stats`: print VM/cache stats when `CONFIG_SECURITY_LUA_LSM_STATS=y`.
+
+## Options
+
+- `--root <path>`: override the Lua-LSM securityfs root.
+- `--config <path>`: override the kernel config path used by `doctor`.
+- `--no-validate`: skip userspace metadata validation before `load`.
+- `--log-level <level>`: set log level.
+- `-h`, `--help`: show command help.
+
+## Environment
+
+- `LOONGSHIELD_LUA_LSM_SECURITYFS_ROOT`: defaults to `/sys/kernel/security/lua`.
+- `LOONGSHIELD_LUA_LSM_SECURITYFS_MOUNT`: defaults to the parent of the root.
+- `LOONGSHIELD_LUA_LSM_CONFIG_FILE`: kernel config used by `doctor`.
+- `LOONGSHIELD_LUA_LSM_ASSUME_CAP_MAC_ADMIN`: test-only capability bypass.
+
+## Kernel Requirements
+
+The running kernel must provide:
+
+```text
+CONFIG_SECURITY=y
+CONFIG_SECURITYFS=y
+CONFIG_LUA=y
+CONFIG_SECURITY_LUA_LSM=y
+CONFIG_LSM=...,lua,...
+```
+
+The `load` and `unload` commands require effective `CAP_MAC_ADMIN`, matching the
+kernel-side securityfs write check.
+
+## Examples
+
+```sh
+loongshield lua-lsm doctor
+loongshield lua-lsm status
+loongshield lua-lsm list
+loongshield lua-lsm load /etc/loongshield/lua-lsm/policies.d/deny_tmp_marker.lua
+loongshield lua-lsm unload deny_tmp_marker
+```
+
+## Exit Codes
+
+- `0`: command completed successfully.
+- `1`: CLI error, readiness failure, missing ABI file, validation failure, missing capability, or kernel write failure.

docs/reference/seharden-cli.md

@@ -2,7 +2,7 @@
 
 `seharden` audits a host against a YAML profile and can optionally apply reinforce actions for failed rules.
 
-The default bundled profile is `cis_alinux_3`, which is aimed at Alibaba Cloud Linux 3 and similar OpenAnolis-style hosts. On other RPM-based systems, pick an explicit profile with `--config`.
+The default bundled profile is `cis_alinux_3`, which targets the CIS Alibaba Cloud Linux 3 Benchmark v2.0.0 and similar OpenAnolis-style hosts. On other RPM-based systems, pick an explicit profile with `--config`.
 
 ## Syntax
 

docs/reference/seharden-profile-format.md

@@ -7,6 +7,13 @@ Profiles are YAML documents consumed by `loongshield seharden`. They define leve
 - `id`: stable profile identifier, for example `agentos_baseline`.
 - `title` or `policy`: human-readable name.
 - `version`: profile version string.
+- `source`: optional upstream benchmark or policy source URL.
+- `benchmark_version`: optional upstream benchmark version when the profile tracks an external benchmark.
+- `benchmark_workbench_source`: optional upstream WorkBench artifact URL.
+- `benchmark_pdf_source`: optional upstream benchmark PDF URL.
+- `benchmark_build_kit_source`: optional upstream benchmark build-kit URL.
+- `benchmark_update_source`: optional upstream release or update note URL.
+- `coverage`: optional short coverage label, for example `automated_subset`.
 - `levels`: ordered level list. Levels may use `inherits_from`.
 - `default_level`: optional level ID used when the caller omits `--level`.
 - `manual_review_required`: optional list of operator review items that stay outside automated host checks.