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.
Run the latest published package without installing it globally:
uvx whitebox-secure-scan@latest version
uvx whitebox-secure-scan@latest review /path/to/repository \
--output ./whitebox-resultsKeep the output directory outside the target repository. The scanner reads target source locally, does not execute it, and does not modify it.
uvx runs the published package in an isolated environment and does not require a permanent installation.
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.1.0 versionpython3 -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-resultsUpgrade an existing installation with:
python -m pip install --upgrade whitebox-secure-scanThe package supports Python 3.11 and newer. uvx and pip use the published PyPI package; no repository checkout is required for normal use.
The Formula is available from Waariss/homebrew-tap:
brew install waariss/tap/whitebox-secure-scan
whitebox-secure-scan version
whitebox-secure-scan doctorThe Homebrew Formula installs the core scanner without the optional parsing
extra. Use the PyPI installation above when local Tree-sitter parser support is
needed. See the Homebrew distribution guide.
The core scanner works without optional parsers. Install the local parsing extras when you want the additional parser support:
python -m pip install "whitebox-secure-scan[parsing]"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.
Local result files from supported tools can be imported without executing them:
whitebox-secure-scan review /path/to/repository \
--import-result semgrep=/path/to/semgrep.json \
--output ./whitebox-resultsSupported import formats include Semgrep, Gitleaks, Bandit, gosec, and FindSecBugs. Imported results retain the external tool and rule IDs and are still review candidates.
| 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 |
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.
- 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.
When the optional parsing extra is installed, the parser layer can use local Tree-sitter grammars for JavaScript, TypeScript, Java, and Go. Without it, the scanner uses a structured lexical fallback. The code graph is bounded to observable declarations, routes, and calls; it is not complete whole-program interprocedural taint analysis.
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
Use this section only when contributing to the project or running its synthetic test suite:
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 srcTests 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 and the technical reference.
Apache License 2.0. See LICENSE.