Open source · Python

KubeForenSys

Capture the forensic state of an Azure Kubernetes Service cluster into Azure Log Analytics: pod logs, events, RBAC, service accounts and more. Then investigate it with KQL.

License
GPL-2.0
Releases
None published · runs from main
Runs on
Python 3.8+ · kubectl · Azure subscription
Cost
Free · Log Analytics usage in your subscription
SetupShell
# Clone and install
git clone git@github.com:invictus-ir/KubeForenSys.git
pip install -r requirements.txt

# Point it at the cluster (.env works too)
export CLUSTER_NAME="your-aks-cluster-name"
python3 kubeforensys.py --since_seconds 172800
✓ eight custom tables in Log Analytics
Works withAzure Kubernetes Service

What it does

A cluster in, KQL tables out

Reads the cluster through your kubeconfig and writes each data type to its own table in Azure Log Analytics.

SourcesOutputsKubeForenSysPython
AKS cluster
Pods and events
RBACkubelogs_CLLog Analytics workspaceEight custom tablesQuery with KQL · kept 30 days

How it works

From cluster to KQL in four steps

Defaults: the last 24 hours, a workspace named KubeForenSys-LAW, region westeurope. All can be changed.

  1. 01

    Authenticate

    Reads your kubeconfig (for AKS, from az aks get-credentials) and signs in to Azure with DefaultAzureCredential.

  2. 02

    Provision

    Creates the workspace, a data collection endpoint and one collection rule per data type.

  3. 03

    Collect

    Pulls pod logs, events, RBAC, service accounts and more from every namespace except kube-system, azure-arc and gatekeeper-system.

  4. 04

    Query with KQL

    Each data type lands in its own custom table. Data is kept for 30 days by default.

What it collects

Eight tables, one per data type

Each table can be queried with KQL in the Log Analytics workspace.

Read the docs
DataWhatTable
Pod logsContainer logs from pods across namespaceskubelogs_CL
EventsKubernetes cluster eventskubeevents_CL
Command historyShell history extracted from containerscommandhistory_CL
Service accountsService account configurationserviceaccounts_CL
Suspicious podsPods flagged against the tool’s detection criteriasuspiciouspods_CL
RBACRoles and role bindingsrbacbindings_CL
CronJobsCronJob container informationcronjobs_CL
Network policiesNetwork policy configurationnetworkpolicies_CL

Before you run it

Permissions, scope and clean-up

Built for AKS

The Azure ingestion path and the managedClusters/read permission are specific to Azure Kubernetes Service. Other managed Kubernetes services are not covered.

What it creates

A Log Analytics workspace, a data collection endpoint, one collection rule per data type and eight custom tables.

Clean-up

Not automated. Delete the created objects in the configured resource group in the Azure portal.

What it skips

The kube-system, azure-arc and gatekeeper-system namespaces are not collected.

Where it’s used

Where it fits

ServiceIncident response

Investigating a compromised Kubernetes cluster.

Open
ServiceCompromise Assessment

Checking a cluster for signs of compromise, as of a date.

Releases

No tagged releases yet

Recent commits

The repository has no published releases. Install from the main branch, and check the commit history for recent changes.

More tools

The rest of the toolkit

KubeForenSys

Captured the cluster and need help reading it?

A responder can query the tables with you.