> 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.

# /pentest

> Start an autonomous penetration testing session

## Overview

The `/pentest` command launches the pentest wizard, guiding you through configuring and starting an autonomous penetration test. Apex deploys a swarm of AI agents that collaboratively test your target for vulnerabilities.

## Usage

```bash
/pentest
```

With flags (skip the wizard):

```bash
/pentest --target https://example.com --tier 3
```

**Aliases**: `/p`, `/web`, `/w`

## How It Works

When you run `/pentest`, Apex presents a streamlined wizard that walks you through:

#### Target Configuration

Enter your session name and target URL. The session name is auto-generated
but can be customized.

#### Optional Configuration

Press `[Tab]` to access advanced configuration options, or press `[Enter]`
to start immediately with defaults.

#### Session Creation

Apex creates the session and deploys an autonomous AI agent swarm against
your target.

![Pentest wizard — target configuration step](/apex/_fern-img/98b8a081a06ef0e2fe872de9f800cb79757330816d5cb42263ae55d417431a17.webp)

## Target Step

The first step collects basic information:

### Session Name

An auto-generated name like `swift-falcon` that identifies your session. Edit this if you prefer a custom name.

### Target URL

The primary URL to test, e.g., `https://example.com`. This is required to start the test.

> **Info**
>
> **Quick Start**: Enter your target URL and press `[Enter]` to begin testing
> immediately with default settings.

## Optional Configuration

Press `[Tab]` from the target step to access advanced configuration options:

### Authentication

Configure credentials for authenticated testing:

#### Login URL

The URL of the login page, e.g., `https://example.com/login`

#### Username & Password

Credentials for authenticating to the target application. These are used to
test authenticated functionality.

#### Auth Instructions

Custom authentication instructions for complex login flows, e.g., "Use OAuth flow, extract bearer token..."

### Scope Constraints

Define boundaries for the penetration test:

#### Allowed Hosts

Specific hostnames the agent is allowed to test. Add multiple hosts by
pressing Enter after each.

#### Allowed Ports

Specific ports to include in testing scope (e.g., 443, 8080).

**Strict Scope**: When enabled, the agent will only test explicitly allowed hosts and ports. Use `↑/↓` to toggle.

### Request Headers

Configure how the agent identifies itself:

| Mode        | Description                     |
| ----------- | ------------------------------- |
| **None**    | No identifying headers are sent |
| **Default** | Sends `User-Agent: pensar-apex` |
| **Custom**  | Define your own custom headers  |

For custom headers, you can add multiple key-value pairs.

## Command Flags

You can bypass the wizard entirely by passing flags:

| Flag                           | Description                                                    |
| ------------------------------ | -------------------------------------------------------------- |
| `--target <url>`               | Target URL to test                                             |
| `--name <name>`                | Session name                                                   |
| `--tier <1-5>`                 | Auto-approve permission tier                                   |
| `--model <model>`              | AI model to use                                                |
| `--auth-url <url>`             | Login page URL                                                 |
| `--auth-user <user>`           | Auth username                                                  |
| `--auth-pass <pass>`           | Auth password                                                  |
| `--auth-instructions`          | Custom auth instructions                                       |
| `--hosts <h1,h2,...>`          | Allowed hosts (comma-separated)                                |
| `--ports <p1,p2,...>`          | Allowed ports (comma-separated)                                |
| `--strict`                     | Enable strict scope mode                                       |
| `--headers <mode>`             | Headers mode: none, default, or custom                         |
| `--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          |
| `--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)   |

## Guiding the Pentest

You can provide guidance to the pentest agent using `--prompt` for general instructions or `--threat-model` to feed in a threat model document.

Both flags support inline text and `@file` references — prefix a file path with `@` to read its contents:

```bash
# Inline guidance
/pentest --target https://example.com --prompt "Focus on authentication bypass"

# File-based guidance
/pentest --target https://example.com --prompt @./pentest-notes.md

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

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

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.

## Keyboard Navigation

| Key           | Action                                                  |
| ------------- | ------------------------------------------------------- |
| `[Tab]`       | Move to next field or access configuration              |
| `[Shift+Tab]` | Move to previous field                                  |
| `[Enter]`     | Start pentest (from target step) or add item (in lists) |
| `[↑/↓]`       | Toggle options (strict scope, header mode)              |
| `[ESC]`       | Go back or cancel                                       |

## Example Workflow

```bash
# Start Apex
pensar

# Launch pentest wizard
/pentest

# Enter session details:
# Session Name: production-api-test
# Target URL: https://api.example.com

# Press Enter to start immediately
# OR press Tab to configure authentication, scope, and headers
```

## Best Practices

> **Success**
>
> **Tips for Effective Testing**: 1. **Use descriptive session names** to easily
> identify tests later 2. **Configure authentication** for testing protected
> endpoints 3. **Define scope constraints** to stay within authorized boundaries
> 4\. **Use custom headers** if the target requires specific identification

> **Warning**
>
> **Security Reminder**: Only test systems you own or have explicit
> authorization to test. Unauthorized testing is illegal.

![Pentest wizard — optional configuration (auth, scope, headers)](/apex/_fern-img/120445da5bd73f66dc2a244c284201f17fa69ec57abd1dcf18c75efebf26e1cb.webp)

## After Starting

Once you start a session:

* The AI agent swarm begins reconnaissance on your target
* Real-time progress is displayed in the terminal
* Vulnerabilities are reported as they're discovered
* The session is automatically saved for later review via `/sessions`

## See Also: /operator

For more hands-on control, use `/operator` to start an interactive session where you guide the AI agent step by step. The operator mode supports plan, manual, and auto modes.

## Related Commands

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

Select AI model before starting a test

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

Configure AI provider API keys

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

View all available commands