Docs · KubeForenSys
KubeForenSys
Collect forensic data from Azure Kubernetes Service clusters into Log Analytics for KQL analysis.
Tool landing page: the KubeForenSys tool overview.
On this page
- Start here
- What the tool is for
- Requirements
- Installation
- Authentication and permissions
- Cluster access
- Azure authentication
- Azure permissions
- Configuration
- Core workflow
- Commands and operating modes
- Inputs and scope
- State collection and time-windowed logs
- Outputs and structure
- Operational cautions and limitations
- Troubleshooting (documented failure modes)
- Version and source information
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.
kubectlconfigured 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:
git clone git@github.com:invictus-ir/KubeForenSys.git
cd KubeForenSys
pip install -r requirements.txtA 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:
az login
az aks get-credentials -g $RESOURCE_GROUP_NAME -n $AKS_NAMEAzure 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/writeMicrosoft.OperationalInsights/workspaces/tables/writeMicrosoft.Insights/dataCollectionEndpoints/writeMicrosoft.Insights/dataCollectionRules/writeMicrosoft.Insights/dataCollectionRules/readMicrosoft.OperationalInsights/workspaces/sharedKeys/actionMicrosoft.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:
SUBSCRIPTION_ID="your-azure-subscription-id"
CLUSTER_NAME="your-aks-cluster-name"
RESOURCE_GROUP_NAME="your-resource-group-name"Core workflow
- Authenticate
kubectlto the target cluster and confirm it can reach the cluster. - Set the subscription, cluster, and resource group values.
- 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.
- Analyze the data in Log Analytics with KQL.
Commands and operating modes
Basic run with defaults:
python3 kubeforensys.pyWith command-line arguments:
python3 kubeforensys.py \
--since_seconds 172800 \
--workspace_name "MyKubeWorkspace" \
--dce_name "MyDataCollectionEndpoint" \
--location "eastus"Options:
--since_seconds: fetch logs from this many seconds ago. Default86400(24 hours).--workspace_name: Log Analytics workspace name. DefaultKubeForenSys-LAW.--dce_name: Data Collection Endpoint name. DefaultKube-DCE.--location: Azure region. Defaultwesteurope.
Inputs and scope
- The tool collects from the cluster identified by your kubeconfig and the
.envvalues. --since_secondsbounds how far back pod logs are fetched.- Collection skips the
kube-system,azure-arc, andgatekeeper-systemnamespaces.
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 |
|---|---|
| Container logs from all pods |
| Kubernetes cluster events |
| Command history from containers |
| Service account configurations |
| Potentially suspicious pods |
| RBAC bindings and roles |
| CronJob container information |
| 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, andgatekeeper-systemare skipped, so their contents are not collected.
Troubleshooting (documented failure modes)
- Kubernetes access. Verify
kubectlis 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.