Custom Instructions

Custom instructions allow you to guide Esprit’s testing strategy, focus on specific vulnerability types, or provide context about your application.

Overview

From esprit/interface/main.py:1090-1091 and esprit/interface/cli.py:74, custom instructions are passed to the scan configuration as user_instructions:

scan_config = {
    "scan_id": args.run_name,
    "targets": args.targets_info,
    "user_instructions": args.instruction or "",
    "run_name": args.run_name,
}

Using —instruction

Provide instructions directly on the command line:

esprit scan https://example.com --instruction "Focus on authentication and session management"

esprit scan https://api.example.com \
  --instruction "Test for SQL injection in all API endpoints"

Short flag: -i is not available. Use the full --instruction flag.

Using —instruction-file

For complex instructions, use a file:

esprit scan https://example.com --instruction-file instructions.txt

Creating an Instruction File

Create a text file with your instructions:

Test the following features:

1. Authentication System
   - Focus on OAuth 2.0 implementation
   - Test for token leakage and CSRF
   - Verify refresh token rotation

2. API Endpoints
   - All endpoints under /api/v2/*
   - Test for IDOR vulnerabilities
   - Check rate limiting on sensitive operations

3. Known Issues
   - Previous scan found XSS in search - verify the patch
   - Check if SQL injection in /users/:id is fixed

Avoid:
   - Do not test the legacy /api/v1/* endpoints
   - Skip file upload tests (already pentested)

File Format

From esprit/interface/main.py:1165-1171, instruction files:

Can be any text format
Are read with UTF-8 encoding
Have whitespace stripped
Must exist and be readable

if hasattr(args, "instruction_file") and args.instruction_file:
    instruction_path = Path(args.instruction_file)
    try:
        with instruction_path.open(encoding="utf-8") as f:
            args.instruction = f.read().strip()
    except Exception as e:
        parser.error(f"Failed to read instruction file: {e}")

You cannot use both --instruction and --instruction-file together. From esprit/interface/main.py:1161-1163:

if args.instruction and args.instruction_file:
    parser.error("Cannot specify both --instruction and --instruction-file.")

Instruction Strategies

Vulnerability-Focused
Feature-Focused
Context-Aware
Constraint-Based

Direct Esprit to focus on specific vulnerability types:

esprit scan https://example.com --instruction "
Focus exclusively on:
1. SQL injection in all form inputs and URL parameters
2. Cross-site scripting (stored and reflected)
3. Authentication bypass techniques
4. Insecure direct object references

Test every input field with:
- SQL injection payloads (union, boolean-based, time-based)
- XSS payloads (script tags, event handlers, encoded variants)
- Parameter manipulation for IDOR
"

Best for: Targeted security assessments, regression testing

Guide testing toward specific application features:

esprit scan github.com/user/repo --instruction "
Focus on the user management system:

Code locations:
- src/controllers/UserController.js
- src/models/User.js
- src/routes/api/users.js

Test scenarios:
- User registration and validation
- Password reset flow
- Email verification process
- Profile update functionality
- Account deletion and data handling

Look for:
- Race conditions in concurrent requests
- IDOR in user profile access
- Mass assignment vulnerabilities
- Email takeover vectors
"

Best for: Component-specific testing, feature releases

Provide application context for smarter testing:

esprit scan ./my-app --instruction "
Application Context:
- Framework: Ruby on Rails 7.x
- Database: PostgreSQL 15
- Authentication: Devise gem
- Authorization: Pundit gem
- File uploads: ActiveStorage with S3 backend
- Background jobs: Sidekiq with Redis

Known Security Controls:
- CSRF protection enabled globally
- SQL prepared statements via ActiveRecord
- Content Security Policy configured
- Rate limiting on API endpoints

Areas of Concern:
- Custom SQL queries in reports module
- File upload validation in attachments
- Admin panel authorization checks
- API authentication (JWT tokens)
"

Best for: Whitebox scans, codebase-specific testing

Set boundaries and constraints:

esprit scan https://example.com --instruction "
Testing Constraints:

In Scope:
- All endpoints under /api/v2/*
- Public-facing web pages
- Authentication flows

Out of Scope:
- /api/v1/* (deprecated, already tested)
- /admin/legacy/* (no longer maintained)
- Third-party integrations
- Load testing and DoS

Rules:
- Do not create more than 5 test accounts
- Avoid testing with amounts > $1.00
- Do not upload files larger than 1MB
- Respect rate limits
"

Best for: Production testing, compliance requirements

Example Use Cases

Pre-Release Security Check

esprit scan github.com/company/api-server \
  --scan-mode standard \
  --instruction "Focus on changes since last release (v2.5.0). \
Review git commits from the past 2 weeks. \
Test new authentication middleware and updated payment endpoints."

Compliance Audit

esprit scan https://app.example.com \
  --scan-mode deep \
  --instruction-file pci-dss-requirements.txt

Where pci-dss-requirements.txt contains:

PCI DSS 4.0 Security Assessment

Requirement 6.2: Protect against vulnerabilities
- Test for SQL injection (Requirement 6.2.4.1)
- Test for XSS (Requirement 6.2.4.2)
- Test for CSRF (Requirement 6.2.4.3)
- Test for insecure deserialization

Requirement 8.3: Authentication
- Multi-factor authentication implementation
- Password complexity enforcement
- Account lockout mechanisms
- Session management security

Requirement 10.2: Logging
- Verify all authentication attempts are logged
- Check that all access to cardholder data is logged

Reporting:
- Map findings to specific PCI DSS requirements
- Include CVSS scores
- Provide evidence of testing

Bug Bounty Recon

esprit scan example.com \
  --scan-mode quick \
  --instruction "Quick recon for bug bounty. \
Focus on high-severity issues: auth bypass, RCE, SQLi, SSRF. \
Skip low-severity info disclosure. \
Only report with working PoC."

Regression Testing

esprit scan https://staging.example.com \
  --instruction "Regression test for ticket SEC-1234. \
Verify that XSS in search functionality is fixed. \
Test payload: <script>alert('XSS')</script> \
Also test encoded variants and attribute injection."

Combining with Scan Modes

Instructions work with all scan modes:

esprit scan https://example.com \
  -m quick \
  --instruction "Focus on authentication only"

Instructions refine the scan strategy but don’t override the mode’s core methodology. A quick scan with instructions will still be time-boxed.

Best Practices

Be specific and actionable

Good:

Test SQL injection in:
- /api/users/:id endpoint (id parameter)
- /search?q= endpoint (q parameter)
- Login form username and password fields

Bad:

Test for SQL injection

Provide context when available

Help Esprit make smarter decisions:

Context: This is a Node.js Express app using MongoDB.
The /api/users endpoint uses raw MongoDB queries without sanitization.
Previous testing found NoSQL injection in the username filter.

Set clear boundaries

Define what to test and what to avoid:

In Scope:
- All /api/v2/* endpoints
- Public web pages

Out of Scope:
- /api/v1/* (legacy)
- /admin/legacy/*
- Load/DoS testing

Use instruction files for complex guidance

When instructions exceed a few lines, use --instruction-file:

Easier to version control
Reusable across scans
Better formatting and organization
Can include detailed checklists

Reference specific code locations (whitebox)

For repository scans, point to specific files:

Review these files for security issues:
- src/auth/login.py (authentication logic)
- src/api/users.py (user CRUD operations)
- src/middleware/auth.js (authorization middleware)

Terminal Output

When custom instructions are provided, they’re incorporated into the scan:

┌─────────────────────────────────────────────────────────────┐
│ ESPRIT                                                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Penetration test initiated                                 │
│                                                             │
│  Target       https://example.com                           │
│  Mode         Standard                                      │
│  Instructions Focus on authentication and session mgmt      │
│  Output       esprit_runs/example-com_a3f2                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Get Started

Configuration

Usage

Architecture

Vulnerability Detection

Custom Instructions

Overview

Using —instruction

Using —instruction-file

Creating an Instruction File

File Format

Instruction Strategies

Example Use Cases

Pre-Release Security Check

Compliance Audit

Bug Bounty Recon

Regression Testing

Combining with Scan Modes

Best Practices

Terminal Output

Next Steps

Scan Modes

Non-Interactive Mode

Build docs developers (and LLMs) love

Get Started

Configuration

Usage

Architecture

Vulnerability Detection

​Overview

​Using —instruction

​Using —instruction-file

​Creating an Instruction File

​File Format

​Instruction Strategies

​Example Use Cases

​Pre-Release Security Check

​Compliance Audit

​Bug Bounty Recon

​Regression Testing

​Combining with Scan Modes

​Best Practices

​Terminal Output

​Next Steps

Scan Modes

Non-Interactive Mode

Build docs developers (and LLMs) love

Overview

Using —instruction

Using —instruction-file

Creating an Instruction File

File Format

Instruction Strategies

Example Use Cases

Pre-Release Security Check

Compliance Audit

Bug Bounty Recon

Regression Testing

Combining with Scan Modes

Best Practices

Terminal Output

Next Steps