Skip to main content

JScope

Evidence-based JavaScript intelligence for bug bounty hunters and web app pentesters.
Reconstructs how a web app behaves from its JS, and refuses to show a finding it can't justify.

CI Python 3.10+ License: MIT


Most JS recon tools hand you a long list of strings. JScope hands you a map (routes, components, API calls, guards, roles) and a ranked list of where to start testing, where every point in the ranking has a stated reason and every finding carries the evidence behind it.

$ jscope analyze tests/sample_react

[where to start testing]  (deterministic ranking; reasons shown)
   68  [CONFIRMED] JS-0004  endpoint: /api/admin/reports/export
       test: Request as an unauthenticated / low-privilege user and check for missing access control.
   58  [CONFIRMED] JS-0001  endpoint: /api/admin/users
       test: Request as an unauthenticated / low-privilege user and check for missing access control.
   54  [CONFIRMED] JS-0003  endpoint: /api/users/{id}/profile
       test: Vary the ID parameter across accounts/sessions and diff authorization results.
   ...

[route map]  6 route(s)   (R=route G=guard role=declared role E=endpoint)
  R /                            UNPROTECTED
      E /api/v1/feed
  R /admin/reports               UNPROTECTED
      E /api/admin/reports/export
  R /login                       UNPROTECTED
      E /api/auth/login
  R /admin/users                 guards=RequireAuth roles=admin
      E /api/admin/users
  R /billing                     guards=RequireAuth
      E /api/payments/invoices
  R /profile                     guards=RequireAuth
      E /api/users/{id}/profile

An unguarded /admin/reports route calling an admin export endpoint is exactly the kind of lead you want surfaced in seconds. Try it yourself on the bundled fixture (tests/sample_react).

Install

python -m pip install --upgrade jscope
jscope https://app.example.com     # or ./path/to/project: analyze, remember, and tell you what to do next

Python 3.10+. YAML OpenAPI specs: pip install "jscope[yaml]". Development: pip install -e ".[dev]"; see docs/RELEASING.md.

One investigation, no re-typing

JScope remembers the current target, its scope host, and the latest findings in .jscope/session.json. After the first command you stop passing paths, files and URLs:

$ jscope https://app.example.com
  target : https://app.example.com
  host   : app.example.com  (resolves to 93.184.216.34)
12 finding(s): CONFIRMED=1, HIGH=3, MEDIUM=5, LOW=3
next: jscope findings | jscope show 1 | jscope graph | jscope report --format html

$ jscope findings --min-confidence HIGH
  #  PRI  CONFIDENCE    STATE       CATEGORY  SUBJECT
  1   68  CONFIRMED     static      endpoint  /api/admin/reports/export
  2   58  HIGH          static      endpoint  /api/admin/users

$ jscope show 1                      # rank, id (JS-0004) or unique text all work
$ jscope show 1 --source             # + source lines around each evidence location
$ jscope graph --unprotected         # routes with no guard
$ jscope confirm --dry-run           # request plan, nothing sent (in the shell: plan, then one question)
$ jscope verify --finding-id 1 --authorize-active-tests
$ jscope status                      # target, scope, evidence state

jscope with no arguments in a terminal opens a shell over the same commands: type a URL or path to start, a number to open that finding, or any command. The shell asks one kind of question only: before runtime traffic.

What stays explicit. Scope is the target's own host and nothing else (an explicit --base-url still requires --allow-host). Active requests require --authorize-active-tests (the shell asks instead). Loopback/private destinations need --allow-private. Non-interactive remote runs need -y. Runtime results are written back to the findings file; the static original is kept once as findings.static.json. STATE separates static observations from probable/confirmed behavior.

Scripting. Every command also works without a session, with explicit files (jscope show JS-0004 --findings-file f.json). --json is available on status, findings and show. Exit codes: 0 ok, 1 error, 2 not found / ambiguous / partial, 3 workspace regression. 0.5 commands, flags and output files are unchanged. Details: docs/REDESIGN_0.6.md.

Other direct commands: jscope analyze, report, ws-scan --fail-on-regression (CI baseline diffing), observe, ai.

Remote commands (go, scan, crawl, download) are bound to the target host, rate-limited, and refuse loopback/private addresses by default. For controlled local testing pass --allow-private.

What makes it different

Typical JS recon JScope
Method regex over bundles tree-sitter AST, constant propagation, dead-branch detection
Output flat list of URLs / strings route, guard and role graph with route-to-API attribution
Findings everything that matches only evidence-backed candidates, scored deterministically
Triage you sort it out ranked "where to start testing", each point explained
Honesty silent on limits every finding states what it could not resolve

Tools like LinkFinder, jsluice and SecretFinder are excellent at fast extraction, and JScope is built to sit alongside them, adding structure and prioritization on top.

How it stays honest

analyzers propose  --->  EvidenceEngine scores + dedups  --->  you see Findings
   (Candidate)             (deterministic, explainable)           (Finding)

Analyzers can never emit a finding directly, only Candidates backed by typed Evidence. That boundary keeps a noisy analyzer (including community plugins) from polluting your output. Confidence means "this pattern exists and means what it looks like", not "this is exploitable"; only the opt-in confirm / verify steps add runtime evidence. Details: docs/EVIDENCE_SCHEMA.md.

What it analyzes

14 built-in analyzers: routes (React Router, Vue Router, Angular, Next.js), authentication and authorization patterns, storage and token handling, GraphQL operations and schemas, OpenAPI specs (correlated both ways with client calls), service workers, source maps, HTML forms/CSP/SRI, WASM modules, secrets, endpoints and framework detection.

Also included: workspaces with baseline diffing (ws-scan), optional AI explanations that never invent findings (docs/AI.md), a plugin system with trust tiers (docs/PLUGINS.md), SARIF output for CI, and opt-in runtime confirmation and browser observation.

Status and limitations

JScope is a beta development tool, not a production scanner. Be aware of these before relying on it:

  • Symbol resolution is a per-file heuristic. There is no cross-file data flow yet, and import resolution handles relative paths only (no @/ or tsconfig aliases).
  • Client-side authorization findings are observations, not vulnerabilities. A missing guard may live in a layout or on the server.
  • Runtime confirmation is opt-in and narrow: GET/OPTIONS only, allow-listed hosts. It shows a route responds, not that it is vulnerable.
  • The accuracy benchmark uses 12 synthetic fixtures; a real-world corpus is on the roadmap.
  • Network scope enforcement is not unified across every component and DNS pinning is not guaranteed on all paths. Read docs/SECURITY_LIMITATIONS.md. Plugins execute arbitrary Python.

Only test systems you own or are explicitly authorized to assess.

Development

git clone https://github.com/LIME1Star/Jscope && cd JScope
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest
python -m jscope benchmark --strict

See CHANGELOG.md for release history and docs/ for each subsystem. Issues and pull requests are welcome.

License

MIT, see LICENSE.

Metadata

Release files for jscope 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jscope 0.6.0
File Size Uploaded Provenance Actions
jscope-0.6.0.tar.gz 251.6 kB Without provenance Details for jscope-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jscope 0.6.0
File Interpreter ABI Platform Actions
jscope-0.6.0-py3-none-any.whl Python 3 none any Details for jscope-0.6.0-py3-none-any.whl

Total release size: 489.6 kB

Release files / jscope-0.6.0.tar.gz

Download URL jscope-0.6.0.tar.gz
Size 251.6 kB
Tags Source
SHA-256 checksum
How to use checksums
ede755f04d9f96190569d2ad98f42fa7ba0e09043bc643b98d8284a2359ea373
BLAKE2b-256 checksum
How to use checksums
1c253044ea066b931641f577ba3a0edb8496762885c20d0ea2a200d412ba2abf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / jscope-0.6.0-py3-none-any.whl

Download URL jscope-0.6.0-py3-none-any.whl
Size 238.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fcf6c6dbdfb41b5ffa33079540f9a09f5cf79969fa6564fe94b41a4138742844
BLAKE2b-256 checksum
How to use checksums
1a3e85a52a4bc6ced10308cc5c5e9a8d4d5d947b9a869be71c7fb009f36d8c4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for jscope 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page