dochia fuzz

The fuzz command runs continuous fuzzing based on random mutators, rather than pre-defined playbooks. This is ideal for discovering unexpected vulnerabilities through randomized input generation.

Basic Usage

dochia fuzz -c <contract> -s <server> -p <path> [OPTIONS]

Required Parameters

-c, --contract=<contract> - Path to your OpenAPI specification file
-s, --server=<server> - Base URL of the API service to test
-p, --path=<path> - Specific API path for continuous fuzzing
-X, --http-method=<http-method> - The HTTP method. Default: POST

⚠️ CRITICAL REQUIREMENT: You must provide at least one stop condition (--stop-XX) and at least one match condition (--match-XX) for the fuzzing command to execute. Fuzzing cannot run without these parameters.

Common Options

-h, --help - Show help message
-V, --version - Show version information
-o, --output=<output> - Output directory for test results

Quick Examples

# Basic fuzzing for 100 seconds with match condition
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-time-in-sec 100 \
  --match-response-codes 500

# Fuzz with specific HTTP method and match 500 errors
dochia fuzz -c api.yml -s http://localhost:8080 -p /users -X POST \
  --match-response-codes 500 \
  --stop-after-errors 10

# Stop after finding 10 errors with input reflection matching
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-errors 10 \
  --match-input

Key Differences from `dochia test`

Aspect	`dochia test`	`dochia fuzz`
Approach	Pre-defined playbooks	Random mutators
Coverage	Comprehensive, systematic	Continuous, randomized
Duration	Fixed (based on playbooks)	Configurable (time/errors/mutations)
Use Case	Complete API validation	Vulnerability discovery
Scope	Multiple paths	Single path focus

Target Configuration

Path and Method Selection

# Specific path and HTTP method
dochia fuzz -c api.yml -s http://localhost:8080 -p /api/users -X POST \
  --stop-after-time-in-sec 300 \
  --match-response-codes 500

# Default method is POST
dochia fuzz -c api.yml -s http://localhost:8080 -p /api/users \
  --stop-after-errors 5 \
  --match-input

Schema Handling

# Handle oneOf/anyOf discriminators
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --schema-discriminator "type=user" \
  --stop-after-mutations 500 \
  --match-response-codes 500

# Custom content type
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --content-type "application/vnd.api+json" \
  --stop-after-time-in-sec 600 \
  --match-input

Stop Conditions

Control when fuzzing stops using these mutually exclusive options:

Time-based Stopping

# Run for 5 minutes (300 seconds)
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-time-in-sec 300 \
  --match-response-codes 500

# Run for 1 hour
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-time-in-sec 3600 \
  --match-input

Error-based Stopping

# Stop after finding 5 errors
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-errors 5 \
  --match-response-codes 500

# Stop after first error
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-errors 1 \
  --match-input

Mutation-based Stopping

# Stop after 1000 test cases
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-mutations 1000 \
  --match-response-codes 500

# Stop after 100 mutations
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --stop-after-mutations 100 \
  --match-input

Match Conditions

Define what constitutes an "error" during fuzzing:

Response Code Matching

# Match 5XX server errors
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-response-codes "500,502,503" \
  --stop-after-errors 10

# Match client and server errors
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-response-codes "400,401,403,500" \
  --stop-after-time-in-sec 600

Response Content Matching

# Match by response size
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-response-size "0,1024" \
  --stop-after-mutations 500

# Match by word count
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-response-words "0,10,100" \
  --stop-after-errors 5

# Match by line count
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-response-lines "1,5" \
  --stop-after-time-in-sec 300

# Match by regex pattern
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-response-regex "error|exception|stack" \
  --stop-after-errors 10

Input Reflection Matching

# Match when fuzzed input appears in response (potential XSS/injection)
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --match-input \
  --stop-after-errors 5

API Configuration

Connection Settings

Option	Description	Default
`--connection-timeout=<timeout>`	Connection timeout (seconds)	10
`--read-timeout=<timeout>`	Response read timeout (seconds)	10
`--write-timeout=<timeout>`	Request write timeout (seconds)	10
`--max-requests-per-minute=<max>`	Rate limiting	10000
`--user-agent=<user-agent>`	Custom User-Agent	dochia/version

Authentication

Basic Authentication

# Username/password
dochia fuzz -c api.yml -s https://api.example.com -p /users \
  --user "username:password" \
  --stop-after-time-in-sec 300 \
  --match-response-codes 500

Header-based Authentication

# Single authentication header
dochia fuzz -c api.yml -s https://api.example.com -p /users \
  --header "Authorization=Bearer token123" \
  --stop-after-errors 5 \
  --match-response-codes 500

# Multiple headers
dochia fuzz -c api.yml -s https://api.example.com -p /users \
  --header "Authorization=Bearer token123" \
  --header "X-API-Key=key456" \
  --stop-after-time-in-sec 600 \
  --match-input

File-based Headers

# YAML file with headers
dochia fuzz -c api.yml -s https://api.example.com -p /users \
  --headers auth-headers.yml \
  --stop-after-mutations 500 \
  --match-response-codes 500

Dynamic Authentication

# Refresh tokens periodically
dochia fuzz -c api.yml -s https://api.example.com -p /users \
  --auth-refresh 1800 \
  --auth-refresh-script ./refresh-token.sh \
  --stop-after-time-in-sec 3600 \
  --match-response-codes 500

SSL/TLS and Proxy

# SSL client certificates
dochia fuzz -c api.yml -s https://secure.api.com -p /users \
  --ssl-keystore client.p12 \
  --ssl-keystore-password "$KEYSTORE_PASS" \
  --stop-after-time-in-sec 900 \
  --match-response-codes 500

# Proxy configuration
dochia fuzz -c api.yml -s https://api.example.com -p /users \
  --proxy http://proxy.company.com:8080 \
  --stop-after-errors 10 \
  --match-input

Data Configuration

URL Parameters

# Replace path parameters
dochia fuzz -c api.yml -s http://localhost:8080 -p /users/{id} \
  -U "id=123" \
  --stop-after-mutations 300 \
  --match-response-codes 500

# Multiple parameters
dochia fuzz -c api.yml -s http://localhost:8080 -p /users/{userId}/orders/{orderId} \
  --url-params "userId:123,orderId:456" \
  --stop-after-time-in-sec 600 \
  --match-input

Query Parameters

# Global query parameters
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  -Q "api_key=secret123" \
  --stop-after-errors 5 \
  --match-response-codes 500

# File-based query parameters
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --query-params query-params.yml \
  --stop-after-time-in-sec 300 \
  --match-input

Reference Data

# Required field values
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  -R "tenantId=company123" \
  --stop-after-mutations 500 \
  --match-response-codes 500

# File-based reference data
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --reference-data reference.yml \
  --stop-after-errors 10 \
  --match-input

Mutator Configuration

Built-in Mutators

# List available mutators
dochia list --mutators -c api.yml

Custom Mutators

# Use custom mutators from directory
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --mutators ./custom-mutators/ \
  --stop-after-time-in-sec 1800 \
  --match-response-codes 500

Custom mutators allow you to define specific fuzzing strategies beyond the built-in random mutations.

Error Detection

Error Keywords

# Detect error information leaks
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --error-keywords error-keywords.txt \
  --stop-after-errors 5 \
  --match-response-regex "error|exception|stack"

error-keywords.txt example:

Database connection failed
Authentication failed
Internal server error
Stack trace

Reporting Options

Output Configuration

# Custom output directory
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  -o ./fuzz-results \
  --stop-after-time-in-sec 600 \
  --match-response-codes 500

# Timestamped reports
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --timestamp-reports \
  --stop-after-errors 10 \
  --match-input

# Different report format
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --output-format "HTML_ONLY" \
  --stop-after-mutations 500 \
  --match-response-codes 500

Console Output

# Verbose logging
dochia fuzz -c api.yml -s http://localhost:8080 -p /users -vvv \
  --stop-after-time-in-sec 300 \
  --match-response-codes 500

# Show progress
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --print-progress \
  --stop-after-errors 5 \
  --match-input

# Mask sensitive headers
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --mask-headers "Authorization,X-API-Key" \
  --stop-after-mutations 300 \
  --match-response-codes 500

Performance Monitoring

# Response time limits
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --max-response-time 5000 \
  --stop-after-time-in-sec 900 \
  --match-response-codes 500

# Execution statistics
dochia fuzz -c api.yml -s http://localhost:8080 -p /users \
  --execution-stats \
  --detailed-execution-stats \
  --stop-after-mutations 1000 \
  --match-input

Practical Examples

Basic Vulnerability Discovery

# Find server errors in user endpoint
dochia fuzz \
  -c user-api.yml \
  -s http://localhost:8080 \
  -p /api/v1/users \
  -X POST \
  --mc "500,502,503" \
  --st 300 \
  -H "Content-Type=application/json"

Input Injection Testing

# Test for input reflection (XSS, injection)
dochia fuzz \
  -c api.yml \
  -s https://webapp.example.com \
  -p /api/search \
  -X GET \
  --mi \
  --mr "script|javascript|<|>" \
  --se 5 \
  -H "Authorization=Bearer $TOKEN"

Rate Limiting and DoS Testing

# Test rate limiting behavior
dochia fuzz \
  -c api.yml \
  -s http://localhost:8080 \
  -p /api/upload \
  -X POST \
  --mc "429,503" \
  --max-requests-per-minute 1000 \
  --sm 500 \
  --execution-stats

Authentication Bypass Testing

# Test authentication with various payloads
dochia fuzz \
  -c secure-api.yml \
  -s https://secure.api.com \
  -p /api/admin/users \
  -X POST \
  --mc "200,201" \
  --se 1 \
  -H "Authorization=Bearer invalid-token" \
  --error-keywords auth-errors.txt

Long-running Security Testing

# Continuous security testing
dochia fuzz \
  -c production-api.yml \
  -s https://api.production.com \
  -p /api/v2/payments \
  -X POST \
  --mc "500,502,503" \
  --mr "error|exception|trace" \
  --mi \
  --st 7200 \
  --max-requests-per-minute 60 \
  --timestamp-reports \
  -o ./security-fuzz-results \
  -H "Authorization=Bearer $PROD_TOKEN"

Best Practices

Match Condition Strategy

Start Broad: Begin with --mc "500" to catch obvious server errors
Add Specificity: Include --mi for injection testing
Use Regex: Add --mr for custom error patterns
Combine Conditions: Use multiple match options together

Stop Condition Strategy

Development: Use --se 5 to stop after few errors
Testing: Use --st 300 for time-boxed testing
Continuous: Use --sm 10000 for extensive fuzzing
Production: Use conservative time limits with rate limiting

Performance Considerations

Use --max-requests-per-minute to avoid overwhelming APIs
Set appropriate timeouts for slow endpoints
Use --timestamp-reports for organized results
Monitor with --execution-stats for performance insights

Exit Codes

Code	Meaning
`0`	Successful execution
`191`	Usage error (incorrect arguments)
`192`	Internal execution error
`ERR`	Number of errors found (e.g., exit code `3` means 3 errors)

dochia test - Systematic testing with playbooks
dochia list - List available paths and endpoints
dochia replay - Replay specific test cases
dochia info - System information

Basic Usage​

Required Parameters​

Common Options​

Quick Examples​

Key Differences from dochia test​

Target Configuration​

Path and Method Selection​

Schema Handling​

Stop Conditions​

Time-based Stopping​

Error-based Stopping​

Mutation-based Stopping​

Match Conditions​

Response Code Matching​

Response Content Matching​

Input Reflection Matching​

API Configuration​

Connection Settings​

Authentication​

Basic Authentication​

Header-based Authentication​

File-based Headers​

Dynamic Authentication​

SSL/TLS and Proxy​

Data Configuration​

URL Parameters​

Query Parameters​

Reference Data​

Mutator Configuration​

Built-in Mutators​

Custom Mutators​

Error Detection​

Error Keywords​

Reporting Options​

Output Configuration​

Console Output​

Performance Monitoring​

Practical Examples​

Basic Vulnerability Discovery​

Input Injection Testing​

Rate Limiting and DoS Testing​

Authentication Bypass Testing​

Long-running Security Testing​

Best Practices​

Match Condition Strategy​

Stop Condition Strategy​

Performance Considerations​

Exit Codes​

Related Commands​

See Also​