How shriyanss/js-recon works
1. Overall shape
- This is a TypeScript/Node.js CLI toolchain, not a single app.
- src/index.ts is the top-level entrypoint, and the repo is organized as a set of independent subcommands that can be run alone or chained through run.
2. Command orchestration layer
- The src/ tree is split by command: lazyload, endpoints, strings, map, analyze, report, refactor, load, fingerprint, mcp, api_gateway, sourcemaps, cs_mast, and run.
- This layer is the user-facing boundary: it parses inputs, dispatches work, and writes results to files or local caches.
3. Target acquisition and browser-driven crawling
- lazyload/ is the acquisition subsystem. It discovers JavaScript resources that are not directly visible in initial HTML.
- It contains framework-specific crawlers for Next.js, Vue, Nuxt, React, Svelte/Astro, and Angular, plus shared download/queue utilities.
- This subsystem uses browser automation and Chromium helpers in src/utility/, which is important because many targets require executing pages or following client-side navigation.
4. Framework detection and specialization
- lazyload/techDetect/ fingerprints the target framework before crawling.
- After detection, framework-specific paths diverge:
- Next.js has the deepest support, including build IDs, manifests, script-tag harvesting, and subsequent-request discovery.
- Vue and Nuxt have their own page-source and build-manifest analysis.
- React, Svelte, and Angular have smaller but still specialized discovery flows.
- This framework split is a key architectural boundary: the same toolchain adapts to different bundle formats and runtime conventions.
5. Endpoint and client-path extraction
- endpoints/ extracts HTTP endpoints and client-side routes from downloaded JS.
- It has framework-specific report generation, including Next.js JSON/reporting helpers and path iteration utilities.
- This module sits between raw JS acquisition and deeper code mapping: it turns discovered scripts into actionable route/API inventories.
6. Code mapping and request reconstruction
- map/ is the main static-analysis subsystem.
- For Next.js, React, Vue, Svelte, and Angular it resolves network behavior such as fetch, Axios, XHR, server actions, GraphQL, and framework-specific connection patterns.
- The map/next_js/resolveAxios* helpers show that request reconstruction is a major concern: the tool traces client wrappers, headers, bodies, exports, and cross-chunk references to rebuild the actual request shape.
- This subsystem produces structured connection data that later feeds analysis and report generation.
7. Static analysis and taint-style reasoning
- analyze/ consumes mapped JS and performs higher-level analysis.
- It includes AST and request engines plus helper routines for direct assignment, member-expression assignment, function identifier resolution, and taint flow.
- The output is a validated structured finding set, suggesting this stage is where raw mappings are turned into security-relevant conclusions.
8. Strings, secrets, and sourcemaps
- strings/ extracts URLs, secrets, and other literals from JS assets.
- sourcemaps/ and sourcemap helpers inside lazyload/ are for recovering original source or mapping minified bundles back to source context.
- These modules are side-channel enrichment steps: they do not drive crawling, but they improve fidelity for analysis and reporting.
9. Persistence, import, and reporting
- load/ ingests exported captures from tools like Burp Suite or Caido into the project’s response cache, creating an alternate data source to live crawling.
- report/ initializes a report database, populates it from analysis/endpoints/mapped JSON/OpenAPI data, and generates HTML/Markdown-style outputs.
- The architectural pattern here is “collect first, normalize into a local store, then render a report.”
10. Automation, AI, and interactive tooling
- run/ is the automation wrapper that chains the core pipeline for quick assessment.
- mcp/ adds an AI-facing interface: CLI chat, one-shot prompting, and an MCP stdio server, backed by command/skill/provider abstractions.
- refactor/ provides deobfuscation and transformation workflows, especially for webpack/React/Next.js bundles, and api_gateway/ manages IP rotation via AWS API Gateway to bypass rate limits or blocks.
- These are support subsystems around the core recon pipeline, extending it to automation, assistance, and operational resilience.
Main entry points: map/index.ts Map · techDetect/index.ts Tech detect · src/index.ts CLI entry · lazyLoad/index.ts Lazyload
Components 27
CLI commands
User-facing command entrypoints and orchestration
Acquisition
Browser-driven crawling and framework-specific JS discovery
- Lazyload · Entry for framework-aware script discovery
src/lazyLoad/index.ts - Tech detect · Detects target framework before specialized crawling
src/lazyLoad/techDetect/index.ts - Next.js crawl · Deep Next.js resource, manifest, and route discovery
src/lazyLoad/next_js/NextJsCrawler.ts - Vue crawl · Vue page-source and client-side path discovery
src/lazyLoad/vue/vue_discoverJsFiles.ts - Nuxt crawl · Nuxt build-manifest and source analysis
src/lazyLoad/nuxt_js/nuxt_getFromPageSource.ts - React crawl · React script-tag, import, and sourcemap discovery
src/lazyLoad/react/react_getScriptTags.ts - Svelte crawl · Svelte page and recursive client-side discovery
src/lazyLoad/svelte/svelte_recursivePageCrawl.ts - Angular crawl · Angular script and page-source discovery
src/lazyLoad/angular/angular_getFromPageSource.ts
Mapping
Static resolution of endpoints and request behavior
- Map · Static-analysis entry for connections and request shapes
src/map/index.ts - Next map · Reconstructs fetch, axios, server actions, and webpack/turbopack calls
src/map/next_js/getFetchInstances.ts - Vue map · Resolves fetch, XHR, and HTTP client behavior in Vue bundles
src/map/vue_js/getViteConnections.ts - React map · Extracts request connections from React bundles
src/map/react_js/getReactConnections.ts - Angular map · Extracts Angular request connections
src/map/angular_js/getAngularConnections.ts - GraphQL · Normalizes GraphQL request shapes
src/map/graphql/resolveGraphql.ts
Analysis
Higher-level reasoning over mapped code and findings
- Analyze · Runs AST and request engines over mapped code
src/analyze/index.ts - Strings · Extracts URLs, secrets, and other literals
src/strings/index.ts - Sourcemaps · Entry for sourcemap-based source reconstruction
src/sourcemaps/index.ts
Output
Persistence, reporting, and export surfaces
Support
Shared utilities and auxiliary workflows
- MCP · Chat, one-shot prompting, and MCP server integration
src/mcp/index.ts - Refactor · Transforms and validates framework-specific bundles
src/refactor/index.ts - API gateway · Checks feasibility and generates rotated requests
src/api_gateway/index.ts - Fingerprint · Standalone target fingerprinting entrypoint
src/fingerprint/index.ts - CS Mast · Additional command surface for specialized workflows
src/cs_mast/index.ts - Utility · Chromium, AI, sandbox, request, and path helpers
src/utility/ai.ts
Connections 34
- CLI entry → Lazyload: dispatches · Top-level CLI routes into acquisition
- CLI entry → Map: dispatches · Top-level CLI routes into mapping
- CLI entry → Analyze: dispatches · Top-level CLI routes into analysis
- CLI entry → Report: dispatches · Top-level CLI routes into reporting
- CLI entry → Run: dispatches · Top-level CLI routes into pipeline execution
- CLI entry → Load: dispatches · Top-level CLI routes into cache import
- Lazyload → Tech detect: detects · Framework detection chooses crawl strategy
- Tech detect → Next.js crawl: next.js · Next.js-specific acquisition path
- Tech detect → Vue crawl: vue · Vue-specific acquisition path
- Tech detect → Nuxt crawl: nuxt · Nuxt-specific acquisition path
- Tech detect → React crawl: react · React-specific acquisition path
- Tech detect → Svelte crawl: svelte · Svelte-specific acquisition path
- Tech detect → Angular crawl: angular · Angular-specific acquisition path
- Lazyload → Utility: uses · Browser automation and shared helpers
- Lazyload → Map: feeds · Discovered scripts move into mapping
- Map → Next map: specializes · Next.js request reconstruction
- Map → Vue map: specializes · Vue request reconstruction
- Map → React map: specializes · React request reconstruction
- Map → Angular map: specializes · Angular request reconstruction
- Map → GraphQL: normalizes · GraphQL query and mutation shapes
- Map → Analyze: feeds · Mapped connections feed higher-level analysis
- Analyze → Report: outputs · Findings are persisted for reporting
- Strings → Analyze: enriches · Literal extraction supports analysis
- Sourcemaps → Lazyload: enriches · Source recovery improves acquisition fidelity
- Sourcemaps → Analyze: enriches · Recovered source context improves analysis
- Load → Report: populates · Imported captures fill the report database
- Run → Lazyload: chains · Automated pipeline begins with acquisition
- Run → Map: chains · Automated pipeline continues to mapping
- Run → Analyze: chains · Automated pipeline continues to analysis
- Run → Report: chains · Automated pipeline ends in reporting
- MCP → Utility: uses · AI interfaces rely on shared infrastructure
- Refactor → Utility: uses · Refactor workflows reuse helpers
- API gateway → Utility: uses · Request generation and network checks reuse helpers
- Fingerprint → Tech detect: shares · Standalone fingerprinting aligns with tech detection