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

> List, view, and dispatch pentests via the Pensar Console API

## Overview

The `pensar pentests` command lets you manage pentests (scans) in your workspace through the Pensar Console API. You can list existing pentests, view details, or dispatch new ones — all from the command line.

All commands operate on the **selected workspace**, which is chosen when you connect with [`pensar login`](/apex/cli-commands/pensar-login). There is no longer a project argument.

## Usage

```bash
pensar pentests                       # List pentests in the workspace (alias: pensar pentests list)
pensar pentests get <pentestId>        # Get pentest details
pensar pentests dispatch [options]     # Dispatch a new pentest
```

## Prerequisites

You must be connected to Pensar Console via [`pensar login`](/apex/cli-commands/pensar-login) before using this command.

## Subcommands

### List Pentests

```bash
pensar pentests
```

Lists all pentests in the selected workspace. Returns a JSON array of pentest objects.

### Get Pentest Details

```bash
pensar pentests get <pentestId>
```

Retrieves detailed information about a specific pentest, including status, findings count, and configuration.

### Dispatch a New Pentest

```bash
pensar pentests dispatch [options]
```

Dispatches a new pentest scan in the selected workspace.

| Flag                            | Description                                                                                                                                                |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--branch <branch>`             | Configured target branch to scan; cannot be combined with endpoint selection                                                                               |
| `--level <level>`               | Scan depth: `priority` by default, or `full`; endpoint selection requires full depth                                                                       |
| `--endpoint-id <UUIDs>`         | Select existing workspace endpoints; repeat the flag or separate UUIDs with commas                                                                         |
| `--endpoint-ids-file <file\|->` | Read one endpoint UUID per line from a file or stdin (`-`); may combine with `--endpoint-id`                                                               |
| `--knowledge-id <UUIDs>`        | Attach up to 20 active [knowledge base](/apex/cli-commands/pensar-knowledge) entries as context for the run; repeat the flag or separate UUIDs with commas |

### Launch selected endpoints

```bash
pensar pentests dispatch \
  --endpoint-id 7e4fe67a-61e5-4aa5-b93a-6871b470aaef \
  --endpoint-id 59e9b6d5-d13b-4912-9e46-a1e801c1d053

pensar pentests dispatch \
  --endpoint-id 7e4fe67a-61e5-4aa5-b93a-6871b470aaef,59e9b6d5-d13b-4912-9e46-a1e801c1d053
```

Use endpoint UUIDs from `pensar apps endpoints <appId>`. A launch accepts 1–1000 unique endpoint IDs in the selected workspace. Duplicate IDs are removed. Endpoint launches use full depth by default; `--level full` is also accepted. They cannot be combined with a branch or priority depth. They test existing endpoints without discovering additional targets or narrowing the selection to code changes.

To read IDs from a file, put one UUID on each line:

```text
7e4fe67a-61e5-4aa5-b93a-6871b470aaef
59e9b6d5-d13b-4912-9e46-a1e801c1d053
```

```bash
pensar pentests dispatch --endpoint-ids-file endpoints.txt
```

Blank lines are ignored. File/stdin input may be combined with `--endpoint-id`; the combined selection is deduplicated. Invalid UUIDs, an empty selection, more than 1,000 unique IDs, incompatible flags, unknown flags, or an unreadable file fail before dispatch.

### Select endpoints in CI

Set `PENSAR_API_KEY` in your CI environment. For a CI-generated `ci-targets.json` containing a `selectedEndpointIds` array of discovered endpoint UUIDs, pipe the computed IDs to stdin:

```bash
jq -r '.selectedEndpointIds[]' ci-targets.json | pensar pentests dispatch --endpoint-ids-file -
```

The command returns the queued scan as JSON without waiting for findings. Use `pensar pentests get <scanId>` to track completion. A successful dispatch does not indicate a passing security assessment. The server validates workspace ownership and application readiness; invalid scope fails without launching a broader scan.

These are hosted Console launches. Local `pensar pentest` and `pensar targeted-pentest` commands run their own workflows; their local target and prompt options are not hosted launch options.

## Examples

```bash
# List all pentests in the workspace
pensar pentests

# Get details for a specific pentest
pensar pentests get scan_def456

# Dispatch a new priority scan
pensar pentests dispatch

# Dispatch a full scan on a specific branch
pensar pentests dispatch --branch main --level full
```

## Related Commands

#### [pensar issues](/apex/cli-commands/pensar-issues)

View security issues found by pentests

#### [pensar fixes](/apex/cli-commands/pensar-fixes)

View suggested fixes for an issue