A powerful directory brute-force tool designed for API reconnaissance and penetration testing. Automatically discovers hidden API endpoints, performs recursive subscanning, and probes HTTP methods for deeper API enumeration.

✨ Core Capabilities:

• 🎯 Fast endpoint discovery using wordlist-based brute-forcing
• 🔄 Automatic recursive subscanning of discovered endpoints
• 🔍 HTTP method probing (GET, POST, PUT, DELETE, PATCH, OPTIONS)
• ⚡ Multi-threaded scanning for improved performance
• 📊 Smart status code handling (200, 401, 403)
• 🔗 Interactive prompts for selective subscanning and probing
• 🕷️ JavaScript scraping for common /api/ endpoints
• 🪟 Terminal multiplexing support (tmux) for parallel operations
• ⏱️ Auto-skip prompts with configurable timeout

• Python 3.6+
• requests library
• tmux (optional, for --split flag)
• xfce-terminal (for Linux desktop environments)

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

# Install dependencies
pip install requests

# Make scripts executable (optional)
chmod +x apispy.py apiprobe.py

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

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

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

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

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

The tool starts by testing a predefined set of common API paths:

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

• Loads endpoints from your wordlist (ignores comments starting with #)
• Tests each endpoint with HTTP GET requests
• Multi-threaded execution for faster scanning
• Identifies responsive endpoints with status codes: 200, 401, 403

When an endpoint is found, you're prompted:

'-> Subscan <url>? (y/n) [Auto-skip in 5s]:

• Choose y/yes to recursively scan that endpoint with the same wordlist
• Automatically launches in a new terminal or tmux split-window
• Auto-skips after 5 seconds if no input provided

After subscanning, you're prompted:

'-> Probe methods on <url>? (y/n) [Auto-skip in 5s]:

• Launches apiprobe.py which tests HTTP methods on the discovered endpoint
• Tests: GET, POST, PUT, DELETE, PATCH, OPTIONS
• Color-coded output (green for 200, yellow for auth-related errors)
• Shows response sizes and Allow header hints

[+] Url found: http://api.example.com/v1            ← 200 OK (accessible)
    '-> Subscan http://api.example.com/v1? (y/n) [Auto-skip in 0s]: 
[-] Timeout: Skipped prompt for http://api.example.com/v1?
    '-> Probe methods on http://api.example.com/v1? (y/n) [Auto-skip in 4s]: 
[-] Url found but not permitted (403 ERR): ...      ← Forbidden but exists
[-] Url found but not permitted (401 ERR): ...      ← Requires authentication

[+] GET     -> STATUS: 200 OK (Size: 1024)
[-] POST    -> STATUS: 405 (Size: 0)
[Header Hint] Allow: GET, HEAD, OPTIONS

Create a simple text file with endpoints (one per line):

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

Note: Lines starting with # are treated as comments and ignored.

Popular API wordlists to use with API-SPY:

• SecLists - API endpoints
• Assetnote API wordlist
• FuzzDB API routes

• 1-5 threads: Conservative, less detection risk, slower
• 5-20 threads: Balanced performance and stealth
• 20-50 threads: Aggressive scanning, faster results
• 50-150 threads: Maximum speed (may trigger WAF/IDS)

# Stealth mode (low threads)
python3 apispy.py http://target.com wordlist.txt -t3

# Balanced mode
python3 apispy.py http://target.com wordlist.txt -t15

# Aggressive mode
python3 apispy.py http://target.com wordlist.txt -t50

• Interactive prompts automatically skip after 5 seconds
• Useful for unattended scanning of large target lists
• Modify timeout=5 in source code to customize

Ensure the wordlist path is correct and the file exists:

ls -la /path/to/wordlist.txt

When subscanning, ensure:

• Main script is named: apispy.py
• Probe script is named: apiprobe.py
• Both are in the same directory

If --split fails:

• Install tmux: sudo apt install tmux
• Ensure you're running in a tmux session: tmux new-session -s scan
• Falls back to xfce-terminal automatically

• Verify the base URL is correct and accessible
• Check firewall/proxy settings
• Ensure the target service is running
• Test manually: curl http://your-url/

• Verify the wordlist contains relevant endpoints
• Check if the target returns status codes other than 200/401/403
• Try with fewer threads to avoid timeouts
• Increase request timeout in check_status() function

⚠️ Legal & Ethical:

• Only test systems you own or have explicit written permission to test
• Unauthorized access to computer systems is illegal in most jurisdictions
• Use API-SPY responsibly for authorized penetration testing and security research
• Respect rate limits and don't perform DoS attacks

1. Obtain Authorization: Get written permission before testing
2. Use Appropriate Wordlists: Choose relevant endpoints for your target
3. Monitor Detection: Watch for WAF/IDS blocks or account lockouts
4. Respect Rate Limits: Use lower thread counts for production systems
5. Document Findings: Log all discovered endpoints for reporting

Edit the source code to adjust timeout values:

def ask_subscan(url, wordlist, timeout=10):  # Change from 5 to 10 seconds

Create wordlists targeting specific API paths:

# Admin endpoints only
grep -i "admin" full-wordlist.txt > admin-wordlist.txt

# v1 API only
grep "v1" full-wordlist.txt > v1-wordlist.txt

Scan multiple targets with a loop:

for target in http://target1.com http://target2.com http://target3.com; do
    python3 apispy.py "$target" wordlist.txt -t10
done

• Orchestrates the scanning workflow
• Manages threading and concurrent requests
• Handles interactive prompts and terminal spawning
• Coordinates subscan and probe operations

• Tests HTTP methods on discovered endpoints
• Reports method availability and status codes
• Extracts hints from HTTP headers
• Provides endpoint capability assessment

Contributions are welcome! Feel free to:

• Report bugs and issues
• Suggest new features
• Improve documentation
• Optimize performance

This tool is provided for educational and authorized security testing purposes only. Users are responsible for ensuring they have proper authorization before scanning any systems. Unauthorized access to computer systems is illegal.

This project is provided as-is for security research and authorized testing purposes.

Created by: austinjump-sec
Repository: austinjump-sec/API-SPY