Metadata-Version: 2.4
Name: probejs
Version: 1.0.1
Summary: A static analysis framework for JavaScript vulnerability detection
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: func_timeout~=4.3.5
Requires-Dist: networkx~=2.4
Requires-Dist: sty~=1.0.0rc0
Requires-Dist: z3-solver~=4.8.8.0
Requires-Dist: tqdm~=4.48.2
Requires-Dist: openai
Requires-Dist: loguru
Requires-Dist: httpx
Provides-Extra: dev
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# probejs

**probejs** is a static analysis tool for JavaScript and TypeScript that detects taint-style vulnerabilities via Object Property Graph (OPG) construction and flow-based trace rules. Its canonical machine-readable output is `report.json`.

## Overview

probejs is a JavaScript static analysis framework that:

- **Generates Object Property Graphs (OPG)** from JavaScript source code
- **Statically tracks object property flows** by simulating assignments, property accesses, and function calls
- **Detects taint-style vulnerabilities** including:
  - OS command injection
  - Cross-site scripting (XSS)
  - Code execution vulnerabilities
  - Prototype pollution
  - Internal property tampering
  - Path traversal
  - NoSQL injection
- **Emits structured JSON bug reports** with source snippets, path diagnostics, and trace rule evaluations
- **Exports analysis results** to CSV/TSV format for further processing
- **Supports npm package analysis**

## Architecture

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.

## Installation

### System Requirements

- **Node.js and npm**: Required for JavaScript/TypeScript AST parsing (automated setup)
- **Python 3.8+**: Required for the core analysis engine

### From PyPI (Recommended)

```bash
pip install probejs
```

On first run, the tool will automatically install its JavaScript dependencies
into `~/.cache/probejs/parser/` via `npm install`. You can also trigger this
step manually ahead of time:

```bash
probejs-setup                # or: python -m probejs setup
```

### From Source (Development)

```bash
git clone <repository-url>
cd probejs

# Install Python package in editable mode
pip install -e .

# Install JavaScript parser dependencies
cd probejs/_parser && npm install && cd ../..

# Verify
python -m probejs input.js
```

Or use the provided installation script:
```bash
./install.sh
```

### Python Dependencies

- `networkx` (~=2.4): Graph data structure library
- `z3-solver` (~=4.8.8.0): Heuristic path feasibility check (used only with `-X` flag)
- `sty` (~=1.0.0rc0): Terminal styling and formatting
- `func_timeout` (~=4.3.5): Function timeout handling
- `tqdm` (~=4.48.2): Progress bars for long-running operations

### JavaScript Dependencies

The JavaScript parser scripts are bundled with the Python package and installed
lazily via npm on first use (or via ``probejs-setup``). They include:

- `esprima` (^4.0.1): JavaScript parser for AST generation
- `typescript` (^5.9): TypeScript/TSX lowering and project configuration support
- `source-map` (^0.6.1): Original TypeScript source location mapping
- `commander` (^3.0.2): Command-line interface utilities
- `ansicolor` (^1.1.84): Terminal color formatting

## Quick Start

```bash
# Analyze a JavaScript or TypeScript file
python -m probejs input.js
python -m probejs input.ts

# Analyze a TypeScript project directory
python -m probejs ./src

# Parse TypeScript supplied on stdin
printf 'const value: string = process.argv[2];' | python -m probejs --typescript -

# Analyze with specific vulnerability type
python -m probejs -t os_command input.js

# Emit a canonical JSON report
python -m probejs --json -t os_command input.js

# Check for prototype pollution
python -m probejs -P input.js

# Disable JS-modeled stubs in builtin_packages/
python -m probejs --no-builtin-packages input.js
```

When `--json` is passed, the JSON report is written to the run log directory as:

- `report.json`: structured bug report with source snippets, path diagnostics, and trace rule evaluations
- `report.schema.json`: schema for the report format

See [docs/USAGE.md](docs/USAGE.md) for detailed usage instructions, examples, and advanced configuration.

### TypeScript support

TypeScript files (`.ts`, `.tsx`, `.mts`, and `.cts`) and ArkTS `.ets` files are automatically lowered to CommonJS before the existing JavaScript AST pipeline runs. The frontend:

- removes type-only syntax while preserving runtime behavior
- converts ES module imports/exports to the existing module-analysis representation
- follows transitive TypeScript imports
- compiles the nearest `tsconfig.json` as a project, including project references
- resolves `baseUrl`/`paths`, package `exports`/`imports`, and workspace packages
- maps AST locations and reports back to the original TypeScript source
- lowers TSX and modern JavaScript syntax to parser-compatible JavaScript
- models `tslib` interop/decorator helpers and uses declaration signatures to identify callback arguments
- normalizes common ArkTS component syntax (`struct`, state/component decorators, and declarative UI blocks) and treats `@Entry` build bodies as analysis entrypoints
- prefers the project's installed TypeScript compiler and records compiler diagnostics/version information in `report.json`
- recognizes callback properties in typed options objects and common Fastify, NestJS, EventEmitter, Commander, Yargs, worker, and serverless entrypoints
- reads HarmonyOS `build-profile.json5`, `module.json5`, and `oh-package.json5` project metadata
- consumes existing external or inline JavaScript source maps when analyzing generated CommonJS

Declaration files (`.d.ts`, `.d.mts`, and `.d.cts`) are not emitted as runtime files, but their signatures inform callback and promise metadata. Common generated/dependency directories are skipped during directory analysis. Type errors do not prevent emission because probejs analyzes runtime flows.

> **Experimental: PoC generation utilities.** The directories `pocgen/` and `skills/probejs-poc-generation/` contain experimental utilities that consume `report.json` to assist with proof-of-concept generation. These are **separate from the core analysis pipeline** and currently rely on LLM-based coding agents (e.g., Codex, Claude) rather than automated symbolic reasoning.

## Documentation

- **[Architecture](docs/ARCHITECTURE.md)**: Detailed architecture, how it works, and output format
- **[Usage Guide](docs/USAGE.md)**: Command-line options, canonical JSON reporting, programmatic usage, and examples
- **[Vulnerability Types](docs/VULNERABILITIES.md)**: Detailed information about each vulnerability type with examples
- **[Troubleshooting](docs/TROUBLESHOOTING.md)**: Limitations, common issues, debugging tips, and references
- **[PoC Generation Workflows](docs/POC_GENERATION.md)**: Difference between the interactive skill and automated runner approaches
- **[PoC Skill](skills/probejs-poc-generation/SKILL.md)**: Agent skill for turning `report.json` findings into runnable PoCs
