diff --git a/modules/nw-networkpolicy-audit-concept.adoc b/modules/nw-networkpolicy-audit-concept.adoc index 57d7dc47bd..58a07657c7 100644 --- a/modules/nw-networkpolicy-audit-concept.adoc +++ b/modules/nw-networkpolicy-audit-concept.adoc @@ -9,7 +9,14 @@ You can configure the destination for audit logs, such as a syslog server or a UNIX domain socket. Regardless of any additional configuration, an audit log is always saved to `/var/log/ovn/acl-audit-log.log` on each OVN-Kubernetes pod in the cluster. -Audit logging is enabled per namespace by annotating the namespace with the `k8s.ovn.org/acl-logging` key as in the following example: +You can enable audit logging for each namespace by annotating each namespace configuration with a `k8s.ovn.org/acl-logging` section. In the `k8s.ovn.org/acl-logging` section, you must specify `allow`, `deny`, or both values to enable audit logging for a namespace. + +[NOTE] +==== +A network policy does not support setting the `Pass` action set as a rule. +==== + +The ACL-logging implementation logs access control list (ACL) events for a network. You can view these logs to analyze any potential security issues. .Example namespace annotation [source,yaml] @@ -26,7 +33,55 @@ metadata: } ---- -The logging format is compatible with syslog as defined by RFC5424. The syslog facility is configurable and defaults to `local0`. An example log entry might resemble the following: +To view the default ACL logging configuration values, see the `policyAuditConfig` object in the `cluster-network-03-config.yml` file. If required, you can change the ACL logging configuration values for log file parameters in this file. + +The logging message format is compatible with syslog as defined by RFC5424. The syslog facility is configurable and defaults to `local0`. The following example shows key parameters and their values outputted in a log message: + +.Example logging message that outputs parameters and their values +[source,terminal] +---- +||acl_log(ovn_pinctrl0)||name="", verdict="", severity="", direction="": +---- + +Where: + +* `` states the time and date for the creation of a log message. +* `` lists the serial number for a log message. +* `acl_log(ovn_pinctrl0)` is a literal string that prints the location of the log message in the OVN-Kubernetes plugin. +* `` sets the severity level for a log message. If you enable audit logging that supports `allow` and `deny` tasks then two severity levels show in the log message output. +* `` states the name of the ACL-logging implementation in the OVN Network Bridging Database (`nbdb`) that was created by the network policy. +* `` can be either `allow` or `drop`. +* `` can be either `to-lport` or `from-lport` to indicate that the policy was applied to traffic going to or away from a pod. +* `` shows packet information in a format equivalent to the `OpenFlow` protocol. This parameter comprises Open vSwitch (OVS) fields. + +The following example shows OVS fields that the `flow` parameter uses to extract packet information from system memory: + +.Example of OVS fields used by the `flow` parameter to extract packet information +[source,terminal] +---- +,vlan_tci=0x0000,dl_src=,dl_dst=,nw_src=,nw_dst=,nw_tos=,nw_ecn=,nw_ttl=,nw_frag=,tp_src=,tp_dst=,tcp_flags= +---- + +Where: + +* `` states the protocol. Valid values are `tcp` and `udp`. +* `vlan_tci=0x0000` states the VLAN header as `0` because a VLAN ID is not set for internal pod network traffic. +* `` specifies the source for the Media Access Control (MAC) address. +* `` specifies the destination for the MAC address. +* `` lists the source IP address +* `` lists the target IP address. +* `` states Differentiated Services Code Point (DSCP) values to classify and prioritize certain network traffic over other traffic. +* `` states Explicit Congestion Notification (ECN) values that indicate any congested traffic in your network. +* `` states the Time To Live (TTP) information for an packet. +* `` specifies what type of IP fragments or IP non-fragments to match. +* `` shows the source for the port for TCP and UDP protocols. +* `` lists the destination port for TCP and UDP protocols. +* `` supports numerous flags such as `SYN`, `ACK`, `PSH` and so on. If you need to set multiple values then each value is separated by a vertical bar (`|`). The UDP protocol does not support this parameter. + +[NOTE] +==== +For more information about the previous field descriptions, go to the OVS manual page for `ovs-fields`. +==== .Example ACL deny log entry for a network policy [source,text] @@ -38,16 +93,17 @@ The logging format is compatible with syslog as defined by RFC5424. The syslog f The following table describes namespace annotation values: -.Audit logging namespace annotation +.Audit logging namespace annotation for `k8s.ovn.org/acl-logging` [cols=".^4,.^6a",options="header"] |==== -|Annotation|Value +|Field|Description -|`k8s.ovn.org/acl-logging` -| -You must specify at least one of `allow`, `deny`, or both to enable audit logging for a namespace. +|`deny` +|Blocks namespace access to any traffic that matches an ACL rule with the `deny` action. The field supports `alert`, `warning`, `notice`, `info`, or `debug` values. -`deny`:: Optional: Specify `alert`, `warning`, `notice`, `info`, or `debug`. -`allow`:: Optional: Specify `alert`, `warning`, `notice`, `info`, or `debug`. +|`allow` +|Permits namespace access to any traffic that matches an ACL rule with the `allow` action. The field supports `alert`, `warning`, `notice`, `info`, or `debug` values. +|`pass` +|A `pass` action applies to an admin network policy's ACL rule. A `pass` action allows either the network policy in the namespace or the baseline admin network policy rule to evaluate all incoming and outgoing traffic. A network policy does not support a `pass` action. |==== diff --git a/networking/network_security/logging-network-security.adoc b/networking/network_security/logging-network-security.adoc index 9edea938d4..eb854a034a 100644 --- a/networking/network_security/logging-network-security.adoc +++ b/networking/network_security/logging-network-security.adoc @@ -17,8 +17,14 @@ include::modules/nw-audit-configuration.adoc[leveloffset=+1] include::modules/nw-operator-cr.adoc[tag=policy-audit] +// Audit logging include::modules/nw-networkpolicy-audit-concept.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources + +* xref:../../networking/network_security/network-policy-apis.adoc#network-policy-apis[Understanding network policy APIs] + include::modules/nw-anp-audit-logging-concept.adoc[leveloffset=+1] include::modules/nw-banp-audit-logging-concept.adoc[leveloffset=+1]