Jaeles: Building a Signature-Based Web Scanner That Speaks YAML

Hook

Most web vulnerability scanners lock you into their detection logic. Jaeles inverts this: the scanner is just the engine, and you control the signatures.

Context

Web application security testing has historically been split between two extremes: commercial scanners with comprehensive checks but zero customization, and raw scripting tools that require building everything from scratch. If you're a bug bounty hunter who discovers a novel injection technique, you face a choice: manually test hundreds of targets, or spend days writing custom automation. Tools like Burp Suite offer powerful features but require expensive licenses and don't integrate cleanly into CI/CD pipelines. Meanwhile, simple fuzzers like ffuf excel at parameter discovery but lack structured vulnerability detection frameworks.

Jaeles emerged from the Osmedeus project ecosystem to solve this specific pain point: automated web vulnerability scanning where the detection logic lives outside the codebase. By treating signatures as first-class data rather than hardcoded checks, it enables security researchers to share, version, and iterate on vulnerability definitions independently of the scanning engine. Written in Go for speed and concurrency, Jaeles prioritizes pipeline integration over GUI features, making it a natural fit for modern recon workflows where tools chain together through stdin/stdout.

Technical Insight

The core architectural decision in Jaeles is its signature format. Each signature is a YAML file describing HTTP requests, variable substitution, and detection patterns. Here's a simplified signature structure:

id: wordpress-xmlrpc-pingback
info:
  name: WordPress XML-RPC Pingback Detection
  severity: medium

requests:
  - raw:
      - |
        POST /xmlrpc.php HTTP/1.1
        Host: {{.BaseURL}}
        Content-Type: text/xml
        
        <?xml version="1.0" encoding="UTF-8"?>
        <methodCall>
          <methodName>pingback.ping</methodName>
          <params>
            <param><value><string>{{.payload}}</string></value></param>
            <param><value><string>{{.BaseURL}}</string></value></param>
          </params>
        </methodCall>
    
    matchers:
      - type: word
        words:
          - "pingback.ping"
        part: body

This signature defines a complete test case: the HTTP request structure with variable placeholders, and matching criteria to identify vulnerable responses. The {{.BaseURL}} and {{.payload}} syntax enables template-based substitution at runtime, allowing single signatures to test multiple targets with varying contexts.

The selector system provides fine-grained control over which signatures execute. Instead of running all available checks, you can filter by tags, severity, or regex patterns. Run a scan targeting only SQL injection checks with jaeles scan -u https://target.com -s 'sqli.*', or exclude noisy signatures with negative selectors. This matters when you're testing production systems where aggressive scanning could trigger WAFs or cause service disruption.

Concurrency handling in Jaeles uses Go's goroutine model to parallelize signature execution across targets. The engine maintains configurable worker pools: one for target processing and another for signature execution per target. You control this through CLI flags like --concurrency for target-level parallelism and --parallel for signature-level threading. For large-scale campaigns scanning thousands of domains, this architecture means you're bottlenecked by network I/O rather than CPU, which is exactly where you want to be.

The server mode transforms Jaeles from a CLI tool into a persistent scanning service. Launch it with jaeles server and it exposes a REST API for submitting scans, querying results, and managing signatures dynamically. This architecture supports use cases like maintaining a long-running scanner that receives targets from bug bounty webhooks or integrating with custom dashboards. The API returns structured JSON responses, making it straightforward to parse results programmatically:

// Example API interaction
type ScanRequest struct {
    URL        string   `json:"url"`
    Signatures []string `json:"signatures"`
}

resp, err := http.Post(
    "http://localhost:5000/scan",
    "application/json",
    bytes.NewBuffer(scanRequestJSON),
)

The Burp Suite integration deserves special attention because it bridges manual and automated testing workflows. The Python extension captures requests from Burp's proxy, forwards them to Jaeles for signature-based analysis, and displays results within Burp's UI. This means you can manually explore an application, identify interesting endpoints, right-click to scan with Jaeles, and see vulnerability results without context-switching to a terminal. It's the integration most commercial scanners charge premium prices for, implemented as a lightweight plugin.

Signature extensibility goes beyond simple pattern matching. Signatures support conditional logic, chained requests where one response informs the next request, and custom detection scripts. You can extract values from responses using regex or JSON paths, then inject them into subsequent requests. This enables complex multi-step vulnerability testing like authentication bypasses that require establishing a session before attempting privilege escalation.

Gotcha

The signature-based model is both Jaeles's greatest strength and its Achilles heel. Your scanning effectiveness is entirely dependent on signature quality and coverage. Unlike commercial scanners with dedicated research teams continuously updating detection logic, Jaeles relies on community contributions to the signature repository. If that repository goes stale—which community projects often do—you're maintaining signatures yourself. The official signature repository hasn't seen major updates recently, which is a yellow flag for production use.

Integration complexity can bite you. While Jaeles pipes data beautifully, the signature format requires understanding YAML quirks, HTTP raw request formatting, and the template variable system. Writing effective signatures demands security expertise: knowing what to test, how to craft malicious payloads, and how to distinguish true positives from false alarms. The learning curve is steeper than point-and-click scanners, making it less suitable for junior team members or organizations without dedicated security engineers. Additionally, the documentation, while functional, lacks the comprehensive tutorials and troubleshooting guides you'd find with more mature projects. Expect to read source code when things don't behave as expected.

Verdict

Use if: You're a bug bounty hunter or pentester who needs customizable automation that integrates with existing recon pipelines (subfinder → httpx → jaeles workflows). It's ideal when you've discovered novel vulnerability patterns and want to test them at scale across multiple targets without writing custom scripts from scratch. The Burp integration makes it valuable for teams doing manual testing who want to augment their workflow with automated checks on interesting endpoints. Skip if: You need a turnkey scanner with comprehensive, actively maintained vulnerability coverage out of the box. The project's maintenance status suggests it's not receiving active development, making it risky for organizations requiring long-term support. Also skip if your team lacks security expertise to write and validate signatures—you'll spend more time troubleshooting than scanning. For those scenarios, Nuclei offers a similar architecture with significantly more active development and a larger template community.