OpenAPI / Swagger Import

What OpenAPI/Swagger import does

REST APIs are often invisible to a standard crawler - they have no HTML links, no forms, and no pages to follow. By importing your OpenAPI 3.x or Swagger 2.x specification, Shieldome reads the machine-readable contract that describes every endpoint, every HTTP method, and every parameter your API exposes. Those endpoints are then fed directly into the scanner's injection engine, so your full API surface gets tested without any crawling.

What gets tested

Every endpoint extracted from the spec is passed through the same injection checks that run against crawled forms and URLs:

• SQL injection - error-based and boolean-blind indicators in query params and request bodies
• Reflected XSS - benign probe strings echoed back in JSON or HTML responses
• IDOR / broken object-level authorisation - ID parameters swapped between users
• Auth bypass - unauthenticated access to authenticated endpoints
• Path traversal - ../ sequences in path and query parameters
• Rate limiting - rapid repeat requests to detect missing throttling
• Security headers - X-Content-Type-Options, X-Frame-Options, CORS policy

Supported formats

Both servers[0].url (OpenAPI 3.x) and host + basePath (Swagger 2.x) are supported for resolving the base URL. If you want to scan a different environment (staging, local) than what the spec declares, pass target_url in the request body to override it.

How to use - scan form

1. Open the New Scan panel and enter your API's base URL in the target field.
2. Expand Advanced options and click Import OpenAPI spec.
3. Either upload a .yaml / .json file from disk, or paste the public URL of your spec (e.g. https://api.example.com/openapi.json).
4. Shieldome shows a preview of the extracted endpoints. Click Start Scan.

How to use - REST API

Use POST /api/scan/from-openapi to start an OpenAPI-driven scan programmatically.

Option A - upload a spec file

curl -X POST https://app.shieldome.io/api/scan/from-openapi \
  -H "X-API-Key: $SHIELDOME_API_KEY" \
  -F "file=@./openapi.yaml"

Option B - fetch spec by URL

curl -X POST https://app.shieldome.io/api/scan/from-openapi \
  -H "X-API-Key: $SHIELDOME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec_url":   "https://petstore3.swagger.io/api/v3/openapi.json",
    "target_url": "https://api.staging.example.com"
  }'

The target_url field overrides the base URL declared in the spec - useful for pointing the scan at a staging or local environment while still using your production spec.

Response

{
  "scan_id":        "a1b2c3d4-...",
  "endpoint_count": 42,
  "base_url":       "https://api.example.com",
  "paths": [
    { "method": "GET",  "url": "https://api.example.com/users" },
    { "method": "POST", "url": "https://api.example.com/users" },
    { "method": "GET",  "url": "https://api.example.com/users/{id}" }
  ]
}

Poll GET /api/scan/{scan_id}/progress for live status, or GET /api/scan/{scan_id} for the final report - exactly the same as a regular scan.

Combining with authentication

API scans often require a bearer token or API key. Pass auth the same way you would for a standard authenticated scan - via the auth_config field in a regular POST /api/scan body, or via the Auth section of the scan form. The injected credentials apply to every endpoint imported from the spec.

{
  "target_url": "https://api.example.com",
  "scan_type":  "vuln",
  "auth_config": {
    "type":  "token",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "openapi_spec_url": "https://api.example.com/openapi.json"
}

Limitations

• WebSocket endpoints are not supported - only HTTP(S) methods are tested.
• The spec must be either uploaded directly or accessible via a public URL. Specs behind authentication are not automatically fetched; download the file locally and upload it instead.
• Path parameters (e.g. /users/{id}) are fuzzed with a placeholder value (FUZZ). Provide realistic example values in your spec's example fields for more accurate testing.
• A maximum of 200 endpoints are imported per spec. For very large specs, consider splitting by tag or by service.
• GraphQL schemas are not OpenAPI - use the standard scan target with a GraphQL endpoint URL instead.