diff --git a/cmd/policy-assistant/README.md b/cmd/policy-assistant/README.md index c199002e..49854fef 100644 --- a/cmd/policy-assistant/README.md +++ b/cmd/policy-assistant/README.md @@ -18,19 +18,17 @@ Policy Assistant is a static analysis tool which ***simulates the action of netw For instance, Policy Assistant can simulate and walk through which policies impact cluster traffic: ```shell -$ policy-assistant analyze --namespace demo --mode walkthrough +$ policy-assistant analyze --mode walkthrough --policy-path policies/ --traffic-path traffic.json verdict walkthrough: -+---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ -| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | -+---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ -| demo/[pod=a] -> demo/[pod=b]:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | -+---------------------------------------+---------+-------------------------------------------------------------+ + -| demo/[pod=a] -> demo/[pod=b]:81 (TCP) | Denied | [ANP] Pass (pass-81) -> [BANP] Deny (baseline-deny) | | -+---------------------------------------+---------+-------------------------------------------------------------+ + -| demo/[pod=b] -> demo/[pod=a]:80 (TCP) | Allowed | [ANP] Allow (allow-80) | | -+---------------------------------------+---------+-------------------------------------------------------------+ + -| demo/[pod=b] -> demo/[pod=a]:81 (TCP) | Denied | [ANP] Pass (pass-81) -> [NPv1] Dropped (demo/deny-to-pod-a) | | -+---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| demo/deployment/a -> demo/pod/b:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+ + +| demo/deployment/a -> demo/pod/b:81 (TCP) | Denied | [ANP] No-Op -> [BANP] Deny (baseline-deny) | | ++-------------------------------------------------+ +-----------------------------------------------------------------------------+ + +| demo2/[app=nginx] -> demo/deployment/a:81 (TCP) | | [ANP] Pass (development-ns) -> [NPv1] Dropped (demo/deny-anything-to-pod-a) | | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ ``` ### Quick Install @@ -167,20 +165,20 @@ Combined: Visualize how traffic would be allowed/denied and which policies are causing the verdict. +For more information, see the [walkthrough demo](./examples/demos/walkthrough/README.md). + ```shell -$ policy-assistant analyze --mode walkthrough --policy-path cmd/policy-assistant/examples/demos/kubecon-eu-2024/policies/ +$ policy-assistant analyze --mode walkthrough --policy-path policies/ --traffic-path traffic.json verdict walkthrough: -+---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ -| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | -+---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ -| demo/[pod=a] -> demo/[pod=b]:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | -+---------------------------------------+---------+-------------------------------------------------------------+ + -| demo/[pod=a] -> demo/[pod=b]:81 (TCP) | Denied | [ANP] Pass (pass-81) -> [BANP] Deny (baseline-deny) | | -+---------------------------------------+---------+-------------------------------------------------------------+ + -| demo/[pod=b] -> demo/[pod=a]:80 (TCP) | Allowed | [ANP] Allow (allow-80) | | -+---------------------------------------+---------+-------------------------------------------------------------+ + -| demo/[pod=b] -> demo/[pod=a]:81 (TCP) | Denied | [ANP] Pass (pass-81) -> [NPv1] Dropped (demo/deny-to-pod-a) | | -+---------------------------------------+---------+-------------------------------------------------------------+------------------------------+ ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| demo/deployment/a -> demo/pod/b:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+ + +| demo/deployment/a -> demo/pod/b:81 (TCP) | Denied | [ANP] No-Op -> [BANP] Deny (baseline-deny) | | ++-------------------------------------------------+ +-----------------------------------------------------------------------------+ + +| demo2/[app=nginx] -> demo/deployment/a:81 (TCP) | | [ANP] Pass (development-ns) -> [NPv1] Dropped (demo/deny-anything-to-pod-a) | | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ ``` ## Development diff --git a/cmd/policy-assistant/examples/demos/walkthrough/README.md b/cmd/policy-assistant/examples/demos/walkthrough/README.md new file mode 100644 index 00000000..1c3908c5 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/README.md @@ -0,0 +1,81 @@ +## Use Cases + +1. Test a new policy before applying it to your cluster. +2. Understand which policies are affecting traffic in your cluster. + +## Overview + +```bash +# single source/destination read from cluster. policies read from YAML files +policy-assistant analyze --mode walkthrough \ + --policy-path policies/ \ + --src-workload demo/deployment/a \ + --dst-workload demo/pod/b \ + --port 81 \ + --protocol TCP + +# multiple traffic tuples (not necessarily read from cluster). policies read from cluster +policy-assistant analyze --mode walkthrough \ + --namespace demo \ + --traffic-path traffic.json +``` + +Example output: + +```bash ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| TRAFFIC | VERDICT | INGRESS WALKTHROUGH | EGRESS WALKTHROUGH | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +| demo/deployment/a -> demo/pod/b:80 (TCP) | Allowed | [ANP] Allow (allow-80) | no policies targeting egress | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+ + +| demo/deployment/a -> demo/pod/b:81 (TCP) | Denied | [ANP] No-Op -> [BANP] Deny (baseline-deny) | | ++-------------------------------------------------+ +-----------------------------------------------------------------------------+ + +| demo2/[app=nginx] -> demo/deployment/a:81 (TCP) | | [ANP] Pass (development-ns) -> [NPv1] Dropped (demo/deny-anything-to-pod-a) | | ++-------------------------------------------------+---------+-----------------------------------------------------------------------------+------------------------------+ +``` + +## Demo + +To try for yourself: + +1. Download `policy-assistant` via the [Quick Install](../../../README.md#quick-install) guide. +1. Leverage the JSON/YAML files in this folder. +1. Not required: create a Kubernetes cluster and apply any desired YAML files. + +## Usage + +### Specifying Policies + +#### Option 1: reference policies from YAML files + +Use this argument: `--policy-path ` + +#### Option 2: reference policies from cluster + +Specify the `--namespace` or `--all-namespaces`. + +### Specifying Pods + +#### Option 1: specify single source/destination in CLI args + +You can use the following arguments to reference Pods from cluster by workload name: + +```bash +policy-assistant analyze --mode walkthrough \ + --src-workload demo/deployment/a \ + --dst-workload demo/pod/b \ + --port 81 \ + --protocol TCP +``` + +#### Option 2: specify multiple source/destination pairs in JSON + +You can also reference Pods via JSON. +You can also specify Pods which are not running in a cluster in this JSON. + +See the example *traffic.json* file. + +```bash +policy-assistant analyze --mode walkthrough \ + --traffic-path traffic.json +``` diff --git a/cmd/policy-assistant/examples/demos/walkthrough/demo-deployment-a.yaml b/cmd/policy-assistant/examples/demos/walkthrough/demo-deployment-a.yaml new file mode 100644 index 00000000..5cdc31fc --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/demo-deployment-a.yaml @@ -0,0 +1,46 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + namespace: demo + labels: + pod: a + name: a +spec: + replicas: 1 + selector: + matchLabels: + pod: a + template: + metadata: + labels: + pod: a + spec: + containers: + - command: + - /agnhost + - serve-hostname + - --tcp + - --http=false + - --port + - "80" + image: registry.k8s.io/e2e-test-images/agnhost:2.43 + imagePullPolicy: IfNotPresent + name: cont-80-tcp + ports: + - containerPort: 80 + name: serve-80-tcp + protocol: TCP + - command: + - /agnhost + - serve-hostname + - --tcp + - --http=false + - --port + - "81" + image: registry.k8s.io/e2e-test-images/agnhost:2.43 + imagePullPolicy: IfNotPresent + name: cont-81-tcp + ports: + - containerPort: 81 + name: serve-81-tcp + protocol: TCP diff --git a/cmd/policy-assistant/examples/demos/walkthrough/demo-pod-b.yaml b/cmd/policy-assistant/examples/demos/walkthrough/demo-pod-b.yaml new file mode 100644 index 00000000..5a1a92e1 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/demo-pod-b.yaml @@ -0,0 +1,37 @@ +apiVersion: v1 +kind: Pod +metadata: + namespace: demo + labels: + pod: b + name: b +spec: + containers: + - command: + - /agnhost + - serve-hostname + - --tcp + - --http=false + - --port + - "80" + image: registry.k8s.io/e2e-test-images/agnhost:2.43 + imagePullPolicy: IfNotPresent + name: cont-80-tcp + ports: + - containerPort: 80 + name: serve-80-tcp + protocol: TCP + - command: + - /agnhost + - serve-hostname + - --tcp + - --http=false + - --port + - "81" + image: registry.k8s.io/e2e-test-images/agnhost:2.43 + imagePullPolicy: IfNotPresent + name: cont-81-tcp + ports: + - containerPort: 81 + name: serve-81-tcp + protocol: TCP diff --git a/cmd/policy-assistant/examples/demos/walkthrough/policies/anp1.yaml b/cmd/policy-assistant/examples/demos/walkthrough/policies/anp1.yaml new file mode 100644 index 00000000..0d2fe94d --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/policies/anp1.yaml @@ -0,0 +1,18 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: AdminNetworkPolicy +metadata: + name: anp1 +spec: + priority: 1 + subject: + namespaces: {} + ingress: + - name: "allow-80" + action: "Allow" + from: + - namespaces: + namespaceSelector: {} + ports: + - portNumber: + protocol: TCP + port: 80 diff --git a/cmd/policy-assistant/examples/demos/walkthrough/policies/anp2.yaml b/cmd/policy-assistant/examples/demos/walkthrough/policies/anp2.yaml new file mode 100644 index 00000000..512a7e3c --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/policies/anp2.yaml @@ -0,0 +1,16 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: AdminNetworkPolicy +metadata: + name: anp2 +spec: + priority: 2 + subject: + namespaces: {} + ingress: + - name: "development-ns" + action: "Pass" + from: + - namespaces: + namespaceSelector: + matchLabels: + development: "true" diff --git a/cmd/policy-assistant/examples/demos/walkthrough/policies/banp.yaml b/cmd/policy-assistant/examples/demos/walkthrough/policies/banp.yaml new file mode 100644 index 00000000..a548aba0 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/policies/banp.yaml @@ -0,0 +1,13 @@ +apiVersion: policy.networking.k8s.io/v1alpha1 +kind: BaselineAdminNetworkPolicy +metadata: + name: default +spec: + subject: + namespaces: {} + ingress: + - name: "baseline-deny" + action: "Deny" + from: + - namespaces: + namespaceSelector: {} diff --git a/cmd/policy-assistant/examples/demos/walkthrough/policies/npv1.yaml b/cmd/policy-assistant/examples/demos/walkthrough/policies/npv1.yaml new file mode 100644 index 00000000..f64111e0 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/policies/npv1.yaml @@ -0,0 +1,12 @@ +kind: NetworkPolicy +apiVersion: networking.k8s.io/v1 +metadata: + namespace: demo + name: deny-anything-to-pod-a +spec: + policyTypes: + - Ingress + podSelector: + matchLabels: + pod: a + ingress: [] diff --git a/cmd/policy-assistant/examples/demos/walkthrough/traffic.json b/cmd/policy-assistant/examples/demos/walkthrough/traffic.json new file mode 100644 index 00000000..b1755bf2 --- /dev/null +++ b/cmd/policy-assistant/examples/demos/walkthrough/traffic.json @@ -0,0 +1,49 @@ +[ + { + "Source": { + "Internal": { + "Workload": "demo/deployment/a" + } + }, + "Destination": { + "Internal": { + "Workload": "demo/pod/b" + } + }, + "Protocol": "TCP", + "ResolvedPort": 80, + "ResolvedPortName": "serve-80-tcp" + }, + { + "Source": { + "Internal": { + "Workload": "demo/deployment/a" + } + }, + "Destination": { + "Internal": { + "Workload": "demo/pod/b" + } + }, + "Protocol": "TCP", + "ResolvedPort": 81, + "ResolvedPortName": "serve-81-tcp" + }, + { + "Source": { + "Internal": { + "PodLabels": {"app": "nginx"}, + "NamespaceLabels": {"development": "true"}, + "Namespace": "demo2" + } + }, + "Destination": { + "Internal": { + "Workload": "demo/deployment/a" + } + }, + "Protocol": "TCP", + "ResolvedPort": 81, + "ResolvedPortName": "serve-81-tcp" + } +]