Whitebox Testing

Overview

Whitebox testing with Pensar Apex provides full source code access to the AI agent, enabling deep static analysis of your application’s attack surface before deployment. Unlike blackbox testing, whitebox analysis directly reads your codebase to understand routes, endpoints, authentication logic, and data flows. This approach is ideal for:

Pre-deployment security reviews - catch vulnerabilities before code reaches production
Shift-left security - integrate security testing early in the development lifecycle
Comprehensive coverage - discover all endpoints, including those not exposed externally
CI/CD integration - automate security checks in your build pipeline

Quick Start

Clone or Navigate to Your Codebase

cd /path/to/your/project

Run Whitebox Pentest

Use the --cwd flag to enable whitebox mode:

pensar pentest --target https://example.com --cwd /path/to/your/project

Review Results

Apex will:

Analyze your source code to map all endpoints
Identify authentication and authorization logic
Generate pentest objectives for each route
Test discovered endpoints against the live target

The --target URL is still required in whitebox mode—Apex uses it to test discovered endpoints against your live staging/dev environment.

How Whitebox Testing Works

The `--cwd` Flag

The --cwd (current working directory) flag signals Apex to perform source code analysis instead of external reconnaissance:

# Blackbox: External probing only
pensar pentest --target https://app.example.com

# Whitebox: Source code analysis + live testing
pensar pentest --target https://app.example.com --cwd ~/projects/myapp

From the CLI implementation:

// src/cli.ts
const target = getArgRequired("--target");
const cwd = getArg("--cwd");

if (cwd) console.log(`Cwd:     ${cwd} (whitebox)`);

const session = await sessions.create({
  name: cwd ? "Whitebox Pentest" : "Blackbox Pentest",
  targets: [target],
  config: {
    ...(cwd ? { cwd } : {}),
  },
});

Whitebox Attack Surface Discovery

When cwd is provided, Apex uses the WhiteboxAttackSurfaceAgent instead of the blackbox agent:

// From src/core/api/attackSurface.ts
export async function runAttackSurfaceAgent(
  input: AttackSurfaceAgentInput,
): Promise<AttackSurfaceResult | WhiteboxAttackSurfaceResult> {
  const isWhitebox = "cwd" in input && !!input.cwd;

  if (isWhitebox) {
    return runWhiteboxAttackSurface(
      input as AttackSurfaceAgentInput & { cwd: string },
    );
  }

  return runBlackboxAttackSurface(input);
}

The whitebox agent performs a deterministic workflow:

Repository Analysis

Identify the repository structure:

Monorepo vs single app
Package manager (npm, yarn, pnpm, bun)
Framework detection (Next.js, Express, FastAPI, Django, etc.)

App Discovery

Find all apps/services in the codebase:

Web frontends
API services
Background workers
Microservices

Endpoint Mapping

For each app, use coding agents to extract:

All API routes and their HTTP methods
Web pages and their URL paths
Authentication requirements
Authorization logic
Input validation rules

Objective Generation

Generate pentest objectives for each endpoint:

Input validation testing
Authentication bypass attempts
Authorization checks (BOLA, privilege escalation)
Business logic flaws

Agent Architecture

// From src/core/agents/specialized/whiteboxAttackSurface/agent.ts
export class WhiteboxAttackSurfaceAgent extends OffensiveSecurityAgent<WhiteboxAttackSurfaceResult> {
  constructor(opts: WhiteboxAttackSurfaceAgentInput) {
    const { model, codebasePath, session } = opts;

    super({
      system: WHITEBOX_ATTACK_SURFACE_SYSTEM_PROMPT,
      prompt: buildPrompt(codebasePath),
      model,
      session,
      activeTools: [
        // Filesystem tools for Phase 1 repo identification
        "read_file",
        "list_files",
        "grep",
        "document_asset",
        // Orchestration for Phase 2 app analysis
        "spawn_coding_agent",
        // Response tool
        "submit_results",
      ],
      stopWhen: hasToolCall("submit_results"),
    });
  }
}

The agent uses specialized coding subagents (via spawn_coding_agent) to analyze each app in parallel, providing high-fidelity endpoint extraction.

Whitebox vs Blackbox

Feature	Blackbox	Whitebox
Source Code Access	❌ No	✅ Yes (via `--cwd`)
Discovery Method	External probing (HTTP requests, port scans)	Static analysis (reads files directly)
Speed	Slower (network latency)	Faster (local filesystem)
Coverage	Only exposed endpoints	All endpoints (including internal/undocumented)
Accuracy	May miss hidden endpoints	Complete endpoint mapping
Use Case	Production/staging testing	Pre-deployment security review
Best For	External security posture	Code-level vulnerability detection

Whitebox testing is faster and more comprehensive because it doesn’t rely on fuzzing or guessing endpoints—it reads your code directly.

Example Workflows

Testing a Next.js App

cd ~/projects/my-nextjs-app
pensar pentest --target https://staging.example.com --cwd .

Apex will:

Detect the Next.js framework from package.json and file structure
Parse app/ or pages/ directory to find all routes
Extract API routes from app/api/ or pages/api/
Identify server actions and their authentication
Test each endpoint against the live staging URL

Testing a Monorepo

cd ~/projects/monorepo
pensar pentest --target https://staging.example.com --cwd .

Apex will:

Detect the monorepo structure (Nx, Turborepo, Lerna, etc.)
Discover all apps in apps/ or packages/
Spawn parallel coding agents to analyze each app
Aggregate results into a unified attack surface map
Prioritize high-value targets for testing

Testing an Express API

cd ~/projects/express-api
pensar pentest --target http://localhost:3000 --cwd .

Apex will:

Read your Express route definitions (app.get, app.post, etc.)
Extract middleware (authentication, validation)
Map all endpoints with their HTTP methods
Generate test cases for each route
Test against your local dev server

Best Practices

1. Use Whitebox for Pre-Deployment Reviews

Run whitebox tests before merging to production. This catches vulnerabilities at the code level before they’re exposed externally.

# .github/workflows/security.yml
name: Security Scan
on: [pull_request]
jobs:
  pentest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Apex Whitebox Scan
        run: |
          pensar pentest \
            --target https://staging.example.com \
            --cwd . \
            --model claude-sonnet-4-5
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

2. Provide Both Source and Live Target

Whitebox mode requires both --cwd and --target:

--cwd tells Apex where to read your source code
--target tells Apex where to test the discovered endpoints

# ✅ Correct
pensar pentest --target https://staging.example.com --cwd ~/myapp

# ❌ Missing target (won't know where to test)
pensar pentest --cwd ~/myapp

# ❌ Missing cwd (falls back to blackbox mode)
pensar pentest --target https://staging.example.com

3. Use Version Control

Ensure your codebase is under version control (Git) for best results:

cd ~/projects/myapp
git status  # Verify you're in a git repo
pensar pentest --target https://staging.example.com --cwd .

Apex may use Git metadata to understand the repository structure.

4. Exclude Sensitive Files

If your codebase contains secrets or PII in test fixtures:

# Create a .gitignore-style file for Apex (future feature)
# For now, ensure secrets are in .env files (which Apex won't leak)

Apex never sends source code to AI providers—it runs local static analysis tools and only sends structured metadata (endpoint names, HTTP methods) to the AI.

5. Review Whitebox Results

Whitebox analysis outputs structured JSON with complete endpoint maps:

// ~/.pensar/sessions/<session-name>/results/whitebox-attack-surface.json
{
  "repoType": "monorepo",
  "packageManager": "pnpm",
  "apps": [
    {
      "name": "web-app",
      "path": "apps/web",
      "framework": "nextjs",
      "pages": [
        { "path": "/", "file": "app/page.tsx" },
        { "path": "/dashboard", "file": "app/dashboard/page.tsx" }
      ],
      "apiEndpoints": [
        {
          "path": "/api/users",
          "method": "GET",
          "requiresAuth": true,
          "file": "app/api/users/route.ts"
        }
      ]
    }
  ],
  "summary": {
    "totalApps": 3,
    "totalPages": 12,
    "totalApiEndpoints": 47,
    "totalPentestObjectives": 94
  }
}

Supported Frameworks

Apex’s whitebox analysis supports:

Language	Frameworks
JavaScript/TypeScript	Next.js, Express, Fastify, NestJS, Remix
Python	FastAPI, Django, Flask
Go	Gin, Echo, Chi
Ruby	Rails, Sinatra
PHP	Laravel, Symfony
Java	Spring Boot

Framework support is constantly expanding. If your framework isn’t listed, Apex will still attempt generic route extraction.

Troubleshooting

”Could not determine repository type”

Cause: Apex couldn’t identify the project structure. Solution:

Ensure you have a package.json (JS/TS) or similar manifest
Check that the --cwd path points to the repository root
Verify the directory contains source code (not a build output folder)

“No apps discovered”

Cause: Apex couldn’t find any application entrypoints. Solution:

For monorepos, ensure apps are in standard locations (apps/, packages/)
For single apps, ensure there’s a clear entrypoint (index.js, main.py, etc.)
Check that your framework is supported

”Whitebox analysis timed out”

Cause: The codebase is very large or complex. Solution:

Use a smaller scope—point --cwd to a specific app subdirectory
Increase timeouts in your session configuration
Split monorepo analysis into multiple runs (one per app)

Combining Whitebox and Blackbox

Strategy: Use whitebox for discovery, blackbox for validation

Phase 1: Whitebox Discovery
```
pensar pentest --target https://staging.example.com --cwd ~/myapp
```
Result: Complete endpoint map from source code.
Phase 2: Blackbox Testing
```
pensar pentest --target https://production.example.com
```
Result: Validate that production behaves as expected (no extra exposed endpoints).
Compare Results
- Whitebox found 47 endpoints in the code
- Blackbox found 52 endpoints externally
- Investigation: What are the 5 extra endpoints? Old code? Misconfigurations?

CI/CD Integration

GitHub Actions Example

name: Whitebox Security Scan
on:
  pull_request:
    branches: [main]

jobs:
  apex-whitebox:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Apex
        run: curl -fsSL https://pensarai.com/install.sh | bash

      - name: Run Whitebox Pentest
        run: |
          pensar pentest \
            --target https://staging.myapp.com \
            --cwd . \
            --model claude-sonnet-4-5
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: apex-report
          path: ~/.pensar/sessions/*/report.md

GitLab CI Example

apex-whitebox:
  stage: security
  image: pensarai/apex:latest
  script:
    - pensar pentest --target $STAGING_URL --cwd . --model claude-sonnet-4-5
  artifacts:
    paths:
      - ~/.pensar/sessions/*/report.md
  only:
    - merge_requests

Next Steps

Blackbox Testing

Learn external testing without source code

Authentication

Configure credentials for authenticated endpoints

Docker Setup

Run Apex in a containerized environment

vLLM Setup

Use local models for offline whitebox analysis

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

Overview

Quick Start

How Whitebox Testing Works

The `--cwd` Flag

Whitebox Attack Surface Discovery

Agent Architecture

Whitebox vs Blackbox

Example Workflows

Testing a Next.js App

Testing a Monorepo

Testing an Express API

Best Practices

1. Use Whitebox for Pre-Deployment Reviews

2. Provide Both Source and Live Target

3. Use Version Control

4. Exclude Sensitive Files

5. Review Whitebox Results

Supported Frameworks

Troubleshooting

”Could not determine repository type”

“No apps discovered”

”Whitebox analysis timed out”

Combining Whitebox and Blackbox

CI/CD Integration

GitHub Actions Example

GitLab CI Example

Next Steps

Blackbox Testing

Authentication

Docker Setup

vLLM Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

​Overview

​Quick Start

​How Whitebox Testing Works

​The --cwd Flag

​Whitebox Attack Surface Discovery

​Agent Architecture

​Whitebox vs Blackbox

​Example Workflows

​Testing a Next.js App

​Testing a Monorepo

​Testing an Express API

​Best Practices

​1. Use Whitebox for Pre-Deployment Reviews

​2. Provide Both Source and Live Target

​3. Use Version Control

​4. Exclude Sensitive Files

​5. Review Whitebox Results

​Supported Frameworks

​Troubleshooting

​”Could not determine repository type”

​“No apps discovered”

​”Whitebox analysis timed out”

​Combining Whitebox and Blackbox

​CI/CD Integration

​GitHub Actions Example

​GitLab CI Example

​Next Steps

Blackbox Testing

Authentication

Docker Setup

vLLM Setup

Build docs developers (and LLMs) love

Overview

Quick Start

How Whitebox Testing Works

The `--cwd` Flag

Whitebox Attack Surface Discovery

Agent Architecture

Whitebox vs Blackbox

Example Workflows

Testing a Next.js App

Testing a Monorepo

Testing an Express API

Best Practices

1. Use Whitebox for Pre-Deployment Reviews

2. Provide Both Source and Live Target

3. Use Version Control

4. Exclude Sensitive Files

5. Review Whitebox Results

Supported Frameworks

Troubleshooting

”Could not determine repository type”

“No apps discovered”

”Whitebox analysis timed out”

Combining Whitebox and Blackbox

CI/CD Integration

GitHub Actions Example

GitLab CI Example

Next Steps