{"id":32648231,"url":"https://github.com/bl4ck0w1/swmap","last_synced_at":"2026-04-21T03:31:40.071Z","repository":{"id":319236445,"uuid":"1076628900","full_name":"bl4ck0w1/swmap","owner":"bl4ck0w1","description":"Service Worker security scanner that maps scope, caching, routes \u0026 Workbox behavior into actionable risk static-first with optional AST/headless.","archived":false,"fork":false,"pushed_at":"2025-11-04T20:06:27.000Z","size":170,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-04T21:21:39.756Z","etag":null,"topics":["app-sec","bug-bounty","crawler","dynamic-analysis","penetration-testing","playwright","pwa","recon","security-tools","service-worker","static-analysis","web-security","work-box"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bl4ck0w1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-15T06:09:44.000Z","updated_at":"2025-11-04T20:06:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"c5efe51d-2b7a-4232-9884-bfe759d936fc","html_url":"https://github.com/bl4ck0w1/swmap","commit_stats":null,"previous_names":["bl4ck0w1/swmap"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bl4ck0w1/swmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bl4ck0w1%2Fswmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bl4ck0w1%2Fswmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bl4ck0w1%2Fswmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bl4ck0w1%2Fswmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bl4ck0w1","download_url":"https://codeload.github.com/bl4ck0w1/swmap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bl4ck0w1%2Fswmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32075222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-sec","bug-bounty","crawler","dynamic-analysis","penetration-testing","playwright","pwa","recon","security-tools","service-worker","static-analysis","web-security","work-box"],"created_at":"2025-10-31T06:01:54.415Z","updated_at":"2026-04-21T03:31:40.066Z","avatar_url":"https://github.com/bl4ck0w1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SWMap\n\n![swmap-logo](logo.png)\n\n**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.\n\nBuilt for bug bounty hunters, red teams, and product security engineers who want rigor, speed, and explainability.\n\n## Why SWMap?\n\nMost 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:\n\n- **Security-first analysis** — Effective scope calc (incl. `Service-Worker-Allowed`), widened/root scopes, mixed-origin pitfalls.\n- **Caching scrutiny** — Sensitive route patterns (`/api`, `/auth`, `/user`, `/admin`), pre/runtime caching, cache-poisoning indicators.\n- **Workbox awareness** — Detects Workbox and modules (precaching, routing, strategies).\n- **Code-risk patterns** — `eval` / `Function` usage, string timers, credentialed fetches, dynamic execution hints.\n- **Infra/CDN SW detection** — Tags known CDN/infrastructure SWs (e.g. Akamai 3PM) so you don’t over-hunt them.\n- **Operator-ready outputs** — TSV (grep-able) and JSON (automation); quiet/verbose modes; evidence dumps.\n- **Deep analysis (Static + Dynamic)** — **AST-based** parsing for precision and **Headless** validation for real behavior.\n- **WAF-friendly + profiles** — Can send browsery headers and load per-target profiles.\n- **Auth-only SWs** — Can import a Netscape cookie file into headless to reach SWs that only appear after login.\n\n## Features at a Glance\n\n- **Dynamic runtime validation (headless/Playwright)**: prove interception, precache behavior, and SWR hints.\n- **AST recursion (bounded, same-origin)**: follows `importScripts`/ESM up to a safe depth for better route/strategy visibility.\n- **Scope math \u0026 misconfig flags**: effective scope calculation + `Service-Worker-Allowed` detection; flags widened/root scopes.\n- **Workbox \u0026 Flutter awareness**: detects Workbox patterns/strategies and zero-byte Flutter SWs.\n- **Route seeding \u0026 same-origin crawl**: drive coverage with `--route-seed`; crawling is on when headless is on.\n- **Proxy-ready**: `--proxy` is wired for both HTTP fetching and headless context.\n- **Login automation**: `--login-script` + `--login-wait` to get past auth-gated registrations.\n- **Evidence bundles**: `--evidence-dir` dumps summary, headless responses, redacted HTML.\n- **CI-friendly outputs**: `--json`, `--sarif`, and `--nuclei-out` for re-verification.\n\n---\n**Flow:** Targets → Fetch/Probe → Static (scope, routes, patterns) → AST → *(optional)* Headless validate → Score \u0026 flag → Filter/Serialize → Summarize.\n\n---\n\n## 🚀 Quick Start\n\n### Requirements\n\n- **Python** ≥ 3.9\n- **macOS / Linux / Windows**\n- **Optional (AST fallback):** **Node.js** ≥ 16 (used when the Python AST can’t parse)\n- **Optional (Headless):** **Playwright** + a browser (we’ll install below)\n\n### Install\n\n**Linux / macOS (bash):**\n\n```bash\ngit clone https://github.com/bl4ck0w1/swmap.git\ncd swmap\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n# install playwright runtime browser\npython -m playwright install chromium\n# make the installer executable\nchmod +x scripts/install.sh\n# add swmap to PATH if your install script does that\nbash scripts/install.sh\n````\n\n**Windows (PowerShell):**\n\n```powershell\ngit clone https://github.com/bl4ck0w1/swmap.git\ncd swmap\npy -m venv .venv\n.\\.venv\\Scripts\\activate\npip install -r requirements.txt\npython -m playwright install chromium\n#powershell\nSet-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass\n# install the CLI entrypoint\n.\\scripts\\install.ps1\n```\n\nAfter install, you should have the `swmap` command on PATH. You can always run in place with:\n\n```bash\npython swmap.py\n```\n\n### Verify\n\n```bash\nswmap --help\n# or\npython swmap.py --help\n```\n\n### Update Security Patterns (optional)\n\n```bash\npython scripts/update_patterns.py --update\n# validate\npython scripts/update_patterns.py --validate\n```\n\n## 🧰 CLI Overview\n\n```bash\n\n$ swmap --help\n                                                            \n  █████  █████ ███ █████ █████████████    ██████   ████████ \n ███░░  ░░███ ░███░░███ ░░███░░███░░███  ░░░░░███ ░░███░░███\n░░█████  ░███ ░███ ░███  ░███ ░███ ░███   ███████  ░███ ░███\n ░░░░███ ░░███████████   ░███ ░███ ░███  ███░░███  ░███ ░███\n ██████   ░░████░████    █████░███ █████░░████████ ░███████ \n░░░░░░     ░░░░ ░░░░    ░░░░░ ░░░ ░░░░░  ░░░░░░░░  ░███░░░  \n                                                   ░███     \n                                                   █████    \n                                                  ░░░░░     \n\nService Worker Security Mapper - Advanced SW recon tool\n\nInformation Options\n  -h, --help                Show this help message and exit\n  -V, --version             Show version information and exit\n\nInput Options\n  target                    Single URL to scan (e.g., https://target.com)\n  -i, --input               Read targets from file (one URL per line)\n\nScan Options\n  -P, --parallel            Concurrent scans (default: 6, max: 20)\n  -t, --timeout             Request timeout in seconds (default: 15)\n  --max-sw-bytes            Maximum SW script size in bytes (default: 524288)\n  --max-routes              Maximum routes to extract per SW (default: 50)\n  --deep                    Legacy deep static parse hint (sets AST recursion to 3 if not overridden)\n  --delay-ms                Delay between headless navigations (ms) to avoid rate-limits (default: 0)\n  --no-probe                Skip common SW filename probing\n\nEnhanced Analysis (runtime + AST)\n  --headless                Enable headless browser validation (default: off)\n  --no-headless             Disable headless browser validation\n  --ast                     Enable AST analysis (default)\n  --no-ast                  Disable AST analysis\n  --ast-depth               Recurse importScripts/ESM to this depth (default: 2; or 3 if --deep and not overridden)\n  --headless-timeout        Headless timeout (ms)\n  --headless-max-routes     Max routes to probe dynamically\n  --headless-crawl          Crawl same-origin links (default)\n  --no-headless-crawl       Disable headless crawl\n  --route-seed              Seed route (repeatable)\n  --login-script            Path to a JS file to run before crawl (auto-login etc.)\n  --login-wait              CSS selector to wait for after login\n  --prove-interception      Prove response interception via Service Worker\n  --no-prove-interception   Disable interception proof\n  --prove-precache          Prove precache via CacheStorage audit\n  --no-prove-precache       Disable precache proof\n  --prove-swr               Try to detect stale-while-revalidate behavior\n  --no-prove-swr            Disable SWR proof\n  --offline-replay          After crawl, go offline and replay seeds to prove offline render\n  --offline-wait            Wait after going offline before replay (ms, default: 1500)\n  --logout-url              URL to visit to logout before offline replay\n  --logout-script           JS to execute to logout before offline replay\n\nSecurity Analysis Options\n  --risk-threshold          Only output findings with risk score \u003e= N (0-100)\n  --no-risk-assessment      Skip risk scoring and security analysis\n  --include-patterns        Output detected security patterns in detail\n  --sensitive-only          Only output workers with sensitive route patterns\n\nOutput Options\n  --json                    Emit stable JSON v1\n  --sarif                   Write SARIF 2.1.0 file with findings\n  --nuclei-out              Directory to write Nuclei verifier templates (one per SW)\n  --evidence-dir            Directory to dump evidence bundle per target\n  --explain                 Print a decision chain for each target (discover/probe/runtime)\n  --quiet                   Suppress comments and progress messages\n  --verbose                 Detailed analysis output\n  -o, --output              Write results table/JSONL to file\n\nNetwork Options\n  --ua, --user-agent        Custom User-Agent string\n  --header                  Extra HTTP header (repeatable, e.g., \"K: V\")\n  --cookie                  Cookie header value\n  --proxy                   HTTP/SOCKS proxy URL (applies to HTTP fetches and headless)\n  --cookies                 Path to Netscape cookie file to import into headless context (auth-only SWs)\n  --profile                 Load headers/cookies/proxy/login/route seeds from JSON profile (CLI args override profile)\n  --waf-friendly            Apply a browser-like header set to reduce WAF/tooling blocks\n\nFor more information visit: https://github.com/bl4ck0w1/swmap\n```\n\n## 🧾 Usage Examples\n\n**1. Single target, TSV to stdout (quick recon)**\n\n```bash\nswmap https://app.example.com\n```\n\n**2. Batch scan, JSON to file (automation)**\n\n```bash\nswmap -i targets.txt --json -o results.jsonl\n```\n\n**3. Deeper static pass, but only keep interesting SWs**\n\n```bash\nswmap -i urls/subdomains.txt --deep --sensitive-only --risk-threshold 70 --json\n```\n\n**4. Scan as logged-in user (cookies + browsery headers + headless)**\n\n```bash\nswmap https://portal.example.com --headless --cookie \"SESSION=abcd1234\" --waf-friendly --route-seed /app/ --route-seed /api/me --json\n```\n\n**5. Headless proof + evidence bundle (for a report)**\n\n```bash\nswmap https://pwa.example.com --headless --prove-interception --prove-precache --route-seed /dashboard --route-seed /api/profile --evidence-dir evidence/ --json\n```\n\n**6. Generate SARIF + Nuclei from a scan (CI / team handoff)**\n\n```bash\nswmap -i scope.txt --json --sarif swmap.sarif --nuclei-out nuclei-templates/\n```\n\n**7. Use a profile (headers/proxy/cookies stored in JSON)**\n\n```bash\nswmap https://intranet.example.com --profile profiles/intranet.json --json\n```\n\n\n## ❓ Some Questions You Could Ask\n\n1. **Could this Service Worker control more of my origin than intended?**\n   Check for broadened scopes (e.g. `Service-Worker-Allowed: /`) and verify the **effective scope** SWMap calculates.\n\n2. **Is anything sensitive being precached or served from cache?**\n   Look for `/api`, `/auth`, `/user`, `/admin` routes in findings and confirm via **headless cache audit** when possible.\n\n3. **Which strategies is the worker actually using — and are they safe here?**\n   Identify `cacheFirst`, `networkFirst`, `staleWhileRevalidate`, etc. Match strategy to data sensitivity.\n\n4. **Do static indicators match real behavior?**\n   Use **headless validation** to confirm route interception and network flows before filing or remediating.\n\n5. **What would make this finding actionable in CI or a bug report?**\n   Export **JSON**, include flags, scope math, and (if used) headless witnesses; set `--risk-threshold` to enforce policy.\n\n\n## 🛠️ Troubleshooting\n\n* If Playwright says it can’t find a browser, run:\n\n  ```bash\n  python -m playwright install chromium\n  ```\n\n* If AST keeps failing on minified SWs, try `--no-ast` to confirm it’s the parser, or install Node.js ≥ 16 so the fallback can run.\n\n* If WAF keeps blocking you, try `--waf-friendly` and/or supply the exact headers your browser used.\n\n* If Powershell Blocks the script during the installation, try `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass` and re-run the script.\n\n* If you encounter any issues, please open an issue on GitHub.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the **Apache 2.0** License — see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n### Security Researcher 😎\n\n* [LinkedIn](https://www.linkedin.com/in/elie-uwimana)\n\n## Compliance \u0026 Ethics\n\n⚠️ **Authorized Use Only**\n\nSWMap is designed for:\n\n* Penetration testing with explicit written permission\n* Bug bounty programs within platform guidelines\n* Government / enterprise cybersecurity operations\n* Academic research in controlled environments\n\nDo **not** run it on infrastructure you don’t own or aren’t authorized to test.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbl4ck0w1%2Fswmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbl4ck0w1%2Fswmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbl4ck0w1%2Fswmap/lists"}