Metadata-Version: 2.4
Name: whitebox-secure-scan
Version: 1.0.1
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

`whitebox-secure-scan` is an offline, read-only white-box secure-code triage tool for penetration testers. It identifies high-signal security review leads, records precise file and line evidence, groups related instances into root causes, and provides reviewer guidance.

It is designed to accelerate source-code review not to replace a penetration tester, confirm exploitability automatically, or generate a final pentest report. Every candidate requires independent verification by an authorized security engineer.

It scans Python 3.11+, JavaScript/TypeScript, Java, and Go locally. It does not import, execute, upload, or modify target code and does not contact package registries or external AI services during scans.

## Install and run

```bash
python3 -m venv .venv && . .venv/bin/activate
python -m pip install -e ".[dev]"
whitebox-secure-scan review /path/to/repository --output ./whitebox-results
```

The normal `review` workflow keeps only the useful review outputs: `SUMMARY.md`, `report.md`, `findings.json`, `root-causes.json`, and `review-points.json`. Detailed inventory, routes, metadata, SARIF, and handoff packaging remain available through advanced compatibility commands. Results are review leads, not automatic vulnerability confirmations.

## Scope

The engine combines Python AST parsing, structured lexical analysis for the other supported languages, framework evidence detection, conservative source/sink heuristics, secret redaction, confidence scoring, duplicate suppression, route inventory, normalized reporting, safety-bounded walking, and local adapter interfaces. Findings are review leads or review points, not confirmed vulnerabilities.

Java uses a structured lexical fallback that removes comments/Javadocs, masks string literals for API matching, and requires observable method or constructor invocation. It distinguishes code surfaces such as production, test, utility, demo, generated, and configuration. Findings include `verdict_candidate`, `code_surface`, `proof_gaps`, `counterevidence`, parser metadata, and source/sink diagnostics.

JavaScript and TypeScript use the same conservative structured-lexical approach when an optional AST parser is unavailable. Upload findings require both an uploaded-file source and a write/storage sink; blob responses, report downloads, browser exports, API wrappers, identifiers, comments, and UI labels are not upload or execution evidence. Dynamic execution requires an invocation of `eval`, `Function`, `vm`, or a `child_process` API. Literal-secret findings require a credential-shaped value, while environment-variable lookups and labels such as `Change Password` are excluded.

The normal command is `whitebox-secure-scan review /path/to/repository`. Other commands are advanced support utilities. See [the compact technical reference](docs/REFERENCE.md).

Triage commands are `sample-unreported` for deterministic negative-review candidates and `compare` for old/new result comparison. Use `--production-only` for production results, `--include-test-code` to inspect ordinary test code, `--include-test-secrets` to retain test-source secrets, and `--root-causes-only` when consuming grouped results.

The operational workflow is: scan to an output directory outside the target, inspect the concise summary and evidence, optionally send the bounded handoff package to an approved internal verifier, then manually validate candidates. Default controls are offline operation, redaction, no repository execution, no external tools, bounded file reads, no symlink following, and no writes to the target repository.
