,--,
,--. ,---.'|
,--/ /| ,--, ,----.. | | :
,---,': / ' ,--.'| / / \ : : |
: : '/ / | | : / . : | ' :
.--.--. | ' , : : ' . / ;. \ ; ; '
/ / ' ' | / ,--.--. | ' | ,---. . ; / ` ; ' | |__
| : /`./ | ; ; / \ ' | | / \ ; | ; \ ; | | | :.'|
| : ;_ : ' \ .--. .-. | | | : / / | | : | ; | ' ' : ;
\ \ `. | | ' \__\/: . . ' : |__ . ' / | . | ' ' ' : | | ./
`----. \ ' : |. \ ," .--.; | | | '.'| ' ; /| ' ; \; / | ; : ;
/ /`--' / | | '_\.' / / ,. | ; : ; ' | / | \ \ ', . \ | ,/
'--'. / ' : | ; : .' \ | , / | : | ; : ; | '---'
`--'---' ; |,' | , .-./ ---`-' \ \ / \ \ .'`--"
'---' `--`---' `----' `---`
🚀 Automate and run KQL queries at scale, using GitHub Actions.
Tip
Detailed documentation can be found in the corresponding wiki page.
sKaleQL is a comprehensive template repository for managing, executing, and organizing Kusto Query Language (KQL) queries against Azure Log Analytics Workspaces. It provides a structured approach to query management with flexible output formats, automated execution, and comprehensive documentation.
There is really no limit to how you can use this tool, it all depends on why you're using Log Analytics Workspaces in the first place. Whether it's for security, monitoring, auditing, or something else entirely, if you have a set of KQL queries you want to automate, sKaleQL is here to help. By combining the power of KQL with GitHub Actions, you can bring automation and efficiency into your workflows effortlessly.
Here are just a few examples of how sKaleQL can make a difference:
- Automated Health Checks: Regularly query for service errors, performance issues, or failed logins.
- Security and Threat Monitoring: Run scheduled KQL queries to detect anomalies, threats, or suspicious activity.
- Compliance Validation: Ensure logs reflect adherence to security and compliance standards.
- Reporting and Data Export: Generate and store logs or metrics as artifacts for analysis.
- Cost and Usage Monitoring: Track ingestion rates and resource usage for optimization.
- Incident Response Automation: Pre-build incident queries to speed up investigations.
- Incident Retrospectives: Pull relevant logs automatically after an incident for analysis and RCA (Root Cause Analysis).
- Business Metrics Tracking: Monitor and extract business-level KPIs (e.g., signups, payments, errors) if logged to Azure Monitor.
- Resource Inventory Tracking: Automatically query and export lists of resources (VMs, Containers, Storage) for auditing purposes.
- Structured Query Management: Organize queries in logical folders
- Flexible Output Formats: JSON, Table, TSV, YAML, and more
- Multiple Output Destinations: Console display or file output
- Advanced Transformations: Filter results using JMESPath queries
- Compression Options: Optimize storage with GZIP or ZIP compression
- Automation: GitHub Actions workflow for scheduled query execution
- Local Execution: Run queries from your development environment
For detailed information on using this repository, refer to:
- Azure Guide: Azure setup
- GitHub Guide: GitHub Actions setup
- Configuration Guide: KQL config file format and options
- Usage Guide: General usage instructions
Note
The device folder under library is a sample folder containing example queries. You can create your own folders and queries as needed. All new folder must be created under the library directory.
Click the Use this template button to create your own repository based on this template.
- Register an app in Azure Active Directory
- Assign
Log Analytics Readerpermissions to the app - Configure federated credentials for GitHub Actions
- Set required secrets:
AZURE_CLIENT_ID,AZURE_SUBSCRIPTION_ID,AZURE_TENANT_ID,WORKSPACE_ID - Store your KQL queries in folders under the
librarydirectory - Configure query outputs using
.kql-config.yamlfiles
- Go to the Actions tab and run the execute-queries workflow
- Specify the folder containing your queries
# Set up virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r .github/scripts/kql_query_executor/requirements.txt
# Login to Azure
az login
# Make sure you are in the repository root
python .github/scripts/kql_query_executor/main.py \
-w <workspace-id> \
-f library/<query-folder> \
-s kql-config-schema.jsonInformation about contributing to this project can be found here.
A project created with love in Greece by christosgalano & cyb3rmik3.
This project is licensed under the MIT License.