diff --git a/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc b/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc index 3fcb9db5a1ec..e36ccbe64fee 100644 --- a/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc +++ b/modules/retrieving-connectivity-mapping-information-from-a-kubernetes-manifest-directory.adoc @@ -49,3 +49,7 @@ Each line is composed of the following elements: * `conn`:: Represents the permissible connectivity attributes. An endpoint follows the format `namespace/name[Kind]`. For example, `default/backend[Deployment]`. + +Opional: To see which policies and rules are responsible for allowing or denying specific connections, you can use the `--explain` option with the `roxctl netpol connectivity map` command. +You can use the output to debug network policy configurations. +For more information about understanding the explanation output, see "Retriving explanations". diff --git a/modules/retrieving-explanations.adoc b/modules/retrieving-explanations.adoc new file mode 100644 index 000000000000..73472f492ed0 --- /dev/null +++ b/modules/retrieving-explanations.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: PROCEDURE +[id="retrieving-explanations_{context}"] += Retrieving explanations + +[role="_abstract"] +You can understand why connections are allowed or denied based on your Kubernetes network policy rules by retrieving the explanations. + +.Procedure + +* To generate a connectivity report with explanations, run the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ roxctl netpol connectivity map --explain <1> +---- ++ +<1> Specify the path to the folder, which can include sub-folders that contain YAML resources and network policies for analysis. + +When you use the `--explain` flag, the connectivity report includes an *explanation section* that details the specific policies and rules relevant to each allowed or blocked connection. diff --git a/modules/roxctl-netpol-connectivity-map-command-options.adoc b/modules/roxctl-netpol-connectivity-map-command-options.adoc index daad02ed7371..64f8a5899d50 100644 --- a/modules/roxctl-netpol-connectivity-map-command-options.adoc +++ b/modules/roxctl-netpol-connectivity-map-command-options.adoc @@ -13,6 +13,9 @@ The `roxctl netpol connectivity map` command supports the following options: |Option |Description +|`--explain` +|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format. + |`--fail` |Fail on the first encountered error. The default value is `false`. diff --git a/modules/roxctl-netpol-connectivity-map.adoc b/modules/roxctl-netpol-connectivity-map.adoc index 91c15ba0437a..8cae6565bc1a 100644 --- a/modules/roxctl-netpol-connectivity-map.adoc +++ b/modules/roxctl-netpol-connectivity-map.adoc @@ -21,7 +21,10 @@ $ roxctl netpol connectivity map [flags] <1> |=== |Option |Description -|`--exposure` +|`--explain` +|Enhance the analysis of permitted connectivity with explanations per denied/allowed connection; supported only for txt output format. + +|`--exposure` |Enhance the analysis of permitted connectivity by using exposure analysis. The default value is `false`. |`--fail` @@ -33,6 +36,9 @@ $ roxctl netpol connectivity map [flags] <1> |`-f`, `--output-file string` |Save the connections list output into a specific file. +|`-h`, `--help` +|View the help text for the `roxctl netpol connectivity map` command. + |`-o`, `--output-format string` |Configure the connections list in a specific format. Supported formats include `txt`, `json`, `md`, `dot`, and `csv`. The default value is `txt`. diff --git a/modules/understanding-connectivity-explanations.adoc b/modules/understanding-connectivity-explanations.adoc new file mode 100644 index 000000000000..a02d41480d89 --- /dev/null +++ b/modules/understanding-connectivity-explanations.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * operating/build-time-network-policy-tools.adoc + +:_mod-docs-content-type: CONCEPT +[id="understanding-connectivity-explanations_{context}"] += Understanding Connectivity Explanations + +[role="_abstract"] +To understand precisely which parts of your Kubernetes network policy YAML files are responsible for allowing or denying connections, you can use the `roxctl netpol connectivity map` command which includes an explainability mode. +You can debug and refine your network policies by using the explainability mode which provides additional details beyond the standard connectivity report. + +As a developer or DevOps professional, you might encounter situations where a connection you expect to be open is denied, or you need to confirm which specific rules allow the connection. + +The following are examples of some common issues: + +* Mismatched ingress and egress rules, where one side of a connection allows traffic but the other denies it. +* Typographical errors that cause policies to open different ports or protocols than intended. + +The explainability mode provides insights into how each side of a connection is affected by your policy rules. You can quickly identify the configuration mistakes by using the explainability mode. + +[discrete] +== Example allowed connections + +Consider that you have a Kubernetes cluster with the following components: + +* A *Monitoring service* called `monitoring-service` that collects data from various applications. +* A core *Internal application A* called `internal-app-a` that actively exposes monitoring endpoints and needs monitoring. +* A network policy configuration that defines Admin Network Policy (ANP) to `pass` connections from monitoring into namespaces with label `security: internal`, and a specific Network Policy (NP) that explicitly allows connections from `monitoring-service` into `internal-app-a`. + +You can see the YAML manifest for this example at link:https://github.com/np-guard/netpol-analyzer/tree/0ac857e19bfab4b281ca9bdfb2bbc5ea319b5065/tests/anp_banp_explain_demo[`netpol-analyzer/tests/anp_banp_explain_demo/`]. + +To analyze the network policies and provides an explanation for each connection, you can run the `roxctl netpol connectivity map --explain` command on this setup. + +The explainability output for allowed connections from the `monitoring-service` deployment for such configuration shows: + +[source,terminal] +---- +Connections between monitoring/monitoring-service[Pod] => internal-apps/internal-app-a[Pod]: +Allowed connections: + Allowed TCP, UDP, SCTP due to the following policies and rules: + Egress (Allowed) due to the system default (Allow all) + Ingress (Allowed) + AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring + NetworkPolicy 'internal-apps/allow-monitoring' allows connections by Ingress rule #1 +---- + +In this example, the connection from `monitoring/monitoring-service` to `internal-apps/internal-app-a` is allowed by the combination of ANP `pass-monitoring` that applies broadly on all namespaces with the label `security: internal` and a more specific NP `internal-apps/allow-monitoring` tailored for `internal-app-a`. The output shows that multiple policies can contribute to allowing a connection. + +[discrete] +== Example blocked connections + +Consider an isolated data service `isolated-data-service` which denies all external access by default for security reasons. + +You can see the YAML manifest for this example at link:https://github.com/np-guard/netpol-analyzer/tree/7ab6bbd421d3d80cbfff7cd1529ff8caf0137fbc/tests/anp_banp_explain_demo_2[`netpol-analyzer/tests/anp_banp_explain_demo_2/`]. + +To analyze the network policies and provides an explanation for each connection, you can run the `roxctl netpol connectivity map --explain` command on this setup. + +The explainability output for blocked connections from the `monitoring-service` deployment to this workload shows: + +[source,terminal] +---- +Connections between monitoring/monitoring-service[Pod] => isolated-apps/isolated-data-service[Pod]: + +Denied connections: + Denied TCP, UDP, SCTP due to the following policies and rules: + Egress (Allowed) due to the system default (Allow all) + Ingress (Denied) + AdminNetworkPolicy 'pass-monitoring' passes connections by Ingress rule pass-ingress-from-monitoring + BaselineAdminNetworkPolicy 'default' denies connections by Ingress rule deny-ingress-from-monitoring +---- + +In this example, the connection to `data/isolated-data-service` is blocked by a combination of ANP with Pass action, and of BANP that denies all connections from `monitoring` by default. diff --git a/operating/build-time-network-policy-tools.adoc b/operating/build-time-network-policy-tools.adoc index efe62293e278..84f66450ee74 100644 --- a/operating/build-time-network-policy-tools.adoc +++ b/operating/build-time-network-policy-tools.adoc @@ -65,6 +65,10 @@ include::modules/retrieving-connectivity-mapping-information-from-a-kubernetes-m * xref:../cli/command-reference/roxctl-netpol.adoc#roxctl-netpol-connectivity-map_roxctl-netpol[roxctl netpol connectivity map command options]. +include::modules/retrieving-explanations.adoc[leveloffset=+2] + +include::modules/understanding-connectivity-explanations.adoc[leveloffset=+3] + include::modules/connectivity-map-output-formats-and-visualizations.adoc[leveloffset=+2] include::modules/generating-svg-graphs-from-the-dot-output-using-graphviz.adoc[leveloffset=+2]