API-SPY 🕵️👻

Un potente strumento di brute-force sulle directory progettato per la ricognizione di API e il penetration testing. Scopre automaticamente endpoint API nascosti, esegue sottoscansioni ricorsive e sonda i metodi HTTP per un'enumerazione API più approfondita.

Caratteristiche

✨ Funzionalità principali:

• 🎯 Scoperta rapida di endpoint tramite brute-force basato su wordlist
• 🔄 Sottoscansione ricorsiva automatica degli endpoint scoperti
• 🔍 Sondaggio dei metodi HTTP (GET, POST, PUT, DELETE, PATCH, OPTIONS)
• ⚡ Scansione multi-thread per prestazioni migliori
• 📊 Gestione intelligente dei codici di stato (200, 401, 403)
• 🔗 Prompt interattivi per sottoscansione e sondaggio selettivi
• 🕷️ Estrazione di JavaScript per endpoint /api/ comuni
• 🪟 Supporto per multiplexer di terminale (tmux) per operazioni parallele
• ⏱️ Salto automatico dei prompt con timeout configurabile

Installazione

Prerequisiti

• Python 3.6+
• Libreria requests
• tmux (opzionale, per il flag --split)
• xfce-terminal (per ambienti desktop Linux)

Configurazione

# Clona il repository
git clone https://github.com/austinjump-sec/API-SPY.git
cd API-SPY

# Installa le dipendenze
pip install requests

# Rendi eseguibili gli script (opzionale)
chmod +x apispy.py apiprobe.py

Utilizzo

Sintassi di base

python3 apispy.py <baseUrl> <wordlist> [OPZIONI]

Argomenti obbligatori

Argomento	Descrizione
<baseUrl>	URL di destinazione (es., http://example.com o http://api.example.com)
<wordlist>	Percorso del file wordlist contenente gli endpoint (uno per riga)

Argomenti opzionali

Argomento	Descrizione
--t<numero>	Numero di thread (max 150, predefinito: 1)
--split	Usa tmux split-window invece di nuove finestre di terminale
--debug	Mostra messaggi di errore altrimenti nascosti
--loud	Mostra tutti i messaggi, positivi ed errori, evidenziando quelli che non restituiscono 404
--js	Cerca file JavaScript ed estrae da quelli trovati eventuali endpoint API comuni hardcoded

Esempi

Scansione di base con impostazioni predefinite (mono-thread)

python3 apispy.py http://api.example.com wordlist.txt

Scansione multi-thread con 10 thread

python3 apispy.py http://api.example.com wordlist.txt -t10

Usa tmux per operazioni parallele

python3 apispy.py http://api.example.com wordlist.txt -t5 --split

Sottoscansione di un URL specifico con un numero maggiore di thread

python3 apispy.py http://api.example.com/v1 wordlist.txt -t20

Come Funziona

Fase 1: Test degli endpoint API comuni

Lo strumento inizia testando un insieme predefinito di percorsi API comuni:

• api, v1, v2, api/v1, api/v2, graphql, rest

Fase 2: Brute-force con wordlist

• Carica gli endpoint dalla tua wordlist (ignora i commenti che iniziano con #)
• Testa ogni endpoint con richieste HTTP GET
• Esecuzione multi-thread per una scansione più rapida
• Identifica gli endpoint che rispondono con i codici di stato: 200, 401, 403

Fase 3: Sottoscansione interattiva (opzionale)

Quando viene trovato un endpoint, viene visualizzato un prompt:

'-> Sottoscansionare <url>? (y/n) [Salto automatico in 5s]:

• Scegli y/yes per scansionare ricorsivamente quell'endpoint con la stessa wordlist
• Si avvia automaticamente in un nuovo terminale o in una finestra tmux divisa
• Salto automatico dopo 5 secondi se non viene fornito alcun input

Fase 4: Sondaggio dei metodi HTTP (opzionale)

Dopo la sottoscansione, viene visualizzato un prompt:

'-> Sondare i metodi su <url>? (y/n) [Salto automatico in 5s]:

• Avvia apiprobe.py che testa i metodi HTTP sull'endpoint scoperto
• Testa: GET, POST, PUT, DELETE, PATCH, OPTIONS
• Output con codifica a colori (verde per 200, giallo per errori legati all'autenticazione)
• Mostra le dimensioni delle risposte e i suggerimenti dell'intestazione Allow

Interpretazione dell'Output

Script principale API-SPY

[+] Url trovato: http://api.example.com/v1            ← 200 OK (accessibile)
    '-> Sottoscansionare http://api.example.com/v1? (y/n) [Salto automatico in 0s]: 
[-] Timeout: Prompt saltato per http://api.example.com/v1?
    '-> Sondare i metodi su http://api.example.com/v1? (y/n) [Salto automatico in 4s]: 
[-] Url trovato ma non consentito (403 ERR): ...      ← Vietato ma esistente
[-] Url trovato ma non consentito (401 ERR): ...      ← Richiede autenticazione

Script API-Probe

[+] GET     -> STATUS: 200 OK (Dimensione: 1024)
[-] POST    -> STATUS: 405 (Dimensione: 0)
[Suggerimento Intestazione] Allow: GET, HEAD, OPTIONS

Formato della Wordlist

Crea un semplice file di testo con gli endpoint (uno per riga):

admin
users
api/users
v1/products
v2/customers
/api/v1/auth
/graphql
search
data
config

Nota: Le righe che iniziano con # sono trattate come commenti e ignorate.

Wordlist Consigliate

Wordlist API popolari da usare con API-SPY:

• SecLists - Endpoint API
• Wordlist API di Assetnote
• Route API di FuzzDB

Suggerimenti per le Prestazioni

Linee guida sul numero di thread

• 1-5 thread: Approccio prudente, minor rischio di rilevamento, più lento
• 5-20 thread: Prestazioni e furtività bilanciate
• 20-50 thread: Scansione aggressiva, risultati più rapidi
• 50-150 thread: Velocità massima (può attivare WAF/IDS)

# Modalità furtiva (pochi thread)
python3 apispy.py http://target.com wordlist.txt -t3

# Modalità bilanciata
python3 apispy.py http://target.com wordlist.txt -t15

# Modalità aggressiva
python3 apispy.py http://target.com wordlist.txt -t50

Comportamento del timeout

• I prompt interattivi vengono saltati automaticamente dopo 5 secondi
• Utile per la scansione non presidiata di lunghi elenchi di target
• Modifica timeout=5 nel codice sorgente per personalizzarlo

Risoluzione dei Problemi

"Wordlist non trovata"

Assicurati che il percorso della wordlist sia corretto e che il file esista:

ls -la /path/to/wordlist.txt

Errore di nome script errato

Quando esegui la sottoscansione, assicurati che:

• Lo script principale si chiami: apispy.py
• Lo script di sondaggio si chiami: apiprobe.py
• Entrambi si trovino nella stessa directory

tmux split-window non funziona

Se --split fallisce:

• Installa tmux: sudo apt install tmux
• Assicurati di essere in una sessione tmux: tmux new-session -s scan
• Il fallback su xfce-terminal avviene automaticamente

"Connessione fallita" per tutti gli endpoint

• Verifica che l'URL di base sia corretto e accessibile
• Controlla le impostazioni di firewall/proxy
• Assicurati che il servizio di destinazione sia in esecuzione
• Testa manualmente: curl http://tuo-url/

Nessun risultato trovato

• Verifica che la wordlist contenga endpoint pertinenti
• Controlla se il target restituisce codici di stato diversi da 200/401/403
• Prova con meno thread per evitare timeout
• Aumenta il timeout delle richieste nella funzione check_status()

Considerazioni sulla Sicurezza