Metadata-Version: 2.4
Name: gerviJS
Version: 3.1.0
Summary: JS recon for pentesters. Finds secrets, endpoints, and infrastructure in JavaScript.
Author: Euron Osmani
License: MIT
Project-URL: Homepage, https://github.com/Euronii/gervis
Project-URL: Repository, https://github.com/Euronii/gervis
Project-URL: Issues, https://github.com/Euronii/gervis/issues
Project-URL: Changelog, https://github.com/Euronii/gervis/blob/main/CHANGELOG.md
Keywords: security,pentest,recon,javascript,secrets,bug-bounty,osint,appsec,source-maps
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: aiohttp>=3.8
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: lxml
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# gerviJS

[![CI](https://github.com/Euronii/gervis/actions/workflows/ci.yml/badge.svg)](https://github.com/Euronii/gervis/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/gervijs)](https://pypi.org/project/gervijs/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

JS recon for pentesters. Crawls targets, pulls every JavaScript file, unpacks source maps, and extracts secrets, API endpoints, infrastructure details, and tech stack. Built for real engagements, not CTFs.

## Why

Every modern web app ships JavaScript to the browser. That JS contains API routes your proxy never saw, hardcoded keys the dev forgot to remove, internal IPs that map the network, and enough context to plan an entire engagement. Gervis automates the boring part so you can focus on exploitation.

**Built for a low false-positive rate.** Every secret pattern is format-validated, entropy-checked, and filtered against known placeholders, so what gets flagged is overwhelmingly real — not the regex noise most JS grep tools drown you in.

**Source map unpacking.** When gervis finds `.map` files, it downloads and reverses them to original source code, then runs the full analysis pipeline on the recovered files. Devs leave hardcoded keys, internal routes, and auth bypass notes in source that gets "hidden" by minification — gervis finds all of it.

## Install

```bash
pipx install gervijs       # recommended: isolated CLI install
# or
pip install gervijs
```

Installs two equivalent commands: `gervijs` and the shorter alias `gervis`.

Run the latest without installing:

```bash
pipx run gervijs https://target.com
```

From source:

```bash
git clone https://github.com/Euronii/gervis
cd gervis
pip install -e .
```

## Usage

```
gervis https://target.com                        # full scan
gervis https://target.com --probe                # scan + validate endpoints
gervis https://target.com --json                 # machine-readable output
gervis https://target.com --markdown -o report.md   # markdown report
gervis https://target.com --endpoints | httpx    # pipe paths to httpx
gervis https://target.com --urls | httpx         # pipe full URLs to httpx
gervis https://target.com --wordlist | ffuf -w -   # JS-derived wordlist
gervis https://target.com --secrets              # secrets only (TSV)
gervis https://target.com -d 3 -v                # deep crawl, verbose
gervis -l targets.txt                            # scan multiple targets
gervis -l targets.txt --json -o results.json     # multi-target JSON
```

## What it finds

### Source Map Unpacking
When JS files reference `.map` files (`//# sourceMappingURL=` directives or `SourceMap`/`X-SourceMap` headers), gervis:
1. Downloads the `.map` file
2. Parses v3 source map format (`sources` + `sourcesContent`)
3. Recovers original unminified source files (skips `node_modules`/vendor)
4. Deduplicates by content hash
5. Runs the full analysis pipeline (secrets, endpoints, infra, tech) on every recovered file

The banner shows `srcmap=N` when source files are recovered. Findings from source map files are tagged with `[map]` in the source field.

### Secrets
Format-validated detection for 40+ secret types:

| Provider | Patterns |
|----------|----------|
| AWS | Access keys, secret keys |
| Google | API keys, OAuth client IDs, GCP service accounts |
| GitHub | PATs, OAuth tokens, app tokens, fine-grained PATs |
| Slack | Bot tokens, user tokens, app tokens, webhooks |
| Stripe | Secret keys, publishable keys, restricted keys, test keys |
| Firebase | API keys, database URLs |
| Twilio | Account SIDs, auth tokens, API keys |
| SendGrid | API keys |
| Mailgun | API keys, domain keys |
| Auth0 | Client secrets |
| Supabase | Anon keys, service keys |
| Azure | Storage keys, connection strings |
| Cloudinary | URLs with credentials |
| npm/PyPI | Tokens |
| Sentry | DSNs |
| Datadog | API keys |
| Algolia | Admin keys |
| Mapbox | Public and secret tokens |
| Generic | High-entropy values in secret-named variables |
| Crypto | Private keys (RSA, EC, DSA, PGP), hardcoded JWTs |

Every match passes:
1. **Format validation** — provider-specific regex with boundary checks
2. **Entropy filtering** — configurable per pattern, kills low-entropy junk
3. **Placeholder detection** — catches `your_api_key_here`, `example`, `test`, env references
4. **Comment filtering** — skips secrets in JS comments
5. **Severity classification** — critical/high/medium/low based on impact

**Full secret values in output.** No truncation — you see the entire key/token/credential.

### Endpoints
- API paths (`/api/`, `/v1/`, `/rest/`, `/rpc/`)
- Auth flows (`/oauth/`, `/token/`, `/callback/`, `/sso/`)
- Admin panels (`/admin/`, `/dashboard/admin`, `/backoffice/`)
- Debug/monitoring (`/actuator/`, `/health/`, `/metrics/`, `/profiler/`)
- Internal paths (`/internal/`, `/__`, `/private/`)
- GraphQL endpoints
- WebSocket URLs (`ws://`, `wss://`)
- HTTP method detection (GET, POST, PUT, DELETE, PATCH)
- Smart path normalization (UUIDs, numeric IDs, hashes replaced with `{id}`)
- CDN/asset filtering (40+ CDN hosts, 30+ asset extensions filtered out)
- Frontend router extraction (React Router, Vue Router, Angular)

### Infrastructure
- Internal IPs (RFC1918 validated, false-positive filtered)
- Source maps (both directives and URL references)
- Debug flags and environment checks (`NODE_ENV`, `debugMode`, etc.)
- Cloud storage (S3 buckets, GCS buckets, Azure Blob containers)
- Firebase project URLs
- Email addresses (junk-filtered)
- Developer comments with sensitive content (TODO, FIXME, HACK, password, etc.)

### Tech Stack
90+ technologies detected across 8 categories:
- **Frameworks:** React, Angular, Vue, Next.js, Nuxt, Svelte, Remix, Gatsby, Astro, SolidJS
- **Libraries:** jQuery, Axios, Apollo, Socket.io, D3, Three.js, Chart.js, tRPC
- **Auth:** Auth0, Okta, Cognito, Clerk, NextAuth, Keycloak, Passport.js, Firebase Auth
- **Cloud:** Firebase, Supabase, AWS SDK, Amplify, Azure, GCP, Vercel, Netlify, Cloudflare Workers
- **Analytics:** GA, GTM, Segment, Mixpanel, Amplitude, Hotjar, PostHog, FullStory
- **Build:** Webpack, Vite, Parcel, esbuild, Turbopack
- **Security:** Sentry, reCAPTCHA, hCaptcha, Cloudflare Turnstile
- **Payments:** Stripe, PayPal, Braintree

Version extraction where possible.

## Multi-target mode

Scan a list of URLs from a file:

```bash
# targets.txt — one URL per line, # comments skipped
https://app1.example.com
https://app2.example.com
# https://skip-this.com

gervis -l targets.txt                    # scan all targets
gervis -l targets.txt --json -o all.json # combined JSON array
gervis -l targets.txt --endpoints        # endpoints from all targets
gervis -l targets.txt --wordlist         # combined wordlist
```

Text/markdown output shows each target separated by `===`. Pipe modes add `# target_url` comments between targets.

## Output modes

| Flag | Output | Pipe to |
|------|--------|---------|
| *(default)* | Colored text, grouped by category | terminal |
| `--json` | Structured JSON with severity/confidence | jq, scripts |
| `--markdown` | Full report with tables | docs, reports |
| `--endpoints` | One path per line | httpx, nuclei, ffuf |
| `--urls` | Full URLs (base + path) | httpx, curl |
| `--secrets` | TSV: severity, kind, value, source | grep, awk |
| `--wordlist` | Paths, params, keys from JS | ffuf, gobuster |

## Options

```
  URL                 Target URL (or use -l for file)
  -l, --list FILE     File with target URLs (one per line)
  -d, --depth INT     Crawl depth (default: 2)
  --probe             Probe discovered endpoints (HEAD/GET)
  --json              JSON output
  --markdown          Markdown report
  --endpoints         Endpoints only (pipe-friendly)
  --urls              Full URLs (pipe-friendly)
  --secrets           Secrets only (TSV)
  --wordlist          Generate wordlist from JS
  -o, --output FILE   Write output to file
  -v, --verbose       Show all endpoints + progress
  -q, --quiet         No banner
  -t, --timeout INT   Request timeout in seconds (default: 10)
  -c, --concurrency   Max concurrent requests (default: 20)
  -V, --version       Version
  -h, --help          Help
```

## Examples

### Recon pipeline
```bash
# Find endpoints, probe them, check for vulns
gervis https://target.com --urls | httpx -silent -mc 200,301,302,403 | nuclei -t exposures/

# Build custom wordlist from JS
gervis https://target.com --wordlist > custom.txt
ffuf -u https://target.com/FUZZ -w custom.txt

# Quick secrets check
gervis https://target.com --secrets | grep -i critical

# Multi-target recon
cat subdomains.txt | httpx -silent | sed 's/$//' > live.txt
gervis -l live.txt --endpoints | sort -u > all_endpoints.txt
```

### Save report
```bash
gervis https://target.com --markdown -o report.md
gervis https://target.com --json -o findings.json
```

## Nothing saved to disk

Gervis holds all JS content in memory only. No files are written unless you explicitly use `-o FILE`. Safe for client engagements.

## Development

```bash
pip install -e ".[dev]"   # install with dev tooling
pytest -q                 # run the test suite
ruff check .              # lint
```

CI runs ruff + pytest on Python 3.9–3.13 for every push and pull request.

- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — how the pipeline works and the design decisions behind it
- [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup and conventions
- [CHANGELOG.md](CHANGELOG.md) — release history

## Legal

Use gervis only against systems you are authorized to test. You are
responsible for complying with all applicable laws and the scope of your
engagement.

## License

MIT

