API-SPY 🕵️👻

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.

Features

✨ 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

Installation

Prerequisites

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

Setup

# 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

Usage

Basic Syntax

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

Required Arguments

Argument	Description
<baseUrl>	Target URL (e.g., http://example.com or http://api.example.com)
<wordlist>	Path to wordlist file containing endpoints (one per line)

Optional Arguments

Argument	Description
--t<number>	Thread count (max 150, default: 1)
--split	Use tmux split-window instead of new terminal windows
--debug	Shows otherwise hidden error messages
--loud	Shows all messages, positive and errors, highlighting any that dont return 404
--js	Scans for JavaScript files and scrapes any found ones for common hardcoded API endpoints

Examples

Basic scan with default settings (single-threaded)

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

Multi-threaded scan with 10 threads

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

Use tmux for parallel operations

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

Subscan specific URL with higher thread count

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

How It Works

Phase 1: Common API Endpoint Testing

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

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

Phase 2: Wordlist Brute-Force

• 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

Phase 3: Interactive Subscanning (Optional)

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

Phase 4: HTTP Method Probing (Optional)

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

Output Interpretation

API-SPY Main Script

[+] 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

API-Probe Script

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

Wordlist Format

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.

Recommended Wordlists

Popular API wordlists to use with API-SPY:

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

Performance Tips

Thread Count Guidelines

• 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

Timeout Behavior

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

Troubleshooting

"Wordlist not found"

Ensure the wordlist path is correct and the file exists:

ls -la /path/to/wordlist.txt

Script named incorrectly error

When subscanning, ensure:

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

tmux split-window not working

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

"Connection Failed" for all endpoints

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

No results found

• 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

Security Considerations

⚠️ 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

Best Practices

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

Advanced Usage

Custom Timeout Values

Edit the source code to adjust timeout values:

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