/network-config-analyzer

A semantic analyzer for resources that configure network connectivity (e.g., Kubernetes NetworkPolicy).

Primary LanguagePythonApache License 2.0Apache-2.0

Network Config Analyzer (NCA)

.github/workflows/test-push.yml .github/workflows/codeql-analysis.yml

What is NCA?

NCA is a tool for analyzing Network Policies and other connectivity-configuration resources. It takes such resources as input, in addition to a list of relevant endpoints, and provides answers to queries such as:

  • What is my current connectivity posture?
  • How is my connectivity posture changing?
  • Is specific traffic allowed/denied?
  • What are the endpoints that are not covered by any policy?
  • Are my policies implemented efficiently?

Installation (requires Python 3.8 or above)

For command-line use, NCA is installed with:

pip install network-config-analyzer

NCA can also be consumed as a Docker container, GitHub Action or Tekton Tasks.

Usage

Basic NCA command-line usage:

nca <query> [--resource_list <resource_list>] [--base_resource_list <base_resource_list>]

For example:

nca --connectivity --resource_list k8s  # Read policies and endpoints from a live Kubernetes cluster and report connectivity
# OR
nca --semantic_diff -r istio --base_resource_list ./old_config  # Compare two istio connectivity configs

The full list of queries is:

  • --sanity - Running several sanity checks on the given set of NetworkPolicies
  • --connectivity - Get the list of allowed connections (as firewall rules or as a graph) as implied by the given set of NetworkPolicies
  • --semantic_diff - Get the semantic connectivity difference (as firewall rules) between two sets of NetworkPolicy sets
  • --equiv - Semantically comparing two sets of NetworkPolicy sets to decide whether they allow exactly the same traffic
  • --interferes - Checking whether the given set of NetworkPolicies interferes with the base set of NetworkPolicies (allows more traffic between relevant endpoints)
  • --permits - Checking whether the base set of NetworkPolicies permits the traffic explicitly specified in the given set of NetworkPolicies
  • --forbids - Checking whether the base set of NetworkPolicies forbids the traffic explicitly specified in the given set of NetworkPolicies

The arguments to --resource_list and to --base_resource_list should be one of:

  • a path to a yaml/json file defining NetworkPolicies and/or endpoints
  • a path to a directory with files containing NetworkPolicies and/or endpoints
  • a URL of a GitHub repository/dir/file with NetworkPolicies and/or endpoints
  • The string k8s, instructing the tool to take all NetworkPolicies and endpoints from a Kubernetes cluster (using kubectl)
  • The string calico, instructing the tool to take all NetworkPolicies and endpoints from a Kubernetes cluster with Calico (using calicoctl)
  • The string istio, instructing the tool to take all AuthorizationPolicies and endpoints from a Kubernetes cluster with Istio (using kubectl)

Additional command-line switches:

  • --resource_list <an argument from the list above>
    Specifies where to take namespaces, endpoints and NetworkPolicies from. This switch may be specified multiple times
    shorthand: -r
  • --ns_list <an argument from the list above>
    Specifies where to take the list of namespaces from (and ignoring namespaces found by --resource_list). This switch may be specified multiple times
    default: the result of kubectl get ns
    shorthand: -n
  • --pod_list <an argument from the list above>
    Specifies where to take the list of pods/endpoints from (and ignoring those found by --resource_list). This switch may be specified multiple times
    default: the result of kubectl get pods -A
    shorthand: -p
  • --base_resource_list <an argument from the list above>
    Specifies where to take namespaces, endpoints and NetworkPolicies to compare against. This switch may be specified multiple times
  • --base_np_list <an argument from the list above>
    The set of NetworkPolicies to compare against. Using this switch will ignore NetworkPolicies found by --base_resource_list
    default: The result of kubectl get netpol -A
    shorthand: -b
  • --base_ns_list <an argument from the list above>
    Specifies files with list of namespaces to compare against (and ignoring those found by --base_resource_list). This switch may be specified multiple times
  • --base_pod_list <an argument from the list above>
    Specifies files with list of pods/endpoints to compare against (and ignoring those found by --base_resource_list). This switch may be specified multiple times
  • --ghe_token <token>
    A valid token to access a GHE repository
  • --period <minutes>
    Run NCA with given arguments every specified number of minutes
  • --daemon
    Run NCA as a daemon. Send and receive data using a REST API.
  • --output_format <format>
    Output format specification (txt/yaml/csv/md/dot).
    default: txt
    shorthand: -o
  • --file_out <file name>
    A file path to redirect output into.
    shorthand -f
  • --expected_output <file name>
    A file path to the expected query output (for connectivity or semantic_diff queries).\
  • --pr_url <URL>
    Write output as GitHub PR comment. URL points to the relevant comments resource in the GitHub API.
    e.g., https://api.github.com/repos/shift-left-netconfig/online-boutique/issues/1/comments
  • --output_endpoints
    Choose endpoints type in output (pods/deployments).
    default: deployments

For more information on command-line switches combinations, see Common Query Patterns

Exit Code Meaning:

The exit value of running a command-line without a scheme is the combination of two factors:

  1. The result of running the query (0/1) as specified here
  2. The result of comparing the query output with the expected output file contents (if given)

And it can be in the range 0 to 3 as followed:

  • 0 : query result is 0, output comparison passed.
  • 1 : query result is 1, output comparison passed.
  • 2 : query result is 0, output comparison failed.
  • 3 : query result is 1, output comparison failed.

Running with a scheme file

Scheme files allow running NCA on multiple queries in a single command-line, and also for fine-tuning the output. To run NCAs with a scheme file, use the --scheme switch.

nca --scheme <scheme_file>

where scheme_file is a yaml file describing what to verify.

Scheme files should follow this specification. See an example scheme file.

Supported platforms

  • Kubernetes
  • Calico
  • Istio (see what is supported here.)

Contributing

If you have any questions or issues you can create a new issue here.

Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example:

  1. Fork the repo
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

License

All source files must include a Copyright and License header. The SPDX license header is preferred because it can be easily scanned.

If you would like to see the detailed LICENSE click here.

#
# Copyright 2020- IBM Inc. All rights reserved
# SPDX-License-Identifier: Apache2.0
#