@js-recon/js-recon 1.3.1-beta.2

package/CLAUDE.md

@@ -0,0 +1,290 @@
+# js-recon
+
+Static analysis tool that maps API endpoints and detects client-side security issues by analyzing Next.js (webpack/turbopack) and Vue.js bundles. Written in TypeScript, compiled to `build/` before running.
+
+## Build & run
+
+```bash
+npm run cleanup   # rm -rf build/ + tsc (full rebuild)
+npm run start -- <subcommand> [options]
+```
+
+`cleanup` must be run before testing any TypeScript change when using the `run` command.
+
+## Subcommands
+
+| Command       | Purpose                                                                            |
+| ------------- | ---------------------------------------------------------------------------------- |
+| `lazyload`    | Download JS chunks from a target URL                                               |
+| `strings`     | Extract strings/paths/secrets from JS files                                        |
+| `map`         | Parse webpack/turbopack bundles into a structured `mapped.json`                    |
+| `endpoints`   | Extract client-side routes                                                         |
+| `analyze`     | Run YAML rules against `mapped.json` / OpenAPI spec                                |
+| `report`      | Generate HTML/SQLite report                                                        |
+| `run`         | Run all of the above in sequence (primary interface)                               |
+| `api-gateway` | Manage AWS API Gateway for IP rotation                                             |
+| `mcp`         | AI-powered CLI / one-shot chat (`-c`) / Model Context Protocol server (`--server`) |
+
+## Key source files
+
+- `src/index.ts` — CLI entry point; all subcommand definitions and option declarations live here
+- `src/run/index.ts` — orchestrates the full pipeline (`run` subcommand); two tech-specific flows (Next.js 8-step, Vue 4-step)
+- `src/analyze/index.ts` — loads/validates rules, runs AST and request engines
+- `src/analyze/helpers/initRules.ts` — downloads/caches rules from GitHub to `~/.js-recon/rules`
+- `src/analyze/helpers/validate.ts` — validates rules and checks `js_recon_version` compatibility
+- `src/analyze/helpers/schemas.ts` — Zod schema for rule YAML files
+- `src/map/graphql/resolveGraphql.ts` — framework-agnostic GraphQL operation scanner. Visits every `StringLiteral` and `TemplateLiteral` in every JS file, validates with the `graphql` library's `parse()`, and emits each operation as a POST request under a flat `GraphQL` collection folder. Inlines transitively-referenced fragment definitions into each printed query so emitted requests are self-contained. Runs in every framework branch of `map/index.ts` when `--openapi` is on and `--no-graphql`/`--ngql` is not set.
+- `src/map/next_js/resolveFetch.ts` — resolves `fetch()` calls, detects Next.js framework chunks
+- `src/map/next_js/resolveServerActions.ts` — detects `createServerReference(actionId, ...)` calls, derives App Router routes from chunk file paths, traces argument call sites (same-chunk and cross-chunk), and emits POST endpoints with `next-action` headers and typed arg hints (e.g. `<string:userId>`) into the global OpenAPI output
+- `src/map/next_js/utils.ts` — `resolveNodeValue`, `resolveVariableInChunk`, `substituteVariablesInString`
+- `src/map/vue_js/vue_resolveXhr.ts` — directory-scan resolver for `new XMLHttpRequest()` + `.open()/.setRequestHeader()/.send()` patterns. Shared by Vue/React/Svelte pipelines; the `frameworkName` arg only changes log labels. Reaches ground-truth XHR sites but in axios/Got/Ky-style bundles the URL/method come from a dispatcher config (`re.url`, `re.method`) and resolve only to opaque `[member:re.url]` placeholders that taint analysis cannot unwind across the library's internal dispatch chain — those entries fail the `looksLikeUrl` check at emit time. Catch the wrapper-level call instead via `vue_resolveHttpClient`.
+- `src/map/vue_js/vue_resolveHttpClient.ts` — directory-scan resolver for `<obj>.<verb>(<url>, [body], [config])` calls where `<verb>` ∈ {get,post,put,delete,patch,head,options}. Designed for bundles whose transport layer overrides `XMLHttpRequest.prototype.{open,send,setRequestHeader}` (axios xhrAdapter and similar wrappers): the override layer is irrelevant to URL extraction because the literal URL is composed at the client-instance method call site, not inside the adapter. The `looksLikeUrl` heuristic (post-placeholder-strip, must contain `/` or scheme) filters out `Map.get` / `Headers.delete` / `EventBus.post` false positives while keeping partially-resolved URLs like `[call:base()]<literal>/[var X]`. Three resolution stages run on every captured callsite — each addresses a separate gap exposed when an RPC wrapper is hidden behind multiple layers of webpack-exported helpers:
+    1. `resolveFromAssignments` — walks `binding.constantViolations` for `[unresolved: NAME]` markers, so identifiers declared as `let X;` and assigned later in the function body (e.g. `(X = a + "/" + b)` inside a sequence expression) resolve to their RHS. `resolveNodeValue`'s Identifier handler only looks at `binding.init`, which is empty for late-assigned locals.
+    2. `expandParamPlaceholders` — fans out one captured callsite into one URL per caller chain. Walks the `enclosingFn.parent` chain to find which named function declares each `[param:X]`, then substitutes **every** placeholder owned by that same function from a single caller's args (keeps `[param:e]`/`[param:t]` consistent across one caller — never mixing args from different callsites). Recurses on the caller's `enclosingFn` so a forwarding wrapper (`Se(e,t,n) → ae.request(e,t,n,...)`) walks up to the wrapper's own callers.
+    3. Taint substitution falls back to `substituteCallerPlaceholders` / `substituteCallerHeaders` for body/header placeholders that don't have multi-caller fan-out semantics.
+
+    Wired into Vue / React / Svelte pipelines in `map/index.ts`.
+
+- `src/map/vue_js/taint_utils.ts` — shared taint analysis primitives. Several pieces are non-obvious and exist to make `vue_resolveHttpClient` (and `vue_resolveXhr`) work on webpack output:
+    - `EnclosingFn.paramNames` + `parent` chain: `resolveNodeValue` emits `[param:X]` for any param at any index in any enclosing function. The chain lets the helpers resolve such a marker against whichever enclosing scope actually declared X — bundled code routinely nests the resolution callsite inside an anonymous `.then(function ($) {…})` whose own params don't include X, while X is a param of an outer named function.
+    - `buildAliasMap`: collects `{ exportedName: localBinding }` and `{ exportedName: () => localBinding }` patterns from object literals on a **per-file** basis. Webpack's `a.d(b, { name: () => Binding })` getter exports and re-export registries (`const ae = { request: Me }`) hide the local minifier name behind a meaningful key; without this map, `getCallers("Me")` would miss every `ae.request(...)` / `r.default.request(...)` callsite. **The map must be file-scoped** — minifier locals (`Se`, `Me`) collide across modules, and a global alias map blends unrelated functions into the same name set.
+    - `makeGetCallers` accepts an optional `sourceFile` argument so callers can scope alias lookup to the file where the binding was declared. Direct minifier-local matches (`bindingName.length ≤ 2`) are dropped from the candidate list because they generate too many false positives across files; meaningful aliases (length > 2) are kept and used for both bare-identifier (`X(...)`) and member-expression (`<anything>.X(...)`) callsite matching. Overflow returns the partial caller list rather than nothing — the file-scoped alias map already suppresses noise, so partial coverage beats none.
+- `src/map/next_js/getWebpackConnections.ts` — extracts chunk code from webpack bundles
+- `src/map/next_js/interactive_helpers/esqueryGen.ts` — `esquery` interactive command: minifies a pasted snippet, matches it against each chunk's minified AST nodes, prints loose/strict selectors. Vue's command handler imports the same module — keep it framework-agnostic.
+- `src/map/next_js/interactive.ts` / `src/map/vue_js/interactive.ts` — export both the blessed-backed `interactive()` entry and a headless `runCommands(chunks, mapFile, commands)` that pipes `outputBox.log` to stdout for `-c/--command` execution.
+- `src/map/next_js/interactive_helpers/inputPatch.ts` — `enableCursorInput(inputBox)` patches a blessed textbox instance to support cursor movement, mid-string insertion, and paste-at-cursor. It overrides `_listener`/`setValue`/`_updateCursor`/`clearValue` on the instance. **Don't try to remove blessed's listener after the fact** — blessed re-binds `this._listener` on every focus, so overriding `_listener` on the instance is the only race-free approach. Shared by Next.js and Vue interactive entries.
+- `src/globalConfig.ts` — current version string and tool-wide constants
+- `src/utility/globals.ts` — mutable global state (tech detection result, AI config, OpenAPI flag, etc.)
+
+## `run` pipeline in detail
+
+`run` is the primary subcommand. It calls `processUrl` for each target, which dispatches to one of two pipelines based on the detected front-end framework (`globalsUtil.getTech()`).
+
+### Next.js pipeline (8 steps)
+
+1. **Lazyload** — downloads initial JS chunks via Puppeteer; detects framework; sets `globalsUtil.getTech()` to `"next"`
+2. **Strings** — scans downloaded JS for strings, extracts URL paths → `extracted_urls.json`
+3. **Lazyload (subsequent requests)** — re-crawls using the extracted paths to fetch dynamically loaded chunks; also fetches `buildId`
+4. **Strings (pass 2)** — re-runs strings on the expanded chunk set; generates `extracted_urls.txt` (permuted) and `extracted_urls-openapi.json`; optionally scans secrets (`--secrets`)
+5. **Lazyload re-pass (step 4.5)** — a second subsequent-requests crawl to pick up chunks for dynamic routes discovered in pass 2
+6. **Strings re-pass (step 4.6)** — strings pass over the re-pass chunks
+7. **Map** — parses webpack/turbopack bundles; resolves `fetch()` calls and axios usage; generates `mapped.json` and `mapped-openapi.json`; CDN-aware: if JS was served from a different host, `getCdnDir` finds the CDN output dir and passes that to map instead of `outputDir/host`
+8. **Endpoints** — extracts client-side route paths; uses `___subsequent_requests` directory presence to decide whether to pass a JS directory
+9. **Analyze** — loads YAML rules (from `-r/--rules` if provided, otherwise default rules cache); runs AST engine and request engine; writes `analyze.json`
+10. **Report** — populates SQLite DB (`js-recon.db`) and generates HTML report
+
+### Vue.js pipeline (4 steps)
+
+1. **Lazyload** — same as Next.js step 1; sets `globalsUtil.getTech()` to `"vue"`
+2. **Map** — scans the entire `outputDir` (Vue chunks spread across asset hosts)
+3. **Analyze** — same rule loading as Next.js; `-r/--rules` is forwarded here too
+4. **Report** — same as Next.js; if `endpoints.json` doesn't exist it is written as `[]` since Vue endpoints extraction isn't implemented yet
+
+### Tech detection flow
+
+`lazyLoad` sets the global tech string. If it remains `""` after lazyload, `run` exits (single URL) or skips (batch). Techs other than `"next"` and `"vue"` only get lazyload; the rest of the pipeline is skipped with a warning.
+
+### Batch mode
+
+When `-u` points to a file of URLs, each line is processed sequentially. For each URL:
+
+- A subdirectory `output/<host>/` is created
+- `clearJsUrls()` / `clearJsonUrls()` reset the URL sets so previous targets don't bleed over
+- All output paths are prefixed with `workingDir/`
+
+## Adding a new flag to `run`
+
+1. Declare the option in `src/index.ts` on the `run` command (`.option(...)`)
+2. If it configures a global, call the setter in the `action` handler before `await run(cmd)`
+3. If it needs to reach a downstream module (like `analyze`), thread it through `cmd` — `processUrl` receives the full `cmd` object and passes it to submodule calls
+
+**Example — `-r/--rules` flag (added in this codebase):**
+
+- Declared in `src/index.ts`: `.option("-r, --rules <file/dir>", "Rules file or directory (passed to analyze module)")`
+- In `src/run/index.ts` the `analyze` calls use `cmd.rules || ""` — empty string tells `analyze` to use the default rules cache
+
+**Example — `--lazyload-timeout` flag:**
+
+- Declared in `src/index.ts` on both the `lazyload` and `run` commands: `.option("--lazyload-timeout <minutes>", ..., "30")`
+- Threaded directly into each `lazyLoad()` call as `Number(cmd.lazyloadTimeout) * 60 * 1000` (converts minutes → ms). Unlike flags that set a global, this one is passed as a parameter — no setter in the action handler.
+
+## Interactive-mode commands
+
+The `map -i` blessed UI dispatches user input through `interactive_helpers/commandHandler.ts`. The same handler runs headlessly when commands are supplied via `-c/--command`:
+
+- The `-c` option's commander coerce function splits each value on `&&` (with optional whitespace) and concatenates into a single command array. So `-c "list fetch && esquery * fetch"` is two commands; passing `-c` twice has the same effect.
+- `map`'s entry point checks `commands.length > 0` first — if non-empty, it calls `nextRunCommands` / `vueRunCommands` and skips the blessed UI even when `-i` is also set.
+- New commands should be added to **both** `next_js/interactive_helpers/commandHandler.ts` and `vue_js/interactive_helpers/commandHandler.ts`, plus the corresponding `helpMenu.ts` entry. When the implementation is framework-agnostic (e.g. `esquery`), put it under `next_js/interactive_helpers/` and import it from the Vue handler — don't duplicate.
+- `list server_actions` is intentionally Next.js-only (it reads from `getOpenapiOutput()` filtered by `next-action` header) and has no Vue counterpart.
+
+## Reversing RPC-style API calls from manual browser observations
+
+When the user supplies a call-stack screenshot or notes from a real session ("XHR sent here, sink is this prototype override, body comes from this function"), the goal isn't to reproduce that exact target — it's to find the _generic pattern_ that the bundler emitted and add resolver support for it. The reverse-engineering workflow that produced the HTTP-client resolver:
+
+1. **Read the call stack bottom-up.** The deepest frame is almost always the transport (`XMLHttpRequest.send`, `fetch`); ignore it. The next frames going up are the HTTP library (axios's `_request` / `dispatchXhrRequest`); ignore those too unless the URL is literal at that level. Look for the first frame whose source line contains _a recognisable path fragment or template string_ — that's the wrapper callsite worth resolving.
+2. **Identify the URL composition site.** Open the file at that frame in the downloaded bundle (`output/<host>/static/js/<chunk>.js`) and find the literal. Typical webpack patterns are `client.post(base + "literal/path/" + paramVar, body, config)` or `client.request({ url: base + "/" + paramVar, method: "POST" })`. Note what's a literal, what's a parameter, what's a local variable.
+3. **Walk inward from the wrapper.** For every non-literal in the URL, find where it came from in the same function. If it's a `let X;` followed by `X = a + "/" + b` in a sequence expression, that's `resolveFromAssignments`' territory. If it's a function parameter, that's taint analysis' territory.
+4. **Walk outward from the wrapper.** Look at the callers of the enclosing function. In webpack bundles the function is usually exported through one of:
+    - A registry object: `const ae = { request: Me, postUnchecked: Se }` — callsites read `ae.request(...)`, NOT `Me(...)`.
+    - A webpack getter export: `a.d(b, { request: () => Me })` — same effect, different shape.
+    - Both. The same binding often appears in multiple aliases.
+
+    Both shapes are recognised by `buildAliasMap` in `taint_utils.ts` and _must be matched per file_ — minifier locals like `Se`, `Me` collide across modules.
+
+5. **Trace forwarding wrappers all the way out.** A wrapper like `Se(e, t, n) → ae.request(e, t, n, ...)` just forwards its parameters. After substituting at the wrapper level, recurse into Se's own callers; the externally-meaningful arguments (`s.signIn.namespace`) are several layers up.
+6. **Confirm the literal source.** The outermost caller passes a `MemberExpression` like `s.signIn.namespace`. Find the `const s = { signIn: { namespace: "...", method: "..." } }` declaration — `resolveNodeValue` handles this naturally as long as the binding is in scope at the caller's location.
+
+If at any layer the new resolver returns `[unresolved: X]` or `[param:X]`, that's a signal which primitive is missing — extend `taint_utils.ts` (chain walk, per-file aliases, member-expression matching, late-assignment recovery) rather than special-casing the wrapper. The goal is a primitive that resolves _similar_ RPC-style libraries in unrelated apps, not the one bundle in front of you.
+
+**Do not encode target-specific paths or service names in code or comments.** When iterating, run `map` against the downloaded chunks and grep the resulting `mapped-openapi.json` for the expected URL fragment — never paste that fragment into source.
+
+### How to test changes here
+
+The HTTP-client resolver runs inside the `map` step of the React/Vue/Svelte pipeline; verify it as part of the full `run` pipeline (see "Testing a change" below). Quick iteration loop while debugging:
+
+```bash
+npx tsc
+node --max-old-space-size=8192 build/index.js map \
+    -d output/<host>/static/js -o /tmp/jsr-mapped -t react -f json \
+    2>&1 | grep "URL: " | sort -u
+```
+
+This bypasses the slow `lazyload` step by reusing already-downloaded chunks. The final acceptance test is still `npm run cleanup && npm run start -- run -u <target> -y -k`; grep `mapped-openapi.json` for the expected resolved URL fragment.
+
+## Rules
+
+Rules are YAML files (`.yml`/`.yaml`) in two places:
+
+- **Workspace:** `../js-recon-rules/` (relative to this repo)
+- **Installed cache:** `~/.js-recon/rules`
+
+`initRules` downloads rules from GitHub when missing or when the cached version doesn't match the latest release. `js_recon_version` (required) must be declared in every rule (e.g. `js_recon_version: ">=X.Y.Z"`); `initRules` uses it to validate compatibility and skips incompatible rules with a warning. The version check strips prerelease suffixes (e.g. `1.3.1-alpha.3` → `[1,3,1]`).
+
+Rule categories:
+
+- `ast/` — AST-based pattern matching against chunk code (uses `@babel/parser` + `esquery`)
+- `request/` — OpenAPI/request-level checks against the resolved endpoint list
+
+When `-r` points to a single file, only that rule is loaded. When it points to a directory, all `.yml`/`.yaml` files are loaded recursively.
+
+## Testing a change
+
+**Testing is mandatory for every change.** Before reporting a task complete:
+
+1. Run `npm run cleanup` to rebuild TypeScript.
+2. Run the `run` subcommand against the target the user provides. Do not use `analyze` or other individual subcommands as a substitute — the `run` subcommand must be used to validate end-to-end behavior.
+3. If the user has not provided a target, ask for one before proceeding.
+
+Typical test invocation:
+
+```bash
+npm run cleanup && npm run start -- run -u <target-url> -y -k
+```
+
+## Release process
+
+Releasing a new version touches three repos. Work on `dev` (js-recon, js-recon-rules) and `stage` (js-recon-docs). Do **not** touch `js-recon-research` — it is private and excluded from releases.
+
+**Ordering is critical**: release js-recon first (including the GitHub release so CI publishes it to npm), then snapshot and PR js-recon-docs. This ensures the docs `version_check` CI step passes instead of failing due to a missing npm package.
+
+### When a user asks to prepare a release
+
+Before writing any files, gather the current state:
+
+1. Check `package.json` and `src/globalConfig.ts` for the current version — both must match. If they don't, fix them first.
+2. Find the latest git tag: `git describe --tags --abbrev=0`
+3. List unreleased commits: `git log <latest-tag>..HEAD --oneline | grep -E "^[a-f0-9]+ (feat|fix)"`
+4. Check if `CHANGELOG.md` already has an `(unreleased)` entry for the current version — if so, only the date needs to be added.
+5. Check `js-recon-rules` for unreleased commits since its last tag: `git -C ../js-recon-rules log $(git -C ../js-recon-rules describe --tags --abbrev=0)..HEAD --oneline`
+6. Check `js-recon-docs` for commits since the last version snapshot: `git -C ../js-recon-docs log --oneline -20`
+
+### Phase 1 — js-recon (release first)
+
+1. **Bump version** (if not already at the target version) — update `version` in `src/globalConfig.ts` and `package.json`. Both must match.
+
+2. **Update CHANGELOG** — if the version heading already exists as `(unreleased)`, replace it with the real date (`## <version> - <YYYY-MM-DD>`). Otherwise add the full section with `### Fixed`, `### Performance`, `### Added`, `### Changed` sub-sections. Verify every `feat`/`fix` commit since the previous tag is covered:
+
+    ```bash
+    git log <prev-tag>..HEAD --oneline | grep -E "^[a-f0-9]+ (feat|fix)"
+    ```
+
+3. **Update README** — ensure the Commands table in `README.md` lists every subcommand declared in `src/index.ts`. The `refactor` and `load` subcommands are easy to miss — explicitly verify they are present.
+
+4. **Update rules** (`js-recon-rules` repo, `dev` branch) — if there are substantive unreleased commits (not just merge/cleanup commits), update `CHANGELOG.md` and `version.txt`, push to `dev`, and open a PR (`shriyanss/js-recon-rules` dev→main, title=rules version, body=rules changelog section).
+
+5. **Push** `js-recon` dev branch: `git push origin dev`
+
+6. **Open PR** using `gh pr create`:
+   | Repo | Source | Target | Title | Body |
+   |------|--------|--------|-------|------|
+   | `shriyanss/js-recon` | `dev` | `main` | bare version string (e.g. `v1.3.1-alpha.4`) | raw `## <version>` changelog section |
+
+7. **Monitor js-recon CI** — use `gh pr checks <pr-number> --repo shriyanss/js-recon` and poll until all checks complete. Handle CodeRabbit suggestions (see below). Do NOT merge — wait for user approval.
+
+8. **Create GitHub release** — after the PR is merged to main:
+
+    ```bash
+    gh release create v<version> \
+      --repo shriyanss/js-recon \
+      --title "v<version>" \
+      --notes "<changelog section>" \
+      --prerelease    # set for any version containing "alpha" or "beta"
+    ```
+
+    `--latest` flag rules:
+    - **Omit** `--latest` if the version contains `alpha` or `beta`
+    - **Add** `--latest` only for stable releases (no pre-release suffix in the version string)
+
+    Previous tag is left to GitHub's automatic detection (do not set `--target` or `--tag` beyond the tag name itself).
+
+9. **Wait for npm publish** — monitor the release pipeline: `gh run list --repo shriyanss/js-recon --workflow release`. Confirm the npm package is live at the new version before proceeding to Phase 2.
+
+### Phase 2 — js-recon-docs (after npm is live)
+
+10. **Fix doc gaps** — cross-check `docs/docs/modules/*.md` against `src/index.ts` and the new CHANGELOG entries. Add or update any missing flags, options, or command descriptions.
+
+11. **Snapshot** — run inside `js-recon-docs/`:
+
+    ```bash
+    npx docusaurus docs:version <version>
+    ```
+
+    This creates `versioned_docs/version-<version>/`, updates `versions.json`, and creates `versioned_sidebars/version-<version>-sidebars.json`.
+
+12. **Keep `lastVersion` stable** — `lastVersion` in `docusaurus.config.ts` stays pointing to the last stable release. Do **not** update it for alpha or beta versions.
+
+13. **Push** `js-recon-docs` stage branch and open PR:
+
+    ```bash
+    git -C ../js-recon-docs add .
+    git -C ../js-recon-docs commit -m "docs: snapshot v<version>"
+    git -C ../js-recon-docs push origin stage
+    gh pr create --repo shriyanss/js-recon-docs \
+      --head stage --base main \
+      --title "v<version>" \
+      --body "<brief summary of doc changes>"
+    ```
+
+14. **Monitor docs CI** — `version_check` should pass now that the npm package is live. CodeRabbit rate-limit comments are non-blocking.
+
+### Handling CodeRabbit
+
+After any PR is created, poll for review comments:
+
+```bash
+gh api repos/shriyanss/js-recon/pulls/<pr>/comments
+```
+
+For each suggestion: apply a fix commit to `dev` for correctness bugs or convention violations. Skip trivial style preferences. The PR updates automatically.
+
+### Stop before merge
+
+Do NOT merge any PR. Once all CI checks pass and CodeRabbit suggestions are addressed, present a summary to the user: what changed in each repo, PR links, CI status, CodeRabbit disposition. Wait for explicit merge approval.
+
+## Security / confidentiality
+
+When a change is informed by behavior observed on a real target (URLs, endpoint names, response shapes, finding details, etc.):
+
+- **Do not include any target information in code comments, commit messages, docstrings, variable names, or any other artifact.**
+- This applies to hostnames, paths, parameter names, response content, or any other detail that could identify the target.
+- If context from the target is needed to describe a change, describe it in abstract terms only (e.g. "URL parameter passed to fetch" not "https://example.com/api/docs passes `file` param to fetch").

package/Dockerfile

@@ -0,0 +1,34 @@
+FROM ghcr.io/puppeteer/puppeteer:24.43.1
+
+WORKDIR /home/pptruser
+
+# selectively copy the source files
+COPY ./package.json .
+COPY ./package-lock.json .
+COPY ./tsconfig.json .
+COPY ./src ./src
+
+USER root
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    unzip \
+    libnspr4 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
+    libxcomposite1 libxdamage1 libxrandr2 libgbm1 libxkbcommon0 \
+    libasound2 libpangocairo-1.0-0 libxfixes3 libxi6 libxinerama1 \
+    libxcursor1 libdrm2 && \
+    rm -rf /var/lib/apt/lists/*
+RUN npm ci
+RUN npm run build
+
+USER pptruser
+RUN ./node_modules/.bin/puppeteer browsers install chrome && \
+    for zip in /home/pptruser/.cache/puppeteer/chrome/*-chrome-linux64.zip; do \
+        [ -f "$zip" ] || break; \
+        version="${zip%-chrome-linux64.zip}"; version="${version##*/}"; \
+        dest="/home/pptruser/.cache/puppeteer/chrome/linux-${version}"; \
+        unzip -o "$zip" -d "${dest}/" && chmod +x "${dest}/chrome-linux64/chrome"; \
+    done
+
+ENV IS_DOCKER=true
+ENV NODE_OPTIONS="--max-http-header-size=99999999"
+ENTRYPOINT ["node", "build/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shriyans Sudhi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# JS Recon
+
+![NPM Licence](https://img.shields.io/npm/l/%40shriyanss%2Fjs-recon) ![GitHub repo size](https://img.shields.io/github/repo-size/shriyanss/js-recon) ![NPM Downloads](https://img.shields.io/npm/dm/%40shriyanss%2Fjs-recon) ![GitHub commit activity (dev)](https://img.shields.io/github/commit-activity/w/shriyanss/js-recon/dev) ![NPM Last Update](https://img.shields.io/npm/last-update/%40shriyanss%2Fjs-recon) ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/shriyanss/js-recon)
+
+<p align="center">
+  <a href="https://js-recon.io">
+    <img src="https://js-recon.io/img/js-recon-logo.png" alt="JS Recon Logo" width="100">
+  </a>
+</p>
+
+A powerful tool for JavaScript reconnaissance. `js-recon` helps you discover, download, and analyze JavaScript files to uncover endpoints, secrets, and other valuable information from any web application running supported frameworks.
+
+It can also reconstruct HTTP requests that the app makes to the server, and output them to the OpenAPI spec.
+
+## Installation
+
+This tool requires Node.JS and `npm` to be installed. The [official download page](https://nodejs.org/en/download) can be referred. Please install **22.17.0 (LTS)** or later. Downloading older versions might break the tool.
+
+To install the tool globally, run:
+
+```bash
+npm i -g @shriyanss/js-recon
+```
+
+For detailed installation and setup process, please refer to the [Installation page](https://js-recon.io/docs/docs/installation)
+
+## Framework Support
+
+The features in JS Recon tool are built after thorough research on apps running different frameworks.
+
+Please refer to the [Framework Support](https://js-recon.io/docs/docs/framework-support) page for detailed information on feature compatibility across different frameworks.
+
+## Quick Start
+
+```bash
+# Get a list of all commands
+js-recon --help
+
+# Get help for a specific command
+js-recon <command> --help
+```
+
+To launch a quick assesment against a target, the `run` module can be used to automate other modules
+
+```bash
+js-recon run -u https://app.example.com
+```
+
+## Commands
+
+`js-recon` provides a suite of commands for comprehensive JavaScript analysis. For detailed usage and examples, please refer to its full documentation.
+
+| Command       | Description                                                                   | Documentation                                                  |
+| ------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `lazyload`    | Downloads dynamically loaded JavaScript files from a target.                  | [Read Docs](https://js-recon.io/docs/docs/modules/lazyload)    |
+| `endpoints`   | Extracts API endpoints and client-side paths from JS files.                   | [Read Docs](https://js-recon.io/docs/docs/modules/endpoints)   |
+| `strings`     | Extracts strings, URLs, and potential secrets from JS files.                  | [Read Docs](https://js-recon.io/docs/docs/modules/strings)     |
+| `map`         | Maps function calls and analyzes code, with optional AI-powered descriptions. | [Read Docs](https://js-recon.io/docs/docs/modules/map)         |
+| `api-gateway` | Manages AWS API Gateway for IP rotation to bypass rate limits.                | [Read Docs](https://js-recon.io/docs/docs/modules/api-gateway) |
+| `run`         | Runs all analysis modules automatically on a target.                          | [Read Docs](https://js-recon.io/docs/docs/modules/run)         |
+| `analyze`     | Analyzes the code.                                                            | [Read Docs](https://js-recon.io/docs/docs/modules/analyze)     |
+| `report`      | Generates a report from the analysis modules.                                 | [Read Docs](https://js-recon.io/docs/docs/modules/report)      |
+| `mcp`         | AI-powered interactive CLI, one-shot chat, and MCP stdio server.              | [Read Docs](https://js-recon.io/docs/docs/modules/mcp)         |
+| `fingerprint` | Detects the JavaScript framework used by a target URL (JSON/JSONL output).    | [Read Docs](https://js-recon.io/docs/docs/modules/fingerprint) |
+| `refactor`    | Refactors and deobfuscates webpack modules from a mapped JSON file.           | [Read Docs](https://js-recon.io/docs/docs/modules/refactor)    |
+| `load`        | Populates the response cache from a Caido or Burp Suite export.               | [Read Docs](https://js-recon.io/docs/docs/modules/load)        |
+
+## Key Features
+
+- Downloads all dynamically loaded JS files (refered as `lazyload`) from website with supported frameworks
+- Use API gateway to rotate IP addresses to bypass firewall
+- Extract strings from the discovered JS files, and extract potential secrets, endpoints, etc. from them
+- Endpoints modules extracts client-side paths from the app
+- Map feature analyzes the JS files and outputs it to a JSON file. An interactive mode can be then used to analyze it
+- Reconstruct HTTP requests that the app makes to the server, and output them to the OpenAPI spec
+- Run analyze to find potential issues in JS code and the HTTP requests the app makes
+- Generate a report from the analyze module
+
+## Example Scenario
+
+Refer to [this page](https://js-recon.io/docs/docs/example-scenarios/next-js) where an example scenario of running this tool against a Next.JS target is demonstrated.
+
+## Documentation
+
+For detailed guides, command options, and advanced usage examples, please check out the JS Recon Site at https://js-recon.io
+
+## Labs
+
+<p align="center">
+  <img src="https://github.com/shriyanss/js-recon-labs/blob/main/static/labs-banner.png?raw=true" alt="JS Recon Labs" width="300"/>
+</p>
+
+Labs to test JS Recon tool are available [here](https://github.com/shriyanss/js-recon-labs). Walkthroughs are available [here](https://js-recon.io/labs).
+
+## Contributing
+
+Please refer to the [Contributing](https://js-recon.io/contributing) page for detailed information on contributing to this project.
+
+## License
+
+JS Recon is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Supported Versions
+
+The three most recent versions receive security fixes. Older versions are unsupported.
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Report vulnerabilities by emailing: **shriyanss@ss0x00.com**
+
+Include in your report:
+
+- Description of the vulnerability and its potential impact
+- Steps to reproduce or a proof-of-concept
+- Affected version(s)
+- Any suggested mitigations, if known
+
+You can expect an acknowledgement within **72 hours**. If a vulnerability is confirmed, a fix will be prioritized based on severity.
+
+## Scope
+
+js-recon is a security research tool. Reports are in scope if they affect:
+
+- The js-recon CLI itself (arbitrary code execution, path traversal, unsafe deserialization, etc.)
+- The Docker container image
+- Dependencies with known CVEs that affect js-recon's attack surface
+
+Out of scope:
+
+- Vulnerabilities in targets analyzed by js-recon (that is the intended use case, not a bug)
+- Issues requiring physical access or social engineering of the operator
+
+## Disclosure Policy
+
+Once a fix is available, coordinated public disclosure is preferred. Please allow reasonable time (up to 90 days) for a patch to be released before public disclosure.