sql-xel-parser 1.0.0__tar.gz

sql_xel_parser-1.0.0/.gitignore

@@ -0,0 +1,106 @@
+# XEL Parser .gitignore
+
+# Data directories
+data/
+*.xel
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+.claude/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Distribution / packaging
+.Python
+pip-log.txt
+pip-delete-this-directory.txt
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Outputs
+*.json
+*.csv
+*.txt
+!requirements.txt
+!LICENSE.txt
+*.log
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear in the root
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Project specific
+test_events.xel
+output*.json
+big_sample.json
+extracted_*.json
+*.xel

sql_xel_parser-1.0.0/INSTALL.md

@@ -0,0 +1,213 @@
+# Installation Guide
+
+## Quick Install
+
+```bash
+# Install from source
+pip install -e .
+
+# Or install from PyPI
+pip install sql-xel-parser
+```
+
+## Usage After Installation
+
+After installation, you can use the `sql-xel-parser` command directly:
+
+```bash
+sql-xel-parser --help
+sql-xel-parser input.xel -f json -o output.json
+```
+
+## Installation Methods
+
+### Method 1: Install from Source (Development)
+
+```bash
+# Clone or navigate to the project directory
+cd xel-log-parse
+
+# Install in development mode
+pip install -e .
+
+# Test installation
+sql-xel-parser --version
+```
+
+### Method 2: Install from Source (Standard)
+
+```bash
+cd xel-log-parse
+pip install .
+```
+
+### Method 3: Install from PyPI
+
+```bash
+pip install sql-xel-parser
+```
+
+### Method 4: Install with pipx (Isolated)
+
+```bash
+# Install pipx if you don't have it
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+
+# Install sql-xel-parser in isolated environment
+pipx install /path/to/xel-log-parse
+
+# Now sql-xel-parser command is globally available
+sql-xel-parser --help
+```
+
+## Verify Installation
+
+```bash
+# Check if package is installed
+pip show sql-xel-parser
+
+# Check version
+sql-xel-parser --version
+
+# Test with help
+sql-xel-parser --help
+
+# Test with real data
+sql-xel-parser data/sql-ptfm-prod-westus3 -r --limit 5 -f summary
+```
+
+## Command Availability
+
+The `sql-xel-parser` command will be available if your Python's `bin` directory is in your PATH:
+
+```bash
+# Check if command is available
+which sql-xel-parser
+
+# If not found, you can:
+# 1. Use: sql-xel-parser (works everywhere)
+# 2. Add Python bin to PATH
+# 3. Use the full path: /path/to/python/bin/sql-xel-parser
+```
+
+### Adding Python bin to PATH
+
+**macOS/Linux:**
+```bash
+# Find your Python bin directory
+python -c "import sys; import os; print(os.path.dirname(sys.executable))"
+
+# Add to your ~/.bashrc or ~/.zshrc
+export PATH="/path/to/python/bin:$PATH"
+
+# Reload shell
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+**Windows:**
+```cmd
+# Add to PATH in System Environment Variables
+# Or use: sql-xel-parser
+```
+
+## Dependencies
+
+- Python 3.8 or higher
+- python-dateutil (automatically installed)
+
+## Uninstall
+
+```bash
+pip uninstall sql-xel-parser
+```
+
+## Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/josephvolmer/sql-xel-parser.git
+cd sql-xel-parser
+
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with dependencies
+pip install -e .
+
+# Run tests
+sql-xel-parser data/test.xel -f summary
+```
+
+## Troubleshooting
+
+### Command not found: sql-xel-parser
+
+**Solution**: Use `sql-xel-parser` instead, or add Python's bin directory to your PATH.
+
+### ImportError: No module named 'xel_parser'
+
+**Solution**: Make sure you've installed the package:
+```bash
+pip install -e .
+```
+
+### Permission denied when installing
+
+**Solution**: Use `--user` flag:
+```bash
+pip install --user -e .
+```
+
+Or use a virtual environment:
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+## Quick Start Examples
+
+```bash
+# After installation, try these commands:
+
+# Parse single file
+sql-xel-parser data/sql-ptfm-prod-westus3/master/SqlDbAuditing_ServerAudit/2026-03-03/19_00_56_668_0.xel -f summary
+
+# Parse entire directory
+sql-xel-parser data/sql-ptfm-prod-westus3 -r -f summary
+
+# Export to JSON
+sql-xel-parser data/sql-ptfm-prod-westus3 -r --limit 100 -o audit_data.json
+
+# Search for specific content
+sql-xel-parser data/sql-ptfm-prod-westus3 -r --search "Payments"
+
+# Count events by type
+sql-xel-parser data/sql-ptfm-prod-westus3 -r --count-by name
+```
+
+## Platform-Specific Notes
+
+### macOS
+- Uses system Python or Homebrew Python
+- Virtual environments recommended
+- Use `python3` and `pip3` commands
+
+### Linux
+- Usually has Python pre-installed
+- May need to install `python3-venv` package
+- Use `python3` and `pip3` commands
+
+### Windows
+- Install Python from python.org
+- Use `python` and `pip` commands
+- May need to run as Administrator for system-wide install
+
+## Support
+
+For issues or questions:
+- Check the [README.md](README.md) for usage examples
+- See [QUICKSTART.md](QUICKSTART.md) for quick start guide
+- Report bugs at: https://github.com/josephvolmer/sql-xel-parser/issues

sql_xel_parser-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 XEL Parser Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sql_xel_parser-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include PYPI.md
+include LICENSE
+include requirements.txt
+include QUICKSTART.md
+include INSTALL.md
+recursive-include docs *.md *.sql
+recursive-include examples *.py
+recursive-include sql_xel_parser *.py
+prune data
+prune __pycache__
+prune .github
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *~
+global-exclude .DS_Store

sql_xel_parser-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: sql-xel-parser
+Version: 1.0.0
+Summary: Parse and analyze SQL Server Extended Events (.xel) files
+Home-page: https://github.com/josephvolmer/sql-xel-parser
+Author: SQL XEL Parser Contributors
+Author-email: 
+License: MIT
+Project-URL: Homepage, https://github.com/josephvolmer/sql-xel-parser
+Project-URL: Documentation, https://github.com/josephvolmer/sql-xel-parser/blob/main/README.md
+Project-URL: Repository, https://github.com/josephvolmer/sql-xel-parser
+Project-URL: Bug Tracker, https://github.com/josephvolmer/sql-xel-parser/issues
+Keywords: xel,sql-server,extended-events,audit-logs,parser
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Logging
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dateutil>=2.8.0
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# SQL XEL Parser
+
+Parse and analyze SQL Server Extended Events (.xel) files without requiring SQL Server.
+
+Tested with **671 production Azure SQL audit log files**. Works cross-platform (Linux, macOS, Windows).
+
+## Features
+
+✅ **No SQL Server Required** - Parse binary XEL files using UTF-16 extraction
+✅ **Multiple Export Formats** - JSON, JSON Lines, CSV, Text, Markdown, Summary
+✅ **Advanced Filtering** - By event name, time range, field values, regex search
+✅ **Analysis Tools** - Aggregation, grouping, counting, top-N queries
+✅ **Batch Processing** - Recursive directory processing with 671+ file support
+✅ **Python API** - Use programmatically in your own scripts
+✅ **CLI Tool** - Powerful command-line interface
+
+## Installation
+
+```bash
+pip install sql-xel-parser
+```
+
+## Quick Start
+
+### Command Line
+
+```bash
+# Get summary of XEL files
+sql-xel-parser audit.xel -f summary
+
+# Export to JSON
+sql-xel-parser audit.xel -o events.json
+
+# Process entire directory
+sql-xel-parser /path/to/logs/ -r -f summary
+
+# Search for security events
+sql-xel-parser audit.xel --search "fail|error|denied" -o security.json
+
+# Export to CSV for Excel
+sql-xel-parser audit.xel -f csv -o export.csv
+```
+
+### Python API
+
+```python
+from sql_xel_parser import XELParser, XELAnalyzer, XELConverter
+
+# Parse XEL file
+parser = XELParser('audit.xel')
+events = list(parser.parse())
+
+# Analyze and filter
+analyzer = XELAnalyzer(events)
+failed_logins = analyzer.search('(?i)fail|error')
+
+# Export results
+converter = XELConverter()
+json_output = converter.to_json(failed_logins.get_events(), indent=2)
+```
+
+## What Gets Extracted
+
+**Successfully extracted:**
+- Event names and types
+- Timestamps
+- SQL statements and error messages
+- Server names, databases, IPs
+- Usernames and session IDs
+- All text-based audit data
+
+**May be incomplete:**
+- Pure numeric fields without string representation
+- Binary data types (BLOB)
+- Complex nested binary structures
+
+Uses UTF-16 string extraction method - ideal for text-heavy events like audit logs and security monitoring.
+
+## Use Cases
+
+- **Azure SQL Audit Logs** - Primary use case, tested with production data
+- **Security & Compliance** - Track access patterns and failed logins
+- **SQL Server Extended Events** - Parse system_health, query tracking
+- **Automated Monitoring** - CI/CD pipelines and scheduled analysis
+- **SIEM Integration** - Export to Splunk, ELK, or other log analysis tools
+
+## Documentation
+
+- [Full Documentation](https://github.com/josephvolmer/sql-xel-parser)
+- [Quick Start Guide](https://github.com/josephvolmer/sql-xel-parser/blob/main/QUICKSTART.md)
+- [Advanced Usage](https://github.com/josephvolmer/sql-xel-parser/tree/main/docs)
+- [Python API Examples](https://github.com/josephvolmer/sql-xel-parser/tree/main/examples)
+
+## Requirements
+
+- Python 3.8+
+- python-dateutil
+
+## License
+
+MIT License
+
+## Links
+
+- **GitHub**: https://github.com/josephvolmer/sql-xel-parser
+- **Issues**: https://github.com/josephvolmer/sql-xel-parser/issues
+- **Documentation**: https://github.com/josephvolmer/sql-xel-parser/blob/main/README.md

sql_xel_parser-1.0.0/PYPI.md

@@ -0,0 +1,107 @@
+# SQL XEL Parser
+
+Parse and analyze SQL Server Extended Events (.xel) files without requiring SQL Server.
+
+Tested with **671 production Azure SQL audit log files**. Works cross-platform (Linux, macOS, Windows).
+
+## Features
+
+✅ **No SQL Server Required** - Parse binary XEL files using UTF-16 extraction
+✅ **Multiple Export Formats** - JSON, JSON Lines, CSV, Text, Markdown, Summary
+✅ **Advanced Filtering** - By event name, time range, field values, regex search
+✅ **Analysis Tools** - Aggregation, grouping, counting, top-N queries
+✅ **Batch Processing** - Recursive directory processing with 671+ file support
+✅ **Python API** - Use programmatically in your own scripts
+✅ **CLI Tool** - Powerful command-line interface
+
+## Installation
+
+```bash
+pip install sql-xel-parser
+```
+
+## Quick Start
+
+### Command Line
+
+```bash
+# Get summary of XEL files
+sql-xel-parser audit.xel -f summary
+
+# Export to JSON
+sql-xel-parser audit.xel -o events.json
+
+# Process entire directory
+sql-xel-parser /path/to/logs/ -r -f summary
+
+# Search for security events
+sql-xel-parser audit.xel --search "fail|error|denied" -o security.json
+
+# Export to CSV for Excel
+sql-xel-parser audit.xel -f csv -o export.csv
+```
+
+### Python API
+
+```python
+from sql_xel_parser import XELParser, XELAnalyzer, XELConverter
+
+# Parse XEL file
+parser = XELParser('audit.xel')
+events = list(parser.parse())
+
+# Analyze and filter
+analyzer = XELAnalyzer(events)
+failed_logins = analyzer.search('(?i)fail|error')
+
+# Export results
+converter = XELConverter()
+json_output = converter.to_json(failed_logins.get_events(), indent=2)
+```
+
+## What Gets Extracted
+
+**Successfully extracted:**
+- Event names and types
+- Timestamps
+- SQL statements and error messages
+- Server names, databases, IPs
+- Usernames and session IDs
+- All text-based audit data
+
+**May be incomplete:**
+- Pure numeric fields without string representation
+- Binary data types (BLOB)
+- Complex nested binary structures
+
+Uses UTF-16 string extraction method - ideal for text-heavy events like audit logs and security monitoring.
+
+## Use Cases
+
+- **Azure SQL Audit Logs** - Primary use case, tested with production data
+- **Security & Compliance** - Track access patterns and failed logins
+- **SQL Server Extended Events** - Parse system_health, query tracking
+- **Automated Monitoring** - CI/CD pipelines and scheduled analysis
+- **SIEM Integration** - Export to Splunk, ELK, or other log analysis tools
+
+## Documentation
+
+- [Full Documentation](https://github.com/josephvolmer/sql-xel-parser)
+- [Quick Start Guide](https://github.com/josephvolmer/sql-xel-parser/blob/main/QUICKSTART.md)
+- [Advanced Usage](https://github.com/josephvolmer/sql-xel-parser/tree/main/docs)
+- [Python API Examples](https://github.com/josephvolmer/sql-xel-parser/tree/main/examples)
+
+## Requirements
+
+- Python 3.8+
+- python-dateutil
+
+## License
+
+MIT License
+
+## Links
+
+- **GitHub**: https://github.com/josephvolmer/sql-xel-parser
+- **Issues**: https://github.com/josephvolmer/sql-xel-parser/issues
+- **Documentation**: https://github.com/josephvolmer/sql-xel-parser/blob/main/README.md