Autonomous White-Box Security & Code Audit Engine for Web Applications and APIs
Quick Start • Architecture • Playbooks • Reporting • Security Model • Contributing
REI Pentest Box is a local-first, containerized CLI orchestrator that helps security engineers and developers perform automated white-box code audits and API vulnerability assessments through isolated agent execution and structured SARIF/HTML reporting.
Unlike black-box dynamic scanners that send unguided HTTP payloads to remote endpoints, REI Pentest Box combines local source-code analysis (SAST) with context-aware API verification. By mounting target repositories in read-only mode and executing reasoning agents inside isolated Docker containers, REI Pentest Box identifies business-logic flaws, authorization bypasses, and injection risks directly at the code level without compromising live infrastructure.
Traditional application security testing often suffers from three core operational challenges:
- Disconnected Context: Black-box scanners lack visibility into backend routing, ORM definitions, and authorization middleware, leading to high false-positive rates.
- Unsafe Execution: Running automated security tools directly on developer host machines risks polluting environments and leaking local credentials.
- Unstandardized Evidence: Auditing outputs are frequently scattered across raw log files, making report compilation tedious and difficult to integrate into CI/CD pipelines.
REI Pentest Box addresses these issues through:
- Local-First Containerization: All agent activities run inside dedicated Docker containers. Target source code is mounted as read-only (
:ro), while state is preserved in isolated overlay directories. - Deterministic Workflows: Powered by Temporal, scan workflows are crash-safe, resumable, and fully auditable.
- Standards-Compliant Deliverables: Findings are exported automatically in standard SARIF 2.1.0, standalone HTML Audit Dashboards, and CycloneDX SBOM JSON manifests.
- Scans backend application code to map routes, middleware, and database access layers.
- Identifies unsanitized data paths flowing from HTTP endpoints (sources) to database query or shell execution functions (sinks).
- Audits authentication guards, RBAC/ABAC implementations, and IDOR vulnerabilities.
- Playbook Engine: Applies structured audit scenarios aligned with OWASP Top 10 (2021), CWE Top 25, and API Security Top 10.
- Multi-Agent Orchestrator: Distributes analysis tasks across specialized internal roles:
ReconAgent: Maps project topology, framework configuration, and endpoints.TaintAnalyzer: Traces variable flow and input sanitization boundaries.PatchAgent: Generates candidate remediation diffs for identified flaws.
- Parses application manifests (
package.json,pnpm-lock.yaml) to extract direct and transitive dependencies. - Generates a standard CycloneDX-JSON (v1.4) Software Bill of Materials (SBOM) for supply-chain risk tracking.
+-----------------------------------------------------------------------------------+
| USER HOST (CLI) |
| |
| ./rei start -u https://api.local -r /path/to/target-repo -w audit-session-1 |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| DOCKER ENVIRONMENT |
| |
| +-----------------------+ +------------------------------+ |
| | rei-temporal | <--- gRPC :7233 -> | rei-worker container | |
| | (Workflow State) | | | |
| +-----------------------+ | - Target Repo (Mounted :ro) | |
| | - Overlay Dir (~/.rei/) | |
| | - Temporal Worker + Client | |
| | - Playwright & SAST Harness | |
| +------------------------------+ |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| DELIVERABLES ENGINE |
| |
| ./workspaces/audit-session-1/.rei/deliverables/ |
| ├── sarif_report.json (SARIF 2.1.0 Format for GitHub/SonarQube) |
| ├── audit_dashboard.html (Standalone Interactive HTML Report) |
| ├── sbom.json (CycloneDX Software Bill of Materials) |
| └── findings.md (Human-Readable Summary) |
+-----------------------------------------------------------------------------------+
Ensure the following tools are installed on your host machine:
- Node.js
>= 18.0.0 - pnpm
>= 9.0.0(ornpm/npx) - Docker Engine
>= 24.0.0and Docker Compose
git clone https://github.com/rootcastleco/rei-pentest-box.git
cd rei-pentest-box
# Install dependencies and build monorepo packages
pnpm install
pnpm buildRun the interactive setup wizard to configure your preferred LLM provider. Credentials are saved securely to ~/.rei/config.toml with restricted permissions (0o600).
./rei setupSupported Providers: Anthropic Claude, OpenAI, Custom OpenAI-Compatible Endpoints (OpenRouter, Ollama, vLLM), AWS Bedrock.
Launch a white-box audit scan against a local project repository and test URL:
./rei start \
--url http://localhost:3000 \
--repo /path/to/my-application \
--workspace demo-auditMonitor execution logs in real time:
./rei logs demo-auditOnce complete, audit deliverables are exported to ./workspaces/demo-audit/.rei/deliverables/.
Run a complete white-box assessment specifying a custom configuration file and output directory:
./rei start \
--url https://staging-api.internal.local \
--repo /src/backend-service \
--config ./custom-audit-config.yaml \
--output ./audit-reports/q1-2026 \
--workspace backend-q1-auditList active and completed audit workspaces:
./rei workspacesCheck the status of running background worker containers:
./rei statusStop running audit containers and clean up Temporal state:
./rei stop --cleanREI Pentest Box reads configuration settings from ~/.rei/config.toml or custom YAML files provided via --config.
| Variable / Key | Type | Default | Description | Security Notes |
|---|---|---|---|---|
ANTHROPIC_API_KEY |
String | <none> |
API key for Anthropic provider | Saved with 0o600 file permissions |
OPENAI_API_KEY |
String | <none> |
API key for OpenAI provider | Saved with 0o600 file permissions |
CUSTOM_BASE_URL |
String | <none> |
Base URL for custom/local OpenAI proxy | Useful for local Ollama / vLLM proxies |
TEMPORAL_ADDRESS |
String | localhost:7233 |
Temporal server gRPC address | Internal communication channel |
REI_HOME |
Path | ~/.rei/ |
Host state directory | Stores keys, workspaces, and logs |
REI Pentest Box generates three primary audit deliverables upon session completion:
Standard format compatible with GitHub Code Scanning, DefectDojo, and SonarQube:
{
"$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
"version": "2.1.0",
"runs": [
{
"tool": {
"driver": {
"name": "RootCastle REI Engine",
"version": "1.1.0",
"informationUri": "https://rootcastle.com"
}
},
"results": [
{
"ruleId": "A03:2021-SQLi",
"level": "error",
"message": { "text": "Unsanitized user input reaching raw SQL query in getUserById." },
"locations": [
{
"physicalLocation": {
"artifactLocation": { "uri": "src/controllers/userController.ts" },
"region": { "startLine": 42 }
}
}
]
}
]
}
]
}A single-file HTML report featuring executive statistics, severity breakdown, location references, and recommended remediation patches.
Caution
LEGAL DISCLAIMER & RESPONSIBILITY WAIVER REI Pentest Box is developed strictly for EDUCATIONAL PURPOSES, ACADEMIC RESEARCH, CTF (CAPTURE THE FLAG) COMPETITIONS, AND AUTHORIZED DEFENSIVE CODE AUDITING IN CONTROLLED LAB ENVIRONMENTS. It is a non-commercial, open-source security tool intended for research.
- Unauthorized Use Prohibited: Running this tool against target systems or source code without explicit, written authorization from the owner is illegal and violates local and international cybercrime laws.
- Limitation of Liability: The authors, maintainers, and RootCastle Engineering shall not be held liable for any misuse, unauthorized scanning, data loss, or direct/indirect damages resulting from the operation of this software.
- User Responsibility: End users are solely responsible for acquiring legal consent prior to initiating audits and for ensuring full compliance with applicable legislation.
Important
Authorization & Scope Warning REI Pentest Box is designed exclusively for authorized security auditing, defensive code verification, academic research, and training in controlled laboratory environments. Commercial exploitation or unauthorized targeting is strictly prohibited. Users must obtain explicit written permission from system owners prior to running assessments.
- Read-Only Target Mounts: Target source directories are mounted into the worker container as read-only (
:ro). The engine cannot alter original host source files during an audit. - Credential Isolation: API keys stored in
~/.rei/config.tomlare never written into generated workspace reports or deliverables. - Process Boundary: Worker processes run inside containerized Docker environments with restricted network interfaces (
rei-net).
rei-pentest-box/
├── apps/
│ ├── cli/ # Node.js CLI Orchestrator (@rootcastle/rei)
│ │ ├── src/commands/ # start, stop, workspaces, logs, setup, build
│ │ ├── src/docker.ts # Docker process & volume mounting controls
│ │ └── src/index.ts # CLI entry point
│ └── worker/ # Worker Execution Engine (@rei/worker)
│ ├── src/audit/ # SARIF, HTML, SBOM, and Playbook modules
│ ├── src/temporal/ # Temporal workflows, activities, & workers
│ └── src/ai/pi/ # Agent execution harness & tool bindings
├── docker-compose.yml # Local Temporal cluster definition
├── Dockerfile # Worker container image definition
├── entrypoint.sh # Container permission & UID alignment script
├── rei # Executable CLI launcher script
└── package.json # Root workspace metadata (rei-engine)
| Command | Purpose |
|---|---|
pnpm build |
Compiles CLI and Worker packages via Turborepo |
pnpm check |
Runs TypeScript type checking across all workspace packages |
pnpm clean |
Cleans build artifacts (dist/) |
./rei build |
Rebuilds local rei-worker Docker container image |
| Risk Vector | Impact | Mitigated By | Status |
|---|---|---|---|
| Host File Corruption | High | Target repository is mounted :ro into containers |
Implemented |
| API Key Exposure in Reports | High | Audit log sanitization and environment isolation | Implemented |
| Container Escalation | Medium | Container runs with non-root user mapping (entrypoint.sh) |
Implemented |
| Unbounded Concurrency | Medium | Temporal task queues throttle activity execution | Implemented |
- v1.0.0: Core CLI container orchestrator and Temporal pipeline.
- v1.1.0: Native SARIF 2.1.0 exporter, HTML Audit Dashboard, and CycloneDX SBOM analyzer.
- v1.2.0: SAST Playbook Engine (OWASP Top 10 / CWE) and Multi-Agent Crew Orchestrator.
- v1.3.0: Automated Remediation PR Generator (Git patch export).
- v1.4.0 (Planned): Native VS Code Extension integration for inline SARIF viewing.
This project is licensed under the AGPL-3.0 License. See LICENSE for details.
- Original Work: Copyright (C) 2025 Keygraph, Inc.
- Engine Enhancements: Copyright (C) 2026 RootCastle Engineering & Innovation (rootcastle.com)
If REI Pentest Box improves your authorized security auditing workflow, consider starring the repository.