API Surface Mapper & Fuzzer (FFUF + Python)

Este proyecto busca crear una herramienta automatizada para descubrir endpoints ocultos, versiones no documentadas y rutas internas en APIs REST, correlando resultados para detectar:

Endpoints no documentados
Versiones legacy (/v1, /v2, /beta)
Métodos HTTP no esperados
Posibles BOLA / IDOR candidates
Diferencias de comportamiento por rol / token

Arquitectura del proyecto

api-ffuf-hunter/
│
├── wordlists/
│   ├── endpoints.txt
│   ├── versions.txt
│   ├── methods.txt
│
├── modules/
│   ├── ffuf_runner.py
│   ├── response_analyzer.py
│   ├── auth_profiles.py
│   ├── report_generator.py
│
├── configs/
│   └── targets.yaml
│
├── output/
│   ├── raw/
│   ├── analyzed/
│
├── main.py
└── README.md

Cual es el objetivo de este proyecto:

Enumeración dirigida a APIs
Análisis de respuestas JSON-aware
Correlación de resultados
Output accionable para Burp / scripts

Esta dividido en 4 archivos:

1. FFUF Runner (Python ejecutando ffuf)

Qué hace:

Ejecuta ffuf desde Python
Usa headers de API (Authorization, Content-Type)
Salida en JSON
Controla rate-limit

import subprocess
import json
from pathlib import Path

def run_ffuf(url, wordlist, headers, output_file):
    cmd = [
        "ffuf",
        "-u", f"{url}/FUZZ",
        "-w", wordlist,
        "-H", f"Authorization: {headers['Authorization']}",
        "-H", "Content-Type: application/json",
        "-mc", "200,201,202,204,401,403",
        "-of", "json",
        "-o", output_file
    ]

    subprocess.run(cmd, stdout=subprocess.DEVNULL)

2. Análisis inteligente de respuestas

Qué busca:

Respuestas con estructura JSON válida
Diferencias entre 200 vs 403
Campos interesantes: id, user_id, account_id

import json

def analyze_ffuf_output(path):
    with open(path) as f:
        data = json.load(f)

    findings = []

    for r in data["results"]:
        if r["status"] in [200, 403]:
            findings.append({
                "endpoint": r["url"],
                "status": r["status"],
                "length": r["length"],
                "words": r["words"]
            })

    return findings

3. Profiles de autenticación

AUTH_PROFILES = {
    "user": {
        "Authorization": "Bearer USER_TOKEN"
    },
    "admin": {
        "Authorization": "Bearer ADMIN_TOKEN"
    }
}

Que hacer:

Ejecutas la misma fuzzing con distintos tokens
Detectas diferencias de acceso → BOLA

4. Reporte orientado a hunting

def generate_markdown(findings):
    md = "# API Hidden Surface Report\n\n"
    for f in findings:
        md += f"- `{f['endpoint']}` → **{f['status']}**\n"
    return md

Archivo principal

main.py (flujo completo)

from modules.ffuf_runner import run_ffuf
from modules.response_analyzer import analyze_ffuf_output
from modules.report_generator import generate_markdown

run_ffuf(
    url="https://api.target.com",
    wordlist="wordlists/endpoints.txt",
    headers={"Authorization": "Bearer XXX"},
    output_file="output/raw/ffuf.json"
)

findings = analyze_ffuf_output("output/raw/ffuf.json")
report = generate_markdown(findings)

print(report)

Bugs que puedes encontrar con este proyecto

Hidden endpoints
Legacy APIs
BOLA
Broken auth
Debug endpoints

← Back to projects

Info