kaudite

README

kaudite

Kubernetes Audit Tool - A security testing tool for auditing Kubernetes clusters, extracting service account tokens, and analysing cluster configurations.

Overview

kaudite is a command-line tool designed for security professionals and DevOps engineers to audit Kubernetes clusters. It provides two main capabilities as of right now, with more planned:

1. Cluster Configuration Dump: Extract and export cluster resources and metadata for analysis. It does this in a way which is compatible for import with IceKube if needed.
2. Privilege Escalation Testing: Identify and extract service account tokens from pods to test for potential privilege escalation paths. This is designed to be run after kubeletmein when you have compromised the kubelet on a node and want to ferret out secrets you can access that may allow for privilege escalation.

Features

Dump Command

• Dump all cluster resources to local files (JSON or YAML)
• Export cluster metadata including API versions, resources, and preferred versions
• Organise output by resource kind and/or namespace
• Automatically sanitise sensitive data (e.g., Secret data)
• Filter out specific API versions
• Support for custom output directories

Escalate Command

• Extract service account tokens from pods
• Support for both legacy Secret-based tokens and TokenRequest API
• Check extracted tokens for interesting permissions (pod create/update, secret get)
• Generate kubeconfig files with discovered service account contexts
• Watch mode for continuous monitoring of new pods
• Filter by namespace, service account, or node
• Option to ignore the pod the tool is running in

Installation

Pre-built Binaries

Download the latest release from the Releases page.

Build from Source

Prerequisites:

• Go 1.21.4 or later
• Make (optional, for using the Makefile)

# Clone the repository
git clone https://github.com/4armed/kaudite.git
cd kaudite

# Build using Make
make build

# Or build directly with Go
go build -o kaudite .

Usage

Dump Command

Dump all cluster resources to the current directory:

kaudite dump

Dump to a specific directory with YAML output:

kaudite dump --directory ./cluster-dump --output yaml

Organise output by namespace and kind:

kaudite dump --split-ns --split-kind --directory ./organised-dump

Skip specific API versions:

kaudite dump --skip-api-versions clientsecret.supervisor.pinniped.dev/v1alpha1

Skip metadata output (used by IceKube):

kaudite dump --skip-metadata

Available Flags:

• -d, --directory: Output directory (default: current directory)
• -c, --create-directory: Create output directory if it doesn't exist (default: true)
• -x, --skip-api-versions: Skip resources with specified API versions
• -m, --skip-metadata: Skip metadata in output
• --split-kind: Split output into directories based on resource kind
• --split-ns: Split output into directories based on namespace
• -o, --output: Output format (json, yaml)
• -v, --verbose: Enable verbose logging

Escalate Command

Extract all service account tokens from pods:

kaudite escalate

Extract tokens from a specific namespace:

kaudite escalate --namespace kube-system

Extract tokens for a specific service account:

kaudite escalate --service-account my-sa --namespace default

Watch for new pods and extract tokens continuously:

kaudite escalate --watch

Extract tokens only from pods on a specific node. You will almost certainly need to supply this parameter on modern Kubernetes deployments:

kaudite escalate --node node-1

Disable permission checking:

kaudite escalate --check-permissions=false

Available Flags:

• -o, --output-file: Kubeconfig output file (default: kaudite.yaml)
• -n, --namespace: Namespace to read secrets from
• -s, --service-account: Specific service account to target
• --node: Node to process secrets for
• -p, --check-permissions: Check tokens for interesting permissions (default: true)
• -w, --watch: Watch for new pods after initial listing
• --ignore-own-pod: Skip processing the pod the tool is running in (default: true)
• -v, --verbose: Enable verbose logging

Examples

Security Audit Workflow

1. Dump cluster configuration for analysis:

   kaudite dump --directory ./audit-$(date +%Y%m%d) --output yaml
   

2. Extract service account tokens and check for privilege escalation:

   kaudite escalate --output-file ./discovered-tokens.yaml --check-permissions
   

3. Test discovered tokens:

   kubectl --kubeconfig ./discovered-tokens.yaml get pods
   

Continuous Monitoring

Monitor a namespace for new pods and extract their tokens:

kaudite escalate --namespace production --watch --output-file production-tokens.yaml

Security Considerations

⚠️ Important: This tool is designed for authorised security testing and auditing purposes only.

• Only use this tool on clusters you own or have explicit permission to test
• The tool extracts service account tokens which can be used for privilege escalation
• Generated kubeconfig files contain sensitive authentication tokens
• Always follow responsible disclosure practices when reporting security findings
• Ensure compliance with your organisation's security policies before use

Requirements

• Kubernetes cluster access (via kubeconfig or in-cluster configuration)
• Appropriate RBAC permissions to list pods, secrets, and service accounts
• For TokenRequest API support: Kubernetes 1.20+ with BoundServiceAccountTokenVolume feature enabled

Building

Using Make

# Build with tests
make build

# Quick build without tests
make build-quick

# Build Linux binary
make build-linux

# Run tests
make test

# Clean build artifacts
make clean

Manual Build

# Get version from git
GITVERSION=$(git describe --dirty --always --tags --long)

# Build
go build -trimpath -ldflags "-X github.com/4armed/kaudite/cmd.GitVersion=${GITVERSION}" -o kaudite .

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

4ARMED Limited

• Website: https://www.4armed.com/
• Email: code@4armed.com

Disclaimer

This tool is provided for security testing and auditing purposes. Users are responsible for ensuring they have proper authorisation before using this tool on any Kubernetes cluster. The authors and contributors are not responsible for any misuse of this tool.

Documentation

Overview

Copyright © 2024 4ARMED Limited