Building a YAML-Powered Vulnerability Scanner: Inside Jaeles’ Signature Architecture
Hook
Most vulnerability scanners become obsolete the moment a new CVE drops. Jaeles turns that model on its head by letting you write YAML signature files instead of recompiling Go code.
Context
Web application security scanning has traditionally been a binary choice: use commercial tools with comprehensive checks but poor automation, or write custom scripts that are fast but disposable. Enter Jaeles, written by @j3ssiejjj and integrated into the Osmedeus reconnaissance framework. The core insight is architectural: vulnerability detection logic lives entirely outside the scanner binary in external YAML “signatures.” Instead of hardcoding checks in Go, Jaeles loads signatures from a separate repository at runtime. This means adding support for a fresh CVE doesn’t require touching the codebase—just drop a new YAML file in the signatures repository. For security researchers who need to test the same vulnerability pattern across hundreds of domains daily, this separation of concerns is transformative. The scanner becomes infrastructure; the signatures become the intelligence layer.
Technical Insight
Jaeles’ architecture revolves around three components: the core scanning engine written in Go, a separate signatures repository containing YAML-based vulnerability definitions, and a flexible input/output pipeline designed for Unix-style composition. The scanner accepts URLs from stdin, files, or direct parameters, executes signature checks concurrently, and outputs results in JSON or HTML. Let’s examine how a signature works in practice. Here’s a simplified example based on the repository structure:
id: nginx-vhost-xss
info:
name: Nginx Virtual Host Header XSS
severity: medium
requests:
- method: GET
redirect: false
headers:
- Host: "{{.BaseURL}}><script>alert(1)</script>"
detections:
- type: word
part: response
words:
- "><script>alert(1)</script>"This signature injects a payload into the Host header and checks if it reflects in the response unescaped. The {{.BaseURL}} syntax uses Go’s template engine, allowing dynamic parameter substitution at runtime. You can override these variables via the -p flag: jaeles scan -s 'nginx' -u target.com -p 'root=[[.URL]]'. This parameterization enables signature reuse across different contexts without duplication.
The concurrency model leverages Go’s goroutines. When you specify -c 50, Jaeles spawns up to 50 concurrent workers processing URLs from the input queue. Each worker loads applicable signatures based on selectors (regex patterns matching signature paths), executes HTTP requests, and evaluates detection rules. The selector system allows combining multiple patterns: jaeles scan -s 'jira' -s 'ruby' -u target.com loads all signatures matching either pattern, while -x 'tomcat' excludes specific signatures. The -G flag treats selectors as raw regex rather than path globs, giving you precise control over which checks run.
Integration points extend Jaeles beyond standalone scanning. The server mode (jaeles server) exposes an HTTP API for triggering scans programmatically. A Burp Suite plugin sends requests from your proxy history directly to Jaeles for signature-based analysis. Output can be piped to custom handlers: -f 'noti_slack "{{.vulnInfo}}"' sends findings to Slack in real-time. This composability mirrors the Unix philosophy—small tools doing one thing well, connected via standard interfaces.
The HTML reporting system generates visual summaries of scan results, aggregating vulnerabilities by severity and providing remediation context. Combined with the JSON output mode, you can feed results into ticketing systems, vulnerability management platforms, or custom dashboards. The proxy support (--proxy http://127.0.0.1:8080) lets you route all traffic through Burp or other intercepting proxies for manual verification of automated findings.
One architectural decision worth highlighting: signature storage is intentionally decoupled. The main repository contains only the engine; the separate jaeles-signatures repository must be installed independently. This keeps the core tool lightweight and allows the signature database to evolve independently. Contributors can submit new signatures without touching the scanner codebase, lowering the barrier to community contributions. The trade-off is slightly more complex setup—new users must install both repositories.
Gotcha
The signature dependency is Jaeles’ biggest operational friction. The scanner requires the separate jaeles-signatures repository to function. The README warns about this with a bold note, but first-time users may miss it and face errors when no signatures load. This design choice optimizes for modularity but creates setup complexity compared to tools that bundle default checks.
The README lists several “Planned Features” including adding more signatures, input sources, APIs, proxy plugins, Web UI actions, and integrations with other tools. Without visibility into recent development activity, it’s unclear which features are actively being pursued. For production security workflows, this introduces uncertainty about long-term maintenance and support.
Signature quality is community-dependent. The effectiveness of Jaeles depends on what signatures exist for your target stack. If you’re testing niche frameworks or newer technologies, coverage may be limited. The signature repository requires manual review to understand what’s actually tested. YAML-based checks can have false positives depending on how detection rules are written, requiring signature auditing before trusting results.
Verdict
Use Jaeles if you’re conducting bug bounty research or red team assessments at scale where speed and customization matter more than comprehensive out-of-the-box coverage. It shines when you need to run targeted checks across thousands of URLs daily, integrate scanning into existing reconnaissance pipelines (especially if you’re already using Osmedeus), or rapidly prototype custom vulnerability checks without compiling code. The YAML signature model is ideal for teams that want to codify institutional knowledge about specific vulnerability patterns. Skip it if you need a turnkey solution with guaranteed maintenance and support—the planned features and development trajectory aren’t fully clear from the README. Also avoid it if you’re unfamiliar with Go tooling and YAML debugging, as troubleshooting signature failures requires understanding the template syntax and HTTP detection logic. For researchers who value lightweight, Unix-friendly tools designed for pipeline integration, Jaeles offers a compelling architecture that respects the principle of separation between scanning infrastructure and vulnerability intelligence.
