<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: building-api-security-scanners
description: >-
  Build automated API security scanners that test for OWASP API Top 10
  vulnerabilities including broken authentication, BOLA/IDOR, excessive data
  exposure, rate limiting bypass, and injection attacks against REST and
  GraphQL endpoints.
domain: cybersecurity
subdomain: automation-scripting
tags:
  - api-security
  - owasp-api-top-10
  - rest
  - graphql
  - authentication
  - bola
  - injection
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1190"]
---

# Building API Security Scanners

## Overview

APIs are the primary attack surface for modern applications. This skill covers
building automated scanners that test REST and GraphQL endpoints for OWASP API
Top 10 vulnerabilities — BOLA/IDOR, broken authentication, excessive data exposure,
lack of rate limiting, and injection flaws. Scanners produce structured findings
with severity ratings and remediation guidance.

Mode: `[MODE: RED]` — API vulnerability testing with detection notes.

## Prerequisites

| Requirement | Details |
|---|---|
| Python 3.10+ with `requests` (`pip install requests`) | Required |
| Target API with authorization (test/staging environment) | Required |
| API documentation or OpenAPI/Swagger spec | Required |
| Optional | `graphql-core` for GraphQL introspection |

## Key Concepts

### BOLA/IDOR Testing

```python
import requests

def test_bola(base_url: str, endpoint: str, ids: list[str], token: str) -> list[dict]:
    """Test for Broken Object Level Authorization."""
    findings = []
    headers = {"Authorization": f"Bearer {token}"}
    for obj_id in ids:
        url = f"{base_url}{endpoint.replace('{id}', obj_id)}"
        resp = requests.get(url, headers=headers, timeout=10)
        if resp.status_code == 200:
            findings.append({
                "vulnerability": "BOLA/IDOR",
                "endpoint": endpoint,
                "object_id": obj_id,
                "status": resp.status_code,
                "severity": "high",
            })
    return findings
```

### Rate Limit Testing

```python
def test_rate_limit(url: str, method: str = "GET", count: int = 100) -> dict:
    """Test API rate limiting by sending rapid requests."""
    results = []
    for i in range(count):
        resp = requests.request(method, url, timeout=5)
        results.append(resp.status_code)
        if resp.status_code == 429:
            return {"rate_limited": True, "requests_before_limit": i + 1}
    status_counts = {s: results.count(s) for s in set(results)}
    return {"rate_limited": False, "total_requests": count, "status_distribution": status_counts}
```

### Authentication Bypass Tests

```python
def test_auth_bypass(url: str) -> list[dict]:
    """Test for common authentication bypass patterns."""
    findings = []
    tests = [
        {"name": "no_auth", "headers": {}},
        {"name": "empty_bearer", "headers": {"Authorization": "Bearer "}},
        {"name": "null_token", "headers": {"Authorization": "Bearer null"}},
        {"name": "admin_role", "headers": {"X-Role": "admin"}},
    ]
    for test in tests:
        resp = requests.get(url, headers=test["headers"], timeout=5)
        if resp.status_code == 200:
            findings.append({
                "vulnerability": "auth_bypass",
                "test": test["name"],
                "status": resp.status_code,
                "severity": "critical",
            })
    return findings
```

## Workflow

### Step 1: Scan API Endpoints

```bash
node scripts/agent.js --action scan --base-url https://api.example.com --endpoints /users/{id},/orders/{id}
```

### Step 2: Test Rate Limiting

```bash
node scripts/agent.js --action rate-limit --base-url https://api.example.com/login --count 50
```

### Step 3: Test Authentication

```bash
node scripts/agent.js --action auth-test --base-url https://api.example.com/admin
```

## Verification

- [ ] BOLA test correctly identifies accessible unauthorized objects
- [ ] Rate limit test detects absence of 429 responses
- [ ] Auth bypass test checks multiple evasion techniques
- [ ] All findings include severity, endpoint, and evidence
- [ ] Scanner respects scope constraints and doesn't test production

## References

- [OWASP API Security Top 10](https://owasp.org/API-Security/)
- [OWASP API Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)
- [MITRE ATT&CK T1190 — Exploit Public-Facing Application](https://attack.mitre.org/techniques/T1190/)
