Runbooks Overview¶

Runbooks are pre-configured security testing workflows that automate common scanning scenarios.

What are Runbooks?¶

Runbooks are reusable, pre-configured sets of security testing modules that execute in sequence to accomplish specific testing objectives.

Benefits: - Consistency: Same tests every time - Efficiency: No manual configuration - Best Practices: Built by experts - Reusability: Use across engagements - Automation: Schedule and repeat

Runbook Structure¶

runbook:
  name: "Web Application Security Scan"
  description: "Comprehensive web app testing"

  modules:
    - name: "subdomain_enum"
      tool: "amass"
      mode: "passive"

    - name: "port_scan"
      tool: "nmap"
      ports: "80,443,8080,8443"

    - name: "web_scan"
      tool: "nikto"
      tuning: "1,2,3"

    - name: "vuln_scan"
      tool: "nuclei"
      severity: "critical,high"

Built-in Runbooks¶

Web Application Testing¶

Web App Security Scan: - Subdomain enumeration - Port scanning - Web server fingerprinting - Content discovery - Vulnerability scanning - SSL/TLS analysis

API Security Scan: - Endpoint discovery - Authentication testing - Authorization checks - Input validation - Rate limiting tests

Network Testing¶

Network Discovery: - Host discovery - Port scanning - Service enumeration - OS fingerprinting

Full Network Scan: - Comprehensive port scan - Service version detection - Vulnerability assessment - Configuration analysis

Reconnaissance¶

Passive Reconnaissance: - OSINT gathering - Subdomain enumeration (passive) - Certificate transparency - DNS records

Active Reconnaissance: - Subdomain brute force - DNS enumeration - Port scanning - Service detection

Vulnerability Assessment¶

Quick Vulnerability Scan: - Common vulnerabilities - Critical/High severity only - Fast execution

Comprehensive Vulnerability Scan: - All vulnerability checks - All severity levels - Detailed analysis

Using Runbooks¶

Execute from Web UI¶

Steps: 1. Navigate to Attack Platform → Runbooks 2. Browse or search runbooks 3. Click on runbook 4. Click Execute 5. Configure parameters: - Target (URL, domain, IP) - Engagement - Options 6. Click Start Execution

📸 Screenshot: Runbook execution form

Execute from CLI¶

Command:

aphids-cli \
  --api-key $API_KEY \
  --runbook RUNBOOK_ID \
  --target-url https://example.com \
  --engagement ENGAGEMENT_ID

With Options:

aphids-cli \
  --api-key $API_KEY \
  --runbook web-app-scan \
  --target-url https://example.com \
  --engagement pentest-2024 \
  --verbose

Creating Custom Runbooks¶

From Web UI¶

Steps: 1. Navigate to Attack Platform → Runbooks 2. Click Create Runbook 3. Set basic info: - Name - Description - Category 4. Add modules: - Select tool - Configure options - Set order 5. Test runbook 6. Save

Module Configuration¶

Each Module Needs: - Tool: Which security tool to use - Options: Tool-specific parameters - Order: Execution sequence - Conditions: When to run (optional)

Example Module:

module:
  name: "nmap_scan"
  tool: "nmap"
  options:
    ports: "1-65535"
    scan_type: "syn"
    timing: "4"
    scripts: "default,vuln"

Module Dependencies¶

Sequential Execution: - Modules run in order - Each waits for previous - Results passed forward

Conditional Execution:

module:
  name: "web_scan"
  tool: "nikto"
  condition: "port_80_open OR port_443_open"

Runbook Categories¶

By Purpose¶

Reconnaissance: - Information gathering - Asset discovery - Technology identification

Scanning: - Port scanning - Service detection - Vulnerability scanning

Exploitation (if authorized): - Proof of concept - Validation testing

Reporting: - Data collection - Evidence gathering

By Target Type¶

Web Applications: - Web app scanning - API testing - Content discovery

Networks: - Network discovery - Port scanning - Service enumeration

Cloud: - Cloud asset discovery - Configuration review - Compliance checking

Runbook Parameters¶

Required Parameters¶

All Runbooks Need: - Target: What to scan (URL, domain, IP, range) - Engagement: Which engagement to associate with

Optional Parameters¶

Common Options: - Timing: Scan speed/stealth - Depth: How thorough - Scope: What to include/exclude - Output: Verbosity level

Example:

parameters:
  target: "example.com"
  engagement: "pentest-2024"
  timing: "polite"  # Slow and stealthy
  depth: "comprehensive"
  exclude: ["staging.example.com"]

Monitoring Execution¶

Real-Time Monitoring¶

View Progress: 1. Navigate to Automation Engine → Scan Executions 2. Find your execution 3. Click to view details 4. Monitor module progress

Execution Details: - Overall status - Current module - Modules completed - Modules remaining - Estimated completion - Logs

Execution Logs¶

Log Levels: - INFO: Normal operations - WARNING: Issues encountered - ERROR: Failures - DEBUG: Detailed information

View Logs: 1. Open scan execution 2. Click Logs tab 3. Filter by level 4. Search logs 5. Download logs

Runbook Results¶

Viewing Results¶

After Completion: 1. Navigate to execution 2. Click Results tab 3. View discovered assets 4. Check vulnerabilities 5. Review raw output

Result Sections: - Summary: High-level stats - Assets: Discovered assets - Vulnerabilities: Found issues - Raw Output: Tool output

Exporting Results¶

Export Options: - PDF: Report format - JSON: API format - CSV: Spreadsheet - HTML: Web format

Export Process: 1. Open execution results 2. Click Export 3. Select format 4. Configure options 5. Download

Scheduling Runbooks¶

One-Time Execution¶

Immediate: - Execute now - Manual trigger

Scheduled: - Set future date/time - One-time execution

Recurring Execution¶

Schedule Options: - Daily - Weekly - Monthly - Custom cron

Configuration: 1. Select runbook 2. Click Schedule 3. Set frequency 4. Set time 5. Enable notifications 6. Save schedule

Example Schedule:

schedule:
  frequency: "weekly"
  day: "Sunday"
  time: "02:00"
  timezone: "UTC"
  enabled: true

Best Practices¶

Runbook Design¶

✅ Single Purpose: One objective per runbook
✅ Logical Order: Sequence modules properly
✅ Error Handling: Plan for failures
✅ Documentation: Clear descriptions
✅ Testing: Validate before production

Execution¶

✅ Test First: Run on test targets
✅ Monitor: Watch execution progress
✅ Review Results: Validate findings
✅ Document: Add notes and context
✅ Follow Up: Act on findings

Maintenance¶

✅ Update Regularly: Keep modules current
✅ Review Performance: Optimize slow runbooks
✅ Clean Up: Archive unused runbooks
✅ Version Control: Track changes
✅ Share: Collaborate with team

Troubleshooting¶

Runbook Won't Start¶

Check: - Valid target specified - Engagement selected - Permissions - Resource availability

Runbook Fails¶

Common Causes: - Target unreachable - Network restrictions - Invalid parameters - Tool errors

Solutions: - Check target accessibility - Review firewall rules - Validate parameters - Check tool logs

Incomplete Results¶

Causes: - Scan timeout - Network issues - Target blocking

Solutions: - Increase timeout - Check connectivity - Adjust scan parameters - Use stealth mode

Related: Creating Runbooks | Attack Trees | Scan Executions