Skip to main content

Playbooks Overview

Dochia uses playbooks to systematically test different aspects of your API. Each playbook represents a specific testing strategy designed to uncover potential vulnerabilities, edge cases, or implementation issues.

What are Playbooks?​

Playbooks are automated test scenarios that:

  • Target specific types of vulnerabilities or edge cases
  • Generate test data based on your OpenAPI specification
  • Send requests with intentionally crafted payloads
  • Analyze responses to identify potential issues

Dochia includes over 100 built-in playbooks organized into three main categories.

Playbook Categories​

Field Playbooks (72 playbooks)​

Field playbooks focus on testing individual request fields by manipulating their values in various ways.

Boundary Testing​

  • String Boundaries: Test minLength/maxLength constraints
  • Numeric Boundaries: Test minimum/maximum values for integers and decimals
  • Exact Values: Send values that match exact boundary conditions

Data Type Validation​

  • Type Confusion: Send strings to numeric fields, numbers to string fields
  • Format Validation: Test string formats (email, date-time, UUID, etc.)
  • Enum Validation: Test invalid enum values and case sensitivity

Unicode and Character Testing​

  • Emoji Handling: Single and multi-codepoint emojis in various positions
  • Unicode Edge Cases: Abugidas, Hangul fillers, bidirectional overrides
  • Special Characters: Zero-width characters, Zalgo text, control characters

Size and Structure Testing​

  • Large Values: Very large strings (40,000+ characters) and numbers
  • Empty Values: Empty strings, null values, missing fields
  • Array/Object Manipulation: Replace arrays with primitives, objects with arrays

Advanced Field Testing​

  • Mass Assignment: Test additional properties in objects
  • Duplicate Keys: Test JSON parsing with duplicate field names
  • Field Removal: Systematically remove required and optional fields

Header Playbooks (29 playbooks)​

Header playbooks test HTTP header handling and security.

Header Manipulation​

  • Header Injection: CRLF injection, special characters in headers
  • Header Removal: Remove required headers systematically
  • Duplicate Headers: Send duplicate header names

Content Negotiation​

  • Accept Headers: Test unsupported media types, dummy values
  • Content-Type: Test invalid and unsupported content types
  • Content-Length: Test invalid length values

Security Headers​

  • Security Best Practices: Check for security headers (CSP, X-Frame-Options)
  • Header Validation: Test header value constraints

Load Testing​

  • Large Header Count: Send thousands of random headers
  • Large Header Values: Test very large header values

Body Playbooks (25 playbooks)​

Body playbooks test request body handling and overall API behavior.

Authentication Testing​

  • Bypass Authentication: Test endpoints without required auth headers
  • Resource Access: Verify deleted resources are inaccessible

HTTP Method Testing​

  • Undocumented Methods: Test methods not in your OpenAPI spec
  • Non-REST Methods: Test WebDAV and other non-REST HTTP methods
  • Custom Methods: Test hypothetical HTTP methods

Body Structure Testing​

  • Malformed JSON: Send invalid JSON syntax
  • Empty Bodies: Test empty strings, null bodies, empty arrays/objects
  • Random Bodies: Send random data types as request bodies

Happy Path Testing​

  • Complete Requests: Send properly populated requests
  • Example Values: Use examples from your OpenAPI specification

Using Playbooks​

Run All Playbooks​

# Run all available playbooks
dochia test -c api.yml -s https://api.example.com

Run Specific Playbooks​

# Run only boundary testing playbooks
dochia test -c api.yml -s https://api.example.com \
  --playbooks "StringFieldsLeftBoundary,StringFieldsRightBoundary,IntegerFieldsLeftBoundary"

# Run security-focused playbooks
dochia test -c api.yml -s https://api.example.com \
  --playbooks "BypassAuthentication,CheckSecurityHeaders,DummyAcceptHeaders"

Skip Specific Playbooks​

# Skip performance-intensive playbooks
dochia test -c api.yml -s https://api.example.com \
  --skip-playbooks "VeryLargeStrings,LargeNumberOfRandomHeaders"

Fuzzing vs Playbooks​

Dochia offers two main testing approaches:

Playbooks (dochia test)​

  • Systematic: Each playbook tests a specific scenario
  • Predictable: Known test cases with expected behaviors
  • Comprehensive: Covers common vulnerabilities and edge cases
  • Organized: Categorized by testing focus (fields, headers, body)

Fuzzing (dochia fuzz)​

  • Random: Uses mutators to generate unexpected inputs
  • Unpredictable: May discover unknown edge cases
  • Exploratory: Good for finding unusual bugs
  • Mutator-based: Uses 30+ mutators to transform valid data

For more details on fuzzing, see Fuzzing Overview.

Playbook Selection Strategy​

Development Environment​

# Focus on core functionality and common issues
dochia test -c api.yml -s http://localhost:8080 \
  --playbooks "HappyPath,NullValuesInFields,EmptyStringsInFields,StringFormatValidation"

Staging Environment​

# Comprehensive testing before production
dochia test -c api.yml -s https://staging-api.example.com \
  --skip-playbooks "VeryLargeStrings,LargeNumberOfRandomHeaders"

Security Testing​

# Focus on security-related playbooks
dochia test -c api.yml -s https://api.example.com \
  --playbooks "BypassAuthentication,CheckSecurityHeaders,MalformedJson,RandomDummyInvalidJsonBody"

Performance Testing​

# Test with large payloads and high load
dochia test -c api.yml -s https://api.example.com \
  --playbooks "VeryLargeStrings,LargeNumberOfRandomHeaders,OverflowArraySize"

Understanding Playbook Results​

Each playbook execution provides:

  • Test Description: What the playbook is testing
  • Request Details: The exact payload sent
  • Response Analysis: Whether the response was expected
  • Issue Classification: Severity and type of any issues found

Best Practices​

  1. Start Small: Begin with core playbooks like HappyPath and basic validation
  2. Incremental Testing: Gradually add more playbooks as your API matures
  3. Environment-Specific: Use different playbook sets for different environments
  4. Regular Execution: Run playbooks as part of your CI/CD pipeline
  5. Review Results: Analyze failed tests to improve your API implementation

See Also​