One-liner: A powerful, GUI-driven regex utility for red teams, pentesters, and developers — build, test, catalog and apply regular expressions with presets, live testing, and an extensible pattern library.
- About
- Features
- Repository structure (file map)
- Requirements & Installation
- Quick Start
- GUI Walkthrough & Usage
- Pattern Library & Presets
- Advanced Workflows & Integrations
- Extending & Development Guide
- Security Considerations
- Testing & QA
- Contribution Guidelines
- Changelog & Roadmap
- Credits & License
This repository provides an Advanced Regex Tool implemented in Python with a GUI layer. It aims to be a professional tool for interactive regex construction, validation, and application to real-world red‑team and developer tasks (logs, data extraction, reconnaissance, input validation, payload shaping).
The README below assumes the project is the single-file GUI application advanced_regex_tool.py backed by a centralized pattern_library.py and a presets JSON file. The layout is designed for maintainers and contributors who want a high-quality README suitable for published open-source projects and pentest toolkits.
- Interactive GUI for building and testing regular expressions.
- Pattern library with categorized reusable patterns and presets (emails, IPs, URLs, tokens, hashes, credentials, etc.).
- JSON-based presets for quick matching and sample payloads.
- Save/load presets and export pattern sets.
- Real-time match highlighting, explained capture groups, an FF8 d replacement preview.
- Utilities to generate synthetic test data from regex presets (for fuzzing and testing parsers).
- Audit/logging capabilities (
regex_tool_audit.log) for reproducible test runs. - Theme customization and user-friendly UI (
Theme.py). - Designed for offline usage (no telemetry) — suitable for restricted/air-gapped pentest environments.
Short map of files and what they do (use this as a quick guide for contributors):
advanced_regex_tool.py— Main application (entrypoint). Implements GUI, event handlers, pattern tester, and export features.pattern_library.py— Pattern library module. Contains categorized regex patterns, helper functions to fetch/search patterns, and documentation strings for each pattern.regex_presets.json— Presets & sample payloads. JSON file listing preset patterns and sample inputs for quick testing and templates.Theme.py— UI theming. Centralized color, font, and layout configuration used by the GUI (light/dark/retro modes, etc.).requirements.txt— Python dependencies required to run the GUI and supporting modules.assets/— Static assets used by the UI (icons, images, screenshots).
Tip: Keep the
pattern_library.pyfocused on pure data — minimal side effects — so it can be safelyimported in CI and unit tests.
System requirements
- Python 3.10+ recommended (backwards compatibility depends on used libraries).
- Works on Windows, Linux, and macOS (GUI toolkit dependent — see
requirements.txt).
Install (recommended, in virtualenv)
python -m venv .venv
source .venv/bin/activate # or `.venv\Scripts\activate` on Windows
pip install --upgrade pip
pip install -r requirements.txtRun the app
python advanced_regex_tool.pyIf you prefer to run from source with editable installs for development:
pip install -e .(If a setup.py / pyproject.toml is added later, prefer using pip install -e ..)
- Launch the application:
python advanced_regex_tool.py. - Load a preset from
regex_presets.jsonvia File → Load Preset. - Type or paste test input into the Input panel.
- Build or paste a regex in the Pattern field and press Test / Run.
- Inspect matches, capture groups, and replacement preview in the Results panel.
- Save successful patterns to the pattern library or export them as JSON.
Main panels
- Pattern Editor — Where you type or assemble regex pieces. Supports named placeholders and helpers.
- Preset Browser — Category view of common patterns (IP, email, URL, credit card, hash, JWT, etc.).
- Input / Test Case — Paste raw data you want to match against. Multi-line support included.
- Results / Explanation — Match list, named groups, start/end indexes, and a short natural language explanation for each capture (where possible).
- Generator utilities — Produce fake inputs from presets for testing downstream parsers and fuzzers.(Disabled)
Power user features
- Toggle multiline / DOTALL / IGNORECASE / VERBOSE flags.
- Visual group numbering and replacement preview.
- Export selected patterns to
regex_presets.jsonor to clipboard. - Audit logging toggle — keep a private activity log for test repeatability.
Organization
- Patterns are grouped (e.g.,
network,identity,tokens,filepaths,hashes). - Each pattern entry should include:
name,description,pattern,flags, andexamples.
Example pattern entry (JSON)
{
"name": "IPv4 (strict)",
"description": "Matches valid IPv4 addresses 0.0.0.0 - 255.255.255.255",
"pattern": "(?:(?:25[0-5]|2[0-4]\d|[01]?\d?\d)(?:\.|$)){4}",
"flags": "",
"examples": ["192.168.1.1", "8.8.8.8"]
}Maintainer best practices
- Keep patterns readable: use inline comments and
re.VERBOSEwhen patterns are complex. - Add strict and permissive variants where appropriate (for discovery vs. validation).
- Provide at least 2–3 positive and negative examples per pattern for tests.
For Red Teamers & Pentesters
- Use the pattern generator to produce test payloads for log ingestion or WAF bypass testing.
- Chain regex extraction with output → CSV export → pivot into other reconnaissance tools.
- Integrate with
Auto-Exploit Toolstyle modules by exporting a curated set of patterns for scanning (bulk match across large targets).
For Developers
- Validate user inputs (emails, IPs, tokens) by using a strict validation variant from the library.
- Use presets to seed unit tests and fuzzers.
Automation
- CLI mode (not present yet) should support
--run-presets,--export-results,--audit-log, and--headlessoptions to integrate into CI pipelines.
Code style & tests
- Use
blackandruff/flake8for consistent formatting and linting. - Add unit tests under
tests/that cover pattern matching, serialization, and GUI-critical flows (if GUI logic is separated from presentation).
Module responsibilities
pattern_library.py— data only (no UI I/O), with simple APIs:get_pattern(name),search(query),list_categories().advanced_regex_tool.py— should import the library, wire UI, and keep business logic minimal in the UI layer.Theme.py— purely theme constants and helper accessors.
Suggested development tasks
- Split GUI code into
ui/package if the file grows beyond ~1500–2000 lines. - Add a dedicated CLI entry-point (
console_scripts) for headless usage. - Add example
pyproject.tomland pre-commit hooks.
- Never run untrusted regexes against data with catastrophic backtracking without timeouts/limits — provide a sandboxed execution or a regex timeout.
- Sanitize exported logs containing sensitive matched data; provide opt-in redaction or per-pattern redaction rules.
- If the app offers pastebin or sharing features, warn users about PII and default to local-only exports.
Regex ReDoS mitigation
- Use safe matching libraries (e.g.,
regexpackage with timeouts) or run regex evaluation in a subprocess with controlled CPU/time limits. - Provide an option to analyze a pattern's worst-case complexity and suggest safer alternatives.
- Unit tests: patterns, serialization, example IO.
- Fuzz tests: generate inputs from presets and run them through each pattern to ensure no catastrophic behavior.
- GUI tests: keep the UI logic thin and test it using a combination of unit tests for logic and manual QA for UX.
- Fork the repository.
- Create a feature branch:
git checkout -b feat/my-new-pattern. - Add tests for any new pattern or behavior (in
tests/). - Run linters and formatters, then open a PR describing the change.
Code of conduct
- Be respectful. Follow normal open-source etiquette.
- v0.x — Core GUI + pattern library + presets.
- v0.x+1 — CLI/headless mode, safe-runtime for regexes.
- v1.0 — Stable API, packaged releases, built installers for Windows/macOS.
Test an IP
# pattern (permissive)
\b(?:\d{1,3}\.){3}\d{1,3}\b
# strict — removes values >255 using a more precise subpattern
(?:(?:25[0-5]|2[0-4]\d|[01]?\d?\d)(?:\.|$)){4}
Export sample JSON entry to add to regex_presets.json
{
"category": "network",
"name": "IPv4 - strict",
"pattern": "(?:(?:25[0-5]|2[0-4]\\d|[01]?\\d?\\d)(?:\\.|$)){4}",
"description": "Strict IPv4 pattern",
"examples": ["192.168.0.1"]
}- Author: SpectralZero
- License:
MIT LICENSE.
Last Updated: Version 2.0 | 2024
