Snowcat gathers and analyzes the configuration of an Istio cluster and audits it for potential violations of security best practices.
Like all cloud infrastructure, Istio requires some hardening effort beyond what a default deployment offers. The Istio Security Best Practices document covers this in great detail. This hardening process has a lot of moving parts and it's easy to miss one of the steps that could assist an attacker in compromising a cluster. Snowcat was built to make the detection of these missing hardening steps as straightforward as possible.
The two usage modes can help engineers analyze their clusters from different perspectives:
- The perspective of an attacker that has just obtained code execution on an Istio workload but without any other context or permissions.
- The perspective of a systems engineer that has the ability to dump all relevant configuration information for analysis.
By implementing analysis methods for both of these perspectives, Snowcat is able to gather a more "complete" picture of the security posture of an Istio cluster.
For more information, please read our blog post.
You can install Snowcat locally by using any one of the options listed below.
$ go install github.com/praetorian-inc/snowcat/cmd/snowcat@latest
-
Download the binary for your OS from the releases page.
-
(OPTIONAL) Download the
checksums.txt
file to verify the integrity of the archive
# Check the checksum of the downloaded archive
$ shasum -a 256 snowcat_${VERSION}_${ARCH}.tar.gz
b05c4d7895be260aa16336f29249c50b84897dab90e1221c9e96af9233751f22 snowcat_${VERSION}_${ARCH}.tar.gz
$ cat snowcat_${VERSION}_${ARCH}_checksums.txt | grep snowcat_${VERSION}_${ARCH}.tar.gz
b05c4d7895be260aa16336f29249c50b84897dab90e1221c9e96af9233751f22 snowcat_${VERSION}_${ARCH}.tar.gz
- Extract the downloaded archive
$ tar -xvf snowcat_${VERSION}_${ARCH}.tar.gz
- Move the
snowcat
binary into your path:
$ mv ./snowcat /usr/local/bin/
# clone the Snowcat repo
$ git clone https://github.com/praetorian-inc/snowcat.git
# navigate into the repo directory and build
$ cd snowcat
$ go build
# Move the Snowcat binary into your path
$ mv ./snowcat /usr/local/bin
There are two main modes of operation for Snowcat. With no positional argument, Snowcat will assume it is running inside of a cluster enabled with Istio, and begin to enumerate the required data. Optionally, you can point snowcat at a directory containing Kubernets YAML files.
# running with a directory specified will cause it to run in file analysis mode
./snowcat [options] <directory name>
./snowcat [options]
# deploy snowcat to your cluster as a Job
$ kubectl -n default apply -f https://raw.githubusercontent.com/praetorian-inc/snowcat/main/deploy/job.yaml
job.batch/snowcat created
# wait a few moments for the scan to complete
# review snowcat logs
$ kubectl -n default logs jobs/snowcat
...
time="2021-10-22T17:47:50Z" level=info msg="running auditor" auditor="Overly Broad Gateway Hosts"
time="2021-10-22T17:47:50Z" level=info msg="running auditor" auditor="Weak Service Account Authentication"
time="2021-10-22T17:47:50Z" level=info msg="found jwt policy" auditor="Weak Service Account Authentication" policy=third-party-jwt
snowcat job complete! use the following command to export the results:
kubectl -n default cp snowcat-46tj5:/data snowcat-results
# download results from the running pod
$ kubectl -n default cp snowcat-46tj5:/data snowcat-results
snowcat help
Snowcat comes equipped with several command line options to influence the
operation of the tool. Additionally, many configuration options can be passed
to the tool through a configuration file. By default, Snowcat looks for the
config file at ./snowcat.yml
(the directory from which the tool is run), but
can be passed as a switch to specify an arbitrary file location.
Configuration of Snowcat is handled by a combination of Cobra and Viper. This allows Snowcat to be configured through the following methods, in order of precedence.
- Command Line Flag
- Environment Variables
- Configuration File
It should be noted that any data that is discovered during a run will overwrite all configuration options.
The following configuration options can be specified:
-
-c <file>
--config <file>
- the configuration file location (default:./snowcat.yml
) -
-l <level>
--log-level <level>
- log level for console output, because logging is handled by Logrus, the currently supported levels are trace, debug, info, warning, error, fatal, and panic. (default:info
) -
-s
--save-config
- if this switch is passed, the configuration of Snowcat will be written out to the specified config file. This is useful if the tool is to be run multiple times on the same cluster to allow for fewer arguments to be passed in subsequent runs. NOTE: this will overwrite the existing config file every time. -
--format [text|json]
- the output format for the tool, this is eithertext
for human readable content, orjson
for structured output. -
--export <directory>
- this flag will cause Snowcat to output the discovered Kubernetes resources to a directory as YAML files -
--output <path>
- this flag will cause Snowcat to scan results to the specified file -
--istio-version <version>
- if the Istio control plane version is known prior to running the tool, it can be passed via this flag. Additionally, it binds to the configuration variableistio-version
in the configuration file. -
--istio-namespace <namespace>
- if the namespace running the Istio control plane is known prior to running the tool, it can be passed via this flag. Additionally, it binds to the configuration variableistio-namespace
in the configuration file. -
--discovery-address <ip:port>
- this specifies the address of the unauthenticated XDS port. It is bound to the configuration variablediscovery-address
. -
--debugz-address <ip:port>
- this specifies the address of the Istiod's debug API. It is bound to the configuration variabledebugz-address
. -
--kubelet-addresses <list of ip:port>
- this specifies a list of kubelet nodes read-only API ports. It is bound to the configuration variablekubelet-addresses
-
--job-mode
- this flag is used indeploy/job.yaml
to pause the snowcat binary and provide information to the user on how to extract results from a running container. NOTE: this is not useful outside the Job usage scenario.
To set these flags with environment variables, simply uppercase the
configuration variable name, and replace dashes with underscores, for example:
istio-version
-> ISTIO_VERSION