On-Demand Scans
Trigger on-demand attack surface scans for domains and IP ranges. This endpoint allows enterprise users to initiate comprehensive security scans for their assets with a focus on attack surface discovery.
Trigger Attack Surface Scan
Submit a request to scan a specific target with focus on attack surface discovery and vulnerability identification.
HTTP Request
GET https://fullhunt.io/api/v1/attack-surface/on-demand-scan
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| target | Yes | string | The target to scan (domain, IP address, or IP range in CIDR notation) |
Example Request - Domain Scan
curl "https://fullhunt.io/api/v1/attack-surface/on-demand-scan?target=acme.com" \
-H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"
Example Request - IP Address Scan
curl "https://fullhunt.io/api/v1/attack-surface/on-demand-scan?target=8.8.8.8" \
-H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"
Example Request - IP Range Scan
curl "https://fullhunt.io/api/v1/attack-surface/on-demand-scan?target=8.8.8.0/24" \
-H "X-API-KEY: xxxx-xxxx-xxxx-xxxxxx"
Example Response
{
"status": "success",
"message": "Attack surface scan request for 'acme.com' has been successfully queued for processing",
"target": "acme.com",
"type": "domain",
"scan_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": 1683721587
}
Supported Target Types
Domain Names
Comprehensive attack surface discovery for entire domains.
target=acme.com
IP Addresses
Scan individual IP addresses for exposed services and vulnerabilities.
target=8.8.8.8
IP Ranges
Scan IP ranges in CIDR notation for infrastructure discovery.
target=8.8.8.0/24
Response Fields
| Field | Type | Description |
|---|---|---|
status | string | Status of the scan request ("success") |
message | string | Human-readable status message |
target | string | The target that was queued for scanning |
type | string | Detected type of target (domain/ip) |
scan_id | string | Unique identifier for tracking the scan |
timestamp | integer | Unix timestamp when the scan was queued |
Target Validation
The API automatically validates and processes different target types:
- Domains: Must be valid domain format (e.g., example.com)
- IP Addresses: Must be valid IP addresses.
- IP Ranges: Must be valid CIDR notation (e.g., 8.8.8.0/24)
Rate Limiting
- 10 requests per minute per API key
- Higher limits available for high-volume enterprise customers
- Contact FullHunt support for custom rate limits
Error Handling
| Status Code | Description |
|---|---|
| 200 | Success - scan queued |
| 400 | Bad Request - invalid target format |
| 401 | Unauthorized - invalid API key |
| 403 | Forbidden - insufficient credits |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Example Error Response
{
"error": "Invalid target provided"
}
Use Cases
Attack Surface Management
- Discover all exposed services and endpoints
- Identify potential attack vectors
- Monitor changes in attack surface over time
Security Assessment
- Perform comprehensive security scans
- Identify vulnerabilities and misconfigurations
- Validate security improvements after changes
Compliance & Auditing
- Regular scans for compliance requirements
- Document security posture for audits
- Track remediation progress
Infrastructure Monitoring
- Monitor new deployments and changes
- Validate security configurations
- Detect unauthorized services or endpoints
Integration Best Practices
- Monitor Credits: Check credit balance before making requests
- Implement Retry Logic: Handle rate limits and temporary failures
- Store Scan IDs: Keep track of scan requests for correlation
- Error Handling: Implement proper error handling and user feedback
- Rate Limit Awareness: Respect the 10 requests/minute limit
Scan Results
- Scan results are integrated into the main FullHunt database
- Results become available through standard FullHunt APIs
- Processing time varies based on target complexity
- Results include discovered hosts, services, technologies, and vulnerabilities
Security Considerations
- Authorization: Ensure you have permission to scan target assets
- API Key Security: Store API keys securely and rotate regularly
- Data Handling: Follow data protection regulations for scan results
- Responsible Scanning: Only scan assets you own or have permission to test