Quick Start

Your First Scan

This guide walks you through scanning your first target with Esprit. You’ll learn how to:

Choose between Esprit Cloud and local mode
Connect an LLM provider
Run a scan and interpret results
Review vulnerability reports

Prerequisites: You’ve installed Esprit and verified it’s working with esprit --version

Interactive Launchpad

The fastest way to get started is the interactive launchpad UI. Just run:

esprit

The launchpad guides you through:

Provider selection - Choose Esprit Cloud or connect your own LLM
Model selection - Pick a model (Claude, GPT, Gemini, etc.)
Target input - Enter a URL, GitHub repo, or local directory
Scan mode - Choose quick, standard, or deep

The launchpad remembers your last settings, so subsequent scans are even faster.

Option 1: Esprit Cloud (Recommended)

Esprit Cloud is the easiest way to get started—no Docker, no API keys, just sign in and scan.

esprit provider login esprit

This opens your browser to authenticate with your Esprit account. After signing in, the CLI automatically saves your credentials.

You should see: ✓ Logged in as [email protected]

Run Your First Scan

esprit scan https://example.com

Esprit automatically:

Spins up a cloud sandbox
Routes your scan through secure infrastructure
Displays vulnerabilities in real-time
Saves results to esprit_runs/<scan-id>/

You’ll see status updates like:

✓ Using Esprit Cloud (no Docker required)
Plan: PRO
Quota: scans 95  |  tokens 480,000

Penetration test initiated
Target  https://example.com
Output  esprit_runs/example-com-2026-03-03-14-32

Review Results

As vulnerabilities are discovered, they appear in real-time:

╭─ XSS-001 ──────────────────────────────────────────╮
│                                                     │
│  Reflected XSS in search parameter                  │
│  Severity  HIGH (CVSS 7.4)                          │
│  Location  /search?q=<payload>                      │
│                                                     │
│  Proof of Concept:                                  │
│  https://example.com/search?q=<script>alert(1)</script>│
│                                                     │
│  Remediation:                                       │
│  Encode user input before rendering in HTML context│
│                                                     │
╰─────────────────────────────────────────────────────╯

Full reports are saved in esprit_runs/<scan-id>/report.json

Free Trial: New accounts get free scans to try Esprit Cloud. Upgrade to Pro for unlimited scanning.

Option 2: Local Mode (Your Own LLM)

If you prefer to use your own API keys or run scans locally, you’ll need Docker installed.

Make sure Docker is installed and running before proceeding.

Connect an LLM Provider

Choose a provider and authenticate:

esprit provider login anthropic

Most providers use OAuth and open your browser for authentication. Antigravity is free and doesn’t require an account.

Use an API key directly

If you prefer environment variables over OAuth:

export ESPRIT_LLM="anthropic/claude-sonnet-4-5"
export LLM_API_KEY="sk-ant-..."
esprit scan https://example.com

Verify Docker Sandbox

Esprit automatically pulls the sandbox image on first scan, but you can pre-download it:

docker pull improdead/esprit-sandbox:latest

The sandbox image (~2GB) contains all security tools: Caido proxy, Playwright, nmap, sqlmap, nuclei, ffuf, and more.

Run Your First Scan

esprit scan https://example.com

Esprit launches a local Docker container and begins testing. You’ll see:

✓ Docker runtime initialized
✓ Sandbox ready (container: esprit-8f3a2b)
Model: anthropic/claude-sonnet-4-5

Penetration test initiated
Target  https://example.com
Output  esprit_runs/example-com-2026-03-03-14-32

Scan Modes

Choose a scan mode based on your time and coverage needs:

Quick (~5 min)
Standard (~15 min)
Deep (~30+ min)

Fast surface-level scan perfect for CI/CD pipelines:

esprit scan https://example.com -m quick

What it covers:

Common vulnerability patterns
Low-hanging fruit (SQL injection, XSS, open redirects)
Basic authentication checks
Known CVEs in detected technologies

Best for:

Pre-deployment checks
Continuous integration
Quick triage

Balanced coverage for regular security testing:

esprit scan https://example.com -m standard

What it covers:

All quick mode checks
Business logic exploration
Authentication and session management
Access control testing
Basic race condition checks

Best for:

Regular security audits
Staging environment testing
Pre-release verification

Comprehensive analysis with multi-step attack chains (default):

esprit scan https://example.com -m deep
# or simply:
esprit scan https://example.com

What it covers:

All standard mode checks
Complex business logic vulnerabilities
Multi-step attack chains
Race condition exploitation
Advanced access control bypasses
Thorough code analysis (for repos)

Best for:

Comprehensive security audits
Production readiness assessment
Compliance requirements (PCI-DSS, SOC 2)

Scanning Different Target Types

Esprit automatically adapts its testing strategy based on target type:

esprit scan https://api.example.com

How does Esprit detect target type?

Esprit analyzes the target to determine its type:

URL with http/https: Web application (black-box testing)
GitHub URL: Repository (white-box code analysis)
Local path: Codebase (white-box with optional local server testing)

For repositories and local paths, Esprit performs static code analysis and can also run a local server if detected.

Custom Testing Instructions

Guide the AI agent with custom instructions:

esprit scan https://example.com --instruction "Focus on authentication and JWT vulnerabilities"

Or load instructions from a file:

echo "Test the admin panel at /admin with default credentials" > instructions.txt
esprit scan https://example.com --instruction-file instructions.txt

Custom instructions help the agent prioritize specific attack vectors or focus on particular areas of your application.

Understanding Results

Real-Time Output

Vulnerabilities appear as they’re discovered:

╭─ SQL-INJECTION-001 ────────────────────────────────────╮
│                                                        │
│  SQL Injection in login endpoint                       │
│  Severity  CRITICAL (CVSS 9.8)                         │
│  Location  POST /api/login                             │
│                                                        │
│  Proof of Concept:                                     │
│  username: admin' OR '1'='1                            │
│  password: anything                                    │
│                                                        │
│  Database: MySQL 8.0.32                                │
│  Query: SELECT * FROM users WHERE username='admin'     │
│         OR '1'='1' AND password='anything'             │
│                                                        │
│  Impact: Complete authentication bypass                │
│                                                        │
│  Remediation:                                          │
│  Use parameterized queries or an ORM                   │
│                                                        │
╰────────────────────────────────────────────────────────╯

Saved Reports

All results are saved to esprit_runs/<scan-id>/:

esprit_runs/example-com-2026-03-03-14-32/
├── report.json          # Machine-readable vulnerability data
├── report.html          # Human-readable HTML report
├── requests/            # HTTP requests and responses
│   ├── xss-001.http
│   ├── sql-injection-001.http
│   └── ...
├── screenshots/         # Browser screenshots of findings
│   ├── xss-001.png
│   └── ...
└── logs/                # Agent execution logs
    └── agent.log

Exit Codes

esprit scan https://example.com
echo $?  # Check exit code

0 - No vulnerabilities found
2 - Vulnerabilities found
1 - Scan error or interrupted

Useful for CI/CD pipelines:

# .github/workflows/security.yml
- name: Security Scan
  run: |
    esprit scan https://staging.example.com --non-interactive
  continue-on-error: true  # Don't fail the build on vulnerabilities

Non-Interactive Mode (CI/CD)

For automated environments, disable the TUI and use JSON output:

esprit scan https://example.com --non-interactive

This mode:

Outputs plain text instead of rich TUI
Exits immediately on error
Returns appropriate exit codes for automation
Still saves full reports to esprit_runs/

name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Esprit
        run: |
          curl -fsSL https://raw.githubusercontent.com/esprit-cli/Esprit/main/scripts/install.sh | bash
          echo "$HOME/.esprit/bin" >> $GITHUB_PATH
      
      - name: Login to Esprit Cloud
        run: esprit provider login esprit
        env:
          ESPRIT_TOKEN: ${{ secrets.ESPRIT_TOKEN }}
      
      - name: Run Security Scan
        run: esprit scan https://staging.example.com --non-interactive -m quick
      
      - name: Upload Report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-report
          path: esprit_runs/

Provider Management

Check your connected providers:

esprit provider status

Output:

Provider    Status      Model
──────────────────────────────────────────────
esprit      Connected   esprit/default
anthropic   Connected   claude-sonnet-4-5
openai      Connected   gpt-5.3-codex
google      Not connected

Switch providers by logging in to a different one:

esprit provider login openai

Logout from a provider:

esprit provider logout anthropic

Troubleshooting

Scan fails with Docker error

Issue: Cannot connect to Docker daemonSolution: Ensure Docker is running:

docker info
# If not running:
sudo systemctl start docker  # Linux
# Or open Docker Desktop on macOS/Windows

No vulnerabilities found

Issue: Esprit completes but reports no vulnerabilitiesPossible reasons:

Your application is secure (good!)
The agent didn’t have enough context. Try:
- Using --instruction to guide the agent
- Running with -m deep for more thorough testing
- Providing authentication credentials for authenticated endpoints

Example:

esprit scan https://example.com -m deep \
  --instruction "Test the authenticated API using token: eyJ0eXAi..."

Scan is too slow

Issue: Scans take longer than expectedSolutions:

Use -m quick for faster but less thorough scans
Upgrade your LLM model (e.g., Claude Sonnet 4.5 is faster than Opus)
For Esprit Cloud, upgrade to a higher-tier plan
Ensure good network connectivity

esprit scan https://example.com -m quick

Rate limit errors

Issue: Rate limit exceeded from LLM providerSolutions:

Wait a few minutes and retry
Switch to Esprit Cloud (higher rate limits)
Use a different LLM provider
For OpenAI/Anthropic, upgrade your API tier

# Switch to Antigravity (free tier with generous limits)
esprit provider login antigravity
esprit scan https://example.com

Target is behind authentication

Issue: Need to test authenticated endpointsSolution: Provide credentials or session tokens:

esprit scan https://example.com \
  --instruction "Login with username: testuser, password: testpass123 before testing"

Or provide a session cookie:

esprit scan https://example.com \
  --instruction "Use session cookie: session=abc123xyz before making requests"

Next Steps

Now that you’ve run your first scan:

Scan Modes

Learn about quick, standard, and deep scanning strategies

Provider Setup

Configure LLM providers and manage authentication

Advanced Usage

Custom instructions, multi-target scans, and more

CI/CD Integration

Automate security scans in your deployment pipeline

Congratulations! You’ve completed your first Esprit security scan. Happy hunting!

Get Started

Configuration

Usage

Architecture

Vulnerability Detection

Your First Scan

Interactive Launchpad

Option 1: Esprit Cloud (Recommended)

Option 2: Local Mode (Your Own LLM)

Scan Modes

Scanning Different Target Types

Custom Testing Instructions

Understanding Results

Real-Time Output

Saved Reports

Exit Codes

Non-Interactive Mode (CI/CD)

Provider Management

Troubleshooting

Next Steps

Scan Modes

Provider Setup

Advanced Usage

CI/CD Integration

Build docs developers (and LLMs) love

Get Started

Configuration

Usage

Architecture

Vulnerability Detection

​Your First Scan

​Interactive Launchpad

​Option 1: Esprit Cloud (Recommended)

​Option 2: Local Mode (Your Own LLM)

​Scan Modes

​Scanning Different Target Types

​Custom Testing Instructions

​Understanding Results

​Real-Time Output

​Saved Reports

​Exit Codes

​Non-Interactive Mode (CI/CD)

​Provider Management

​Troubleshooting

​Next Steps

Scan Modes

Provider Setup

Advanced Usage

CI/CD Integration

Build docs developers (and LLMs) love

Your First Scan

Interactive Launchpad

Option 1: Esprit Cloud (Recommended)

Option 2: Local Mode (Your Own LLM)

Scan Modes

Scanning Different Target Types

Custom Testing Instructions

Understanding Results

Real-Time Output

Saved Reports

Exit Codes

Non-Interactive Mode (CI/CD)

Provider Management

Troubleshooting

Next Steps