Scans API

Trigger and manage automated security scans.

Trigger Scan

POST /api/v1/scans

Trigger a security scan against a target. Scans run synchronously and return results upon completion.

Request Body

Field	Type	Required	Description
target	string	Yes	URL or resource identifier to scan
scan_type	string	No	dast (default), api, cloud_config
configuration	object	No	Scan-specific settings

Scan Types

Type	Description	Scanners Used
dast	Dynamic application security testing	Web vulnerability scanner
api	API endpoint security testing	API-specific checks
cloud_config	Cloud configuration review	Configuration scanner

Example Request

curl -X POST https://api.clawgrc.com/api/v1/scans \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://api.example.com",
    "scan_type": "api"
  }'

Example Response (201 Created)

{
  "id": "scan-uuid",
  "org_id": "org-uuid",
  "target": "https://api.example.com",
  "scan_type": "api",
  "status": "completed",
  "results": {
    "findings_count": 3,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0,
    "info": 0,
    "duration_ms": 12450
  },
  "findings": [
    {
      "id": "finding-uuid-1",
      "title": "Missing HSTS header",
      "severity": "medium"
    },
    {
      "id": "finding-uuid-2",
      "title": "Insecure cookie flags",
      "severity": "medium"
    },
    {
      "id": "finding-uuid-3",
      "title": "Server version disclosure",
      "severity": "high"
    }
  ],
  "started_at": "2025-01-15T14:30:00Z",
  "completed_at": "2025-01-15T14:30:12Z"
}

Built-in Scanners

Claw GRC includes three built-in security scanners:

Dependency Scanner

Checks package dependencies for known CVEs. Supports:

• Python (requirements.txt, pyproject.toml)
• Node.js (package.json, package-lock.json)
• Go (go.mod)

Configuration Scanner

Validates configurations against security baselines:

• TLS configuration (minimum version, cipher suites)
• HTTP security headers (HSTS, CSP, X-Frame-Options)
• Cloud service configurations (S3 bucket policies, IAM roles)

Secrets Scanner

Detects leaked credentials in code and configuration:

• API keys, tokens, and passwords
• AWS access keys
• Private keys and certificates
• Database connection strings

Timeouts

Scan requests have a 60-second timeout. For large targets, the scan may return partial results.

Error Responses

Status	Description
400	Invalid target URL or scan type
422	Validation error in scan configuration
408	Scan timed out

SSRF Protection

The scan endpoint includes SSRF (Server-Side Request Forgery) protection. The following targets are blocked:

• Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
• Loopback addresses (127.x.x.x)
• Link-local addresses (169.254.x.x)
• Cloud metadata endpoints (169.254.169.254)