Skip to content

docs: add blog featuring the seclang_parser #447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fzipi merged 6 commits into from
Jan 30, 2026
Merged

docs: add blog featuring the seclang_parser #447

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
203b894
docs: add blog featuring the seclang_parser
fzipi Jan 22, 2026
3858e03
Initial plan
Copilot Jan 22, 2026
1c56832
fix: apply review feedback on seclang_parser blog post
Copilot Jan 22, 2026
d48ac0f
Merge pull request #448 from coreruleset/copilot/sub-pr-447
fzipi Jan 22, 2026
7b1b516
Apply suggestions from code review
fzipi Jan 29, 2026
11ec401
chore: apply code review comments
fzipi Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions content/blog/2026-01-22-introducing-seclang-parser-unified-antlr-based-parser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
---
date: '2026-01-22'
categories:
- Blog
title: 'Introducing seclang_parser: A Unified ANTLR-Based Parser for SecLang'
author: fzipi
---

We are excited to introduce the community to a significant development in the CRS ecosystem: the [seclang_parser](https://github.com/coreruleset/seclang_parser), an ANTLR-based parser for the SecLang configuration language used by ModSecurity and compatible WAF engines.

## What is seclang_parser?

The seclang_parser is a grammar-based parser built using ANTLR 4 (Another Tool for Language Recognition) that provides a unified, language-agnostic approach to parsing ModSecurity's SecLang configuration files. Rather than maintaining separate parsing implementations across different programming languages, this project consolidates efforts around a single, authoritative grammar specification.

## Why Was This Needed?

Over the years, the CRS and ModSecurity ecosystem has seen multiple attempts to parse and manipulate SecLang configuration files across various programming languages. Each implementation required its own parser, leading to:

- **Fragmentation**: Different parsing implementations with varying levels of completeness and accuracy
- **Duplication of Effort**: Each language community had to reinvent the wheel when building SecLang tooling
- **Maintenance Burden**: Keeping multiple parsers synchronized with SecLang language changes was challenging
- **Inconsistencies**: Subtle differences between parsers could lead to unexpected behavior

The seclang_parser addresses these challenges by providing a single source of truth for the SecLang grammar. From this unified grammar definition, parser code can be automatically generated for multiple target languages, ensuring consistency and reducing maintenance overhead.

## Design Goals and Principles

The project was designed with several key principles in mind:

### Language-Agnostic Architecture
The parser operates independently of its destination programming language. The ANTLR grammar files serve as the authoritative specification, and language-specific parsers are generated automatically.

### High-Level Abstractions
Rather than dealing with low-level parsing details in each target language, the grammar prioritizes simplicity and clarity. This reduces implementation errors and makes the parser easier to understand and maintain.

### Minimal Dependencies
The generated parsers are designed to work with native code without requiring external dependencies or cgo bindings. This makes integration into existing projects straightforward and reduces potential compatibility issues.

### Multi-Language Support
Currently, the project includes working implementations for:
- **Go**: Providing native Go parsing capabilities for tools and services
- **Python 3**: Supporting Python-based tooling and automation

The architecture allows for easy addition of parsers for other languages as the community needs them.

### Implementation Independence
It's important to note that the parser focuses on the SecLang language itself, which is technically independent of any specific implementation. The parser does not differentiate between ModSecurity v2 and v3 or other WAF engine implementations. This means that consuming tools are responsible for handling implementation-specific differences. For example, linters should be aware of features not implemented in ModSecurity v3, and validation tools should account for implementation-specific behaviors.

## How Will It Be Used?

The seclang_parser opens up numerous possibilities for tooling and automation around CRS and ModSecurity configurations:

### Static Analysis Tools
Developers can build linters and validators that analyze SecLang configurations for potential issues, best practices violations, or security concerns before deployment.

### Configuration Management
Automated systems can parse, validate, and transform CRS configurations as part of deployment pipelines, ensuring consistency across environments.

### IDE Integration
The parser can power syntax highlighting, code completion, and error detection in development environments, improving the developer experience when working with CRS rules.

### Testing and Validation
Quality assurance tools can parse rule configurations to extract metadata, validate rule structures, and ensure compliance with project standards.

### Rule Analysis and Optimization
Performance analysis tools can examine rule patterns and suggest optimizations or identify potentially problematic configurations.

### Migration and Transformation
The parser enables building tools that can migrate configurations between different versions or transform rules to match specific deployment requirements.

## Getting Started

The seclang_parser is available on GitHub at [github.com/coreruleset/seclang_parser](https://github.com/coreruleset/seclang_parser). The repository includes:

- ANTLR grammar files defining the SecLang language
- Generated parser code for Go and Python
- Comprehensive test suites ensuring parser accuracy
- Example usage and integration patterns

### Testing the Parser

For Go developers:
```sh
go generate ./... && go test ./...
```

For Python developers:
```sh
# Install dependencies with uv
uv pip install -e .
# Run tests with pytest
pytest
```

## Current Status and Future Direction

The project is already in active use with multiple releases published. Version 0.3.2 was released in November 2025, and the project continues to evolve based on community feedback and real-world usage.

This project represents a collaborative effort to improve the CRS tooling ecosystem. By providing a robust, unified parser, we're laying the foundation for the next generation of CRS development and operations tools.

As the project matures, we expect to see:

- Additional language bindings contributed by the community
- Enhanced error reporting and recovery mechanisms
- Extended test coverage for edge cases and complex configurations
- Integration with existing CRS tooling and workflows

## Contributing

We welcome contributions from the community. Whether you're interested in:

- Adding support for additional programming languages
- Improving the grammar specification
- Enhancing test coverage
- Building tools that leverage the parser
- Reporting bugs or suggesting improvements

Your contributions help make the CRS ecosystem stronger and more accessible.

The seclang_parser is licensed under Apache-2.0, ensuring it can be freely used and integrated into both open source and commercial projects.

## Learn More

To explore the seclang_parser, visit the [GitHub repository](https://github.com/coreruleset/seclang_parser). For questions, suggestions, or discussions about the parser, join us on the [CRS Slack channel](https://owasp.slack.com/archives/CBKGH8A5P) or open an issue on GitHub.

We're excited to see what the community builds with this new tool, and we look forward to your feedback and contributions as the project continues to evolve.