Scan Quality & Debugging¶
Overview¶
Scan quality monitoring provides instant visibility into scan execution health and failure diagnostics. When scans fail or encounter issues, detailed feedback is automatically generated to enable rapid troubleshooting and resolution.
Historically, scan failures required extensive log analysis to identify root causes. This capability delivers actionable diagnostics directly within the platform, significantly reducing investigation time and improving operational efficiency.
Key Capabilities¶
Immediate Failure Detection¶
Failed scan profiles are immediately identified and surfaced, enabling prioritization of troubleshooting efforts and minimization of security coverage gaps.
Diagnostic Information¶
Detailed failure information is provided for each scan issue, including:
- Specific problem codes identifying the failure type
- Contextual error messages describing the root cause
- Direct links to relevant event logs for in-depth investigation
- Actionable remediation guidance where applicable
Multiple Access Methods¶
Scan diagnostics are accessible through:
- Escape Platform UI: Failure details displayed on summary pages and as alerts within scan profile lists
- Public API: Programmatic access via the
GET /profiles/problemsendpoint for integration with monitoring and alerting systems
Accessing Scan Diagnostics¶
Via Platform UI¶
Scan problems are displayed in two locations:
- Profile Summary Page: Comprehensive failure information shown at the top of individual profile pages
- Profile List View: Alert indicators displayed alongside affected scan profiles
Via API¶
Scan diagnostics can be retrieved programmatically:
The API response includes problem codes, messages, and associated metadata for each detected issue.
Automated Notifications¶
Coming Soon
Workflow-based notifications for specific scan failures will be available soon. This capability will enable automatic alerts when scans encounter issues, further streamlining the debugging process.
Problem Code Reference¶
The following table catalogs all scan problem codes as of October 2024. Each problem code represents a specific failure scenario that may be encountered during scan execution.
Private Location Issues¶
| Problem Code | Description | Common Causes |
|---|---|---|
| Proxy unreachable or target host down | API endpoint cannot be reached through configured proxy or directly | Private location offline; Network connectivity issues; Target service unavailable; Incorrect proxy configuration |
| No available locations | No locations with valid proxy configuration found | All private locations offline; Proxy configuration invalid; Direct connections disabled without alternative |
| No locations configured | No public or private locations configured for validation | Missing location assignment; Location configuration not saved |
| Private location unreachable | Configured private location cannot be contacted | Private location service down; Network partition; Invalid location configuration |
| No reachable locations found | None of the configured locations can reach the target | All locations offline; Target service unreachable from all locations; Network restrictions blocking access |
Authentication Issues¶
| Problem Code | Description | Common Causes |
|---|---|---|
| Authentication failure | Authentication process encountered errors | Invalid credentials; Authentication endpoint unavailable; Token generation failure; Session creation failed |
| Authentication configuration error | Authentication preset or credential format invalid | Malformed authentication configuration; Invalid credential syntax; Incompatible authentication method |
| Failed to run scanner - Authentication Error | Scanner cannot proceed due to authentication issues | Feature flag not enabled; Multiple main users configured (frontend); No main user selected (frontend); Context creation failed after retries |
| Authentication failed | User-specific authentication failed | Invalid username or password; Expired credentials; User account locked; MFA requirement not satisfied |
| Authentication processing failed | Error occurred while processing authentication configuration | Configuration parsing error; Incompatible authentication method; Missing required parameters |
| Unable to create authenticated context | Authenticated browser context cannot be established | Session cookie issues; Authentication state not preserved; Browser automation failure |
Configuration Recommendations¶
| Problem Code | Description | Recommended Actions |
|---|---|---|
| Server-side rate limit detected | Target API rate limiting detected during scan | Whitelist Escape IP addresses; Reduce scan rate limit configuration; Coordinate scan timing with API team |
| Scope Manager - Invalid regex pattern | URL pattern in scope configuration invalid | Validate regex syntax; Test pattern against expected URLs; Review scope configuration documentation |
| All routes start with same prefix as base URL | Schema routes redundantly include base URL prefix | Update schema to use relative paths; Verify base URL configuration; Contact API provider for corrected schema |
| High rate of 401/403 responses detected | Significant percentage of requests return authorization errors | Configure user with broader permissions; Verify authentication scope; Review API access control configuration |
| High rate of 5xx server errors detected | Target API returning frequent server errors | Investigate API stability; Review API logs for errors; Consider postponing scan until API stabilized |
| Invalid rate-limit configuration | Configured requests per second value invalid | Update rate limit to valid value; Review rate limit configuration documentation |
Schema Validation Issues¶
| Problem Code | Description | Common Causes |
|---|---|---|
| Invalid GraphQL schema | GraphQL schema cannot be parsed or validated | Syntax errors in schema definition; Unsupported GraphQL features; Schema structure violations |
| Invalid OpenAPI schema | OpenAPI specification cannot be parsed | Invalid JSON/YAML syntax; Missing required fields; Schema specification violations; Unsupported OpenAPI version |
Unreachable Asset Issues¶
| Problem Code | Description | Common Causes |
|---|---|---|
| Asset validation failed | Asset cannot be reached from any configured location | Incorrect URL; Service unavailable; Network restrictions; DNS resolution failure |
| No URL provided | Scan configuration missing target URL | Incomplete scan configuration; URL field left empty |
| Schema not fetchable | API schema document cannot be retrieved | Schema URL incorrect; Schema endpoint requires authentication; Schema file not accessible |
| Service not reachable | Target service URL cannot be accessed | Service offline; Hostname resolution failure; Port closed or filtered; SSL/TLS certificate issues |
Timeout Issues¶
| Problem Code | Description | Recommended Actions |
|---|---|---|
| Scan duration limit reached | Scan exceeded maximum execution time | Split large API specs into smaller profiles; Increase parallel worker count; Remove redundant or unused endpoints; Review and optimize scan configuration |
Security Controls¶
| Problem Code | Description | Recommended Actions |
|---|---|---|
| Captcha detected during authentication | CAPTCHA challenge encountered during login | Contact support for CAPTCHA bypass options; Configure private location with CAPTCHA solving; Implement authentication via API tokens |
| Cloudflare block detected during authentication | Cloudflare WAF blocking authentication attempts | Whitelist Escape IP addresses in Cloudflare; Configure private location behind WAF; Adjust Cloudflare security settings |
| Blocked by Cloudflare | Cloudflare WAF blocking scan traffic | Add Escape IPs to Cloudflare allowlist; Configure private location in same network as target; Reduce scan aggressiveness; Review Cloudflare security rules |
Troubleshooting Best Practices¶
Systematic Diagnosis¶
- Review Problem Codes: Examine specific problem codes reported for each failed scan
- Check Event Logs: Follow diagnostic links to detailed event logs for context
- Verify Configuration: Confirm scan configuration matches target environment requirements
- Test Connectivity: Validate network connectivity and service availability
- Review Credentials: Ensure authentication credentials remain valid and have sufficient permissions
Common Resolution Paths¶
Connection Failures¶
- Verify target service availability using external monitoring tools
- Confirm DNS resolution and network routing
- Check private location health and connectivity
- Review firewall and security group configurations
Authentication Failures¶
- Validate credentials against target environment
- Confirm authentication method compatibility
- Review token expiration and refresh mechanisms
- Test authentication flow manually to identify issues
Configuration Issues¶
- Compare scan configuration against target API requirements
- Validate schema files for syntax and structure
- Review rate limiting and concurrency settings
- Confirm scope and URL pattern configurations
Escalation¶
If problems persist after following diagnostic guidance:
- Export detailed diagnostic information via API
- Capture relevant event logs and error messages
- Document configuration settings and recent changes
- Contact Escape support with collected diagnostic data
Monitoring Recommendations¶
- Enable API Access: Configure monitoring systems to poll the problems API endpoint
- Set Up Alerts: Create notifications for critical problem codes
- Track Trends: Monitor problem code frequency over time to identify systemic issues
- Review Regularly: Establish periodic reviews of scan quality metrics
Future Enhancements¶
Additional diagnostic capabilities planned for future releases:
- Automated notifications via workflows for specific problem types
- Predictive failure analysis based on historical patterns
- Recommended configuration adjustments based on detected issues
- Integration with incident management platforms