From 7d6dc7192b342305372645b07f75647a79c8d029 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sat, 30 Nov 2024 14:14:18 +0800 Subject: [PATCH 1/9] feat: Support wildcard for all bpf permissions and flags. --- apis/varmor/v1beta1/varmorpolicy_types.go | 20 +++++------ .../crd.varmor.org_varmorclusterpolicies.yaml | 36 ++++++++++--------- .../crds/crd.varmor.org_varmorpolicies.yaml | 36 ++++++++++--------- internal/profile/bpf/bpf.go | 8 ++++- .../crd.varmor.org_varmorclusterpolicies.yaml | 36 ++++++++++--------- .../crds/crd.varmor.org_varmorpolicies.yaml | 36 ++++++++++--------- 6 files changed, 93 insertions(+), 79 deletions(-) diff --git a/apis/varmor/v1beta1/varmorpolicy_types.go b/apis/varmor/v1beta1/varmorpolicy_types.go index fcad932..5bd65ae 100644 --- a/apis/varmor/v1beta1/varmorpolicy_types.go +++ b/apis/varmor/v1beta1/varmorpolicy_types.go @@ -58,6 +58,9 @@ type FileRule struct { // Pattern can be any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames Pattern string `json:"pattern"` // Permissions are used to specify the file permissions to be disabled. + // + // Available values: all(*), read(r), write(w), exec(x), append(a) + // Permissions []string `json:"permissions"` } @@ -77,7 +80,7 @@ type NetworkSocketRule struct { // Domains specifies the communication domains of socket. // // Available values: - // *, all, unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, + // all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, // inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, // rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, // rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, @@ -87,13 +90,13 @@ type NetworkSocketRule struct { // Types specifies the communication semantics of socket. Note that the types field and protocols field // are mutually exclusive. // - // Available values: *, all, stream, dgram, raw, rdm, seqpacket, dccp, packet + // Available values: all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet // Types []string `json:"types,omitempty"` // Protocols specifies the particular protocols to be used with the socket. Note that the protocols field // and types field are mutually exclusive. // - // Available values: *, all, icmp, tcp, udp + // Available values: all(*), icmp, tcp, udp // Protocols []string `json:"protocols,omitempty"` } @@ -113,15 +116,13 @@ type PtraceRule struct { // +optional StrictMode bool `json:"strictMode,omitempty"` // Permissions are used to indicate which ptrace-related permissions of the target container should be restricted. - // Available values: trace, traceby, read, readby. - // - // trace, traceby // + // Available values: all(*), trace, traceby, read, readby. + // trace, traceby // For "write" operations, or other operations that are more dangerous, such as: ptrace attaching (PTRACE_ATTACH) to // another process or calling process_vm_writev(2). // - // read, readby - // + // read, readby // For "read" operations or other operations that are less dangerous, such as: get_robust_list(2); kcmp(2); reading // /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file. // @@ -136,8 +137,7 @@ type MountRule struct { // Flags are used to specify the mount flags to enforce. They are almost the same as the 'MOUNT FLAGS LIST' of AppArmor. // // Available values: - // - // All Flags: all + // All Flags: all(*) // Command Flags: ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, // sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, // silent, loud, relatime, norelatime, iversion, noiversion, strictatime, diff --git a/config/crds/crd.varmor.org_varmorclusterpolicies.yaml b/config/crds/crd.varmor.org_varmorclusterpolicies.yaml index c0ca774..020c001 100644 --- a/config/crds/crd.varmor.org_varmorclusterpolicies.yaml +++ b/config/crds/crd.varmor.org_varmorclusterpolicies.yaml @@ -126,8 +126,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -143,7 +144,7 @@ spec: description: "Flags are used to specify the mount flags to enforce. They are almost the same as the 'MOUNT FLAGS LIST' of AppArmor. \n Available - values: \n All Flags: all Command Flags: ro(r, + values: All Flags: all(*) Command Flags: ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, @@ -203,8 +204,8 @@ spec: properties: domains: description: "Domains specifies the communication - domains of socket. \n Available values: *, - all, unix, inet, ax25, ipx, appletalk, netrom, + domains of socket. \n Available values: all(*), + unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, @@ -218,8 +219,8 @@ spec: description: "Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are - mutually exclusive. \n Available values: *, - all, icmp, tcp, udp" + mutually exclusive. \n Available values: all(*), + icmp, tcp, udp" items: type: string type: array @@ -227,7 +228,7 @@ spec: description: "Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive. - \n Available values: *, all, stream, dgram, + \n Available values: all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet" items: type: string @@ -244,8 +245,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -259,13 +261,13 @@ spec: permissions: description: "Permissions are used to indicate which ptrace-related permissions of the target container - should be restricted. Available values: trace, traceby, - read, readby. \n trace, traceby \n For \"write\" - operations, or other operations that are more dangerous, - such as: ptrace attaching (PTRACE_ATTACH) to another - process or calling process_vm_writev(2). \n read, - readby \n For \"read\" operations or other operations - that are less dangerous, such as: get_robust_list(2); + should be restricted. \n Available values: all(*), + trace, traceby, read, readby. trace, traceby For + \"write\" operations, or other operations that are + more dangerous, such as: ptrace attaching (PTRACE_ATTACH) + to another process or calling process_vm_writev(2). + \n read, readby For \"read\" operations or other + operations that are less dangerous, such as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file." diff --git a/config/crds/crd.varmor.org_varmorpolicies.yaml b/config/crds/crd.varmor.org_varmorpolicies.yaml index 5b9984d..e0ac79c 100644 --- a/config/crds/crd.varmor.org_varmorpolicies.yaml +++ b/config/crds/crd.varmor.org_varmorpolicies.yaml @@ -125,8 +125,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -142,7 +143,7 @@ spec: description: "Flags are used to specify the mount flags to enforce. They are almost the same as the 'MOUNT FLAGS LIST' of AppArmor. \n Available - values: \n All Flags: all Command Flags: ro(r, + values: All Flags: all(*) Command Flags: ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, @@ -202,8 +203,8 @@ spec: properties: domains: description: "Domains specifies the communication - domains of socket. \n Available values: *, - all, unix, inet, ax25, ipx, appletalk, netrom, + domains of socket. \n Available values: all(*), + unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, @@ -217,8 +218,8 @@ spec: description: "Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are - mutually exclusive. \n Available values: *, - all, icmp, tcp, udp" + mutually exclusive. \n Available values: all(*), + icmp, tcp, udp" items: type: string type: array @@ -226,7 +227,7 @@ spec: description: "Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive. - \n Available values: *, all, stream, dgram, + \n Available values: all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet" items: type: string @@ -243,8 +244,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -258,13 +260,13 @@ spec: permissions: description: "Permissions are used to indicate which ptrace-related permissions of the target container - should be restricted. Available values: trace, traceby, - read, readby. \n trace, traceby \n For \"write\" - operations, or other operations that are more dangerous, - such as: ptrace attaching (PTRACE_ATTACH) to another - process or calling process_vm_writev(2). \n read, - readby \n For \"read\" operations or other operations - that are less dangerous, such as: get_robust_list(2); + should be restricted. \n Available values: all(*), + trace, traceby, read, readby. trace, traceby For + \"write\" operations, or other operations that are + more dangerous, such as: ptrace attaching (PTRACE_ATTACH) + to another process or calling process_vm_writev(2). + \n read, readby For \"read\" operations or other + operations that are less dangerous, such as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file." diff --git a/internal/profile/bpf/bpf.go b/internal/profile/bpf/bpf.go index e6870be..b15c205 100644 --- a/internal/profile/bpf/bpf.go +++ b/internal/profile/bpf/bpf.go @@ -544,6 +544,8 @@ func generateRawFileRule(bpfContent *varmor.BpfContent, mode uint32, rule varmor for _, permission := range rule.Permissions { switch strings.ToLower(permission) { + case "all", "*": + permissions |= bpfenforcer.AaMayRead | bpfenforcer.AaMayWrite | bpfenforcer.AaMayAppend case "read", "r": permissions |= bpfenforcer.AaMayRead case "write", "w": @@ -572,6 +574,8 @@ func generateRawProcessRule(bpfContent *varmor.BpfContent, mode uint32, rule var for _, permission := range rule.Permissions { switch strings.ToLower(permission) { + case "all", "*": + permissions |= bpfenforcer.AaMayExec case "exec", "x": permissions |= bpfenforcer.AaMayExec } @@ -763,6 +767,8 @@ func generateRawPtraceRule(bpfContent *varmor.BpfContent, mode uint32, rule *var for _, permission := range rule.Permissions { switch strings.ToLower(permission) { + case "all", "*": + permissions |= bpfenforcer.AaPtraceTrace | bpfenforcer.AaPtraceRead | bpfenforcer.AaMayBeTraced | bpfenforcer.AaMayBeRead case "trace": permissions |= bpfenforcer.AaPtraceTrace case "read": @@ -791,7 +797,7 @@ func generateRawMountRule(bpfContent *varmor.BpfContent, mode uint32, rule varmo for _, flag := range rule.Flags { switch strings.ToLower(flag) { // All Flags: - case "all": + case "all", "*": mountFlags = 0xFFFFFFFF reverseMountFlags = 0xFFFFFFFF // Command Flags diff --git a/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml b/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml index c0ca774..020c001 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml @@ -126,8 +126,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -143,7 +144,7 @@ spec: description: "Flags are used to specify the mount flags to enforce. They are almost the same as the 'MOUNT FLAGS LIST' of AppArmor. \n Available - values: \n All Flags: all Command Flags: ro(r, + values: All Flags: all(*) Command Flags: ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, @@ -203,8 +204,8 @@ spec: properties: domains: description: "Domains specifies the communication - domains of socket. \n Available values: *, - all, unix, inet, ax25, ipx, appletalk, netrom, + domains of socket. \n Available values: all(*), + unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, @@ -218,8 +219,8 @@ spec: description: "Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are - mutually exclusive. \n Available values: *, - all, icmp, tcp, udp" + mutually exclusive. \n Available values: all(*), + icmp, tcp, udp" items: type: string type: array @@ -227,7 +228,7 @@ spec: description: "Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive. - \n Available values: *, all, stream, dgram, + \n Available values: all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet" items: type: string @@ -244,8 +245,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -259,13 +261,13 @@ spec: permissions: description: "Permissions are used to indicate which ptrace-related permissions of the target container - should be restricted. Available values: trace, traceby, - read, readby. \n trace, traceby \n For \"write\" - operations, or other operations that are more dangerous, - such as: ptrace attaching (PTRACE_ATTACH) to another - process or calling process_vm_writev(2). \n read, - readby \n For \"read\" operations or other operations - that are less dangerous, such as: get_robust_list(2); + should be restricted. \n Available values: all(*), + trace, traceby, read, readby. trace, traceby For + \"write\" operations, or other operations that are + more dangerous, such as: ptrace attaching (PTRACE_ATTACH) + to another process or calling process_vm_writev(2). + \n read, readby For \"read\" operations or other + operations that are less dangerous, such as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file." diff --git a/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml b/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml index 5b9984d..e0ac79c 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml @@ -125,8 +125,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -142,7 +143,7 @@ spec: description: "Flags are used to specify the mount flags to enforce. They are almost the same as the 'MOUNT FLAGS LIST' of AppArmor. \n Available - values: \n All Flags: all Command Flags: ro(r, + values: All Flags: all(*) Command Flags: ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, @@ -202,8 +203,8 @@ spec: properties: domains: description: "Domains specifies the communication - domains of socket. \n Available values: *, - all, unix, inet, ax25, ipx, appletalk, netrom, + domains of socket. \n Available values: all(*), + unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, @@ -217,8 +218,8 @@ spec: description: "Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are - mutually exclusive. \n Available values: *, - all, icmp, tcp, udp" + mutually exclusive. \n Available values: all(*), + icmp, tcp, udp" items: type: string type: array @@ -226,7 +227,7 @@ spec: description: "Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive. - \n Available values: *, all, stream, dgram, + \n Available values: all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet" items: type: string @@ -243,8 +244,9 @@ spec: syntax, used for matching file paths and filenames type: string permissions: - description: Permissions are used to specify the - file permissions to be disabled. + description: "Permissions are used to specify the + file permissions to be disabled. \n Available + values: all(*), read(r), write(w), exec(x), append(a)" items: type: string type: array @@ -258,13 +260,13 @@ spec: permissions: description: "Permissions are used to indicate which ptrace-related permissions of the target container - should be restricted. Available values: trace, traceby, - read, readby. \n trace, traceby \n For \"write\" - operations, or other operations that are more dangerous, - such as: ptrace attaching (PTRACE_ATTACH) to another - process or calling process_vm_writev(2). \n read, - readby \n For \"read\" operations or other operations - that are less dangerous, such as: get_robust_list(2); + should be restricted. \n Available values: all(*), + trace, traceby, read, readby. trace, traceby For + \"write\" operations, or other operations that are + more dangerous, such as: ptrace attaching (PTRACE_ATTACH) + to another process or calling process_vm_writev(2). + \n read, readby For \"read\" operations or other + operations that are less dangerous, such as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file." From 9e8ac742a6d750d3521633b1190e7577d4dec0e4 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sat, 30 Nov 2024 16:23:36 +0800 Subject: [PATCH 2/9] docs: Update interface specifications --- apis/varmor/v1beta1/varmorpolicy_types.go | 26 +++--- config/crds/crd.varmor.org_armorprofiles.yaml | 6 +- .../crd.varmor.org_varmorclusterpolicies.yaml | 44 +++++---- .../crds/crd.varmor.org_varmorpolicies.yaml | 44 +++++---- .../interface_specification.md | 66 +++++++------ .../interface_specification.zh_CN.md | 73 ++++++++------- .../crds/crd.varmor.org_armorprofiles.yaml | 6 +- .../crd.varmor.org_varmorclusterpolicies.yaml | 44 +++++---- .../crds/crd.varmor.org_varmorpolicies.yaml | 44 +++++---- .../interface_specification.md | 74 ++++++++------- .../interface_specification.md | 93 ++++++++++--------- .../interface_specification.md | 93 ++++++++++--------- .../interface_specification.md | 74 ++++++++------- 13 files changed, 387 insertions(+), 300 deletions(-) diff --git a/apis/varmor/v1beta1/varmorpolicy_types.go b/apis/varmor/v1beta1/varmorpolicy_types.go index 5bd65ae..162e94d 100644 --- a/apis/varmor/v1beta1/varmorpolicy_types.go +++ b/apis/varmor/v1beta1/varmorpolicy_types.go @@ -37,10 +37,7 @@ type Target struct { // will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers). // +optional Containers []string `json:"containers,omitempty"` - // LabelSelector is used to match workloads that meet the specified conditions - // - // Note: - // The type of workloads is determined by the KIND field. + // LabelSelector is used to match workloads that meet the specified conditions. Note that the selector field and name field are mutually exclusive. // +optional Selector *metav1.LabelSelector `json:"selector,omitempty"` } @@ -109,23 +106,26 @@ type NetworkRule struct { } type PtraceRule struct { - // StrictMode is used to indicate whether to restrict ptrace permissions for all source and destination processes. + // StrictMode is used to indicate whether to restrict ptrace operations for all source and destination processes. // Default is false. - // If set to false, it restricts ptrace-related permissions only for processes in other containers. - // If set to true, it restricts ptrace-related permissions for all processes, except those within the init mnt namespace. + // If set to false, it allows a process to perform trace and read operations on other processes within the same container, + // and also allows a process to be subjected to traceby and readby operations by other processes within the same container. + // If set to true, it prohibits all trace, read, traceby, and readby operations within the container. // +optional StrictMode bool `json:"strictMode,omitempty"` // Permissions are used to indicate which ptrace-related permissions of the target container should be restricted. // // Available values: all(*), trace, traceby, read, readby. - // trace, traceby - // For "write" operations, or other operations that are more dangerous, such as: ptrace attaching (PTRACE_ATTACH) to - // another process or calling process_vm_writev(2). + // - trace: prohibiting tracing of other processes. + // - read: prohibiting reading of other processes. + // - traceby: prohibiting being traced by other processes (excluding the host processes). + // - readby: prohibiting being read by other processes (excluding the host processes). // - // read, readby - // For "read" operations or other operations that are less dangerous, such as: get_robust_list(2); kcmp(2); reading - // /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file. + // The trace, traceby permissions for "write" operations, or other operations that are more dangerous, such as: + // ptrace attaching (PTRACE_ATTACH) to another process or calling process_vm_writev(2). // + // The read, readby permissions for "read" operations or other operations that are less dangerous, such as: + // get_robust_list(2); kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* file. Permissions []string `json:"permissions"` } diff --git a/config/crds/crd.varmor.org_armorprofiles.yaml b/config/crds/crd.varmor.org_armorprofiles.yaml index c1c4ec7..eaa76c9 100644 --- a/config/crds/crd.varmor.org_armorprofiles.yaml +++ b/config/crds/crd.varmor.org_armorprofiles.yaml @@ -250,9 +250,9 @@ spec: Note that the name field and selector field are mutually exclusive. type: string selector: - description: "LabelSelector is used to match workloads that meet - the specified conditions \n Note: The type of workloads is determined - by the KIND field." + description: LabelSelector is used to match workloads that meet + the specified conditions. Note that the selector field and name + field are mutually exclusive. properties: matchExpressions: description: matchExpressions is a list of label selector diff --git a/config/crds/crd.varmor.org_varmorclusterpolicies.yaml b/config/crds/crd.varmor.org_varmorclusterpolicies.yaml index 020c001..3e65725 100644 --- a/config/crds/crd.varmor.org_varmorclusterpolicies.yaml +++ b/config/crds/crd.varmor.org_varmorclusterpolicies.yaml @@ -262,27 +262,35 @@ spec: description: "Permissions are used to indicate which ptrace-related permissions of the target container should be restricted. \n Available values: all(*), - trace, traceby, read, readby. trace, traceby For - \"write\" operations, or other operations that are - more dangerous, such as: ptrace attaching (PTRACE_ATTACH) - to another process or calling process_vm_writev(2). - \n read, readby For \"read\" operations or other - operations that are less dangerous, such as: get_robust_list(2); - kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, - or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* - file." + trace, traceby, read, readby. - trace: prohibiting + tracing of other processes. - read: prohibiting + reading of other processes. - traceby: prohibiting + being traced by other processes (excluding the host + processes). - readby: prohibiting being read by + other processes (excluding the host processes). + \n The trace, traceby permissions for \"write\" + operations, or other operations that are more dangerous, + such as: ptrace attaching (PTRACE_ATTACH) to another + process or calling process_vm_writev(2). \n The + read, readby permissions for \"read\" operations + or other operations that are less dangerous, such + as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, + /proc/pid/environ, or /proc/pid/stat; or readlink(2) + of a /proc/pid/ns/* file." items: type: string type: array strictMode: description: StrictMode is used to indicate whether - to restrict ptrace permissions for all source and + to restrict ptrace operations for all source and destination processes. Default is false. If set - to false, it restricts ptrace-related permissions - only for processes in other containers. If set to - true, it restricts ptrace-related permissions for - all processes, except those within the init mnt - namespace. + to false, it allows a process to perform trace and + read operations on other processes within the same + container, and also allows a process to be subjected + to traceby and readby operations by other processes + within the same container. If set to true, it prohibits + all trace, read, traceby, and readby operations + within the container. type: boolean required: - permissions @@ -397,9 +405,9 @@ spec: Note that the name field and selector field are mutually exclusive. type: string selector: - description: "LabelSelector is used to match workloads that meet - the specified conditions \n Note: The type of workloads is determined - by the KIND field." + description: LabelSelector is used to match workloads that meet + the specified conditions. Note that the selector field and name + field are mutually exclusive. properties: matchExpressions: description: matchExpressions is a list of label selector diff --git a/config/crds/crd.varmor.org_varmorpolicies.yaml b/config/crds/crd.varmor.org_varmorpolicies.yaml index e0ac79c..d3b96c7 100644 --- a/config/crds/crd.varmor.org_varmorpolicies.yaml +++ b/config/crds/crd.varmor.org_varmorpolicies.yaml @@ -261,27 +261,35 @@ spec: description: "Permissions are used to indicate which ptrace-related permissions of the target container should be restricted. \n Available values: all(*), - trace, traceby, read, readby. trace, traceby For - \"write\" operations, or other operations that are - more dangerous, such as: ptrace attaching (PTRACE_ATTACH) - to another process or calling process_vm_writev(2). - \n read, readby For \"read\" operations or other - operations that are less dangerous, such as: get_robust_list(2); - kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, - or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* - file." + trace, traceby, read, readby. - trace: prohibiting + tracing of other processes. - read: prohibiting + reading of other processes. - traceby: prohibiting + being traced by other processes (excluding the host + processes). - readby: prohibiting being read by + other processes (excluding the host processes). + \n The trace, traceby permissions for \"write\" + operations, or other operations that are more dangerous, + such as: ptrace attaching (PTRACE_ATTACH) to another + process or calling process_vm_writev(2). \n The + read, readby permissions for \"read\" operations + or other operations that are less dangerous, such + as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, + /proc/pid/environ, or /proc/pid/stat; or readlink(2) + of a /proc/pid/ns/* file." items: type: string type: array strictMode: description: StrictMode is used to indicate whether - to restrict ptrace permissions for all source and + to restrict ptrace operations for all source and destination processes. Default is false. If set - to false, it restricts ptrace-related permissions - only for processes in other containers. If set to - true, it restricts ptrace-related permissions for - all processes, except those within the init mnt - namespace. + to false, it allows a process to perform trace and + read operations on other processes within the same + container, and also allows a process to be subjected + to traceby and readby operations by other processes + within the same container. If set to true, it prohibits + all trace, read, traceby, and readby operations + within the container. type: boolean required: - permissions @@ -396,9 +404,9 @@ spec: Note that the name field and selector field are mutually exclusive. type: string selector: - description: "LabelSelector is used to match workloads that meet - the specified conditions \n Note: The type of workloads is determined - by the KIND field." + description: LabelSelector is used to match workloads that meet + the specified conditions. Note that the selector field and name + field are mutually exclusive. properties: matchExpressions: description: matchExpressions is a list of label selector diff --git a/docs/getting_started/interface_specification.md b/docs/getting_started/interface_specification.md index 652a279..256b5fd 100644 --- a/docs/getting_started/interface_specification.md +++ b/docs/getting_started/interface_specification.md @@ -1,4 +1,3 @@ - # Interface Specification English | [简体中文](interface_specification.zh_CN.md) @@ -6,22 +5,22 @@ English | [简体中文](interface_specification.zh_CN.md) | Field | Subfield | Subfield | Description | |-------|----------|----------|-------------| -|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod -| |name
*string*|-|Optional. Name is used to specify a specific workload name. -| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers). -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note: the type of workloads is determined by the KIND field.* -|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp -| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth -| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules. -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules. -| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules. -| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma. -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|Optional. BpfRawRules is used to set custom BPF rules. -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads. -| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false) -| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. -|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection. +|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod| +| |name
*string*|-|Optional. Name is used to specify a specific workload name.
*Note that the name field and selector field are mutually exclusive.*| +| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers).| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note that the selector field and name field are mutually exclusive.*| +|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| +| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| +| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules.| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules.| +| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules.| +| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html).| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules.| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules.| +| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads.| +| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false)| +| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. | +|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection.| | ||PLACEHOLDER_PLACEHOD| ## AttackProtectionRules @@ -36,23 +35,32 @@ English | [简体中文](interface_specification.zh_CN.md) | Field | Subfield | Description | |-------|----------|-------------| -|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames. -| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `read(r), write(w), append(a), exec(e)` -|processes
*FileRule array*|-|Same as above. -|network
*NetworkRule* |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports. -|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, the processes in the same container will not be restricted. If set to true, even the processes in the same container will be restricted. (Default: false) -| |permissions
*string array*|Prohibited ptrace-related permissions. Available values: `trace, traceby, read, readby`.
- `trace`: Prohibiting process from tracing others.
- `read`: Prohibiting process from reading others.
- `traceby`: Prohibiting process from being traced by others, excluding host processes.
- `readby`: Prohibiting process from being read by others, excluding host processes. -|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2). -| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem. -| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html), `'all'` represents matching all mount flags.
Available values: `all, ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount` +|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames.| +| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `all(*), read(r), write(w), append(a), exec(e)`| +|processes
*FileRule array*|-|Same as above.| +|network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| +| |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| +|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| +| |permissions
*string array*|Prohibited ptrace-related operations. Available values: `all(*), trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other processes.
- `read`: prohibiting reading of other processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes).| +|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| +| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| +| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| |PLACEHOLDER_|PLACEHOLDER_PLACEHOD| +## NetworkSocketRule + +| Field | Description | +|-------|-------------| +|domains
*string array*|Optional. Domains specifies the communication domains of socket.
Available values: `all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| +|types
*string array*|Optional. Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are mutually exclusive.
Available values: `all(*), icmp, tcp, udp`| +|PLACEHOLDER| ## NetworkEgressRule | Field | Description | |-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be. -|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535` +|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| +|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be.| +|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535`| |PLACEHOLDER| diff --git a/docs/getting_started/interface_specification.zh_CN.md b/docs/getting_started/interface_specification.zh_CN.md index 77944c6..5a90fa2 100644 --- a/docs/getting_started/interface_specification.zh_CN.md +++ b/docs/getting_started/interface_specification.zh_CN.md @@ -5,52 +5,61 @@ |字段|子字段|子字段|描述| |---|-----|-----|---| -|target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。 -| |name
*string*|-|可选字段,用于指定防护目标的对象名称。 -| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers) -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。 -|policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp -| |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth -| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。 -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。 -| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。 -| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。 -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。 -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。 -| ||privileged
*bool*|可选字段,若要对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false) -| ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false) -| |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能] -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。 +|target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| +| |name
*string*|-|可选字段,用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| +| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +|policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| +| |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| +| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。| +| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。| +| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| +| ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| +| |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| +|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules |字段|描述| |---|----| -|rules
*string array*|要使用的内置规则列表。 -|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。 -|PLACEHOLDER| +|rules
*string array*|要使用的内置规则列表。| +|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| +|PLACEHOLDER|| ## BpfRawRules |字段|子字段|描述| |---|-----|---| -|files
*FileRule array* |pattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配文件路径、文件名称。 -| |permissions
*string array*|禁止使用的权限,其中 write 权限隐式包含 append, rename, hard link, symbol link 权限。
可用值:`read(r), write(w), append(a), exec(e)` -|processes
*FileRule array*|-|同上 -|network
*NetworkRule* |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。 -|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,同一容器内的进程将不受限制。如果将设置为 true,即使是同一容器内的进程也将受到限制。(默认值:false) -| |permissions
*string array*|禁止使用的权限,可用值: `trace, read, traceby, readby`
- `trace`: 禁止进程跟踪其他进程
- `read`: 禁止进程读取其他进程
- `traceby`: 禁止进程被其他进程跟踪,宿主机进程除外
- `readby`: 禁止进程被其他进程读取,宿主机进程除外 -|mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。 -| |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。 -| |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似,其中 `all` 代表匹配所有 flags。
可用值:`all, ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount` +|files
*FileRule array* |pattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配文件路径、文件名称。| +| |permissions
*string array*|禁止使用的权限,其中 write 权限隐式包含 append, rename, hard link, symbol link 权限。
可用值:`all(*), read(r), write(w), append(a), exec(e)`| +|processes
*FileRule array*|-|同上| +|network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| +| |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| +|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| +| |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| +|mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| +| |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| +| |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似。
可用值:`all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| |PLACEHOLDER_|PLACEHOLDER_PLACEHOD| +## NetworkSocketRule +|字段|描述| +|---|----| +|domains
*string array*|可选字段。用于指定禁止使用的套接字通信域。
可用值:`all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| +|types
*string array*|可选字段。用于指定禁止使用的套接字通信语义。
可用值:`all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`
注意:protocols 和 types 字段互斥,不能同时存在。| +|PLACEHOLDER| + ## NetworkEgressRule |字段|描述| |---|----| -|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
(注:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时出现) -|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。 -|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535` -|PLACEHOLDER| +|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| +|PLACEHOLDER|| diff --git a/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml b/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml index c1c4ec7..eaa76c9 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml @@ -250,9 +250,9 @@ spec: Note that the name field and selector field are mutually exclusive. type: string selector: - description: "LabelSelector is used to match workloads that meet - the specified conditions \n Note: The type of workloads is determined - by the KIND field." + description: LabelSelector is used to match workloads that meet + the specified conditions. Note that the selector field and name + field are mutually exclusive. properties: matchExpressions: description: matchExpressions is a list of label selector diff --git a/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml b/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml index 020c001..3e65725 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml @@ -262,27 +262,35 @@ spec: description: "Permissions are used to indicate which ptrace-related permissions of the target container should be restricted. \n Available values: all(*), - trace, traceby, read, readby. trace, traceby For - \"write\" operations, or other operations that are - more dangerous, such as: ptrace attaching (PTRACE_ATTACH) - to another process or calling process_vm_writev(2). - \n read, readby For \"read\" operations or other - operations that are less dangerous, such as: get_robust_list(2); - kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, - or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* - file." + trace, traceby, read, readby. - trace: prohibiting + tracing of other processes. - read: prohibiting + reading of other processes. - traceby: prohibiting + being traced by other processes (excluding the host + processes). - readby: prohibiting being read by + other processes (excluding the host processes). + \n The trace, traceby permissions for \"write\" + operations, or other operations that are more dangerous, + such as: ptrace attaching (PTRACE_ATTACH) to another + process or calling process_vm_writev(2). \n The + read, readby permissions for \"read\" operations + or other operations that are less dangerous, such + as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, + /proc/pid/environ, or /proc/pid/stat; or readlink(2) + of a /proc/pid/ns/* file." items: type: string type: array strictMode: description: StrictMode is used to indicate whether - to restrict ptrace permissions for all source and + to restrict ptrace operations for all source and destination processes. Default is false. If set - to false, it restricts ptrace-related permissions - only for processes in other containers. If set to - true, it restricts ptrace-related permissions for - all processes, except those within the init mnt - namespace. + to false, it allows a process to perform trace and + read operations on other processes within the same + container, and also allows a process to be subjected + to traceby and readby operations by other processes + within the same container. If set to true, it prohibits + all trace, read, traceby, and readby operations + within the container. type: boolean required: - permissions @@ -397,9 +405,9 @@ spec: Note that the name field and selector field are mutually exclusive. type: string selector: - description: "LabelSelector is used to match workloads that meet - the specified conditions \n Note: The type of workloads is determined - by the KIND field." + description: LabelSelector is used to match workloads that meet + the specified conditions. Note that the selector field and name + field are mutually exclusive. properties: matchExpressions: description: matchExpressions is a list of label selector diff --git a/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml b/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml index e0ac79c..d3b96c7 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml @@ -261,27 +261,35 @@ spec: description: "Permissions are used to indicate which ptrace-related permissions of the target container should be restricted. \n Available values: all(*), - trace, traceby, read, readby. trace, traceby For - \"write\" operations, or other operations that are - more dangerous, such as: ptrace attaching (PTRACE_ATTACH) - to another process or calling process_vm_writev(2). - \n read, readby For \"read\" operations or other - operations that are less dangerous, such as: get_robust_list(2); - kcmp(2); reading /proc/pid/auxv, /proc/pid/environ, - or /proc/pid/stat; or readlink(2) of a /proc/pid/ns/* - file." + trace, traceby, read, readby. - trace: prohibiting + tracing of other processes. - read: prohibiting + reading of other processes. - traceby: prohibiting + being traced by other processes (excluding the host + processes). - readby: prohibiting being read by + other processes (excluding the host processes). + \n The trace, traceby permissions for \"write\" + operations, or other operations that are more dangerous, + such as: ptrace attaching (PTRACE_ATTACH) to another + process or calling process_vm_writev(2). \n The + read, readby permissions for \"read\" operations + or other operations that are less dangerous, such + as: get_robust_list(2); kcmp(2); reading /proc/pid/auxv, + /proc/pid/environ, or /proc/pid/stat; or readlink(2) + of a /proc/pid/ns/* file." items: type: string type: array strictMode: description: StrictMode is used to indicate whether - to restrict ptrace permissions for all source and + to restrict ptrace operations for all source and destination processes. Default is false. If set - to false, it restricts ptrace-related permissions - only for processes in other containers. If set to - true, it restricts ptrace-related permissions for - all processes, except those within the init mnt - namespace. + to false, it allows a process to perform trace and + read operations on other processes within the same + container, and also allows a process to be subjected + to traceby and readby operations by other processes + within the same container. If set to true, it prohibits + all trace, read, traceby, and readby operations + within the container. type: boolean required: - permissions @@ -396,9 +404,9 @@ spec: Note that the name field and selector field are mutually exclusive. type: string selector: - description: "LabelSelector is used to match workloads that meet - the specified conditions \n Note: The type of workloads is determined - by the KIND field." + description: LabelSelector is used to match workloads that meet + the specified conditions. Note that the selector field and name + field are mutually exclusive. properties: matchExpressions: description: matchExpressions is a list of label selector diff --git a/website/docs/getting_started/interface_specification.md b/website/docs/getting_started/interface_specification.md index b106315..5099b3d 100644 --- a/website/docs/getting_started/interface_specification.md +++ b/website/docs/getting_started/interface_specification.md @@ -9,52 +9,62 @@ description: The interface specification of vArmor. | Field | Subfield | Subfield | Description | |-------|----------|----------|-------------| -|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod -| |name
*string*|-|Optional. Name is used to specify a specific workload name. -| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers). -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note: the type of workloads is determined by the KIND field.* -|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp -| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth -| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules. -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules. -| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules. -| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html). -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules. -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules. -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads. -| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false) -| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. -|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection. +|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod| +| |name
*string*|-|Optional. Name is used to specify a specific workload name.
*Note that the name field and selector field are mutually exclusive.*| +| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers).| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note that the selector field and name field are mutually exclusive.*| +|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| +| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| +| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules.| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules.| +| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules.| +| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html).| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules.| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules.| +| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads.| +| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false)| +| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. | +|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection.| | ||PLACEHOLDER_PLACEHOD| ## AttackProtectionRules | Field | Description | |-------|-------------| -|rules
*string array*|List of built-in attack protection rules to be used. -|targets
*string array*|Optional. Targets are used to specify the workloads to which the policy applies. They must be specified as full paths to executable files, and this feature is only effective when using AppArmor as the enforcer. -|PLACEHOLDER +|rules
*string array*|List of built-in attack protection rules to be used.| +|targets
*string array*|Optional. Targets are used to specify the workloads to which the policy applies. They must be specified as full paths to executable files, and this feature is only effective when using AppArmor as the enforcer.| +|PLACEHOLDER|| ## BpfRawRules | Field | Subfield | Description | |-------|----------|-------------| -|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames. -| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `read(r), write(w), append(a), exec(e)` -|processes
*FileRule array*|-|Same as above. -|network
*NetworkRule* |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports. -|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it restricts ptrace-related permissions only for processes in other containers. If set to true, it restricts ptrace-related permissions for all processes, except those within the init mnt namespace. (Default: false) -| |permissions
*string array*|Prohibited ptrace-related permissions. Available values: `trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other container processes.
- `read`: prohibiting reading of other container processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes). -|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2). -| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem. -| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html), `'all'` represents matching all mount flags.
Available values: `all, ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount` +|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames.| +| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `all(*), read(r), write(w), append(a), exec(e)`| +|processes
*FileRule array*|-|Same as above.| +|network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| +| |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| +|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| +| |permissions
*string array*|Prohibited ptrace-related operations. Available values: `all(*), trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other processes.
- `read`: prohibiting reading of other processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes).| +|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| +| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| +| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| |PLACEHOLDER_|PLACEHOLDER_PLACEHOD| +## NetworkSocketRule + +| Field | Description | +|-------|-------------| +|domains
*string array*|Optional. Domains specifies the communication domains of socket.
Available values: `all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| +|types
*string array*|Optional. Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are mutually exclusive.
Available values: `all(*), icmp, tcp, udp`| +|PLACEHOLDER|| ## NetworkEgressRule + | Field | Description | |-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be. -|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535` -|PLACEHOLDER| +|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| +|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be.| +|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535`| +|PLACEHOLDER|| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md index b106315..caee27e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md @@ -3,58 +3,67 @@ sidebar_position: 4 description: The interface specification of vArmor. --- -# Interface Specification +# 接口说明 ## VarmorPolicySpec / VarmorClusterPolicySpec -| Field | Subfield | Subfield | Description | -|-------|----------|----------|-------------| -|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod -| |name
*string*|-|Optional. Name is used to specify a specific workload name. -| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers). -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note: the type of workloads is determined by the KIND field.* -|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp -| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth -| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules. -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules. -| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules. -| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html). -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules. -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules. -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads. -| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false) -| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. -|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection. -| ||PLACEHOLDER_PLACEHOD| +|字段|子字段|子字段|描述| +|---|-----|-----|---| +|target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| +| |name
*string*|-|可选字段,用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| +| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +|policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| +| |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| +| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。| +| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。| +| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| +| ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| +| |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| +|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +| ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules -| Field | Description | -|-------|-------------| -|rules
*string array*|List of built-in attack protection rules to be used. -|targets
*string array*|Optional. Targets are used to specify the workloads to which the policy applies. They must be specified as full paths to executable files, and this feature is only effective when using AppArmor as the enforcer. -|PLACEHOLDER +|字段|描述| +|---|----| +|rules
*string array*|要使用的内置规则列表。| +|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| +|PLACEHOLDER|| ## BpfRawRules -| Field | Subfield | Description | -|-------|----------|-------------| -|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames. -| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `read(r), write(w), append(a), exec(e)` -|processes
*FileRule array*|-|Same as above. -|network
*NetworkRule* |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports. -|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it restricts ptrace-related permissions only for processes in other containers. If set to true, it restricts ptrace-related permissions for all processes, except those within the init mnt namespace. (Default: false) -| |permissions
*string array*|Prohibited ptrace-related permissions. Available values: `trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other container processes.
- `read`: prohibiting reading of other container processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes). -|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2). -| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem. -| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html), `'all'` represents matching all mount flags.
Available values: `all, ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount` +|字段|子字段|描述| +|---|-----|---| +|files
*FileRule array* |pattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配文件路径、文件名称。| +| |permissions
*string array*|禁止使用的权限,其中 write 权限隐式包含 append, rename, hard link, symbol link 权限。
可用值:`all(*), read(r), write(w), append(a), exec(e)`| +|processes
*FileRule array*|-|同上| +|network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| +| |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| +|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| +| |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| +|mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| +| |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| +| |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似。
可用值:`all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| |PLACEHOLDER_|PLACEHOLDER_PLACEHOD| +## NetworkSocketRule +|字段|描述| +|---|----| +|domains
*string array*|可选字段。用于指定禁止使用的套接字通信域。
可用值:`all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| +|types
*string array*|可选字段。用于指定禁止使用的套接字通信语义。
可用值:`all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`
注意:protocols 和 types 字段互斥,不能同时存在。| +|PLACEHOLDER| ## NetworkEgressRule -| Field | Description | -|-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be. -|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535` -|PLACEHOLDER| + +|字段|描述| +|---|----| +|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| +|PLACEHOLDER|| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md index b106315..caee27e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md @@ -3,58 +3,67 @@ sidebar_position: 4 description: The interface specification of vArmor. --- -# Interface Specification +# 接口说明 ## VarmorPolicySpec / VarmorClusterPolicySpec -| Field | Subfield | Subfield | Description | -|-------|----------|----------|-------------| -|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod -| |name
*string*|-|Optional. Name is used to specify a specific workload name. -| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers). -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note: the type of workloads is determined by the KIND field.* -|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp -| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth -| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules. -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules. -| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules. -| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html). -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules. -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules. -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads. -| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false) -| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. -|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection. -| ||PLACEHOLDER_PLACEHOD| +|字段|子字段|子字段|描述| +|---|-----|-----|---| +|target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| +| |name
*string*|-|可选字段,用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| +| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +|policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| +| |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| +| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。| +| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。| +| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| +| ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| +| |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| +|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +| ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules -| Field | Description | -|-------|-------------| -|rules
*string array*|List of built-in attack protection rules to be used. -|targets
*string array*|Optional. Targets are used to specify the workloads to which the policy applies. They must be specified as full paths to executable files, and this feature is only effective when using AppArmor as the enforcer. -|PLACEHOLDER +|字段|描述| +|---|----| +|rules
*string array*|要使用的内置规则列表。| +|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| +|PLACEHOLDER|| ## BpfRawRules -| Field | Subfield | Description | -|-------|----------|-------------| -|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames. -| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `read(r), write(w), append(a), exec(e)` -|processes
*FileRule array*|-|Same as above. -|network
*NetworkRule* |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports. -|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it restricts ptrace-related permissions only for processes in other containers. If set to true, it restricts ptrace-related permissions for all processes, except those within the init mnt namespace. (Default: false) -| |permissions
*string array*|Prohibited ptrace-related permissions. Available values: `trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other container processes.
- `read`: prohibiting reading of other container processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes). -|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2). -| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem. -| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html), `'all'` represents matching all mount flags.
Available values: `all, ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount` +|字段|子字段|描述| +|---|-----|---| +|files
*FileRule array* |pattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配文件路径、文件名称。| +| |permissions
*string array*|禁止使用的权限,其中 write 权限隐式包含 append, rename, hard link, symbol link 权限。
可用值:`all(*), read(r), write(w), append(a), exec(e)`| +|processes
*FileRule array*|-|同上| +|network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| +| |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| +|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| +| |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| +|mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| +| |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| +| |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似。
可用值:`all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| |PLACEHOLDER_|PLACEHOLDER_PLACEHOD| +## NetworkSocketRule +|字段|描述| +|---|----| +|domains
*string array*|可选字段。用于指定禁止使用的套接字通信域。
可用值:`all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| +|types
*string array*|可选字段。用于指定禁止使用的套接字通信语义。
可用值:`all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`
注意:protocols 和 types 字段互斥,不能同时存在。| +|PLACEHOLDER| ## NetworkEgressRule -| Field | Description | -|-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be. -|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535` -|PLACEHOLDER| + +|字段|描述| +|---|----| +|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| +|PLACEHOLDER|| diff --git a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md index b106315..5099b3d 100644 --- a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md +++ b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md @@ -9,52 +9,62 @@ description: The interface specification of vArmor. | Field | Subfield | Subfield | Description | |-------|----------|----------|-------------| -|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod -| |name
*string*|-|Optional. Name is used to specify a specific workload name. -| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers). -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note: the type of workloads is determined by the KIND field.* -|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp -| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth -| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules. -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules. -| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules. -| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html). -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules. -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules. -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads. -| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false) -| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. -|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection. +|target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod| +| |name
*string*|-|Optional. Name is used to specify a specific workload name.
*Note that the name field and selector field are mutually exclusive.*| +| |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers).| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note that the selector field and name field are mutually exclusive.*| +|policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| +| |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| +| |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules.| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|Optional. AttackProtectionRules are used to specify the built-in attack protection rules.| +| ||vulMitigationRules
*string array*|Optional. VulMitigationRules are used to specify the built-in vulnerability mitigation rules.| +| ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html).| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules.| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules.| +| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads.| +| ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false)| +| |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. | +|updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection.| | ||PLACEHOLDER_PLACEHOD| ## AttackProtectionRules | Field | Description | |-------|-------------| -|rules
*string array*|List of built-in attack protection rules to be used. -|targets
*string array*|Optional. Targets are used to specify the workloads to which the policy applies. They must be specified as full paths to executable files, and this feature is only effective when using AppArmor as the enforcer. -|PLACEHOLDER +|rules
*string array*|List of built-in attack protection rules to be used.| +|targets
*string array*|Optional. Targets are used to specify the workloads to which the policy applies. They must be specified as full paths to executable files, and this feature is only effective when using AppArmor as the enforcer.| +|PLACEHOLDER|| ## BpfRawRules | Field | Subfield | Description | |-------|----------|-------------| -|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames. -| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `read(r), write(w), append(a), exec(e)` -|processes
*FileRule array*|-|Same as above. -|network
*NetworkRule* |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports. -|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it restricts ptrace-related permissions only for processes in other containers. If set to true, it restricts ptrace-related permissions for all processes, except those within the init mnt namespace. (Default: false) -| |permissions
*string array*|Prohibited ptrace-related permissions. Available values: `trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other container processes.
- `read`: prohibiting reading of other container processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes). -|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2). -| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem. -| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html), `'all'` represents matching all mount flags.
Available values: `all, ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount` +|files
*FileRule array* |pattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax, used for matching file paths and filenames.| +| |permissions
*string array*|Permissions are used to specify the file permissions to be disabled.
Available values: `all(*), read(r), write(w), append(a), exec(e)`| +|processes
*FileRule array*|-|Same as above.| +|network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| +| |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| +|ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| +| |permissions
*string array*|Prohibited ptrace-related operations. Available values: `all(*), trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other processes.
- `read`: prohibiting reading of other processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes).| +|mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| +| |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| +| |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| |PLACEHOLDER_|PLACEHOLDER_PLACEHOD| +## NetworkSocketRule + +| Field | Description | +|-------|-------------| +|domains
*string array*|Optional. Domains specifies the communication domains of socket.
Available values: `all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| +|types
*string array*|Optional. Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are mutually exclusive.
Available values: `all(*), icmp, tcp, udp`| +|PLACEHOLDER|| ## NetworkEgressRule + | Field | Description | |-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be. -|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535` -|PLACEHOLDER| +|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| +|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be.| +|port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535`| +|PLACEHOLDER|| From 573a05aadc5ee3ca1ceef4fb4849ca84e84e2de2 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sat, 30 Nov 2024 16:33:51 +0800 Subject: [PATCH 3/9] docs: Fix typo --- docs/getting_started/interface_specification.zh_CN.md | 2 +- .../current/getting_started/interface_specification.md | 2 +- .../version-v0.6/getting_started/interface_specification.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting_started/interface_specification.zh_CN.md b/docs/getting_started/interface_specification.zh_CN.md index 5a90fa2..c234146 100644 --- a/docs/getting_started/interface_specification.zh_CN.md +++ b/docs/getting_started/interface_specification.zh_CN.md @@ -20,7 +20,7 @@ | ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md index caee27e..569156e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md @@ -24,7 +24,7 @@ description: The interface specification of vArmor. | ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md index caee27e..569156e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md @@ -24,7 +24,7 @@ description: The interface specification of vArmor. | ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment, StatefulSet, or DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules From 9ee864e4a33f57b65158ea2935cd0dc9519d1c0b Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sat, 30 Nov 2024 16:35:42 +0800 Subject: [PATCH 4/9] docs: Fix typo --- .../interface_specification.zh_CN.md | 32 +++++++++---------- .../interface_specification.md | 32 +++++++++---------- .../interface_specification.md | 32 +++++++++---------- 3 files changed, 48 insertions(+), 48 deletions(-) diff --git a/docs/getting_started/interface_specification.zh_CN.md b/docs/getting_started/interface_specification.zh_CN.md index c234146..c711f0a 100644 --- a/docs/getting_started/interface_specification.zh_CN.md +++ b/docs/getting_started/interface_specification.zh_CN.md @@ -6,21 +6,21 @@ |字段|子字段|子字段|描述| |---|-----|-----|---| |target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| -| |name
*string*|-|可选字段,用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| -| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +| |name
*string*|-|可选字段。用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| +| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| |policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| -| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。| -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。| -| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。| -| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。| -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| -| ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| |enhanceProtect|hardeningRules
*string array*|可选字段。用于指定要使用的内置加固规则。| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段。用于指定要使用的内置规则。| +| ||vulMitigationRules
*string array*|可选字段。用于指定要使用的内置规则。| +| ||appArmorRawRules
*string array*|可选字段。用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段。用于支持用户设置自定义的 BPF 黑名单规则。| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段。用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| +| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +|updateExistingWorkloads
*bool*|-|-|可选字段。用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules @@ -28,7 +28,7 @@ |字段|描述| |---|----| |rules
*string array*|要使用的内置规则列表。| -|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| +|targets
*string array*|可选字段。仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| |PLACEHOLDER|| ## BpfRawRules @@ -40,7 +40,7 @@ |processes
*FileRule array*|-|同上| |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| -|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| +|ptrace
*PtraceRule* |strictMode
*bool*|可选字段。如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| | |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| |mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| | |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| @@ -59,7 +59,7 @@ |字段|描述| |---|----| -|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| -|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| -|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md index 569156e..570859e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md @@ -10,21 +10,21 @@ description: The interface specification of vArmor. |字段|子字段|子字段|描述| |---|-----|-----|---| |target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| -| |name
*string*|-|可选字段,用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| -| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +| |name
*string*|-|可选字段。用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| +| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| |policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| -| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。| -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。| -| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。| -| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。| -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| -| ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| |enhanceProtect|hardeningRules
*string array*|可选字段。用于指定要使用的内置加固规则。| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段。用于指定要使用的内置规则。| +| ||vulMitigationRules
*string array*|可选字段。用于指定要使用的内置规则。| +| ||appArmorRawRules
*string array*|可选字段。用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段。用于支持用户设置自定义的 BPF 黑名单规则。| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段。用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| +| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +|updateExistingWorkloads
*bool*|-|-|可选字段。用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules @@ -32,7 +32,7 @@ description: The interface specification of vArmor. |字段|描述| |---|----| |rules
*string array*|要使用的内置规则列表。| -|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| +|targets
*string array*|可选字段。仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| |PLACEHOLDER|| ## BpfRawRules @@ -44,7 +44,7 @@ description: The interface specification of vArmor. |processes
*FileRule array*|-|同上| |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| -|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| +|ptrace
*PtraceRule* |strictMode
*bool*|可选字段。如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| | |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| |mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| | |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| @@ -63,7 +63,7 @@ description: The interface specification of vArmor. |字段|描述| |---|----| -|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| -|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| -|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md index 569156e..570859e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md @@ -10,21 +10,21 @@ description: The interface specification of vArmor. |字段|子字段|子字段|描述| |---|-----|-----|---| |target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| -| |name
*string*|-|可选字段,用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| -| |containers
*string array*|-|可选字段,用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段,用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +| |name
*string*|-|可选字段。用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| +| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| |policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| -| |enhanceProtect|hardeningRules
*string array*|可选字段,用于指定要使用的内置加固规则。| -| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段,用于指定要使用的内置规则。| -| ||vulMitigationRules
*string array*|可选字段,用于指定要使用的内置规则。| -| ||appArmorRawRules
*string array*|可选字段,用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| -| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段,用于支持用户设置自定义的 BPF 黑名单规则。| -| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段,用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| -| ||privileged
*bool*|可选字段,当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| |enhanceProtect|hardeningRules
*string array*|可选字段。用于指定要使用的内置加固规则。| +| ||attackProtectionRules
*[AttackProtectionRules](#attackprotectionrules) array*|可选字段。用于指定要使用的内置规则。| +| ||vulMitigationRules
*string array*|可选字段。用于指定要使用的内置规则。| +| ||appArmorRawRules
*string array*|可选字段。用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| +| ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段。用于支持用户设置自定义的 BPF 黑名单规则。| +| ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段。用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| +| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| -|updateExistingWorkloads
*bool*|-|-|可选字段,用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| +|updateExistingWorkloads
*bool*|-|-|可选字段。用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| | ||PLACEHOLDER_PLACEHOLD| ## AttackProtectionRules @@ -32,7 +32,7 @@ description: The interface specification of vArmor. |字段|描述| |---|----| |rules
*string array*|要使用的内置规则列表。| -|targets
*string array*|可选字段,仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| +|targets
*string array*|可选字段。仅对指定的可执行文件列表开启 Rules 中的内置规则,此功能仅支持 AppArmor enforcer。| |PLACEHOLDER|| ## BpfRawRules @@ -44,7 +44,7 @@ description: The interface specification of vArmor. |processes
*FileRule array*|-|同上| |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| -|ptrace
*PtraceRule* |strictMode
*bool*|可选字段,如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| +|ptrace
*PtraceRule* |strictMode
*bool*|可选字段。如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| | |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| |mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| | |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| @@ -63,7 +63,7 @@ description: The interface specification of vArmor. |字段|描述| |---|----| -|ipBlock
*string*|可选字段,可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| -|ip
*string*|可选字段,任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| -|port
*int*|可选字段,用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| From 0dba70aed849f1d788e8983a6a28abd3a31a2a95 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sat, 30 Nov 2024 16:59:39 +0800 Subject: [PATCH 5/9] docs: Fix typo --- apis/varmor/v1beta1/varmorpolicy_types.go | 5 ++--- docs/getting_started/interface_specification.md | 10 +++++----- .../getting_started/interface_specification.zh_CN.md | 12 ++++++------ .../docs/getting_started/interface_specification.md | 10 +++++----- .../getting_started/interface_specification.md | 12 ++++++------ .../getting_started/interface_specification.md | 12 ++++++------ .../getting_started/interface_specification.md | 10 +++++----- 7 files changed, 35 insertions(+), 36 deletions(-) diff --git a/apis/varmor/v1beta1/varmorpolicy_types.go b/apis/varmor/v1beta1/varmorpolicy_types.go index 162e94d..e5ea833 100644 --- a/apis/varmor/v1beta1/varmorpolicy_types.go +++ b/apis/varmor/v1beta1/varmorpolicy_types.go @@ -30,7 +30,7 @@ type Target struct { // Kind is used to specify the type of workloads for the protection targets. // Available values: Deployment, StatefulSet, DaemonSet, Pod. Kind string `json:"kind"` - // Name is used to specify a specific workload name. Note that the name field and selector field are mutually exclusive. + // Name is used to specify a specific workload name. // +optional Name string `json:"name,omitempty"` // Containers are used to specify the names of the protected containers. If it is empty, sandbox protection @@ -84,8 +84,7 @@ type NetworkSocketRule struct { // xdp, mctp // Domains []string `json:"domains,omitempty"` - // Types specifies the communication semantics of socket. Note that the types field and protocols field - // are mutually exclusive. + // Types specifies the communication semantics of socket. // // Available values: all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet // diff --git a/docs/getting_started/interface_specification.md b/docs/getting_started/interface_specification.md index 256b5fd..4abd261 100644 --- a/docs/getting_started/interface_specification.md +++ b/docs/getting_started/interface_specification.md @@ -6,9 +6,9 @@ English | [简体中文](interface_specification.zh_CN.md) | Field | Subfield | Subfield | Description | |-------|----------|----------|-------------| |target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod| -| |name
*string*|-|Optional. Name is used to specify a specific workload name.
*Note that the name field and selector field are mutually exclusive.*| +| |name
*string*|-|Optional. Name is used to specify a specific workload name.| | |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers).| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note that the selector field and name field are mutually exclusive.*| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
Note that the selector field and name field are mutually exclusive.| |policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| | |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules.| @@ -41,7 +41,7 @@ English | [简体中文](interface_specification.zh_CN.md) |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| |ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| -| |permissions
*string array*|Prohibited ptrace-related operations. Available values: `all(*), trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other processes.
- `read`: prohibiting reading of other processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes).| +| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`.
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| |mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| | |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| | |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| @@ -52,8 +52,8 @@ English | [简体中文](interface_specification.zh_CN.md) | Field | Description | |-------|-------------| |domains
*string array*|Optional. Domains specifies the communication domains of socket.
Available values: `all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| -|types
*string array*|Optional. Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| -|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are mutually exclusive.
Available values: `all(*), icmp, tcp, udp`| +|types
*string array*|Optional. Types specifies the communication semantics of socket.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket.
Available values: `all(*), icmp, tcp, udp`

Note that the protocols field and types field are mutually exclusive. | |PLACEHOLDER| ## NetworkEgressRule diff --git a/docs/getting_started/interface_specification.zh_CN.md b/docs/getting_started/interface_specification.zh_CN.md index c711f0a..d381cb8 100644 --- a/docs/getting_started/interface_specification.zh_CN.md +++ b/docs/getting_started/interface_specification.zh_CN.md @@ -6,9 +6,9 @@ |字段|子字段|子字段|描述| |---|-----|-----|---| |target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| -| |name
*string*|-|可选字段。用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| -| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +| |name
*string*|-|可选字段。用于指定防护目标的对象名称。| +| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。

注意 selector 字段与 name 字段互斥,不能同时存在。| |policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| | |enhanceProtect|hardeningRules
*string array*|可选字段。用于指定要使用的内置加固规则。| @@ -41,7 +41,7 @@ |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| |ptrace
*PtraceRule* |strictMode
*bool*|可选字段。如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| -| |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| +| |permissions
*string array*|禁止使用 ptrace 相关操作。
可用值: `all(*), trace, read, traceby, readby`
- trace: 禁止跟踪其他进程
- read: 禁止读取其他进程
- traceby: 禁止被其他进程跟踪,宿主机进程除外
- readby: 禁止被其他进程读取,宿主机进程除外| |mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| | |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| | |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似。
可用值:`all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| @@ -52,14 +52,14 @@ |---|----| |domains
*string array*|可选字段。用于指定禁止使用的套接字通信域。
可用值:`all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| |types
*string array*|可选字段。用于指定禁止使用的套接字通信语义。
可用值:`all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| -|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`
注意:protocols 和 types 字段互斥,不能同时存在。| +|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`

注意:protocols 和 types 字段互斥,不能同时存在。| |PLACEHOLDER| ## NetworkEgressRule |字段|描述| |---|----| -|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。

注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| |ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| |port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/docs/getting_started/interface_specification.md b/website/docs/getting_started/interface_specification.md index 5099b3d..d0cdd1a 100644 --- a/website/docs/getting_started/interface_specification.md +++ b/website/docs/getting_started/interface_specification.md @@ -10,9 +10,9 @@ description: The interface specification of vArmor. | Field | Subfield | Subfield | Description | |-------|----------|----------|-------------| |target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod| -| |name
*string*|-|Optional. Name is used to specify a specific workload name.
*Note that the name field and selector field are mutually exclusive.*| +| |name
*string*|-|Optional. Name is used to specify a specific workload name.| | |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers).| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note that the selector field and name field are mutually exclusive.*| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.

Note that the selector field and name field are mutually exclusive.| |policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| | |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules.| @@ -45,7 +45,7 @@ description: The interface specification of vArmor. |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| |ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| -| |permissions
*string array*|Prohibited ptrace-related operations. Available values: `all(*), trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other processes.
- `read`: prohibiting reading of other processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes).| +| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`.
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| |mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| | |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| | |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| @@ -56,8 +56,8 @@ description: The interface specification of vArmor. | Field | Description | |-------|-------------| |domains
*string array*|Optional. Domains specifies the communication domains of socket.
Available values: `all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| -|types
*string array*|Optional. Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| -|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are mutually exclusive.
Available values: `all(*), icmp, tcp, udp`| +|types
*string array*|Optional. Types specifies the communication semantics of socket.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket.
Available values: `all(*), icmp, tcp, udp`

Note that the protocols field and types field are mutually exclusive. | |PLACEHOLDER|| ## NetworkEgressRule diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md index 570859e..e0713d2 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md @@ -10,9 +10,9 @@ description: The interface specification of vArmor. |字段|子字段|子字段|描述| |---|-----|-----|---| |target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| -| |name
*string*|-|可选字段。用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| -| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +| |name
*string*|-|可选字段。用于指定防护目标的对象名称。| +| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。

注意 selector 字段与 name 字段互斥,不能同时存在。| |policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| | |enhanceProtect|hardeningRules
*string array*|可选字段。用于指定要使用的内置加固规则。| @@ -45,7 +45,7 @@ description: The interface specification of vArmor. |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| |ptrace
*PtraceRule* |strictMode
*bool*|可选字段。如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| -| |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| +| |permissions
*string array*|禁止使用 ptrace 相关操作。
可用值: `all(*), trace, read, traceby, readby`
- trace: 禁止跟踪其他进程
- read: 禁止读取其他进程
- traceby: 禁止被其他进程跟踪,宿主机进程除外
- readby: 禁止被其他进程读取,宿主机进程除外| |mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| | |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| | |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似。
可用值:`all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| @@ -56,14 +56,14 @@ description: The interface specification of vArmor. |---|----| |domains
*string array*|可选字段。用于指定禁止使用的套接字通信域。
可用值:`all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| |types
*string array*|可选字段。用于指定禁止使用的套接字通信语义。
可用值:`all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| -|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`
注意:protocols 和 types 字段互斥,不能同时存在。| +|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`

注意:protocols 和 types 字段互斥,不能同时存在。| |PLACEHOLDER| ## NetworkEgressRule |字段|描述| |---|----| -|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。

注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| |ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| |port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md index 570859e..e0713d2 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md @@ -10,9 +10,9 @@ description: The interface specification of vArmor. |字段|子字段|子字段|描述| |---|-----|-----|---| |target|kind
*string*|-|用于指定防护目标的 Workloads 类型。
可用值: Deployment, StatefulSet, DaemonSet, Pod。| -| |name
*string*|-|可选字段。用于指定防护目标的对象名称。注意:name 字段与 selector 字段互斥,不能同时存在。| -| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(注:不含 initContainers, ephemeralContainers)| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。注意 selector 字段与 name 字段互斥,不能同时存在。| +| |name
*string*|-|可选字段。用于指定防护目标的对象名称。| +| |containers
*string array*|-|可选字段。用于指定防护目标的容器名,如果为空默认对 Workloads 中的所有容器开启沙箱防护。(不含 initContainers, ephemeralContainers)| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|可选字段。用于根据标签选择器识别防护目标,并开启沙箱防护。

注意 selector 字段与 name 字段互斥,不能同时存在。| |policy|enforcer
*string*|-|指定要使用的 LSM。
可用值: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|用于指定防护模式。
可用值:AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| | |enhanceProtect|hardeningRules
*string array*|可选字段。用于指定要使用的内置加固规则。| @@ -45,7 +45,7 @@ description: The interface specification of vArmor. |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|对套接字 [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) 创建行为进行访问控制。| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|对外联请求进行访问控制。| |ptrace
*PtraceRule* |strictMode
*bool*|可选字段。如果设置为 false,将允许进程对同一容器内其他进程执行 trace、read 操作,以及允许进程被同一容器内其他进程执行 traceby、readby 操作。如果设置为 true,则将禁止容器内所有进程的 trace、read、traceby、readby 操作。(默认值:false)| -| |permissions
*string array*|禁止使用 ptrace 相关操作,可用值: `all(*), trace, read, traceby, readby`
- `trace`: 禁止跟踪其他进程
- `read`: 禁止读取其他进程
- `traceby`: 禁止被其他进程跟踪,宿主机进程除外
- `readby`: 禁止被其他进程读取,宿主机进程除外| +| |permissions
*string array*|禁止使用 ptrace 相关操作。
可用值: `all(*), trace, read, traceby, readby`
- trace: 禁止跟踪其他进程
- read: 禁止读取其他进程
- traceby: 禁止被其他进程跟踪,宿主机进程除外
- readby: 禁止被其他进程读取,宿主机进程除外| |mounts
*MountRule array* |sourcePattern
*string*|任意符合策略语法的文件路径字符串(最大长度 128 bytes),用于匹配 [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html) 的 source,[UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html) 的 target,以及 MOVE_MOUNT(2) 的 from_pathname。| | |fstype
*string*|任意字符串(最大长度 16 bytes),用于匹配文件系统类型,`*` 代表匹配任意文件系统。| | |flags
*string array*|禁止使用的 mount flags,它们与 AppArmor 的 [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html) 类似。
可用值:`all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| @@ -56,14 +56,14 @@ description: The interface specification of vArmor. |---|----| |domains
*string array*|可选字段。用于指定禁止使用的套接字通信域。
可用值:`all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| |types
*string array*|可选字段。用于指定禁止使用的套接字通信语义。
可用值:`all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| -|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`
注意:protocols 和 types 字段互斥,不能同时存在。| +|protocols
*string array*|可选字段。用于指定禁止使用的套接字特定协议。
可用值:`all(*), icmp, tcp, udp`

注意:protocols 和 types 字段互斥,不能同时存在。| |PLACEHOLDER| ## NetworkEgressRule |字段|描述| |---|----| -|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。
注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。

注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| |ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| |port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md index 5099b3d..d0cdd1a 100644 --- a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md +++ b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md @@ -10,9 +10,9 @@ description: The interface specification of vArmor. | Field | Subfield | Subfield | Description | |-------|----------|----------|-------------| |target|kind
*string*|-|Kind is used to specify the type of workloads for the protection targets.
Available values: Deployment, StatefulSet, DaemonSet, Pod| -| |name
*string*|-|Optional. Name is used to specify a specific workload name.
*Note that the name field and selector field are mutually exclusive.*| +| |name
*string*|-|Optional. Name is used to specify a specific workload name.| | |containers
*string array*|-|Optional. Containers are used to specify the names of the protected containers. If it is empty, sandbox protection will be enabled for all containers within the workload (excluding initContainers and ephemeralContainers).| -| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.
*Note that the selector field and name field are mutually exclusive.*| +| |selector
*[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#labelselector-v1-meta)*|-|Optional. LabelSelector is used to match workloads that meet the specified conditions.

Note that the selector field and name field are mutually exclusive.| |policy|enforcer
*string*|-|Enforcer is used to specify which LSM to use for mandatory access control.
Available values: AppArmor, BPF, Seccomp, AppArmorBPF, AppArmorSeccomp, BPFSeccomp, AppArmorBPFSeccomp| | |mode
*string*|-|Used to specify the protection mode.
Available values: AlwaysAllow, RuntimeDefault, EnhanceProtect, BehaviorModeling, DefenseInDepth| | |enhanceProtect|hardeningRules
*string array*|Optional. HardeningRules are used to specify the built-in hardening rules.| @@ -45,7 +45,7 @@ description: The interface specification of vArmor. |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| |ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| -| |permissions
*string array*|Prohibited ptrace-related operations. Available values: `all(*), trace, traceby, read, readby`.
- `trace`: prohibiting tracing of other processes.
- `read`: prohibiting reading of other processes.
- `traceby`: prohibiting being traced by other processes (excluding the host processes).
- `readby`: prohibiting being read by other processes (excluding the host processes).| +| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`.
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| |mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| | |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| | |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| @@ -56,8 +56,8 @@ description: The interface specification of vArmor. | Field | Description | |-------|-------------| |domains
*string array*|Optional. Domains specifies the communication domains of socket.
Available values: `all(*), unix, inet, ax25, ipx, appletalk, netrom, bridge, atmpvc, x25, inet6, rose, netbeui, security, key, netlink, packet, ash, econet, atmsvc, rds, sna, irda, pppox, wanpipe, llc, ib, mpls, can, tipc, bluetooth, iucv, rxrpc, isdn, phonet, ieee802154, caif, alg, nfc, vsock, kcm, qipcrtr, smc, xdp, mctp`| -|types
*string array*|Optional. Types specifies the communication semantics of socket. Note that the types field and protocols field are mutually exclusive.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| -|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket. Note that the protocols field and types field are mutually exclusive.
Available values: `all(*), icmp, tcp, udp`| +|types
*string array*|Optional. Types specifies the communication semantics of socket.
Available values: `all(*), stream, dgram, raw, rdm, seqpacket, dccp, packet`| +|protocols
*string array*|Optional. Protocols specifies the particular protocols to be used with the socket.
Available values: `all(*), icmp, tcp, udp`

Note that the protocols field and types field are mutually exclusive. | |PLACEHOLDER|| ## NetworkEgressRule From ab98b641220a38d0644ce2fbab8ec1339522f058 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sat, 30 Nov 2024 17:05:21 +0800 Subject: [PATCH 6/9] Update CRD description --- apis/varmor/v1beta1/varmorpolicy_types.go | 4 ++-- config/crds/crd.varmor.org_armorprofiles.yaml | 1 - .../crd.varmor.org_varmorclusterpolicies.yaml | 15 ++++++--------- config/crds/crd.varmor.org_varmorpolicies.yaml | 15 ++++++--------- docs/getting_started/interface_specification.md | 4 ++-- .../crds/crd.varmor.org_armorprofiles.yaml | 1 - .../crd.varmor.org_varmorclusterpolicies.yaml | 15 ++++++--------- .../crds/crd.varmor.org_varmorpolicies.yaml | 15 ++++++--------- .../getting_started/interface_specification.md | 4 ++-- .../getting_started/interface_specification.md | 4 ++-- 10 files changed, 32 insertions(+), 46 deletions(-) diff --git a/apis/varmor/v1beta1/varmorpolicy_types.go b/apis/varmor/v1beta1/varmorpolicy_types.go index e5ea833..c379bdb 100644 --- a/apis/varmor/v1beta1/varmorpolicy_types.go +++ b/apis/varmor/v1beta1/varmorpolicy_types.go @@ -62,10 +62,10 @@ type FileRule struct { } type NetworkEgressRule struct { - // IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. + // IPBlock defines policy on a particular IPBlock with CIDR. // +optional IPBlock string `json:"ipBlock,omitempty"` - // IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be. + // IP defines policy on a particular IP. Note that the ip field and ipBlock field are mutually exclusive. // +optional IP string `json:"ip,omitempty"` // Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports. diff --git a/config/crds/crd.varmor.org_armorprofiles.yaml b/config/crds/crd.varmor.org_armorprofiles.yaml index eaa76c9..3e0ee3e 100644 --- a/config/crds/crd.varmor.org_armorprofiles.yaml +++ b/config/crds/crd.varmor.org_armorprofiles.yaml @@ -247,7 +247,6 @@ spec: type: string name: description: Name is used to specify a specific workload name. - Note that the name field and selector field are mutually exclusive. type: string selector: description: LabelSelector is used to match workloads that meet diff --git a/config/crds/crd.varmor.org_varmorclusterpolicies.yaml b/config/crds/crd.varmor.org_varmorclusterpolicies.yaml index 3e65725..a66d9f6 100644 --- a/config/crds/crd.varmor.org_varmorclusterpolicies.yaml +++ b/config/crds/crd.varmor.org_varmorclusterpolicies.yaml @@ -182,13 +182,12 @@ spec: properties: ip: description: IP defines policy on a particular - IP. If this field is set then neither of the - IPBlock field can be. + IP. Note that the ip field and ipBlock field + are mutually exclusive. type: string ipBlock: description: IPBlock defines policy on a particular - IPBlock with CIDR. If this field is set then - neither of the IP field can be. + IPBlock with CIDR. type: string port: description: Port defines policy on a particular @@ -226,10 +225,9 @@ spec: type: array types: description: "Types specifies the communication - semantics of socket. Note that the types field - and protocols field are mutually exclusive. - \n Available values: all(*), stream, dgram, - raw, rdm, seqpacket, dccp, packet" + semantics of socket. \n Available values: + all(*), stream, dgram, raw, rdm, seqpacket, + dccp, packet" items: type: string type: array @@ -402,7 +400,6 @@ spec: type: string name: description: Name is used to specify a specific workload name. - Note that the name field and selector field are mutually exclusive. type: string selector: description: LabelSelector is used to match workloads that meet diff --git a/config/crds/crd.varmor.org_varmorpolicies.yaml b/config/crds/crd.varmor.org_varmorpolicies.yaml index d3b96c7..66740bf 100644 --- a/config/crds/crd.varmor.org_varmorpolicies.yaml +++ b/config/crds/crd.varmor.org_varmorpolicies.yaml @@ -181,13 +181,12 @@ spec: properties: ip: description: IP defines policy on a particular - IP. If this field is set then neither of the - IPBlock field can be. + IP. Note that the ip field and ipBlock field + are mutually exclusive. type: string ipBlock: description: IPBlock defines policy on a particular - IPBlock with CIDR. If this field is set then - neither of the IP field can be. + IPBlock with CIDR. type: string port: description: Port defines policy on a particular @@ -225,10 +224,9 @@ spec: type: array types: description: "Types specifies the communication - semantics of socket. Note that the types field - and protocols field are mutually exclusive. - \n Available values: all(*), stream, dgram, - raw, rdm, seqpacket, dccp, packet" + semantics of socket. \n Available values: + all(*), stream, dgram, raw, rdm, seqpacket, + dccp, packet" items: type: string type: array @@ -401,7 +399,6 @@ spec: type: string name: description: Name is used to specify a specific workload name. - Note that the name field and selector field are mutually exclusive. type: string selector: description: LabelSelector is used to match workloads that meet diff --git a/docs/getting_started/interface_specification.md b/docs/getting_started/interface_specification.md index 4abd261..3751c18 100644 --- a/docs/getting_started/interface_specification.md +++ b/docs/getting_started/interface_specification.md @@ -60,7 +60,7 @@ English | [简体中文](interface_specification.zh_CN.md) | Field | Description | |-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be.| +|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| +|ip
*string*|Optional. IP defines policy on a particular IP.

Note that the ip field and ipBlock field are mutually exclusive.| |port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535`| |PLACEHOLDER| diff --git a/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml b/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml index eaa76c9..3e0ee3e 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_armorprofiles.yaml @@ -247,7 +247,6 @@ spec: type: string name: description: Name is used to specify a specific workload name. - Note that the name field and selector field are mutually exclusive. type: string selector: description: LabelSelector is used to match workloads that meet diff --git a/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml b/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml index 3e65725..a66d9f6 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_varmorclusterpolicies.yaml @@ -182,13 +182,12 @@ spec: properties: ip: description: IP defines policy on a particular - IP. If this field is set then neither of the - IPBlock field can be. + IP. Note that the ip field and ipBlock field + are mutually exclusive. type: string ipBlock: description: IPBlock defines policy on a particular - IPBlock with CIDR. If this field is set then - neither of the IP field can be. + IPBlock with CIDR. type: string port: description: Port defines policy on a particular @@ -226,10 +225,9 @@ spec: type: array types: description: "Types specifies the communication - semantics of socket. Note that the types field - and protocols field are mutually exclusive. - \n Available values: all(*), stream, dgram, - raw, rdm, seqpacket, dccp, packet" + semantics of socket. \n Available values: + all(*), stream, dgram, raw, rdm, seqpacket, + dccp, packet" items: type: string type: array @@ -402,7 +400,6 @@ spec: type: string name: description: Name is used to specify a specific workload name. - Note that the name field and selector field are mutually exclusive. type: string selector: description: LabelSelector is used to match workloads that meet diff --git a/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml b/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml index d3b96c7..66740bf 100644 --- a/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml +++ b/manifests/varmor/templates/crds/crd.varmor.org_varmorpolicies.yaml @@ -181,13 +181,12 @@ spec: properties: ip: description: IP defines policy on a particular - IP. If this field is set then neither of the - IPBlock field can be. + IP. Note that the ip field and ipBlock field + are mutually exclusive. type: string ipBlock: description: IPBlock defines policy on a particular - IPBlock with CIDR. If this field is set then - neither of the IP field can be. + IPBlock with CIDR. type: string port: description: Port defines policy on a particular @@ -225,10 +224,9 @@ spec: type: array types: description: "Types specifies the communication - semantics of socket. Note that the types field - and protocols field are mutually exclusive. - \n Available values: all(*), stream, dgram, - raw, rdm, seqpacket, dccp, packet" + semantics of socket. \n Available values: + all(*), stream, dgram, raw, rdm, seqpacket, + dccp, packet" items: type: string type: array @@ -401,7 +399,6 @@ spec: type: string name: description: Name is used to specify a specific workload name. - Note that the name field and selector field are mutually exclusive. type: string selector: description: LabelSelector is used to match workloads that meet diff --git a/website/docs/getting_started/interface_specification.md b/website/docs/getting_started/interface_specification.md index d0cdd1a..de86e06 100644 --- a/website/docs/getting_started/interface_specification.md +++ b/website/docs/getting_started/interface_specification.md @@ -64,7 +64,7 @@ description: The interface specification of vArmor. | Field | Description | |-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be.| +|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| +|ip
*string*|Optional. IP defines policy on a particular IP.

Note that the ip field and ipBlock field are mutually exclusive.| |port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535`| |PLACEHOLDER|| diff --git a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md index d0cdd1a..de86e06 100644 --- a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md +++ b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md @@ -64,7 +64,7 @@ description: The interface specification of vArmor. | Field | Description | |-------|-------------| -|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. If this field is set then neither of the IP field can be. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| -|ip
*string*|Optional. IP defines policy on a particular IP. If this field is set then neither of the IPBlock field can be.| +|ipBlock
*string*|Optional. IPBlock defines policy on a particular IPBlock with CIDR. For example:
* 192.168.1.1/24 represents IP addresses within the range of 192.168.1.0 to 192.168.1.255.
* 2001:db8::/32 represents IP addresses within the range of 2001:db8:: to 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff| +|ip
*string*|Optional. IP defines policy on a particular IP.

Note that the ip field and ipBlock field are mutually exclusive.| |port
*int*|Optional. Port defines policy on a particular port. If this field is zero or missing, this rule matches all ports.
Available values: `1 to 65535`| |PLACEHOLDER|| From 515c1b1bc133b89673386fde325259211c5077a0 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sun, 1 Dec 2024 22:38:57 +0800 Subject: [PATCH 7/9] docs: Fix hyperlinks --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 55954c0..db15f31 100644 --- a/README.md +++ b/README.md @@ -37,15 +37,15 @@ vArmor was created by the **Elkeid Team** of the endpoint security department at ## Documentation vArmor reference documents are available at [varmor.org](https://varmor.org). -⏩ **[Quick Start](https://www.varmor.org/docs/introduction#quick-start)** +⏩ **[Quick Start](https://www.varmor.org/docs/main/introduction)** -⚙️ **[Installation](https://www.varmor.org/docs/getting_started/installation)** +⚙️ **[Installation](https://www.varmor.org/docs/main/getting_started/installation)** -📔 **[Usage Instructions](https://www.varmor.org/docs/getting_started/usage_instructions)** +📔 **[Usage Instructions](https://www.varmor.org/docs/main/getting_started/usage_instructions)** -📜 **[Policies and Rules](https://www.varmor.org/docs/guides/policies_and_rules)** +📜 **[Policies and Rules](https://www.varmor.org/docs/main/guides/policies_and_rules)** -⏱️ **[Performance Specifications](https://www.varmor.org/docs/guides/performance)** +⏱️ **[Performance Specifications](https://www.varmor.org/docs/main/guides/performance)** ## Contributing @@ -53,7 +53,7 @@ Thanks for your interest in contributing to vArmor! Here are some steps to help 🤝🏻 Read and agree to the [code of conduct](./CODE_OF_CONDUCT.md). -🛠️ Read the [development guide](docs/development_guide.md). +🛠️ Read the [development guide](https://www.varmor.org/docs/main/guides/development). 💬 Join vArmor [Lark group](https://applink.larkoffice.com/client/chat/chatter/add_by_link?link_token=ae5pfb2d-f8a4-4f0b-b12e-15f24fdaeb24&qr_code=true). From 954bf136ac76179eebf339aa3d3afb6d9b7b24cf Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Sun, 1 Dec 2024 22:39:34 +0800 Subject: [PATCH 8/9] docs: Fix typo --- docs/guides/performance/README.md | 6 +++--- website/docs/guides/performance/index.md | 6 +++--- .../current/guides/performance/index.md | 6 +++--- .../version-v0.6/guides/performance/index.md | 6 +++--- .../versioned_docs/version-v0.6/guides/performance/index.md | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/guides/performance/README.md b/docs/guides/performance/README.md index e31c5aa..87bf110 100644 --- a/docs/guides/performance/README.md +++ b/docs/guides/performance/README.md @@ -9,9 +9,9 @@ The factors affecting performance for vArmor's user-space and kernel-space compo | -------------- | ----------- | | Cluster scale | As the cluster size increases, the CPU and memory consumed by the Manager for managing Agents also increase.| | Resource scale | Creating a large number of VarmorPolicy CRs will result in increased CPU and memory consumption for Manager. Frequent creation/modification/deletion of VarmorPolicy CRs will result in increased CPU and memory consumption for both Manager and Agent in response.| -| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM.
The more rules in a profile, the greater the performance impact on processes.| -| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM.
The more rules in a profile, the greater the performance impact on processes.| -| Seccomp | The basic overhead introduced when the kernel enable the Seccomp.
The more rules in a profile, the greater the performance impact on processes.| +| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| Seccomp | The basic overhead introduced when the kernel enable the Seccomp feature.
The more rules in a profile, the greater the performance impact on processes.| |PLACEHOLDER|| ## Resource Usage diff --git a/website/docs/guides/performance/index.md b/website/docs/guides/performance/index.md index 0e63651..a5b2567 100644 --- a/website/docs/guides/performance/index.md +++ b/website/docs/guides/performance/index.md @@ -13,9 +13,9 @@ The factors affecting performance for vArmor's user-space and kernel-space compo | -------------- | ----------- | | Cluster scale | As the cluster size increases, the CPU and memory consumed by the Manager for managing Agents also increase.| | Resource scale | Creating a large number of VarmorPolicy CRs will result in increased CPU and memory consumption for Manager. Frequent creation/modification/deletion of VarmorPolicy CRs will result in increased CPU and memory consumption for both Manager and Agent in response.| -| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM.
The more rules in a profile, the greater the performance impact on processes.| -| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM.
The more rules in a profile, the greater the performance impact on processes.| -| Seccomp | The basic overhead introduced when the kernel enable the Seccomp.
The more rules in a profile, the greater the performance impact on processes.| +| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| Seccomp | The basic overhead introduced when the kernel enable the Seccomp feature.
The more rules in a profile, the greater the performance impact on processes.| |PLACEHOLDER|| ## Resource Usage diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/guides/performance/index.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/guides/performance/index.md index 0e63651..a5b2567 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/guides/performance/index.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/guides/performance/index.md @@ -13,9 +13,9 @@ The factors affecting performance for vArmor's user-space and kernel-space compo | -------------- | ----------- | | Cluster scale | As the cluster size increases, the CPU and memory consumed by the Manager for managing Agents also increase.| | Resource scale | Creating a large number of VarmorPolicy CRs will result in increased CPU and memory consumption for Manager. Frequent creation/modification/deletion of VarmorPolicy CRs will result in increased CPU and memory consumption for both Manager and Agent in response.| -| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM.
The more rules in a profile, the greater the performance impact on processes.| -| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM.
The more rules in a profile, the greater the performance impact on processes.| -| Seccomp | The basic overhead introduced when the kernel enable the Seccomp.
The more rules in a profile, the greater the performance impact on processes.| +| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| Seccomp | The basic overhead introduced when the kernel enable the Seccomp feature.
The more rules in a profile, the greater the performance impact on processes.| |PLACEHOLDER|| ## Resource Usage diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/guides/performance/index.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/guides/performance/index.md index 0e63651..a5b2567 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/guides/performance/index.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/guides/performance/index.md @@ -13,9 +13,9 @@ The factors affecting performance for vArmor's user-space and kernel-space compo | -------------- | ----------- | | Cluster scale | As the cluster size increases, the CPU and memory consumed by the Manager for managing Agents also increase.| | Resource scale | Creating a large number of VarmorPolicy CRs will result in increased CPU and memory consumption for Manager. Frequent creation/modification/deletion of VarmorPolicy CRs will result in increased CPU and memory consumption for both Manager and Agent in response.| -| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM.
The more rules in a profile, the greater the performance impact on processes.| -| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM.
The more rules in a profile, the greater the performance impact on processes.| -| Seccomp | The basic overhead introduced when the kernel enable the Seccomp.
The more rules in a profile, the greater the performance impact on processes.| +| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| Seccomp | The basic overhead introduced when the kernel enable the Seccomp feature.
The more rules in a profile, the greater the performance impact on processes.| |PLACEHOLDER|| ## Resource Usage diff --git a/website/versioned_docs/version-v0.6/guides/performance/index.md b/website/versioned_docs/version-v0.6/guides/performance/index.md index 0e63651..a5b2567 100644 --- a/website/versioned_docs/version-v0.6/guides/performance/index.md +++ b/website/versioned_docs/version-v0.6/guides/performance/index.md @@ -13,9 +13,9 @@ The factors affecting performance for vArmor's user-space and kernel-space compo | -------------- | ----------- | | Cluster scale | As the cluster size increases, the CPU and memory consumed by the Manager for managing Agents also increase.| | Resource scale | Creating a large number of VarmorPolicy CRs will result in increased CPU and memory consumption for Manager. Frequent creation/modification/deletion of VarmorPolicy CRs will result in increased CPU and memory consumption for both Manager and Agent in response.| -| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM.
The more rules in a profile, the greater the performance impact on processes.| -| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM.
The more rules in a profile, the greater the performance impact on processes.| -| Seccomp | The basic overhead introduced when the kernel enable the Seccomp.
The more rules in a profile, the greater the performance impact on processes.| +| AppArmor LSM | The basic overhead introduced when the kernel enable the AppArmor LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| BPF LSM | The basic overhead introduced when the kernel enable the BPF LSM feature.
The more rules in a profile, the greater the performance impact on processes.| +| Seccomp | The basic overhead introduced when the kernel enable the Seccomp feature.
The more rules in a profile, the greater the performance impact on processes.| |PLACEHOLDER|| ## Resource Usage From a02d08b47730baedf683ade8cd9b607b8b24f9b1 Mon Sep 17 00:00:00 2001 From: Danny__Wei Date: Mon, 2 Dec 2024 10:04:31 +0800 Subject: [PATCH 9/9] docs: Updare interface specifications --- docs/getting_started/interface_specification.md | 4 ++-- docs/getting_started/interface_specification.zh_CN.md | 6 +++--- website/docs/getting_started/interface_specification.md | 4 ++-- .../current/getting_started/interface_specification.md | 6 +++--- .../version-v0.6/getting_started/interface_specification.md | 6 +++--- .../version-v0.6/getting_started/interface_specification.md | 4 ++-- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/getting_started/interface_specification.md b/docs/getting_started/interface_specification.md index 3751c18..ef36de7 100644 --- a/docs/getting_started/interface_specification.md +++ b/docs/getting_started/interface_specification.md @@ -17,7 +17,7 @@ English | [简体中文](interface_specification.zh_CN.md) | ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html).| | ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules.| | ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules.| -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads.| +| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to false, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to true, vArmor will not build Seccomp profile for the target workloads.| | ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false)| | |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. | |updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection.| @@ -41,7 +41,7 @@ English | [简体中文](interface_specification.zh_CN.md) |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| |ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| -| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`.
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| +| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| |mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| | |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| | |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| diff --git a/docs/getting_started/interface_specification.zh_CN.md b/docs/getting_started/interface_specification.zh_CN.md index d381cb8..dfe0d7a 100644 --- a/docs/getting_started/interface_specification.zh_CN.md +++ b/docs/getting_started/interface_specification.zh_CN.md @@ -17,7 +17,7 @@ | ||appArmorRawRules
*string array*|可选字段。用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| | ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段。用于支持用户设置自定义的 BPF 黑名单规则。| | ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段。用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| -| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 false,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 ture,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 true 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| |updateExistingWorkloads
*bool*|-|-|可选字段。用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| @@ -59,7 +59,7 @@ |字段|描述| |---|----| -|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。

注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| -|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。| +|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。

注意:同一个 NetworkEgressRule 中,IP 和 IPBlock 字段互斥,不能同时存在。| |port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/docs/getting_started/interface_specification.md b/website/docs/getting_started/interface_specification.md index de86e06..72c2a83 100644 --- a/website/docs/getting_started/interface_specification.md +++ b/website/docs/getting_started/interface_specification.md @@ -21,7 +21,7 @@ description: The interface specification of vArmor. | ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html).| | ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules.| | ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules.| -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads.| +| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to false, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to true, vArmor will not build Seccomp profile for the target workloads.| | ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false)| | |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. | |updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection.| @@ -45,7 +45,7 @@ description: The interface specification of vArmor. |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| |ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| -| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`.
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| +| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| |mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| | |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| | |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md index e0713d2..326d5fc 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/getting_started/interface_specification.md @@ -21,7 +21,7 @@ description: The interface specification of vArmor. | ||appArmorRawRules
*string array*|可选字段。用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| | ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段。用于支持用户设置自定义的 BPF 黑名单规则。| | ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段。用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| -| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 false,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 ture,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 true 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| |updateExistingWorkloads
*bool*|-|-|可选字段。用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| @@ -63,7 +63,7 @@ description: The interface specification of vArmor. |字段|描述| |---|----| -|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。

注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| -|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。| +|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。

注意:同一个 NetworkEgressRule 中,IP 和 IPBlock 字段互斥,不能同时存在。| |port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md index e0713d2..326d5fc 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/version-v0.6/getting_started/interface_specification.md @@ -21,7 +21,7 @@ description: The interface specification of vArmor. | ||appArmorRawRules
*string array*|可选字段。用于设置自定义的 AppArmor 黑名单规则。每条规则必须以逗号结尾,请参考 [AppArmor 语法](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html) 进行编写。| | ||bpfRawRules
*[BpfRawRules](#bpfrawrules)*|可选字段。用于支持用户设置自定义的 BPF 黑名单规则。| | ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|可选字段。用于支持用户使用 Seccomp enforcer 设置自定义的 Syscall 黑名单规则。请参考 [此文档](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) 创建自定义规则。| -| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 `false`,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 `ture`,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 `true` 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| +| ||privileged
*bool*|可选字段。当对特权容器进行加固,请务必将此值设置为 true。若为 false,将在 **RuntimeDefault** 模式的基础上构造 AppArmor/BPF Profiles。若为 ture,则在 **AlwaysAllow** 模式的基础上构造 AppArmor/BPF Profiles。

注意:当为 true 时,vArmor 不会为目标构造 Seccomp Profiles。(默认值:false)| | ||auditViolations
*bool*|可选字段. 用于审计违反沙箱策略的行为。此特性当前支持 AppArmor 和 BPF enforcers,任何违反沙箱策略的行为都会被记录到宿主机的 `/var/log/varmor/violations.log` 文件中。(默认值:false)| | |modelingOptions|duration
*int*|动态建模的时间。(单位:分钟)[实验功能]| |updateExistingWorkloads
*bool*|-|-|可选字段。用于指定是否对符合条件的工作负载进行滚动更新,从而在 Policy 创建或删除时,对目标工作负载开启或关闭防护。(默认值:false)

注意:vArmor 只会对 Deployment、StatefulSet、DaemonSet 类型的工作负载进行滚动更新,如果 `.spec.target.kind` 为 Pod,需要您自行重建 Pod 来开启或关闭防护。| @@ -63,7 +63,7 @@ description: The interface specification of vArmor. |字段|描述| |---|----| -|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。

注意:同一个 NetworkEgressRule 中,IPBlock 和 IP 字段互斥,不能同时存在。| -|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。| +|ipBlock
*string*|可选字段。可使用任意标准的 CIDR,支持 IPv6。用于对指定 CIDR 范围内的 IP 地址进行外联限制,例如
* 192.168.1.1/24 代表 192.168.1.0 ~ 192.168.1.255 范围内的 IP 地址。
* 2001:db8::/32 代表 2001:db8:: ~ 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff 范围内的 IP 地址。| +|ip
*string*|可选字段。任意标准的 IP 地址,支持 IPv6,用于对特定的 IP 地址进行外联限制。

注意:同一个 NetworkEgressRule 中,IP 和 IPBlock 字段互斥,不能同时存在。| |port
*int*|可选字段。用于对指定的端口进行外联限制,当为空时,默认对(匹配 IP 地址的)所有端口进行外联限制。否则仅对特定端口进行控制。
可用值:`1~65535`| |PLACEHOLDER|| diff --git a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md index de86e06..72c2a83 100644 --- a/website/versioned_docs/version-v0.6/getting_started/interface_specification.md +++ b/website/versioned_docs/version-v0.6/getting_started/interface_specification.md @@ -21,7 +21,7 @@ description: The interface specification of vArmor. | ||appArmorRawRules
*string array*|Optional. AppArmorRawRules is used to set custom AppArmor rules, each rule must end with a comma, please refer to the [AppArmor Syntax](https://manpages.ubuntu.com/manpages/jammy/man5/apparmor.d.5.html).| | ||bpfRawRules
*[BpfRawRules](#bpfrawrules) array*|Optional. BpfRawRules is used to set custom BPF rules.| | ||syscallRawRules
*[LinuxSyscall](https://pkg.go.dev/github.com/opencontainers/runtime-spec@v1.1.0/specs-go#LinuxSyscall) array*|Optional. SyscallRawRules is used to set the custom syscalls blocklist rules with Seccomp enforcer. Please refer to [this document](https://github.com/opencontainers/runtime-spec/blob/main/config-linux.md#seccomp) to create custom rules.| -| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to `nil` or `false`, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to `true`, vArmor will not build Seccomp profile for the target workloads.| +| ||privileged
*bool*|Optional. Privileged is used to identify whether the policy is for the privileged container. If set to false, vArmor will build AppArmor or BPF profiles on top of the **RuntimeDefault** mode. Otherwise, it will build AppArmor or BPF profiles on top of the **AlwaysAllow** mode. (Default: false)

Note: If set to true, vArmor will not build Seccomp profile for the target workloads.| | ||auditViolations
*bool*|Optional. AuditViolations determines whether to audit the actions that violate the mandatory access control rules. Currently, this feature supports AppArmor and BPF enforcers. Any detected violation will be logged to `/var/log/varmor/violations.log` file in the host. (Default: false)| | |modelingOptions|duration
*int*|[Experimental] Duration is the duration in minutes to modeling. | |updateExistingWorkloads
*bool*|-|-|Optional. UpdateExistingWorkloads is used to indicate whether to perform a rolling update on target existing workloads, thus enabling or disabling the protection of the target workloads when policies are created or deleted. (Default: false)

Note: vArmor only performs a rolling update on Deployment, StatefulSet, or DaemonSet type workloads. If `.spec.target.kind` is Pod, you need to rebuild the Pod yourself to enable or disable protection.| @@ -45,7 +45,7 @@ description: The interface specification of vArmor. |network
*NetworkRule* |sockets
*[NetworkSocketRule](#networksocketrule) array*|Optional. Sockets are the list of socket rules to be applied to restrict all [SOCKET(2)](https://man7.org/linux/man-pages/man2/socket.2.html) operations.| | |egresses
*[NetworkEgressRule](#networkegressrule) array*|Optional. Egresses are the list of egress rules to be applied to restrict particular IPs and ports.| |ptrace
*PtraceRule* |strictMode
*bool*|Optional. If set to false, it allows a process to perform trace and read operations on other processes within the same container, and also allows a process to be subjected to traceby and readby operations by other processes within the same container. If set to true, it prohibits all trace, read, traceby, and readby operations within the container. (Default: false)| -| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`.
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| +| |permissions
*string array*|Prohibited ptrace-related operations.
Available values: `all(*), trace, traceby, read, readby`
- trace: prohibiting tracing of other processes.
- read: prohibiting reading of other processes.
- traceby: prohibiting being traced by other processes (excluding the host processes).
- readby: prohibiting being read by other processes (excluding the host processes).| |mounts
*MountRule array* |sourcePattern
*string*|Any string (maximum length 128 bytes) that conforms to the policy syntax of BPF enforcer, used for matching the source paramater of [MOUNT(2)](https://man7.org/linux/man-pages/man2/mount.2.html), the target paramater of [UMOUNT(2)](https://man7.org/linux/man-pages/man2/umount.2.html), and the from_pathname paramater of MOVE_MOUNT(2).| | |fstype
*string*|Any string (maximum length 16 bytes), used for matching the type of filesystem. `'*'` represents matching any filesystem.| | |flags
*string array*|Prohibited mount flags. They are similar to AppArmor's [MOUNT FLAGS](https://manpages.ubuntu.com/manpages/focal/man5/apparmor.d.5.html).
Available values: `all(*), ro(r, read-only), rw(w), suid, nosuid, dev, nodev, exec, noexec, sync, async, mand, nomand, dirsync, atime, noatime, diratime, nodiratime, silent, loud, relatime, norelatime, iversion, noiversion, strictatime, nostrictatime, remount, bind(B), move(M), rbind(R), make-unbindable, make-private(private), make-slave(slave), make-shared(shared), make-runbindable, make-rprivate, make-rslave, make-rshared, umount`|