Shadow API Detection

Definition

Shadow API Detection is the specialized practice of identifying undocumented, unmanaged, or unauthorized API endpoints in production environments using automated tools, traffic analysis, and security scanning techniques. It combines API Discovery methods with security-focused analysis to find APIs that pose immediate risk.

While API Discovery broadly answers “what APIs exist?”, Shadow API Detection specifically targets “what APIs exist that shouldn’t?” or “what APIs exist without proper security controls?” Detection tools actively hunt for dangerous patterns: unauthenticated endpoints processing sensitive data, deprecated APIs still receiving traffic, or third-party SDKs making unauthorized external calls.

Detection is the first step in remediation: you can’t fix what you don’t know exists. Effective detection combines multiple approaches (traffic analysis, code scanning, infrastructure scanning, and active probing) to build a complete picture of an organization’s true API attack surface.

Example

Detection in Action:

A company runs Shadow API detection tools and discovers:

Traffic Analysis (Akto):

• 47 endpoints receiving production traffic not in API documentation
• /api/internal/debug exposed publicly (should be internal only)
• /v1/admin/users has no authentication configured

Code Scanning (Spectral):

• 23 API routes defined in repositories but not registered in inventory
• 12 endpoints with hardcoded API keys or secrets
• 8 endpoints using deprecated authentication methods

Infrastructure Scanning (Custom K8s scanner):

• 34 Kubernetes services with LoadBalancer type not in inventory
• 19 AWS Lambda functions with HTTP triggers and no IAM policies
• 7 API Gateway stages marked “dev” but receiving production traffic

Result: 103 Shadow API candidates requiring triage. High-priority items (public admin endpoints, unauthenticated PII access) escalated immediately.

Analogy

The Security Audit: Imagine auditing a large building for unauthorized access points. You’d check doors (official entrances), windows (potential entrances), and hidden passages (unauthorized entrances). Shadow API Detection is this audit for your infrastructure: systematically checking every possible entry point, comparing what’s documented vs. what actually exists, and flagging discrepancies for investigation.

The Forest Inventory: A forest service doesn’t just trust old maps—they fly drones, use satellite imagery, and send surveyors on foot to count actual trees. Shadow API Detection uses similar multi-method approaches: logs (aerial view), code (satellite imagery), and infrastructure scanning (boots on ground) to find the complete reality.

Code Example

Detection Script (Traffic Analysis + Code Scanning):

#!/bin/bash
# shadow-api-detect.sh
# Comprehensive Shadow API detection

echo "=== Shadow API Detection ==="

# 1. Traffic Analysis: Extract unique endpoints from logs
echo "[1/5] Analyzing traffic logs..."
cat /var/log/api-gateway/*.log \
  | grep "HTTP/1.1" \
  | awk '{print $7}' \
  | sort -u > detected-traffic.txt
echo "Found $(wc -l < detected-traffic.txt) unique endpoints in traffic"

# 2. Code Scanning: Find API routes in source code
echo "[2/5] Scanning source code for API routes..."
# Express.js routes
grep -rh "app\.\(get\|post\|put\|delete\|patch\)" --include="*.js" . \
  | grep -oP '["'\'']\/api\/[^"'\'']+' \
  | sort -u > detected-code.txt
echo "Found $(wc -l < detected-code.txt) API routes in code"

# 3. OpenAPI Spec: Load documented endpoints
echo "[3/5] Loading documented endpoints from OpenAPI spec..."
yq '.paths | keys | .[]' openapi.yaml | sort -u > documented.txt
echo "Found $(wc -l < documented.txt) documented endpoints"

# 4. Identify Shadow APIs
echo "[4/5] Comparing traffic and code against documentation..."

# Traffic-based Shadow APIs
comm -23 detected-traffic.txt documented.txt > shadow-from-traffic.txt
echo "  Traffic analysis: $(wc -l < shadow-from-traffic.txt) Shadow APIs"

# Code-based Shadow APIs
comm -23 detected-code.txt documented.txt > shadow-from-code.txt
echo "  Code analysis: $(wc -l < shadow-from-code.txt) Shadow APIs"

# Combine and deduplicate
cat shadow-from-traffic.txt shadow-from-code.txt | sort -u > shadow-apis.txt
TOTAL=$(wc -l < shadow-apis.txt)
echo "  TOTAL: $TOTAL Shadow API candidates"

# 5. Risk Scoring
echo "[5/5] Scoring Shadow APIs by risk..."
> shadow-apis-scored.txt

while IFS= read -r endpoint; do
  RISK="MEDIUM"
  REASON=""

  # High risk: Admin endpoints
  if echo "$endpoint" | grep -qi "admin"; then
    RISK="HIGH"
    REASON="$REASON [Admin endpoint]"
  fi

  # High risk: Debug/internal endpoints
  if echo "$endpoint" | grep -qiE "debug|internal|test"; then
    RISK="HIGH"
    REASON="$REASON [Debug/internal]"
  fi

  # Critical: User/customer data endpoints
  if echo "$endpoint" | grep -qiE "user|customer|account|profile"; then
    RISK="CRITICAL"
    REASON="$REASON [User data]"
  fi

  # Medium: v1 (potentially deprecated)
  if echo "$endpoint" | grep -q "/v1/"; then
    RISK="MEDIUM"
    REASON="$REASON [Legacy version]"
  fi

  echo "$RISK | $endpoint | $REASON" >> shadow-apis-scored.txt
done < shadow-apis.txt

# Sort by risk (CRITICAL > HIGH > MEDIUM)
sort -t'|' -k1,1 shadow-apis-scored.txt

echo ""
echo "=== Summary ==="
echo "CRITICAL: $(grep -c "^CRITICAL" shadow-apis-scored.txt)"
echo "HIGH:     $(grep -c "^HIGH" shadow-apis-scored.txt)"
echo "MEDIUM:   $(grep -c "^MEDIUM" shadow-apis-scored.txt)"
echo ""
echo "Full report: shadow-apis-scored.txt"

Detection with Akto (Open Source Tool):

# Install Akto
docker run -d -p 8080:8080 aktosecurity/akto

# Point Akto at traffic source
# Option 1: Mirror traffic from API Gateway
kubectl apply -f akto-traffic-mirror.yaml

# Option 2: Analyze existing logs
curl -X POST http://localhost:8080/api/analyze-logs \
  -H "Content-Type: application/json" \
  -d '{
    "logSource": "s3://my-bucket/api-gateway-logs/",
    "timeRange": "7d"
  }'

# View detected APIs
curl http://localhost:8080/api/endpoints | jq '.[] | select(.isDocumented == false)'

# Output: List of Shadow APIs with risk scores

Diagram

graph TB
    A[Shadow API Detection] --> B[Traffic Analysis]
    A --> C[Code Scanning]
    A --> D[Infrastructure Scan]
    A --> E[Active Probing]

    B --> B1[API Gateway Logs]
    B --> B2[Load Balancer Logs]
    B --> B3[WAF Logs]

    C --> C1[Git Repositories]
    C --> C2[OpenAPI Specs]
    C --> C3[IaC Templates]

    D --> D1[Kubernetes]
    D --> D2[Cloud Functions]
    D --> D3[Containers]

    E --> E1[OWASP ZAP]
    E --> E2[Burp Suite]
    E --> E3[Nuclei]

    B1 --> F[Detected Endpoints]
    B2 --> F
    B3 --> F
    C1 --> F
    C2 --> F
    C3 --> F
    D1 --> F
    D2 --> F
    D3 --> F
    E1 --> F
    E2 --> F
    E3 --> F

    F --> G[Compare with Documented APIs]
    G --> H[Shadow API Candidates]
    H --> I[Risk Scoring]
    I --> J[Prioritized Remediation]

    style A fill:#bbdefb
    style F fill:#fff9c4
    style H fill:#ffcdd2
    style J fill:#c8e6c9

Security Notes

Detection Methods Compared

Recommended: Combine all four methods for comprehensive detection.

Common Mistakes

Mistake 1: One-time scanning Shadow APIs appear constantly. Detection must be continuous (daily/weekly), not a one-time audit.

Mistake 2: No triage process Finding 200 Shadow APIs is useless without prioritization. Which are CRITICAL? Which can wait? Implement risk scoring.

Mistake 3: Detection without remediation plan Discovering Shadow APIs is step 1. You also need: owner assignment, security review process, and migration/sunset plan.

Mistake 4: Only using traffic analysis Traffic analysis misses unused Shadow APIs. A vulnerable endpoint with zero traffic is still a risk—attackers will find it.

Mistake 5: Ignoring false positives Not every detected endpoint is a Shadow API. Health checks, metrics endpoints, and CDN paths may appear undocumented but be intentional. Review manually.

Risk Scoring Framework

Score Shadow APIs using this rubric:

Risk = (Data Sensitivity × Authentication Weakness × Traffic Volume) + Modifiers

Data Sensitivity:
- Public/non-sensitive: 1x
- Internal business data: 2x
- PII (personally identifiable information): 3x
- PCI (payment card data): 4x

Authentication Weakness:
- OAuth2/JWT: 1x
- API Key: 2x
- Basic Auth: 3x
- No authentication: 4x

Traffic Volume:
- Zero traffic: 1x
- <100 req/day: 1x
- 100-10K req/day: 2x
- >10K req/day: 3x

Modifiers:
- Admin endpoint: +2
- Debug/internal keyword: +2
- Deprecated version (v1, v2): +1
- External access (internet-facing): +2
- Known CVEs in dependencies: +3

Example:

• /api/v1/admin/users endpoint
• Processes PII (3x)
• No authentication (4x)
• 5K requests/day (2x)
• Admin endpoint (+2)
• Legacy version (+1)
• Risk Score: (3 × 4 × 2) + 2 + 1 = 27 (CRITICAL)

Tools for Shadow API Detection

Open Source:

Akto (https://github.com/akto-api-security/akto)

• Traffic analysis from logs, API Gateways, Kubernetes
• Automated Shadow API detection
• OpenAPI spec generation from traffic

OWASP ZAP (https://www.zaproxy.org/)

• Active security scanning
• API endpoint discovery through spidering
• Automated vulnerability detection

Nuclei (https://github.com/projectdiscovery/nuclei)

• Template-based scanning for known patterns
• Fast, parallelized scanning
• Community-contributed templates

Spectral (https://github.com/spectralops/spectral)

• Code scanning for API definitions and secrets
• CI/CD integration
• OpenAPI linting

Enterprise (Commercial):

Salt Security

• Real-time traffic analysis with ML
• Automated Shadow API discovery and risk scoring
• API attack detection

42Crunch

• API security platform with discovery
• Design-time and runtime protection
• Vulnerability scanning

Traceable AI

• ML-powered API discovery
• Threat detection and blocking
• Compliance monitoring

Noname Security

• Comprehensive API security platform
• Shadow API detection and inventory
• Runtime protection

Triage Workflow

Step 1: Detect (automated daily)

• Run traffic analysis, code scanning, infrastructure scanning
• Generate list of Shadow API candidates

Step 2: Score (automated)

• Apply risk scoring framework
• Sort by CRITICAL > HIGH > MEDIUM

Step 3: Validate (manual, 1-2 hours)

• Review CRITICAL findings manually
• Remove false positives (health checks, internal-only endpoints)
• Confirm actual Shadow APIs

Step 4: Assign Owners (manual, 1 hour)

• Cross-reference with code repositories
• Identify team/developer who deployed endpoint
• Assign ownership in API inventory

Step 5: Remediate (varies)

• CRITICAL: Immediate action (disable or secure within 24 hours)
• HIGH: Security review and plan within 7 days
• MEDIUM: Register in inventory, schedule deprecation

Best Practices

1. Automate detection: Daily traffic analysis, weekly code scans
2. Combine methods: Traffic + Code + Infrastructure for complete coverage
3. Score by risk: Prioritize CRITICAL findings first
4. Triage quickly: CRITICAL Shadow APIs need response within hours, not weeks
5. Track over time: Dashboard showing new Shadow APIs discovered each week
6. Integrate with inventory: Auto-register detected APIs for ongoing management
7. Measure success: Goal = zero CRITICAL Shadow APIs, <10 HIGH at any time

Assessment Tool

Start here: Shadow API Detection Tool

This interactive tool helps you:

• Assess your organization’s Shadow API risk level
• Choose the right detection approach for your infrastructure
• Get a customized detection implementation plan
• Estimate effort and timeline for first detection scan

Further Reading

📚 Book: “Cómo Identificar Shadow APIs Con Herramientas Open Source”

Comprehensive guide to Shadow API Detection with practical tool implementations:

• 🇬🇧 English Edition
• 🇪🇸 Spanish Edition

Detailed coverage:

• Chapter 3: Traffic Analysis with Akto (step-by-step setup)
• Chapter 4: Code Scanning with Spectral and custom scripts
• Chapter 5: Infrastructure Scanning (AWS, Azure, GCP, Kubernetes)
• Chapter 9: Tool Comparison Matrix (20+ tools evaluated)
• Chapter 10: Building a Detection Pipeline (automated CI/CD integration)

Related Terms