OSDOCS-10371: Expand info in Netowkring Audit Logging section

Author: dfitzmau

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]
+----
+<timestamp>|<message_serial>|acl_log(ovn_pinctrl0)|<severity>|name="<acl_name>", verdict="<verdict>", severity="<severity>", direction="<direction>": <flow>
+----
+
+Where:
+
+* `<timestamp>` states the time and date for the creation of a log message.
+* `<message_serial>` 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.
+* `<severity>` 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.
+* `<name>` states the name of the ACL-logging implementation in the OVN Network Bridging Database (`nbdb`) that was created by the network policy.
+* `<verdict>` can be either `allow` or `drop`.
+* `<direction>` can be either `to-lport` or `from-lport` to indicate that the policy was applied to traffic going to or away from a pod.
+* `<flow>` 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]
+----
+<proto>,vlan_tci=0x0000,dl_src=<src_mac>,dl_dst=<source_mac>,nw_src=<source_ip>,nw_dst=<target_ip>,nw_tos=<tos_dscp>,nw_ecn=<tos_ecn>,nw_ttl=<ip_ttl>,nw_frag=<fragment>,tp_src=<tcp_src_port>,tp_dst=<tcp_dst_port>,tcp_flags=<tcp_flags>
+----
+
+Where:
+
+* `<proto>` 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.
+* `<src_mac>` specifies the source for the Media Access Control (MAC) address.
+* `<source_mac>` specifies the destination for the MAC address.
+* `<source_ip>` lists the source IP address
+* `<target_ip>` lists the target IP address.
+* `<tos_dscp>` states Differentiated Services Code Point (DSCP) values to classify and prioritize certain network traffic over other traffic.
+* `<tos_ecn>` states Explicit Congestion Notification (ECN) values that indicate any congested traffic in your network.
+* `<ip_ttl>` states the Time To Live (TTP) information for an packet.
+* `<fragment>` specifies what type of IP fragments or IP non-fragments to match.
+* `<tcp_src_port>` shows the source for the port for TCP and UDP protocols.
+* `<tcp_dst_port>` lists the destination port for TCP and UDP protocols.
+* `<tcp_flags>` 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.
 |====

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]