SWMap

SWMap is an advanced Service Worker security analyzer for modern web apps. It discovers, fetches, and analyzes Service Workers to surface scope risks, caching issues, route exposure, Workbox/Flutter usage, and dangerous code patterns and, when you enable it, it can prove behavior with a headless browser.

Built for bug bounty hunters, red teams, and product security engineers who want rigor, speed, and explainability.

Why SWMap?

Most PWA/SW security reviews stop at “is there a service worker?”. Real apps are messier. SWMap digs into what the worker does and how it can widen attack surface:

• Security-first analysis — Effective scope calc (incl. Service-Worker-Allowed), widened/root scopes, mixed-origin pitfalls.
• Caching scrutiny — Sensitive route patterns (/api, /auth, /user, /admin), pre/runtime caching, cache-poisoning indicators.
• Workbox awareness — Detects Workbox and modules (precaching, routing, strategies).
• Code-risk patterns — eval / Function usage, string timers, credentialed fetches, dynamic execution hints.
• Infra/CDN SW detection — Tags known CDN/infrastructure SWs (e.g. Akamai 3PM) so you don’t over-hunt them.
• Operator-ready outputs — TSV (grep-able) and JSON (automation); quiet/verbose modes; evidence dumps.
• Deep analysis (Static + Dynamic) — AST-based parsing for precision and Headless validation for real behavior.
• WAF-friendly + profiles — Can send browsery headers and load per-target profiles.
• Auth-only SWs — Can import a Netscape cookie file into headless to reach SWs that only appear after login.

Features at a Glance

• Dynamic runtime validation (headless/Playwright): prove interception, precache behavior, and SWR hints.
• AST recursion (bounded, same-origin): follows importScripts/ESM up to a safe depth for better route/strategy visibility.
• Scope math & misconfig flags: effective scope calculation + Service-Worker-Allowed detection; flags widened/root scopes.
• Workbox & Flutter awareness: detects Workbox patterns/strategies and zero-byte Flutter SWs.
• Route seeding & same-origin crawl: drive coverage with --route-seed; crawling is on when headless is on.
• Proxy-ready: --proxy is wired for both HTTP fetching and headless context.
• Login automation: --login-script + --login-wait to get past auth-gated registrations.
• Evidence bundles: --evidence-dir dumps summary, headless responses, redacted HTML.
• CI-friendly outputs: --json, --sarif, and --nuclei-out for re-verification.

---

Flow: Targets → Fetch/Probe → Static (scope, routes, patterns) → AST → (optional) Headless validate → Score & flag → Filter/Serialize → Summarize.

---

🚀 Quick Start

Requirements

• Python ≥ 3.9
• macOS / Linux / Windows
• Optional (AST fallback): Node.js ≥ 16 (used when the Python AST can’t parse)
• Optional (Headless): Playwright + a browser (we’ll install below)

Install

Linux / macOS (bash):

git clone https://github.com/bl4ck0w1/swmap.git
cd swmap
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# install playwright runtime browser
python -m playwright install chromium
# make the installer executable
chmod +x scripts/install.sh
# add swmap to PATH if your install script does that
bash scripts/install.sh

Windows (PowerShell):

git clone https://github.com/bl4ck0w1/swmap.git
cd swmap
py -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
python -m playwright install chromium
#powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# install the CLI entrypoint
.\scripts\install.ps1

After install, you should have the swmap command on PATH. You can always run in place with:

python swmap.py

Verify

swmap --help
# or
python swmap.py --help

Update Security Patterns (optional)

python scripts/update_patterns.py --update
# validate
python scripts/update_patterns.py --validate

🧰 CLI Overview

$ swmap --help
                                                            
  █████  █████ ███ █████ █████████████    ██████   ████████ 
 ███░░  ░░███ ░███░░███ ░░███░░███░░███  ░░░░░███ ░░███░░███
░░█████  ░███ ░███ ░███  ░███ ░███ ░███   ███████  ░███ ░███
 ░░░░███ ░░███████████   ░███ ░███ ░███  ███░░███  ░███ ░███
 ██████   ░░████░████    █████░███ █████░░████████ ░███████ 
░░░░░░     ░░░░ ░░░░    ░░░░░ ░░░ ░░░░░  ░░░░░░░░  ░███░░░  
                                                   ░███     
                                                   █████    
                                                  ░░░░░     

Service Worker Security Mapper - Advanced SW recon tool

Information Options
  -h, --help                Show this help message and exit
  -V, --version             Show version information and exit

Input Options
  target                    Single URL to scan (e.g., https://target.com)
  -i, --input               Read targets from file (one URL per line)

Scan Options
  -P, --parallel            Concurrent scans (default: 6, max: 20)
  -t, --timeout             Request timeout in seconds (default: 15)
  --max-sw-bytes            Maximum SW script size in bytes (default: 524288)
  --max-routes              Maximum routes to extract per SW (default: 50)
  --deep                    Legacy deep static parse hint (sets AST recursion to 3 if not overridden)
  --delay-ms                Delay between headless navigations (ms) to avoid rate-limits (default: 0)
  --no-probe                Skip common SW filename probing

Enhanced Analysis (runtime + AST)
  --headless                Enable headless browser validation (default: off)
  --no-headless             Disable headless browser validation
  --ast                     Enable AST analysis (default)
  --no-ast                  Disable AST analysis
  --ast-depth               Recurse importScripts/ESM to this depth (default: 2; or 3 if --deep and not overridden)
  --headless-timeout        Headless timeout (ms)
  --headless-max-routes     Max routes to probe dynamically
  --headless-crawl          Crawl same-origin links (default)
  --no-headless-crawl       Disable headless crawl
  --route-seed              Seed route (repeatable)
  --login-script            Path to a JS file to run before crawl (auto-login etc.)
  --login-wait              CSS selector to wait for after login
  --prove-interception      Prove response interception via Service Worker
  --no-prove-interception   Disable interception proof
  --prove-precache          Prove precache via CacheStorage audit
  --no-prove-precache       Disable precache proof
  --prove-swr               Try to detect stale-while-revalidate behavior
  --no-prove-swr            Disable SWR proof
  --offline-replay          After crawl, go offline and replay seeds to prove offline render
  --offline-wait            Wait after going offline before replay (ms, default: 1500)
  --logout-url              URL to visit to logout before offline replay
  --logout-script           JS to execute to logout before offline replay

Security Analysis Options
  --risk-threshold          Only output findings with risk score >= N (0-100)
  --no-risk-assessment      Skip risk scoring and security analysis
  --include-patterns        Output detected security patterns in detail
  --sensitive-only          Only output workers with sensitive route patterns

Output Options
  --json                    Emit stable JSON v1
  --sarif                   Write SARIF 2.1.0 file with findings
  --nuclei-out              Directory to write Nuclei verifier templates (one per SW)
  --evidence-dir            Directory to dump evidence bundle per target
  --explain                 Print a decision chain for each target (discover/probe/runtime)
  --quiet                   Suppress comments and progress messages
  --verbose                 Detailed analysis output
  -o, --output              Write results table/JSONL to file

Network Options
  --ua, --user-agent        Custom User-Agent string
  --header                  Extra HTTP header (repeatable, e.g., "K: V")
  --cookie                  Cookie header value
  --proxy                   HTTP/SOCKS proxy URL (applies to HTTP fetches and headless)
  --cookies                 Path to Netscape cookie file to import into headless context (auth-only SWs)
  --profile                 Load headers/cookies/proxy/login/route seeds from JSON profile (CLI args override profile)
  --waf-friendly            Apply a browser-like header set to reduce WAF/tooling blocks

For more information visit: https://github.com/bl4ck0w1/swmap

🧾 Usage Examples

1. Single target, TSV to stdout (quick recon)

swmap https://app.example.com

2. Batch scan, JSON to file (automation)

swmap -i targets.txt --json -o results.jsonl

3. Deeper static pass, but only keep interesting SWs

swmap -i urls/subdomains.txt --deep --sensitive-only --risk-threshold 70 --json

4. Scan as logged-in user (cookies + browsery headers + headless)

swmap https://portal.example.com --headless --cookie "SESSION=abcd1234" --waf-friendly --route-seed /app/ --route-seed /api/me --json

5. Headless proof + evidence bundle (for a report)

swmap https://pwa.example.com --headless --prove-interception --prove-precache --route-seed /dashboard --route-seed /api/profile --evidence-dir evidence/ --json

6. Generate SARIF + Nuclei from a scan (CI / team handoff)

swmap -i scope.txt --json --sarif swmap.sarif --nuclei-out nuclei-templates/

7. Use a profile (headers/proxy/cookies stored in JSON)

swmap https://intranet.example.com --profile profiles/intranet.json --json

❓ Some Questions You Could Ask

1. **Could this Service Worker control more of my origin than