> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/apex/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/apex/_mcp/server.

# pensar pentest

> Run a full autonomous pentest orchestration from the command line

## Overview

The `pensar pentest` command runs a full autonomous penetration test from the command line without launching the TUI. This is ideal for CI/CD pipelines, scripting, and headless environments.

## Usage

```bash
pensar pentest --target <url> [options]
```

## Options

| Flag                           | Description                                                      |
| ------------------------------ | ---------------------------------------------------------------- |
| `--target <url>`               | **(required)** Target URL, domain, or IP address                 |
| `--cwd <path>`                 | Source code path — enables whitebox attack surface analysis      |
| `--mode <mode>`                | Pentest mode: `exfil` (pivoting & flag extraction)               |
| `--model <model>`              | AI model to use (defaults to your configured provider's default) |
| `--prompt <text\|@file>`       | Guidance for the pentest agent (inline text or @filepath)        |
| `--threat-model <text\|@file>` | Threat model to guide the pentest (inline text or @filepath)     |
| `--header "Name: Value"`       | Custom HTTP header sent on every in-scope request (repeatable)   |
| `--headers-from <file>`        | Load headers from a JSON object or `Name: Value` file            |
| `--no-global-headers`          | Skip the snapshot of `pensar config headers` defaults            |
| `--extended-thinking`          | Enable extended thinking for supported models                    |
| `--task-driven`                | Enable task-driven architecture (experimental)                   |

## Examples

```bash
# Basic blackbox pentest
pensar pentest --target https://example.com

# Whitebox pentest with source code access
pensar pentest --target https://example.com --cwd ./my-app

# Specify a model
pensar pentest --target https://example.com --model claude-sonnet-4-5

# Exfil mode for CTF-style flag extraction
pensar pentest --target https://example.com --mode exfil

# Provide inline guidance
pensar pentest --target https://example.com --prompt "Focus on authentication bypass"

# Load guidance from a file
pensar pentest --target https://example.com --prompt @./pentest-notes.md

# Feed a threat model document
pensar pentest --target https://example.com --threat-model @./threat-model.md

# Combine both
pensar pentest --target https://example.com --threat-model @./threat-model.md --prompt "Focus on critical paths"

# Send a custom Authorization header on every in-scope request
pensar pentest --target https://api.example.com \
  --header "Authorization: Bearer $TOKEN"

# Multiple headers loaded from a JSON file
pensar pentest --target https://api.example.com --headers-from ./headers.json
```

## Custom HTTP Headers

Headers passed via `--header` (repeatable) and `--headers-from` are sent on every
in-scope request issued by the agent — `http_request`, supported `execute_command`
tools (curl, nuclei, ffuf, gobuster, httpx, feroxbuster, dirb, wfuzz, wpscan,
sqlmap, nikto), and Playwright browser navigation.

Headers are applied **only to in-scope hosts**. Out-of-scope hosts (CVE writeups,
vendor docs, etc.) never see configured headers.

Precedence (later wins on collision): global defaults (from `pensar config headers`)
\< `--headers-from` file \< `--header` CLI flags. Pass `--no-global-headers` to skip
the global snapshot.

The `--headers-from` file can be either a JSON object (`{"X-API-Key": "abc"}`) or
a newline-separated `Name: Value` file (with `#` comments).

## Guiding the Pentest

The `--prompt` and `--threat-model` flags let you steer the pentest agent with additional context.

Both flags accept inline text or an `@file` reference. Prefix a file path with `@` to read its contents instead of passing the path as a literal string.

When `--threat-model` is used, the content is automatically wrapped with guidance explaining how the agent should use it — prioritizing attack paths by severity, following pentest guidance sections, and verifying control gaps.

## How It Works

1. Apex creates a session (named "Blackbox Pentest" or "Whitebox Pentest" depending on whether `--cwd` is provided)
2. The AI agent swarm is deployed against the target
3. Progress and tool calls are streamed to stdout in real time
4. On completion, a summary is printed with the number of findings and paths to the findings file, POCs directory, and report

## Output

```
============================================================
PENTEST ORCHESTRATION
============================================================
Target:  https://example.com
Model:   claude-sonnet-4-5

→ execute_command
✓ execute_command completed
→ http_request
✓ http_request completed
...

============================================================
RESULTS
============================================================
Findings:  3
Path:      /home/user/.pensar/sessions/.../findings.json
POCs:      /home/user/.pensar/sessions/.../pocs/
Report:    /home/user/.pensar/sessions/.../report.md
```

## Default Model

When `--model` is not provided, Apex uses the default model for your highest-priority configured provider. See [`pensar models`](/apex/tui-slash-commands/models#default-model-per-provider) for the priority order.

> **Warning**
>
> **Authorization Required**: Only test systems you own or have explicit authorization to test.

## Related Commands

#### [pensar targeted-pentest](/apex/cli-commands/pensar-targeted-pentest)

Run a focused pentest with specific objectives

#### [/pentest](/apex/tui-slash-commands/pentest)

Launch a pentest from the TUI with an interactive wizard