Merge pull request #211 from bytedance/update-docs

Update the documentation for version 0.8

Author: Danny-Wei

README.md

@@ -26,10 +26,10 @@ vArmor is a cloud-native container sandbox system. It leverages Linux's [AppArmo
 **vArmor Features:**
 * **Cloud-Native**. vArmor follows the Kubernetes Operator design pattern, allowing users to harden specific workloads by manipulating the [CRD API](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). This approach enables sandboxing of containerized microservices from a perspective closely aligned with business needs.
 * **Multiple Enforcers**. vArmor abstracts AppArmor, BPF, and Seccomp as enforcers, supporting their use individually or in combination. This enables enforcing access control on container file access, process execution, network outbound, syscalls, and more.
-* **Allow-by-Default**. vArmor currently focuses on supporting this model, where only explicitly declared behaviors will be blocked, which effectively minimizes performance impact and enhances usability. Besides, it supports auditing behaviors that violate the access control rules, and the violation behaviors can also be allowed instead of being blocked.
+* **Allow-by-Default**. vArmor currently focuses on supporting this model, where only explicitly declared behaviors will be blocked, which effectively minimizes performance impact and enhances usability. Besides, it supports auditing violations, and these violations can also be allowed rather than blocked.
 * **Built-in Rules**. vArmor features a range of built-in rules ready to use out of the box. They are designed for the Allow-by-Default security model, eliminating the need for expertise in security profile creation.
-* **Behavior Modeling**. vArmor supports behavior modeling for workloads. This can be used for developing an allowlist profile, analyze which built-in rules can harden the application, or guide the configuration of workloads to adhere to the principle of least privilege.
-* **Deny-by-Default**. vArmor is capable of creating an allowlist profile from behavior models and ensuring that only explicitly declared behaviors are permitted.
+* **Behavior Modeling**. vArmor features a range of built-in rules ready to use out of the box. They are designed for the Allow-by-Default security model, eliminating the need for expertise in security profile creation.
+* **Deny-by-Default**. vArmor is capable of using allowlist profiles to harden workloads and provide a more user-friendly approach to develop and manage profiles.
 
 
 vArmor was created by the **Elkeid Team** of the endpoint security department at ByteDance. And the project is still in active development.

README.zh_CN.md

@@ -32,8 +32,8 @@ vArmor 是一个云原生容器沙箱系统，它借助 Linux 的 [AppArmor LSM]
 * **Multiple Enforcers**. vArmor 将 AppArmor、BPF、Seccomp 抽象为 Enforcer，并支持单独或组合使用，从而对容器的文件访问、进程执行、网络外联、系统调用等进行访问控制。
 * **Allow-by-Default**. vArmor 当前重点支持此安全模型，即只有显式声明的行为会被阻断，从而减少性能损失和增加易用性。vArmor 支持对违反访问控制规则的行为进行审计，并支持放行违反访问控制规则的行为。
 * **Built-in Rules**. vArmor 提供了一系列开箱即用的内置规则。这些规则为 Allow-by-Default 安全模型设计，从而极大降低对用户专业知识的要求。
-* **Behavior Modeling**. vArmor 支持对工作负载进行行为建模。这可用于开发白名单安全策略、分析哪些内置规则可用于加固应用、指导工作负载的配置遵循权限最小化原则。
-* **Deny-by-Default**. vArmor 可以基于行为模型创建白名单安全策略，从而确保仅显式声明的行为被允许。
+* **Behavior Modeling**. vArmor 支持对工作负载进行行为建模。这对于制定白名单安全策略、分析哪些内置规则可用于加固应用，或指导工作负载的配置以遵循最小权限原则非常有用。
+* **Deny-by-Default**. vArmor 可以使用白名单安全策略来加固工作负载，并提供一种更便于用户使用的方式来开发和管理安全策略。
 
 vArmor 由字节跳动终端安全团队的 **Elkeid Team** 研发，目前该项目仍在积极迭代中。
 

docs/README.md

@@ -17,10 +17,10 @@ vArmor is a cloud-native container sandbox system. It leverages Linux's [AppArmo
 **vArmor Features:**
 * Cloud-Native. vArmor follows the Kubernetes Operator design pattern, allowing users to harden specific workloads by manipulating the [CRD API](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). This approach enables sandboxing of containerized microservices from a perspective closely aligned with business needs.
 * Multiple Enforcers. vArmor abstracts AppArmor, BPF, and Seccomp as enforcers, supporting their use individually or in combination. This enables enforcing access control on container file access, process execution, network outbound, syscalls, and more.
-* Allow-by-Default. vArmor currently focuses on supporting this model, where only explicitly declared behaviors will be blocked, which effectively minimizes performance impact and enhances usability. Besides, it supports auditing behaviors that violate the access control rules, and the violation behaviors can also be allowed instead of being blocked.
+* Allow-by-Default. vArmor currently focuses on supporting this model, where only explicitly declared behaviors will be blocked, which effectively minimizes performance impact and enhances usability. Besides, it supports auditing violations, and these violations can also be allowed rather than blocked.
 * Built-in Rules. vArmor features a range of built-in rules ready to use out of the box. They are designed for the Allow-by-Default security model, eliminating the need for expertise in security profile creation.
-* Behavior Modeling. vArmor supports behavior modeling for workloads. This can be used for developing an allowlist profile, analyze which built-in rules can harden the application, or guide the configuration of workloads to adhere to the principle of least privilege.
-* Deny-by-Default. vArmor is capable of creating an allowlist profile from behavior models and ensuring that only explicitly declared behaviors are permitted.
+* Behavior Modeling. vArmor features a range of built-in rules ready to use out of the box. They are designed for the Allow-by-Default security model, eliminating the need for expertise in security profile creation.
+* Deny-by-Default. vArmor is capable of using allowlist profiles to harden workloads and provide a more user-friendly approach to develop and manage profiles.
 
 vArmor was created by the **Elkeid Team** of the endpoint security department at ByteDance. And the project is still in active development.
 

docs/README.zh_CN.md

@@ -22,8 +22,8 @@ vArmor 是一个云原生容器沙箱系统，它借助 Linux 的 [AppArmor LSM]
 * **Multiple Enforcers**. vArmor 将 AppArmor、BPF、Seccomp 抽象为 Enforcer，并支持单独或组合使用，从而对容器的文件访问、进程执行、网络外联、系统调用等进行访问控制。
 * **Allow-by-Default**. vArmor 当前重点支持此安全模型，即只有显式声明的行为会被阻断，从而减少性能损失和增加易用性。vArmor 支持对违反访问控制规则的行为进行审计，并支持放行违反访问控制规则的行为。
 * **Built-in Rules**. vArmor 提供了一系列开箱即用的内置规则。这些规则为 Allow-by-Default 安全模型设计，从而极大降低对用户专业知识的要求。
-* **Behavior Modeling**. vArmor 支持对工作负载进行行为建模。这可用于开发白名单安全策略、分析哪些内置规则可用于加固应用、指导工作负载的配置遵循权限最小化原则。
-* **Deny-by-Default**. vArmor 可以基于行为模型创建白名单安全策略，从而确保仅显式声明的行为被允许。
+* **Behavior Modeling**. vArmor 支持对工作负载进行行为建模。这对于制定白名单安全策略、分析哪些内置规则可用于加固应用，或指导工作负载的配置以遵循最小权限原则非常有用。
+* **Deny-by-Default**. vArmor 可以使用白名单安全策略来加固工作负载，并提供一种更便于用户使用的方式来开发和管理安全策略。
 
 vArmor 项目由字节跳动终端安全团队的 **Elkeid Team** 创建，目前该项目仍在积极迭代中。
 

docs/getting_started/installation.md

@@ -36,37 +36,37 @@ helm install varmor varmor-0.7.1.tgz \
 vArmor allows you to configure its functionality during installation using the helm command.
 
 ### General Options
-#### Disable AppArmor enforcer
+#### Disable AppArmor Enforcer
 The AppArmor enforcer should be disabled when the system doesn't support AppArmor LSM. Default: enabled.
 
 ```bash
 --set appArmorLsmEnforcer.enabled=false
 ```
 
-#### Enable BPF enforcer
+#### Enable BPF Enforcer
 The BPF enforcer can be enabled when the system supports BPF LSM. Default: disabled.
 
 ```bash
 --set bpfLsmEnforcer.enabled=true
 ```
 
-#### Enable the BehaviorModeling mode
+#### Enable the BehaviorModeling Mode
 This is an experimental feature. Currently, only the AppArmor and Seccomp enforcers support the BehaviorModeling mode. Please refer to the [BehaviorModeling Mode](../guides/policies_and_rules/policy_modes/behavior_modeling.md) for more details. Default: disabled.
 
 ```bash
 --set behaviorModeling.enabled=true
 ```
 
-#### Configure the search list of audit logs
-vArmor sequentially checks whether the audit logs exist and monitors the first valid file to consume AppArmor and Seccomp audit events for the violation auditing and behavioral modeling features. If you are using *auditd*, the audit events of AppArmor and Seccomp will be stored by default in `/var/log/audit/audit.log`. Otherwise they will be stored in `/var/log/kern.log`. 
+#### Configure the Search List for System Audit Logs
+vArmor sequentially checks whether the system audit logs exist and monitors the first valid file to consume AppArmor and Seccomp audit events for the violation auditing and behavioral modeling features. If you are using *auditd*, the audit events of AppArmor and Seccomp will be stored by default in `/var/log/audit/audit.log`. Otherwise they will be stored in `/var/log/kern.log`. 
 
 You can use the option to specify the audit logs or determine the search order yourself. Please use a vertical bar to separate file paths. Default: `/var/log/audit/audit.log|/var/log/kern.log`.
 
 ```bash
 --set "agent.args={--auditLogPaths=FILE_PATH|FILE_PATH}"
 ```
 
-#### Configure metrics
+#### Configure Metrics
 You can enable metrics to monitor the operation of vArmor. All metrics are exposed at the `/metric` endpoint on port `8081` of every manager instance. Default: disabled.
 
 ```bash
@@ -79,53 +79,73 @@ You can use the following command to create a `ServiceMonitor` object in the nam
 --set metrics.serviceMonitorEnabled=true
 ```
 
-#### Set the log output format to JSON
+#### Set the Log Output Format to JSON
 The default format of agent and manager is TEXT. You can use the following command to set it to JSON.
 
 ```bash
 --set jsonLogFormat.enabled=true
 ```
 
+#### Inject Metadata into Violation Events
+This feature enables you to inject custom metadata into violation events. It enhances the observability of vArmor's audit logs by associating violation events with environment-specific context. Default: No custom metadata.
+
+You can add key-value pairs of metadata using commands similar to the following.
+
+```bash
+--set auditEventMetadata.clusterID="ID" \ 
+--set auditEventMetadata.clusterName="NAME" \  
+--set auditEventMetadata.region="REGION"  
+```
+
 ### Advanced Options
-#### Set the match label of webhook
+#### Set the Match Label of Webhook
 vArmor will only enable sandbox protection for workloads that contain a specific label. You can set the label you want or disable this feature by using `--set 'manager.args={--webhookMatchLabel=}'`. Default: `sandbox.varmor.org/enable=true`.
 
 ```bash
 --set "manager.args={--webhookMatchLabel=KEY=VALUE}"
 ```
 
-#### Disallow restarting the existing workloads
+#### Disallow Restarting the Existing Workloads
 vArmor allows users to decide whether to perform a rolling restart on all target workloads or not, when creating or deleting a policy with the `.spec.updateExistingWorkloads` field. You can disable this feature with following option. Default: enabled.
 
 ```bash
 --set restartExistWorkloads.enabled=false
 ```
 
-#### Run Agent in hostNetwork mode
+#### Disable Pod and Service Egress Control
+The feature extends network access control to restrict container access to specific Pods and Services. You can use the following option to disable it. Default: enabled.
+
+```bash
+--set podServiceEgressControl.enabled=false
+```
+
+The feature is currently only supported by the BPF enforcer and requires Kubernetes v1.21 or higher.
+
+#### Run Agent in HostNetwork Mode
 The agent runs in its own network namespace and exposes the readinessProbe on port `6080` by default. If you want to run it in the host's network namespace, you can use following options.
 
 ```bash
 --set agent.network.hostNetwork=true \
 --set agent.network.readinessPort=HOSTPORT
 ```
 
-#### Enable exclusive mode for BPF enforcer
+#### Enable Exclusive Mode for BPF Enforcer
 If your system supports AppArmor LSM, the default AppArmor profile of container runtime will be applied to the workloads which don't have an AppArmor setting explicitly.
 You can use this option to disable the default AppArmor profile if a policy with a BPF enforcer is applied to the workload. Default: disabled.
 
 ```bash
 --set bpfExclusiveMode.enabled=true
 ```
 
-#### Unload all AppArmor profiles
+#### Unload All AppArmor Profiles
 All AppArmor profiles managed by vArmor will not be unloaded when the Agent exits or vArmor is uninstalled.
 You can use the following option to change this behavior. Default: disabled.
 
 ```bash
 --set unloadAllAaProfiles.enabled=true
 ```
 
-#### Remove all Seccomp profiles
+#### Remove All Seccomp Profiles
 All Seccomp profiles managed by vArmor will not be removed when the Agent exits or vArmor is uninstalled.
 You can use the following option to change this behavior. Default: disabled.
 

docs/getting_started/installation.zh_CN.md

@@ -56,8 +56,8 @@ helm install varmor varmor-0.7.1.tgz \
 --set behaviorModeling.enabled=true
 ```
 
-#### 配置审计日志的搜索列表
-vArmor 顺序检查对应的审计日志是否存在，并通过监控第一个有效的文件来获取 AppArmor 和 Seccomp 的审计事件，从而用于违规审计和行为建模功能。当您使用 *auditd* 时，AppArmor 和 Seccomp 的审计事件会默认保存在 `/var/log/audit/audit.log` 文件中。否则，他们通常会被保存在 `/var/log/kern.log` 文件中。
+#### 配置系统审计日志的搜索列表
+vArmor 顺序检查系统的审计日志是否存在，并通过监控第一个有效的文件来获取 AppArmor 和 Seccomp 的审计事件，从而用于违规审计和行为建模功能。当您使用 *auditd* 时，AppArmor 和 Seccomp 的审计事件会默认保存在 `/var/log/audit/audit.log` 文件中。否则，他们通常会被保存在 `/var/log/kern.log` 文件中。
 
 你可以使用这个选项来配置审计日志、文件搜索顺序。请使用`|`来分割文件。默认值：`/var/log/audit/audit.log|/var/log/kern.log`。
 
@@ -85,6 +85,17 @@ Agent 和 Manager 的日志格式默认为文本格式，您可以使用下面
 --set jsonLogFormat.enabled=true
 ```
 
+#### 注入元数据到违规事件
+此功能使您能够将自定义元数据注入到违规事件。它通过将违规事件与特定于环境的上下文相关联来增强 vArmor 审计日志的可观测性。默认值为空。
+
+您可以使用类似下面的选项来添加元数据的键值对。
+
+```bash
+--set auditEventMetadata.clusterID="ID" \ 
+--set auditEventMetadata.clusterName="NAME" \  
+--set auditEventMetadata.region="REGION"  
+```
+
 ### 高级选项
 
 #### 设置 Webhook 的匹配标签
@@ -101,6 +112,15 @@ vArmor 只会对包含此 label 的 Workloads 开启沙箱防护。你可以使
 --set restartExistWorkloads.enabled=false
 ```
 
+#### 关闭 Pod 和 Service 出口控制
+此功能扩展了网络访问控制，以限制容器对特定 Pod 和 Service 的访问。您可以使用下面的选项关闭它。默认值：开启。
+
+```bash
+--set podServiceEgressControl.enabled=false
+```
+
+当前仅 BPF enforcer 支持此功能，并且需要 Kubernetes v1.21 及以上版本。
+
 #### 在宿主机网络命名空间中运行 Agent
 vArmor 的 Agent 默认运行在独立的网络命名空间中，并在端口 `6080` 暴露就绪探针。如果您想将其部署在宿主网络命名空间中，那么可以使用下面的选项进行配置。