Metadata-Version: 2.4
Name: whitebox-secure-scan
Version: 1.0.2
Summary: Offline white-box secure-code triage for penetration testers.
Author: whitebox-secure-scan contributors
License: Copyright 2026 whitebox-secure-scan contributors
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software distributed
        under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
        CONDITIONS OF ANY KIND, either express or implied. See the License for the
        specific language governing permissions and limitations under the License.
        
Project-URL: Homepage, https://github.com/Waariss/whitebox-secure-scan
Project-URL: Repository, https://github.com/Waariss/whitebox-secure-scan
Project-URL: Issues, https://github.com/Waariss/whitebox-secure-scan/issues
Project-URL: Documentation, https://github.com/Waariss/whitebox-secure-scan#readme
Keywords: security,static-analysis,secure-coding,triage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.0
Provides-Extra: parsing
Requires-Dist: tree-sitter>=0.22; extra == "parsing"
Requires-Dist: tree-sitter-languages>=1.10; extra == "parsing"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# whitebox-secure-scan

[![PyPI](https://img.shields.io/pypi/v/whitebox-secure-scan?logo=pypi&logoColor=white)](https://pypi.org/project/whitebox-secure-scan/)
[![Python](https://img.shields.io/pypi/pyversions/whitebox-secure-scan)](https://pypi.org/project/whitebox-secure-scan/)
[![Tests](https://github.com/Waariss/whitebox-secure-scan/actions/workflows/test.yml/badge.svg)](https://github.com/Waariss/whitebox-secure-scan/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/Waariss/whitebox-secure-scan/blob/main/LICENSE)

![whitebox-secure-scan banner](https://raw.githubusercontent.com/Waariss/whitebox-secure-scan/main/docs/assets/whitebox-secure-scan-banner.svg)

`whitebox-secure-scan` is a local, offline white-box secure-code triage tool for penetration testers. It helps you filter a large codebase into explainable review leads, precise file and line evidence, grouped root causes, and reviewer guidance.

It is a triage aid—not a final penetration-test report and not an automatic vulnerability confirmer. Every candidate must be independently verified by an authorized security engineer.

The analysis stays local: source enters a bounded review pipeline, evidence is grouped for a human reviewer, and no source is sent to an external service.

![Local code review and evidence grouping](https://raw.githubusercontent.com/Waariss/whitebox-secure-scan/main/docs/assets/whitebox-secure-scan-overview.png)

## Quick start

Run the latest published package without installing it globally:

```bash
uvx whitebox-secure-scan@latest version
uvx whitebox-secure-scan@latest review /path/to/repository \
  --output ./whitebox-results
```

Keep the output directory outside the target repository. The scanner reads target source locally, does not execute it, and does not modify it.

## Installation

### Run with `uvx` — recommended

`uvx` runs the published package in an isolated environment and does not require a permanent installation.

```bash
uvx whitebox-secure-scan@latest version
uvx whitebox-secure-scan@latest --help
uvx whitebox-secure-scan@latest review /path/to/repository \
  --output ./whitebox-results
uvx whitebox-secure-scan@1.0.1 version
```

### Install with `pip`

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install whitebox-secure-scan
whitebox-secure-scan version
whitebox-secure-scan review /path/to/repository \
  --output ./whitebox-results
```

Upgrade an existing installation with:

```bash
python -m pip install --upgrade whitebox-secure-scan
```

The package supports Python 3.11 and newer. `uvx` and `pip` use the published PyPI package; no repository checkout is required for normal use.

### Optional parsing dependencies

The core scanner works without optional parsers. Install the local parsing extras when you want the additional parser support:

```bash
python -m pip install "whitebox-secure-scan[parsing]"
```


## What you get

The normal `review` command writes a concise, reviewer-first result set:

| File | Purpose |
| --- | --- |
| `SUMMARY.md` | Fast overview of root causes, locations, and scope |
| `report.md` | Detailed evidence and verification guidance |
| `findings.json` | Normalized finding instances for automation |
| `root-causes.json` | Related instances grouped for efficient review |
| `review-points.json` | Lower-confidence items that need context |

Advanced compatibility commands can also produce inventory, routes, metadata, SARIF, and a bounded internal-AI handoff package.

![whitebox-secure-scan workflow](https://raw.githubusercontent.com/Waariss/whitebox-secure-scan/main/docs/assets/whitebox-secure-scan-workflow.svg)

## What it does—and does not do

| It does | It does not |
| --- | --- |
| Scan Python, JavaScript/TypeScript, Java, and Go source locally | Execute application code, tests, builds, migrations, or package scripts |
| Identify security review leads and review points | Claim that a finding is exploitable or confirmed |
| Preserve file, line, source, sink, and proof-gap context | Replace manual code review or a penetration tester |
| Group related evidence into root causes | Upload source, findings, telemetry, or analytics |
| Work offline by default | Call external AI services or download rules during a scan |

## Safety boundaries

The scanner is designed for controlled white-box review:

- Offline operation is enabled by default.
- Target repositories are treated as read-only.
- Repository code and commands are never executed.
- External scanners are disabled unless explicitly enabled and already installed locally.
- Output paths are safety-checked and should be outside the target repository.
- Symlinks that escape the target are not followed.
- Secrets are redacted by default and snippets are bounded.
- No source code or scan results are sent to a cloud service.

Only scan repositories you are authorized to review.

## Supported languages

- Python
- JavaScript and TypeScript, including common Node.js and frontend patterns
- Java, including common Spring-oriented patterns
- Go

Framework evidence is reported only when it is observable in the repository. Static analysis is intentionally conservative: incomplete flows remain review leads or review points.

## Typical workflow

```text
Scan locally
    ↓
Read SUMMARY.md and grouped root causes
    ↓
Inspect the referenced file and line
    ↓
Verify the complete flow manually
    ↓
Write the approved security finding, if confirmed
```

## Development installation

Use this section only when contributing to the project or running its synthetic test suite:

```bash
git clone https://github.com/Waariss/whitebox-secure-scan.git
cd whitebox-secure-scan
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q
ruff check .
ruff format --check .
mypy src
```

Tests use synthetic fixtures. Do not point the test suite or examples at repositories you do not own or have permission to review. See [CONTRIBUTING.md](https://github.com/Waariss/whitebox-secure-scan/blob/main/CONTRIBUTING.md) and the [technical reference](https://github.com/Waariss/whitebox-secure-scan/blob/main/docs/REFERENCE.md).

## Documentation and support

- [Technical reference](https://github.com/Waariss/whitebox-secure-scan/blob/main/docs/REFERENCE.md)
- [Security boundaries](https://github.com/Waariss/whitebox-secure-scan/blob/main/SECURITY.md)
- [Contributing](https://github.com/Waariss/whitebox-secure-scan/blob/main/CONTRIBUTING.md)
- [Report a security issue](https://github.com/Waariss/whitebox-secure-scan/blob/main/SECURITY.md)
- [GitHub issues](https://github.com/Waariss/whitebox-secure-scan/issues)

## License

Apache License 2.0. See [LICENSE](https://github.com/Waariss/whitebox-secure-scan/blob/main/LICENSE).
