Docs · KubeForenSys

KubeForenSys

Collect forensic data from Azure Kubernetes Service clusters into Log Analytics for KQL analysis.

On this page

Start here 

KubeForenSys collects forensic data from a Kubernetes cluster and ingests it into an Azure Log Analytics workspace for post-compromise analysis. It targets Azure Kubernetes Service (AKS) clusters. A run connects to the cluster through your kubeconfig, provisions the Azure collection infrastructure, collects eight data types, and uploads each to its own custom table in Log Analytics, where you analyze it with KQL.

Tool landing page: the KubeForenSys tool overview.

What the tool is for 

KubeForenSys captures the parts of a Kubernetes cluster that matter in an investigation and puts them somewhere queryable. It collects pod logs, cluster events, container command history, service accounts, suspicious pods, RBAC bindings, CronJob information, and network policies, and sends them to Azure Log Analytics so you can investigate what happened across the cluster.

Requirements 

  • Python 3.8 or higher.
  • kubectl configured and authenticated to the target cluster.
  • An Azure subscription with permissions to create Log Analytics resources.

Installation 

Clone the repository and install the Python dependencies:

Shell
git clone git@github.com:invictus-ir/KubeForenSys.git
cd KubeForenSys
pip install -r requirements.txt

A virtual environment is recommended but not required.

Dependencies (from requirements.txt): kubernetes, python-dotenv, azure.identity, azure.monitor.ingestion, azure.mgmt.containerservice, azure.mgmt.loganalytics, tenacity.

Authentication and permissions 

Cluster access

The tool loads a kubeconfig file through the Kubernetes Python client (config.load_kube_config()). For an AKS cluster, generate credentials first, for example:

Shell
az login
az aks get-credentials -g $RESOURCE_GROUP_NAME -n $AKS_NAME

Azure authentication

The tool authenticates to Azure using DefaultAzureCredential.

Azure permissions

The repository provides a custom role definition at resources/azure/custom_role.json with the following actions:

  • Microsoft.OperationalInsights/workspaces/write
  • Microsoft.OperationalInsights/workspaces/tables/write
  • Microsoft.Insights/dataCollectionEndpoints/write
  • Microsoft.Insights/dataCollectionRules/write
  • Microsoft.Insights/dataCollectionRules/read
  • Microsoft.OperationalInsights/workspaces/sharedKeys/action
  • Microsoft.ContainerService/managedClusters/read

Data actions: Microsoft.Insights/Metrics/Write, Microsoft.Insights/Telemetry/Write.

The custom role can be created at resource group level. The repository notes the same authorization can be achieved with built-in roles: Log Analytics Contributor (workspace and table writes, shared keys), Monitoring Contributor (DCR/DCE creation and telemetry writes), and Reader or Kubernetes Service RBAC Viewer (AKS cluster read). The documentation recommends the custom role to follow least privilege.

Configuration 

Provide three settings through a .env file in the project root or as environment variables:

Shell
SUBSCRIPTION_ID="your-azure-subscription-id"
CLUSTER_NAME="your-aks-cluster-name"
RESOURCE_GROUP_NAME="your-resource-group-name"

Core workflow 

  1. Authenticate kubectl to the target cluster and confirm it can reach the cluster.
  2. Set the subscription, cluster, and resource group values.
  3. Run the tool. It provisions the Azure collection infrastructure, collects the eight data types from the cluster, and uploads each to its custom table in Log Analytics.
  4. Analyze the data in Log Analytics with KQL.

Commands and operating modes 

Basic run with defaults:

Shell
python3 kubeforensys.py

With command-line arguments:

Shell
python3 kubeforensys.py \
  --since_seconds 172800 \
  --workspace_name "MyKubeWorkspace" \
  --dce_name "MyDataCollectionEndpoint" \
  --location "eastus"

Options:

  • --since_seconds: fetch logs from this many seconds ago. Default 86400 (24 hours).
  • --workspace_name: Log Analytics workspace name. Default KubeForenSys-LAW.
  • --dce_name: Data Collection Endpoint name. Default Kube-DCE.
  • --location: Azure region. Default westeurope.

Inputs and scope 

  • The tool collects from the cluster identified by your kubeconfig and the .env values.
  • --since_seconds bounds how far back pod logs are fetched.
  • Collection skips the kube-system, azure-arc, and gatekeeper-system namespaces.

State collection and time-windowed logs

The collected types differ in how time applies. Pod logs are fetched over a time window set by --since_seconds. The other types (events, service accounts, suspicious pods, RBAC bindings, CronJobs, network policies) are collected as the cluster state present at run time.

Outputs and structure 

Data lands in Azure Log Analytics in eight custom tables:

Scroll horizontally on narrow screens.

Table

Contents

kubelogs_CL

Container logs from all pods

kubeevents_CL

Kubernetes cluster events

commandhistory_CL

Command history from containers

serviceaccounts_CL

Service account configurations

suspiciouspods_CL

Potentially suspicious pods

rbacbindings_CL

RBAC bindings and roles

cronjobs_CL

CronJob container information

networkpolicies_CL

Network policy configurations

The tool also creates a Log Analytics workspace, a Data Collection Endpoint, and Data Collection Rules (one per data type). Data is retained for 30 days by default, adjustable in the Azure portal.

Operational cautions and limitations 

  • The tool focuses on Azure Kubernetes Service. The Azure ingestion path and the AKS read permission are Azure-specific. Coverage for other managed Kubernetes services is not asserted by the repository.
  • The tool creates Azure infrastructure during a run and does not currently support deleting it. Remove the created objects manually in the Azure portal, in the configured resource group.
  • Namespaces kube-system, azure-arc, and gatekeeper-system are skipped, so their contents are not collected.

Troubleshooting (documented failure modes) 

  • Kubernetes access. Verify kubectl is configured and can reach the cluster.
  • Resource creation. Confirm the Azure subscription has permission to create Log Analytics resources (see custom_role.json).
  • Network access. Ensure the Data Collection Endpoint has the network access it needs.

Version and source information 

  • Repository: https://github.com/invictus-ir/KubeForenSys
  • Branch: main
  • Commit: d45f408ce4a99f65b91a9868cde1f2899a38a1a8
  • Retrieved: 2026-10-07
  • Releases: none published at retrieval.